User Guide - Free Login Script

Thank you for choosing the Quadodo Login Script for your site. This is an in-depth user's guide which will take you through all the necessary, and simple steps to setup and manage this system. This user's guide must be read before making any changes to any script or installing the system for the first time. If you want just a simple login system, the only part of this you'll need to read are the installation instructions - good luck.

Top

II.i. What's New

In this version of the system there is a simple new feature that allows you to output a list of the current online users. Also in the administration panel (and while updating) you can set what format you want to use for outputting this information.

Top

II.ii. Requirements

This system does have certain requirements that must be met. First of all this system will not work unless you have PHP 4.3.3 or higher. It is also a requirement that you have some sort of database system. The database scripts bundled with this system are MySQL(i) and PostgreSQL. These are some of the best free SQL databases available. If you do choose to use MySQLi as your database, you must have PHP 5.0.0 or higher. The MySQL version should be 3+. The PostgreSQL version should be 7+.

If you have any suggestions on database scripts that should be bundled with the system please visit the forum.

Top

II.iii. Support

Free help is available for this system. You just have to visit the Support Area and post a question. I am alerted of new questions when they are posted and it will be answered as soon as possible.

Top

II.iv. Merging

Merging is a new feature to this system in version 3, and a very useful one. It will allow you to 'merge' the template of your site with the system itself. All the code of this system is embeddable, so you can wrap HTML right around the PHP code. The following files:

activate.php
login.php
members.php
register.php
change_password.php
*Custom Member Pages

Can be wrapped in your HTML code. At the top of each of these files you will find:

<?php
define('QUADODO_IN_SYSTEM', true);
require_once('includes/header.php');
?>

That code is required at the top of those files so that the files can be accessed correctly and the system will work properly. If it's not found every page would show up blank. Between that and the rest of the PHP code, the start of your HTML code can be placed. For example:

<?php
define('QUADODO_IN_SYSTEM', true);
require_once('includes/header.php');
?>
<html>
<head>
<title>Login to My Site</title>
</head>
<body>
<div align="center">
<?php
/*** *** *** *** *** ***
* @package Quadodo Login Script
* @file login.php...
... they are commenting.
*** *** *** *** *** ***/

// Is the user logged in already?
if ($qls->user_info['username'] == '') {
    if (isset($_POST['process'])) {
        // Try to login the user
        if ($qls->User->login_user()) {
        echo LOGIN_SUCCESS;
        }
        else {
        // Output login error
        echo $qls->User->login_error . LOGIN_TRY_AGAIN;
        }
    }
    else {
    // Get the login form
    require_once('html/login_form.php');
    }
}
else {
echo LOGIN_ALREADY_LOGGED;
}
?>
</div>
</body>
</html>

That will align the login form to the center of the page. You can put as much HTML as you like, as long as the code at the start is always at the start and the PHP code in the middle is not altered.

If you want to have the same header and footer for each page you could add whatever you want as the header on each page right at the bottom of the includes/header.php file:

<?php
/*** *** *** *** *** ***
* @package Quadodo Login Script
* @file header.php...
...before the code they are commenting.
*** *** *** *** *** ***/
if (!defined('QUADODO_IN_SYSTEM')) {
exit;
}

// Current language
define('SYS_CURRENT_LANG', 'English');

// The qls class will start the other classes
require_once('qls.class.php');
$qls = new qls();
?>
<html>
<head>
<title>Example.com</title>
</head>
<body>

Then for the footer, you could make a file called footer.php and put it in the includes folder. Then inside this file you could put something like this:

</body>
</html>

Now that you have the footer.php completed you can add this line of code at the bottom of every page (before the ?>) in the main directory that can have this done (list above):

require_once('includes/footer.php');

Top

II.v. Language

The default language of this system is English, but it has the ability to be used in different languages. In the includes/header.php file you will find:

define('SYS_CURRENT_LANG', 'English');

The English refers to the includes/English.lang.php file. If you create or edit this file and save it as something else, it must be named NewName.lang.php or it won't work properly. If you do make another one, the code in the includes/header.php file would have to be changed to:

define('SYS_CURRENT_LANG', 'NewName');

Any of the values in the includes/English.lang.php file can be edited to fit your needs. I suggest you edit the links in their to suit the style of your site if needed.

Top

