How to install “php-login” (MVC version) on Ubuntu 14.04 LTS
IMPORTANT: This script has reached End of Life, so it’s not maintained anymore. However, the concept behind the script has been totally rewritten from scratch, with a new architecture and a new name: HUGE. It’s now a little framework that comes with a fully integrated user login system. Please have a look at https://github.com/panique/huge for more information. The original project (simply called “php-login”) is still online, you can find the code in the 2.x releases on https://github.com/panique/huge/releases.
This tutorial will guide you through the installation process of php-login, a simple but effective, modern, clean and naked PHP application that has a full user authentication system (“login system”) integrated. You can find the very latest version here on GitHub: https://github.com/panique/php-login. This script is part of a set of 4 similar login scripts, from extremely simple (one file!) to quite professional (this one here), have a look on php-login.net for more information. You can also follow the project on Twitter, Facebook or Google+. And by the way, I’m the author of this script :)
Very important: The requirements
First, a very real thing: This project gets bombarded with totally weird, unnecessary and aggressive questions, support requests, “bug reports” and insane mails, usually because people have a problem installing this. In nearly all (!) cases it’s because they simply haven’t followed the install tutorial, skipped steps (!), do really weird stuff or have in general absolutly no idea what they do. You wouldn’t believe the feedback you get when you publish open-source stuff on the web. Some of these mails are pure art. Stuff like (imagine really bad orthography here and a mail address like cockboy88): “Dude, your script is shit and does not work and i have no idea about PHP, but here is the server password, please install the script for me. ASAP.” or “i dont know what composer is so explain it to me”… These mails should be printed on canvas and shown to public on a developer conference or something. This would be cool. Okay, let’s get back to the topic:
1. This script is NOT for beginners. You need to be familiar with the basics of object-oriented programming, MVC, have an understanding of what Composer is and you should be able to work on the linux command line without problems. If you don’t see yourself here, then please have a look at the other version, they might fit much better for you.
2. Please don’t use “hosting”. Hosting is for people who want to upload basic HTML files, it’s not for development! “Hosting” is a big pain in the ass in the PHP world, as it’s so popular, but it makes things much much more complicated (!), usually uses extremely outdated software and comes with totally messed up configs. Basic rule: If the server doesn’t have SSH access, then don’t use it. “Hosting” is a bad relict from the old-school PHP-times, when PHP was used for guestbooks, user-counters and stuff like that. If you don’t have access to the console, then it’s not a real server. Get a real server instead, you can rent servers everywhere for $3+ per month. I recommend DigitalOcean, as they rent servers without long-term-contracts (!) for $5 per month, you can create a new one within seconds and stop/delete them within seconds and only pay by the hours used. Excellent for development. They also offer Ubuntu 14.04 LTS (which is cool as this is out for only some days at the point of writing this tutorial). For a local Ubuntu 14.04 LTS server I can recommend creating a box with Vagrant.
3. This tutorial is for Ubuntu 14.04 LTS. For a local installation on Windows 7 / 8 please see this tutorial.
4. Don’t overcomplicate things! Make everything as clean and simple as possible. There’s no need to create everything in a subfolder, between existing projects or on an existing server. Start fresh and clean, with a naked Ubuntu 14.04 LTS. Use the script in the way it should be used. Go through the tutorial step by step, doing exactly what is says.
The short tutorial
1. Install PHP and MySQL on your Ubuntu 14.04 LTS (will be PHP 5.5 and MySQL 5.5 by default). Also make sure you have the GD extension, OpenSSL and Composer installed and activated mod_rewrite. Please note that OpenSSL, the source of the Hearthbleed bug (that affected major parts of the entire internet, including Yahoo, Tumblr, Facebook, GitHub etc., the Android OS, lots of hardware and… well, yes, basically everything), is used here (for mail transport, not for login issues), but Ubuntu 14.04 LTS comes with a “special” version that is not affected by the bug (but I’m not 100% sure about that as the communication of Ubuntu is really bad).
2. Copy/clone the content of the php-login repository to your server’s web root (make sure the folder is empty before!) via git clone or via Composer.
3. Run the SQL statements from folder application/_installation/ !
4. Make the public/avatars folder writeable (chmod 775, for development 777 is also okay).
5. Edit the application/config/config.php and enter your database credentials (DB_USER etc.), the URL (simply put your URL, IP etc. here), the COOKIE_DOMAIN (note the dot in front of the domain!) and for mail sending the SMTP credentials of your SMTP provider, also set EMAIL_USE_SMTP to true when using SMTP. I use SMTP2GO. If you know what you do, try sending mails with sendmail etc., but this does usually not work by default, as creating a non-spam-blocked mail server is something for people with stronger admin skills.
6. Edit the .htaccess in the project root: If your project is in a subfolder, put the folder name into the line where it says RewriteBase. If not, delete this line.
7. When in the root folder, do composer install to download all dependencies (not necessary anymore when you installed via Composer in step 2).
Done! For more info, especially on how to activate the Facebook-login feature, please see the longer tutorial.
The long, detailed tutorial
1. Install Apache, MySQL, PHP (and PHPMyAdmin)
2. Install mod_rewrite and enable it
3. Install Composer
4. Install GD and OpenSSL
GD is the graphic extension of PHP, we need this for creating captchas. OpenSSL makes mail sending possible. On a standard Ubuntu 14.04 LTS these things are installed by default, but to be correct, here’s how to install. Note that Ubuntu 14.04 LTS comes with a version of OpenSSL that is not affected by the Hearthbleed bug (as far as I know). Hearthbleed affects versions from 1.0.1 to 1.0.1f (and some other branches), versions 1.0.1g and later is fixed. Due to totally weird reasons Ubuntu ships not with 1.0.1g, they seriously deliver a “special” version of 1.0.1f that includes a fix. WTF !? This will probably create a lot of confusion, but let’s assume that the people behind this are not stupid and have reasons for doing so.
sudo apt-get install php5-gd sudo apt-get install openssl sudo service apache2 restart
5. Clean the folder where you want to create the project
Assuming that you want to have the project directly in var/www/html (where Apache has put its index.html and maybe you also have put stuff there), clean this folder like this:
rm -r /var/www/html/*
6. Copy php-login to your server
Do it like you want: Old-school manual copying the files or via git
git clone https://github.com/panique/php-login.git /var/www/html
or via Composer
composer create-project panique/php-login /var/www/html dev-master
If you use the installation via Composer, then this will automatically get all dependencies automatically now, so you can skip step #11.
7. Make the avatar folder writeable
chmod 777 /var/www/html/public/avatars
and check the rights with the stat command. There should be something like 0777 in the output. Note that 777 are too much right for such a folder, and when you go live with your project you should lower the rights, but for this first development installation tutorial it’s okay. Read more about this here, here and here.
8. Fill the database with empty tables
Run the SQL statements from application/_installation/sqlstatements. PHPMyAdmin is perfect for this.
Find the statements here: https://github.com/panique/php-login/tree/master/application/_installation/sql_statements.
9. Edit the config file
Open application/config/config.php (which holds the entire configuration of your application) and
a.) fill in your database credentials. That’s DB_USER, DB_PASS etc.
b.) put your project’s URL or IP into URL. Remove the subfolder from the path if you are not using the script in a special subfolder. If your project is directly in the /var/www/html-path in Ubuntu 14.04 LTS, then simply put your domain/IP in here and don’t forget the trailing slash ! Please not that Ubuntu 14.04 LTS comes with a newer version of Apache that has /var/www/html as default location, not /var/www anymore !
c.) put your project’s URL or IP into COOKIE_DOMAIN. This time, put a dot (!) in front of the domain/IP and don’t use a trailing slash. Yeah, this is weird, but that’s PHP’s default handling of cookie-domain names. To make things cross-browser-safe simply put the dot there. Your COOKIE_DOMAIN should look like ‘.example.com’, ‘.127.0.0.1’ or ‘.localhost’ now.
d.) now the most tricky part: Fill in your SMTP credentials of your SMTP provider in the SMTP part of the config.php and set EMAIL_USE_SMTP to true. Why this ? Because sending mails with PHP’s internal mail() function simply triggers a mail sending request via other linux tools, like sendmail etc. PHP itself does not (and can not) send mails. The big problem is, that mails sent with mail() will often not arrive the receiver, and some of them will also never leave the server. Sending mails is a huge topic. The reasons are complex, afaik mails sent from “unknown” sources, like IP-based servers etc. are completely blocked by most major providers instantly. To clarify: These mails will not end up in the spam folder, these mails will never even arrive the final server! This SMTP thing is not made to annoy you, it’s made to make things work. When you go live with your app you cannot risk that mails don’t arrive. If you know what you do, then leave the SMTP stuff like it is, the application will try to send mails with the server’s default sendmail config (but don’t ask me, thick books have been written about sendmail and the web is full of desperate threads about failing mail sending with PHP and linux ). If you have the skills: Cool, please write a book on How to send bulletproof mails with PHP, a lot of people would pay any price! I’m using SMTP2GO (2000 mails for $5, 100% success rate, note that this is an affiliate link) for mail sending. There are other companies offering SMTP (PostageApp), and even Gmail offers free SMTP usage, but that’s a little bit tricky. Maybe in another tutorial.
e.) OPTIONAL: Change the text, reply-mail-address etc. of the EMAIL_PASSWORD_RESET_SUBJECT etc. ! This is not necessary, especially the example mail address shouldn’t be changed for now, but you should change this when going live on a real domain.
10. Preparing .htaccess for URL rewriting
Edit the .htaccess inside your root folder and change the line that says RewriteBase: when using the script within a sub-folder, put this path here, like /mysubfolder/ ! If your application is in the root of your web folder, then delete this line or comment it out (with a “#”).
11. Fetching PHP dependencies via Composer
If you have chosen to install php-login via Composer in step #6, then the dependencies have been fetched already automatically there. If you haven’t chosen this way of installation, then now go into the base folder of your application (where composer.json is), like
This will make Composer download all the things defined in composer.json, like PHPMailer, the captcha library, the PHP password compatibility library etc.
Your application should now run fine perfectly. By the way, I’ve written this tutorial step by step while doing exactly what it says in a Vagrant box with Ubuntu 14.04 LTS and the same thing on a live remote server, several times. It works like a charm. If you encounter problems, please ask in the support forum or form a bugreport on GitHub. For smaller things please use the comment box below this article.
If you are happy with the script, then feel free to send feedback (or constructive bad feedback if you are not happy) and consider a small donation via PayPal. This project has lots of totally unpaid work behind, and you get a totally free thing, ready to use for any private or commercial projects. Be fair and give something back, especially when you use it in commercial projects and earn money with the script.
It’s also always cool to see live projects that use the script, it would be very nice of you to send in links showing what has been made out of the code.
Optional: Activate Facebook feature
Note: Facebook changes the look, the UI and the way the Facebook App pages work permanently. But you’ll find out what’s meant. Go to https://developers.facebook.com/apps/ and create a new app. Go to “preferences” or whatever it is called, enter your email adress, leave “App Domain” empty, click on “Add platform” and put your URL in “Site URL” (completely with “http://www.”), save. For local development “localhost” works. Things like “127.0.0.1” and IP addresses don’t seem to work, which means you need a real domain to use Facebook’s login kit (this question on StackOverflow might help you with that issue). This is abviously intented by the Facebook devs to avoid abuse. In earlier version of Facebook’s App API you needed to set “sandbox mode” to “deactivated”, now… well… I don’t know, they have removed the button but the app still says “in development mode”.
FACEBOOK_LOGIN in application/config/config.php to
true and put your Facebook app id and the secret token in
You should see the Facebook login / register buttons on the login / register page of your php-login app now.
By the way, the Facebook login works like that: The “Registration / Login with Facebook” button is a link created by the Facebook SDK. When clicked, it will route the user to a Facebook server (and Facebook will check if the user is logged in on THEIR servers) and ask the user to allow or deny read-only access to his/her public Facebook-data (plus email). Then Facebook will send the user back to a URL you passed to Facebook via the button link. That’s it. If the user allowed access, then you’ll have a PHP variable now, containing some of the user’s data (standard stuff plus email in this case). The way php-login has implemented the Facebook login is the official way!
If you want to go deep with Facebook’s authentication API (and maybe other APIs, like Twitter’s, Google’s etc.) have a look on the Facebook SDK repo on Github or the QuickStart for PHP. Third-party authentication is definitly the future, so it’s not wrong to bookmark these links for rainy days.