evolt.org Workers of the Web, Evolt!

Introduction

I just started programming with PHP and MySQL this week and the first script I wanted to write was a login script. I wanted to include the popular "Remember Me" feature seen on a lot of websites that basically keeps users logged into the website, even after they've closed the browser so that the next time they come, they won't have to login again manually.

I found this tutorial Creating a PHP Login Script to be very helpful in writing this script, in fact, a lot of the code presented here is very similar to the code presented in that tutorial. The differences are seen with the new "Remember Me" feature, the use of cookies in addition to sessions, and with slight modifications in the design.

Goals

The ultimate goal is to create a PHP login script with the capability of remembering logged-in users. I also hope this tutorial will serve as a way to introduce people to user sessions and cookies in PHP.

Notes

Although this tutorial uses a MySQL database for storing user information, it has been written so that the data accessing code is separated from the main code through specific functions, so it would be easy to instead use a flat file "database" system, simply by changing the code in those specific functions, without messing with the rest. This tutorial uses the latest and greatest of PHP 4, which means super globals are used, such as $_POST, $_SESSION, etc.. This tutorial will aim to teach you about sessions and cookies through example, however if you need to know more information, go to the official website .

Database

For those of you planning on using a flat file system, you can skip this section. For the rest of us, we want to create a MySQL database table that holds user information, here it is:

CREATE TABLE users (
    username varchar(30),
    password varchar(32));

Of course this table can be modified according to your needs, however the password field must not be less than 32 because it has to store the md5 encrypted versions of passwords which are 32 bytes.

database.php

This file will contain the code that connects you to your MySQL database and the functions that access user information, you need to modify this to show your MySQL username, password and database.

<?

/**
 * Connect to the mysql database.
 */
$conn = mysql_connect("localhost", "your_username", "your_password") or die(mysql_error());
mysql_select_db('your_database', $conn) or die(mysql_error());

?>

Allow Users to Sign-Up

Before we can login users, we need users. Here we will focus on the code that allows users to sign-up, registering their username and password.

register.php

<?
session_start(); 
include("database.php");

/**
 * Returns true if the username has been taken
 * by another user, false otherwise.
 */
function usernameTaken($username){
   global $conn;
   if(!get_magic_quotes_gpc()){
      $username = addslashes($username);
   }
   $q = "select username from users where username = '$username'";
   $result = mysql_query($q,$conn);
   return (mysql_numrows($result) > 0);
}

/**
 * Inserts the given (username, password) pair
 * into the database. Returns true on success,
 * false otherwise.
 */
function addNewUser($username, $password){
   global $conn;
   $q = "INSERT INTO users VALUES ('$username', '$password')";
   return mysql_query($q,$conn);
}

/**
 * Displays the appropriate message to the user
 * after the registration attempt. It displays a 
 * success or failure status depending on a
 * session variable set during registration.
 */
function displayStatus(){
   $uname = $_SESSION['reguname'];
   if($_SESSION['regresult']){
?>

<h1>Registered!</h1>
<p>Thank you <b><? echo $uname; ?></b>, your information has been added to the database, you may now <a href="main.php" title="Login">log in</a>.</p>

<?
   }
   else{
?>

<h1>Registration Failed</h1>
<p>We're sorry, but an error has occurred and your registration for the username <b><? echo $uname; ?></b>, could not be completed.<br>
Please try again at a later time.</p>

<?
   }
   unset($_SESSION['reguname']);
   unset($_SESSION['registered']);
   unset($_SESSION['regresult']);
}

if(isset($_SESSION['registered'])){
/**
 * This is the page that will be displayed after the
 * registration has been attempted.
 */
?>

<html>
<title>Registration Page</title>
<body>

<? displayStatus(); ?>

</body>
</html>

<?
   return;
}

/**
 * Determines whether or not to show to sign-up form
 * based on whether the form has been submitted, if it
 * has, check the database for consistency and create
 * the new account.
 */