II.vi. Updating

There is a new update module that comes with the system that will allow you to quickly upgrade to the newest version. You should have downloaded only the changed files from my site if you are updating from an older version. The update files are located in the:

/install/updates/update_{OLD_VERSION}.php

And can be run using a URL like this:

http://www.example.com/install/updates/update_{OLD_VERSION}.php

For example if you are updating to 3.1.6 from 3.1.5 you can run /install/updates/update_3.1.5.php and you will be given a form to fill out. When you update the system none of your old data will be lost. Some features may have been removed but all the information you input to the old features will still exist in your database.
They don't really need to be deleted but they will not be used by the system anymore. If you're still having problems you can always ask a question in the Support Area.

Top

III. Installation

The first thing you need to do if you haven't yet, is to upload this entire system to your site. It can be in any folder you wish. There is no index file provided with the system, so you will have to make one yourself. If you want to know how to edit the members page please see the section on bottom. The following sections will teach you how to fill in the fields on the installation page. If you don't know what you're doing I suggest you read this section carefully and make sure you don't miss anything.

Top

III.i. SQL Setup

Configuring the SQL is simple enough. All you have to do is fill in the necessary fields according to the information that your host gave you, or that you created. If you need more detail look at the sections below.

Top

III.i.1. Table Prefix

This is the prefix that will go on the front of all of your SQL tables. This is useful if you have tables with the same names as the ones that will be created by this system. It may also be useful if you need to create similar tables later. The default is qls3_ but it can be anything you like as long as it starts with a letter or underscore, followed by 0 - 253 letters, numbers or underscores. If you don't want to use a prefix, just leave the field blank.

Top

III.i.2. Database Type

The database type is the type of database you wish to use for this system. The only choices that are currently available are MySQL(i) and PostgreSQL. These are both excellent database systems, but your host probably only supports one. The MySQL choice is available for any version of PHP, while the MySQLi type requires PHP 5+. If you don't see the MySQLi choice it is because the script determined that you don't have the necessary PHP version.

Top

III.i.3. Database Port

This is the port that you connect to your database with. This should have been provided by your host. If you use a free database host such as freesql.org, you will see the port as a number at the end of the server name they gave you. If you really have no idea what this is, you don't need to fill the field out because it's most likely not needed.

Top

III.i.4. Database Server Name

The database server name is the name of the server where your database can be reached. For the most part, unless your host gave you different information, it is always localhost. If your host gave you another server name use that one or it won't work.

Top

III.i.5. Database Username

This along with the other SQL information should have been provided by your host. If it's not, you may need to create a username by yourself. If you use a management system such as cPanel you can create and manage databases via the MySQL section on the main page. If you are still having trouble managing databases, you may visit the Support Area and ask a question.

Top

III.i.6. Database Password

The database password should have been given along with your username. If you created a database it should be the password you entered. If you still don't know how to setup databases please visit the Support Area and ask a question.

Top

III.i.7. Database Name

The database name was either given by your host or created when you created a database. The username and password must correspond to the database or it won't work correctly. If you are still having trouble understanding how to work databases please visit the Support Area and ask a question.

Top

III.ii. Cookie Information

The cookie information is important as it decides how to manage user's sessions while logged into your site. Cookies are necessary (well sessions at least) for running a login system. This system sets both sessions and cookies at the same time. This way if a browser doesn't allow cookies the session will still exist.

Top

III.ii.1. Cookie Prefix

The cookie prefix should be set so collisions between cookie/session names won't happen. It must start with a letter or underscore, followed by 0 - 253 letters, numbers or underscores. If you don't want to use it, just leave the field blank.

Top

III.ii.2. Cookie Path

The cookie path should be equal to the path to this system. For example, if this system is located at http://www.example.com/members/ then the cookie path would be equal to /members/ (with both /). It is important that this is set correctly because the cookies won't work right and if you have user authentication then the activation link won't work.

Top

III.ii.3. Cookie Secure

This option is to set the security for cookies. This should only be used if your site is accessed through https:// instead of http://. If you don't know which one to choose just choose No.

Top

III.ii.4. Cookie Length

The cookie length determines how long you want cookies/sessions to last (in seconds) before they expire in the database. Right now it is set at 1209600 which is two weeks. If the user's browser supports cookies, the cookie will update the time in the database every visit. This will make sure that it is only after 2 weeks of no activity that they are logged out. Here are some useful periods of time in seconds:

Time Period	In Seconds	Math
1 hour	3600	3600 * 1
6 hours	21600	3600 * 6
1 day	86400	3600 * 24
1 week	604800	(3600 * 24) * 7
2 weeks	1209600	((3600 * 24) * 7) * 2
1 month	2419200	((3600 * 24) * 7) * 4
6 months	14515200	(3600 * 24) * (365 / 2)
1 year	31536000	(3600 * 24) * 365

Top

III.ii.5. Cookie Domain

The cookie domain is very important as it tells the browser which site the cookie can be read from. It is also used to determine the activation link for your site. For example, if your site was http://www.example.com/ you would put .example.com (with the dot at the front). This allows the cookie to be read by your site and any subdomains of your site. Make sure there is no www in front of it or the activation link sent to users won't work.

Top

III.iii. Security Information

Security is very important when it comes to programming. This system has many internal security features as well as external. The external features include maximum login attempts and a security image. These will help to stop spammers and just plain mean people from hurting your site.

Top

III.iii.1. Maximum Login Attempts

The maximum login attempts is the number of times that someone can fail at logging in for 12 hours. The default value is 5 but it can be set to anything from 1 to 99. I don't suggest that you use anything below 5 attempts as it may stop some real users from logging in. This can cause them to be annoyed and leave your site.

Top

III.iii.2. Security Image

The security image feature will stop robots or spammers from creating fake user accounts on your site. Fake user accounts can be used to advertise or just ruin your site. This feature requires the GD library for PHP. This field will only show up on the installation page if the library exists, if not it won't show up. I suggest you use this feature if possible but it will use around 100kB of bandwidth everytime it is viewed.

Top

III.iii.3. Maximum Upload Size

This is the maximum file size of a PHP file that can be uploaded to your site (in bytes). The only people allowed to access this are people who have access to the admin panel. It is currently set to 1MB.

Top

III.iii.4. Allow Public Registrations

Public registrations may defeat the purpose of having a login system, so in this version there is the ability to stop people from registering on your site. If you disallow public registrations, you have to send people invites via the admin panel. More is explained in the admin panel section of this guide.

Top

III.iv. User Settings

These are the settings that will apply to all and any user that signs up for your site.

Top

III.iv.1. Maximum Username Length

This is the maximum length (in characters) that a username can be when a user signs up for your site. The maximum length will include this number, so if you choose 15 someone could use the username a12345678901234 and it would work. The maximum value you can enter is 99. Anything higher will crash the system.

Top

III.iv.2. Minimum Username Length

This is the minimum length (in characters) that a username can be when a user signs up for your site. The minimum length will include this number, so if you choose 2 someone could use the username a1 and it would still work. The maximum length that you can enter is 99 - if it's higher the system won't work properly.

Top

III.iv.3. Maximum Password Length

This is the maximum length (in characters) of a password that a user can enter. This should be kept between 15 and 30 for security reasons. The maximum value you can enter is 99 - if it's higher the system will fail.

Top

III.iv.4. Minimum Password Length

The minimum password length is important because it won't let users enter small passwords that can be broken easily. The best value for this is 4, 5 or 6. The maximum value you can enter is 99 though I don't suggest using it.

Top

III.iv.5. Activation Type

The activation type is the type of authentication that users are required to go through before their account becomes active. The three choices are None, User or Admin. None will require no activation - they can login as soon as they register. User means they will be sent an email with an activation link. They won't be able to login until they follow this link and activate their account. This prevents robots from having accounts. Admin means that only you can decide whether or not to activate their account. This will be useful if you only want certain people signing up for your site.

Top

III.iv.6. User RegEx

RegEx is short for Regular Expressions. It is generally used for matching and replacing certain character strings in programming. The default value is (^([_a-z0-9]+)(\.[_a-z0-9]+)*). This will allow users to enter usernames that begin with an underscore, number or letter followed by a period, underscore, letter or number. The PHP function used to do this matching is the eregi() function so only regular expressions that will work with that function will work.

Top

III.iv.7. Login Redirect URL

The login redirect URL is the URL to which users will be redirected once they login to your site. It can be relative to the current path of the login system or a full URL. It must be set or the user will be redirected to a non-existant page.