if(isset($_POST['subjoin'])){
   /* Make sure all fields were entered */
   if(!$_POST['user'] || !$_POST['pass']){
      die('You didn\'t fill in a required field.');
   }

   /* Spruce up username, check length */
   $_POST['user'] = trim($_POST['user']);
   if(strlen($_POST['user']) > 30){
      die("Sorry, the username is longer than 30 characters, please shorten it.");
   }

   /* Check if username is already in use */
   if(usernameTaken($_POST['user'])){
      $use = $_POST['user'];
      die("Sorry, the username: <strong>$use</strong> is already taken, please pick another one.");
   }

   /* Add the new account to the database */
   $md5pass = md5($_POST['pass']);
   $_SESSION['reguname'] = $_POST['user'];
   $_SESSION['regresult'] = addNewUser($_POST['user'], $md5pass);
   $_SESSION['registered'] = true;
   echo "<meta http-equiv=\"Refresh\" content=\"0;url=$HTTP_SERVER_VARS[PHP_SELF]\">";
   return;
}
else{
/**
 * This is the page with the sign-up form, the names
 * of the input fields are important and should not
 * be changed.
 */
?>

<html>
<title>Registration Page</title>
<body>
<h1>Register</h1>
<form action="<? echo $HTTP_SERVER_VARS['PHP_SELF']; ?>" method="post">
<table align="left" border="0" cellspacing="0" cellpadding="3">
<tr><td>Username:</td><td><input type="text" name="user" maxlength="30"></td></tr>
<tr><td>Password:</td><td><input type="password" name="pass" maxlength="30"></td></tr>
<tr><td colspan="2" align="right"><input type="submit" name="subjoin" value="Join!"></td></tr>
</table>
</form>
</body>
</html>


<?
}
?>

Read through the code and see what it's doing, there are comments there to help you. It was written with you in mind, I tried to make it so people could just paste their website specific html code in between the php code with ease. Don't be scared when you see the use of session variables right away, they are used to tell the script key information like the requested username, registration attempt and registration success. With this information the script knows what to display, and when the registration is done, it "forgets" the information (by unsetting the variables).

Note

You'll notice that the script immediately refreshes itself after the registration request, this is done to eliminate the case where users, for any reason, hit the Refresh button on their browser and cause a pop-up window that says the page has expired and prompts the user to send the registration request again. This technique is also used in the login script, so watch out for it.

Allow Users to Log-In

Now the fun begins, now that we have users, we can log them in. This is the heart of this tutorial, it will create the login script with the "Remember me" feature that we all want, and it accomplishes this by using cookies.

login.php

<?

/**
 * Checks whether or not the given username is in the
 * database, if so it checks if the given password is
 * the same password in the database for that user.
 * If the user doesn't exist or if the passwords don't
 * match up, it returns an error code (1 or 2). 
 * On success it returns 0.
 */
function confirmUser($username, $password){
   global $conn;
   /* Add slashes if necessary (for query) */
   if(!get_magic_quotes_gpc()) {
	$username = addslashes($username);
   }

   /* Verify that user is in database */
   $q = "select password from users where username = '$username'";
   $result = mysql_query($q,$conn);
   if(!$result || (mysql_numrows($result) < 1)){
      return 1; //Indicates username failure
   }

   /* Retrieve password from result, strip slashes */
   $dbarray = mysql_fetch_array($result);
   $dbarray['password']  = stripslashes($dbarray['password']);
   $password = stripslashes($password);

   /* Validate that password is correct */
   if($password == $dbarray['password']){
      return 0; //Success! Username and password confirmed
   }
   else{
      return 2; //Indicates password failure
   }
}

/**
 * checkLogin - Checks if the user has already previously
 * logged in, and a session with the user has already been
 * established. Also checks to see if user has been remembered.
 * If so, the database is queried to make sure of the user's 
 * authenticity. Returns true if the user has logged in.
 */
function checkLogin(){
   /* Check if user has been remembered */
   if(isset($_COOKIE['cookname']) && isset($_COOKIE['cookpass'])){
      $_SESSION['username'] = $_COOKIE['cookname'];
      $_SESSION['password'] = $_COOKIE['cookpass'];
   }

   /* Username and password have been set */
   if(isset($_SESSION['username']) && isset($_SESSION['password'])){
      /* Confirm that username and password are valid */
      if(confirmUser($_SESSION['username'], $_SESSION['password']) != 0){
         /* Variables are incorrect, user not logged in */
         unset($_SESSION['username']);
         unset($_SESSION['password']);
         return false;
      }
      return true;
   }
   /* User not logged in */
   else{
      return false;
   }
}