Top

III.iv.8. Logout Redirect URL

The logout redirect URL is the URL to which users will be redirected to once they logout from your site. It can be relative to the current path of the login system or a full URL. It must be set or the user will be redirected to a non-existant page.

Top

III.iv.9. Default Group Name

This will be the default group that users will be assigned to when they register. The default value is Default.

Top

III.iv.10. Default Mask Name

This will be the default permission mask name that will be assigned to the default group. The permissions are automatically set but can be edited later. The default value is Default.

Top

III.iv.11. Redirect Type

This is the type of redirection the system will use when redirecting users. It should be set on the recommended PHP redirection type. The other two may have compatibility problems whereas the PHP method will not.

III.iv.12. Online Users Format

This is the format that the usernames will be output if you choose to use the online user list feature. The default value for this field is {username}. This is just the user's username by itself. You can also use {id} which would be replaced by their user ID. HTML can be used in that field if you need to link to a user profile or something of that sort. {username} and {id} will always be replaced.

Top

III.iv.13. Online Users Separator

This is the thing that will separate usernames when outputting the current online user list. It defaults to just a comma ( , ) but anything could be used (including HTML).

Top

III.v. Admin User Information

The admin user information is important because it is the main account of the system. Without it you won't be able to manage anything from the admin panel or activate users (if you selected Admin for the activation type).

Top

III.v.1. Username

This is what your username will be. It will be used as the main account for your site and will be the only account allowed to access the admin panel. It must follow the same restrictions as what you entered before this field. If you put a maximum length on usernames for 15 you can't have a 18 character username for the admin username.

Top

III.v.2. Password

This is the password for the admin account. Try to make it as secure as possible because you don't want random people going onto your admin account and messing around in the admin panel.

Top

III.v.3. Email Address

This is your email address. It isn't really used for anything, but in future versions may be needed for new functionality. A valid email address must be entered that is between the length of 6 and 101.

Top

IV. Admin Panel

The admin panel is a very important feature of this system. It allows you to manage users (edit, delete and ban) as well as manage the rest of the system. You are also able to see updates to the system (in English only) at anytime. In version 3.1.x you can now allow more than one user access to the admin panel because of the new permission mask and grouping system. The entire admin panel is based on AJAX, so it loads quickly. The only fault with this is that the back button is broken, and you must click the Go button instead of hitting the Enter/Return button on your keyboard.

Top

IV.i. Main

In this area you just see a brief message about the login script. You will be able to select one of the tabs/links in the menu to go to a new page. The available links under the Main tab are: PHP Info, Updates and Configuration.

Top

IV.i.1. PHP Info

This will display all the information about your PHP configuration. If nothing shows up it is because your host has disabled the phpinfo() function. Be careful with who you allow to access this, because they may be able to hack your site with the information.

Top

IV.i.2. Updates