/**
 * Determines whether or not to display the login
 * form or to show the user that he is logged in
 * based on if the session variables are set.
 */
function displayLogin(){
   global $logged_in;
   if($logged_in){
      echo "<h1>Logged In!</h1>";
      echo "Welcome <b>$_SESSION[username]</b>, you are logged in. <a href=\"logout.php\">Logout</a>";
   }
   else{
?>

<h1>Login</h1>
<form action="" method="post">
<table align="left" border="0" cellspacing="0" cellpadding="3">
<tr><td>Username:</td><td><input type="text" name="user" maxlength="30"></td></tr>
<tr><td>Password:</td><td><input type="password" name="pass" maxlength="30"></td></tr>
<tr><td colspan="2" align="left"><input type="checkbox" name="remember">
<font size="2">Remember me next time</td></tr>
<tr><td colspan="2" align="right"><input type="submit" name="sublogin" value="Login"></td></tr>
<tr><td colspan="2" align="left"><a href="register.php">Join</a></td></tr>
</table>
</form>

<?
   }
}


/**
 * Checks to see if the user has submitted his
 * username and password through the login form,
 * if so, checks authenticity in database and
 * creates session.
 */
if(isset($_POST['sublogin'])){
   /* Check that all fields were typed in */
   if(!$_POST['user'] || !$_POST['pass']){
      die('You didn\'t fill in a required field.');
   }
   /* Spruce up username, check length */
   $_POST['user'] = trim($_POST['user']);
   if(strlen($_POST['user']) > 30){
      die("Sorry, the username is longer than 30 characters, please shorten it.");
   }

   /* Checks that username is in database and password is correct */
   $md5pass = md5($_POST['pass']);
   $result = confirmUser($_POST['user'], $md5pass);

   /* Check error codes */
   if($result == 1){
      die('That username doesn\'t exist in our database.');
   }
   else if($result == 2){
      die('Incorrect password, please try again.');
   }

   /* Username and password correct, register session variables */
   $_POST['user'] = stripslashes($_POST['user']);
   $_SESSION['username'] = $_POST['user'];
   $_SESSION['password'] = $md5pass;

   /**
    * This is the cool part: the user has requested that we remember that
    * he's logged in, so we set two cookies. One to hold his username,
    * and one to hold his md5 encrypted password. We set them both to
    * expire in 100 days. Now, next time he comes to our site, we will
    * log him in automatically.
    */
   if(isset($_POST['remember'])){
      setcookie("cookname", $_SESSION['username'], time()+60*60*24*100, "/");
      setcookie("cookpass", $_SESSION['password'], time()+60*60*24*100, "/");
   }

   /* Quick self-redirect to avoid resending data on refresh */
   echo "<meta http-equiv=\"Refresh\" content=\"0;url=$HTTP_SERVER_VARS[PHP_SELF]\">";
   return;
}

/* Sets the value of the logged_in variable, which can be used in your code */
$logged_in = checkLogin();

?>

This one's a little bit tricky because of the function calling. Let me just clarify what this script does.

It first checks to see if the login form has just been filled out and submitted, if not it checks to see if a session has already been established where the username and password are already known. This is true in two cases, when the user has chosen to be remembered and a session is established automatically, or when the user has not chosen to be remembered but has already logged in and is still using the same browser window that he used to log in.

If either of these two cases is true, then it verifies that the username is in the database and that the password is valid, if these two checks pass then the almighty $logged_in variable is set to true, false otherwise. If the user has just filled out the login form and submitted it, the script detects this and then verifies the authenticity of the username and password, if all is well then session variables are set with the username and md5 encrypted password.

Great, but when does the login form get displayed? That's all up to you. It's up to you the programmer to display the login form when the $logged_in variable is false. But wait! I have added a function that you can call that relieves you of this horrible burden. The displayLogin() function is there to check if the $logged_in variable is true or not and displays information accordingly. How to use this function is described in the Usage section.

Note

login.php is not meant to be a stand-alone file like register.php, it is meant to be included at the top of every file that needs to use it, so it doesn't contain the call to "session_start()", that should be at the top of the file that wants to include login.php, as you will see in the examples below.

Remember Me Feature

So, how was this accomplished again? As is described in login.php, when a user chooses to be remembered, two cookies are set on the user's computer. Well, really one cookie, but one that contains two important pieces of information: the username and the md5 encrypted password. What is a cookie anyways? It is a temporary file that is stored on the user's computer on behalf of the website in order to hold information that is important to the website. How long does this temporary file last? As long as we say so. As written, the expiry time is 100 days, after which the cookie will be deleted. However, it also gets deleted when the user decides to log out, as you will soon see.

Allow Users to Log-Out

If users want to log-out, we should let them. All we need to do is delete the cookies we've set if they chose to be remembered, and simply unset the session variables. Done.

logout.php

<?
session_start(); 
include("database.php");
include("login.php");

/**
 * Delete cookies - the time must be in the past,
 * so just negate what you added when creating the
 * cookie.
 */
if(isset($_COOKIE['cookname']) && isset($_COOKIE['cookpass'])){
   setcookie("cookname", "", time()-60*60*24*100, "/");
   setcookie("cookpass", "", time()-60*60*24*100, "/");
}

?>

<html>
<title>Logging Out</title>
<body>

<?

if(!$logged_in){
   echo "<h1>Error!</h1>\n";
   echo "You are not currently logged in, logout failed. Back to <a href=\"main.php\">main</a>";
}
else{
   /* Kill session variables */
   unset($_SESSION['username']);
   unset($_SESSION['password']);
   $_SESSION = array(); // reset session array
   session_destroy();   // destroy session.

   echo "<h1>Logged Out</h1>\n";
   echo "You have successfully <b>logged out</b>. Back to <a href=\"main.php\">main</a>";
}

?>

</body>
</html>

You're probably wondering why login.php was included in logout.php, seems a little weird right? Well, if the user is not logged in how can we log them out? We use login.php to verify that the user really is logged in with the help of the variable $logged_in which gets set when login.php is run.

Flat File Database

If you don't have MySQL, don't worry, you can still use this script! All you would have to do is change the following functions to include your flat file user management code, but remember to keep the operations and return values consistent with the documentation.

• In register.php - change usernameTaken() and addNewUser()
• In login.php - change confirmUser() and checkLogin()

Usage

Now that everything has been coded, all that's left is for you to know how to actually use this beast.

• database.php - make sure you put your own MySQL information into it
• register.php and logout.php - no changes needed, however you could change the html to reflect that of your website
• login.php - In order to use it within a file you must call "session_start()" before the line where you include login.php.

I've mentioned the function "displayLogin()" found within login.php. If you call it within one of your files, it will display the login form if no user is logged in, if a user is logged in, it displays a message reflecting such. The point of this is so that you won't have to include that code in all of your files, all you have to do is just call the function:

Example: main.php

<? 
/* Include Files *********************/
session_start(); 
include("database.php");
include("login.php");
/*************************************/
?>

<html>
<title>Jpmaster77's Login Script</title>
<body>

<? displayLogin(); ?>

</body>
</html>

You should also know that login.php sets a boolean variable called $logged_in, which is true when a user is logged in, and false when no user is logged in. You can use this variable in your files for whatever you'd like.

Example: main2.php

<? 
/* Include Files *********************/
session_start(); 
include("database.php");
include("login.php");
/*************************************/
?>

<html>
<title>Jpmaster77's Login Script</title>
<body>

<? 
if($logged_in){
   echo 'Logged in as '.$_SESSION['username'].', <a href="logout.php">logout</a>';
}else{
   echo 'Not logged in.';
}
?>

</body>
</html>

Improvements

What can make this script even better? Well, you can add a check to enforce that usernames are strictly alphanumeric, without any wacky characters. At registration, you probably want more info from the user (email, homepage, location,..), but this script is about user logins, so we only focused on the username and password.

Also the error pages are not very cool, for example, when someone doesn't enter a field thats required from the form, instead of just stopping and printing an error message, you can redirect him to the form again, but have specified which field was left blank (in red lettering possibly). There's more that I'm sure you'll think of.

Conclusion

I hope you were able to learn something from my script, and if you choose to use my script on your site, I hope you enjoy it. Good luck programming!