On this page you will find the current updates to the system for your version. Updates are only available in English though :(

Top

IV.i.3. Configuration

The configuration is basically the same as the installation information. If you need to know how to fill out one of the fields read the installation section. You will not be able to change the SQL information via this form. If you need to edit the SQL information please visit the Support Area and ask a question.

IV.ii. Users

In this tab you will be able to add, list, remove, edit or see pending accounts. The available links under the Users tab are: Add, List, Remove, Edit and Pending Accounts.

Top

IV.ii.1. Add User

When adding a user all you have to do is fill out the form. The username is their username and must follow the guidelines you set in the configuration. The password can be whatever you want, and then you must confirm it. The email address should be a valid one in case a plugin is installed which uses their email address. You must also confirm the email address to avoid typos. Their permission mask doesn't have to be set unless you want a special permission mask for this one user, instead of using the one for the group. When you select the group, the permission mask for the group will be used for the user, unless you specified a specific mask for them.

Top

IV.ii.2. List Users

The user list is just that. It will list all the users currently registered for your site. It uses a pagination system to decrease bandwidth consumption and only shows 20 users at a time. From the user list you will be able to Edit or Remove the user. Be careful because if you click the remove button there is no way to reverse it.

Top

IV.ii.3. Remove User

On this page you will be given a text box in which you can enter a username to remove. The username must be exact or it will return an error of not found. If you don't know who you want to delete, go to the user list and remove from there.

Top

IV.ii.4. Edit User

From the edit user form you will be able to specify a new username, email address, permission mask, group and whether or not they are banned. You should only allow certain people to access this, because they could possible edit information about your account.

Top

IV.ii.5. Pending Accounts

Here you will find a list of users' accounts that need activation. If you don't require activations on your site nothing will appear here. If you do require Admin activation or User activation their accounts will be available to activate from the panel.

Top

IV.iii. Groups

Here you will be able to manage your user groups. User groups are things that allow the grouping of users. It can be useful for applying permission masks to a mass number of your users. Certain groups may only be able to access certain parts of your site. The links available under the Groups tab include: add, list, remove and edit.

Top

IV.iii.1. Add Group

Using the add group form you can add user groups. The first field you will find is the group name. It should only be alphanumeric and contain 1 - 255 characters. Next you will find the permission mask. It will be the permissions associated with this group. All users in the group will have that mask, unless you specified a specific mask for them. The next field is the leader. It must be a valid username. If a valid username is not entered it will return an error. Finally you have the choice whether or not to allow the group to the public. Public groups can have anyone join them via the group control panel.

Top

IV.iii.2. List Groups

Here you will find a group list. It contains all the groups that have been created so far. You will be able to edit the group, remove the group or edit the leader of the group (edit their actual account information). All the groups will be listed, no pagination is present.

Top

IV.iii.3. Remove Group

On the remove group page you will find a drop down with all the groups. Select a group and then click Go. The selected group will be removed from the site, and all users under that group will be put in the default group. You can also remove groups from the group list.

Top

IV.iii.4. Edit Group

Editing a group is the same as adding a group except you are just updating the information. If you follow the link in the group list, you will be brought right to the information. If you don't and follow the link under the tab you will be brought to a drop down with all the groups listed. You can then choose one.

Top

IV.iv. Pages

The paging system is a new feature in 3.1.x. It allows you to add, list, edit and remove pages. There are several ways to add a page (explained below). The only thing is that the Page section in the admin panel doesn't use AJAX, it actually submits the form. This means you will leave the admin panel for a second, until you click the link to go back.

Top

IV.iv.1. Add Page

Any custom page should have this at the very very top:

<?php
define('QUADODO_IN_SYSTEM', true);
require_once('includes/header.php');
$qls->Security->check_auth_page('{PAGE_NAME}');
?>

There are three ways to add a page to the system:

Uploading via Admin Panel
Creating in the Admin Panel
Uploading via an FTP Program

When uploading via the admin panel, you can select a PHP file on your computer (must have .php extension) and upload it. It will be automatically added to the database. When a file is added to the database it can be decided whether or not to allow certain masks/groups to visit it.

When creating in the admin panel you have to give it a name - it may overwrite the file if it is found so choose the name wisely (an error will be output too). You must also insert some kind of page data.

When uploading via an FTP program (or some other way) you should go to the form in the Add Page section. On bottom it says Create a New File Here. Using that form, enter the file name that you just uploaded but put absolutely nothing in the textarea for the content. This will add the file to the database, but allow you to upload it via your FTP program.

Top

IV.iv.2. List Pages

The list pages section will list all the pages you have on the site. It will also give you the option to edit the page, or remove the page (those functions are explained below). There is no pagination present in the page list so all the pages will be shown.

Top

IV.iv.3. Remove Page

When you go to the remove page area, you will be given a drop down with a list of current pages. Select one and click Go. You can also remove pages from the actual page list. When you remove a page, it will be removed from the database and your site so make sure you have copies if you need them!

Top

IV.iv.4. Edit Page

The edit page form allows you to edit the name of the file and the content. You can insert whatever you like in the text area, but some code should stay the same (such as header information). You should also limit people from having access to this area of the admin panel, as some may use it against you :(

Top

IV.v. Permissions

The permissions system is a new feature in the 3.1.x release. It allows you to block/allow certain users from doing certain things on the login system. You can allow certain administrator functions, or just block certain groups from accessing pages. The links available under the Permissions tab are: add mask, list masks, remove mask and edit mask.

Top

IV.v.1. Add Mask

The add mask form is a rather big form to do. On the left hand side you have a list of administrator functions and whether or not to allow them to do it. They will not be able to do anything in the admin panel unless the first one is selected as allowed. You should only give those permissions to people you trust, because they may be able to hurt your site.

On the right hand side you have the pages that are currently on your site. When a page is added, it is automatically added to the database as not allowed to view. There also must be a special code on any page if you want the permission system to work (it's mentioned above in the Add Page section).

Top

IV.v.2. List Masks

Here you will find a list of all the masks currently in your database. From there you will be able to edit or remove them. If you select to remove them there is no other confirmation so make sure you don't click it by accident!

Top

IV.v.3. Remove Mask

On this page you will find a drop down with all the names of your masks. All you have to do is select a mask and click Go. It will immediately be removed and all the groups with the selected mask will be reset to the default mask.

Top

IV.v.4. Edit Mask

Editing a mask is the same thing as adding a mask except you're updating the information. You must edit a mask everytime you add a page because no one will be allowed to access the page (for security reasons).

Top

IV.vi. Invitations

The invitation system is new with the 3.1.x release. It allows you to invite people to sign up for your site if you have disabled public registrations. When you disable public registrations and someone goes to the register.php page, they will recieve an error. When you send an invite a code is given to the user which is in the URL. The code is then read by the system and it sees that they are allowed to sign up so it allows them.

On the invitation form you will find a place to put the person's email address along with your email address. Next you will find a place to put the URL of the register.php page. This is necessary because the user needs a link to follow to the register page. The link to the register page may already be generated by the PHP script. It must follow this format:

http://www.example.com/path/register.php

There can be nothing at the end or the user will follow a bad link. Once the user accepts the invitation the code they were given becomes invalid.

Top

V. Member Section

With the new version of this login script member sections can be made with very little coding necessary. There is currently a file located in the main directory of the login system called members.php. It is the basic layout of the pages that will require authentication. Here is what that file currently looks like:

<?php
define('QUADODO_IN_SYSTEM', true);
require_once('includes/header.php');
$qls->Security->check_auth_page('members.php');
?>

<?php
// Look in the USERGUIDE.html for more info
if ($qls->user_info['username'] != '') {
?>

You are logged in as <?php echo $qls->user_info['username']; ?><br />
Your email address is set to <?php echo $qls->user_info['email']; ?><br />
There have been <b><?php echo $qls->hits('members.php'); ?></b> visits to this page.

<?php
}
else {
?>

You are currently not logged in.

<?php
}
?>

That file could be edited to look something like this:

<?php
define('QUADODO_IN_SYSTEM', true);
require_once('includes/header.php');
$qls->Security->check_auth_page('members.php');
?>
<html>
<head>
<title>Member Section</title>
</head>
<body>
<div align="center">
<?php
if ($qls->user_info['username'] != '') {
?>

Hello there <b><?php echo $qls->user_info['username']; ?></b>!!<br />
Your current email address is set to <b><?php echo $qls->user_info['email']; ?></b>
There have been <b><?php echo $qls->hits('members.php'); ?></b> visits to this page.

<?php
}
else {
?>

Sorry but you must be <a href="register.php">registered</a> and <a href="login.php">logged in</a> to access this area.

<?php
}
?>
</div>
</body>
</html>

As you can probably tell, all the user information is available via $qls->user_info['name']. The available information that is default by the system is:

$qls->user_info['id'] - Their ID number
$qls->user_info['username'] - Their username
$qls->user_info['password'] - Their password hash
$qls->user_info['code'] - Their activation code
$qls->user_info['active'] - Whether they are active or not
$qls->user_info['last_login'] - The UNIX timestamp of the last time they logged in
$qls->user_info['last_session'] - The last value of their last session
$qls->user_info['blocked'] - Whether they are blocked or not
$qls->user_info['tries'] - Recorded tries until this point (it's reset every 12 hours)
$qls->user_info['last_try'] - The UNIX timestamp of their last try
$qls->user_info['email'] - Their email address
$qls->user_info['mask_id'] - Their mask ID
$qls->user_info['group_id'] - Their group ID
$qls->hits('{FILE_NAME}') - The current page hits

Another useful function is the $qls->Security->check_auth_page('{FILE_NAME}'); function. This will check to see if the user is allowed to access the page.

As many of these pages can be created as you want. They can be written in the admin panel under the pages tab. If you still can't figure out how to do this, please post a question in the Support Area.

Top