<html>
<head>
<title>
PHPPageProtect Readme
</title>
<style>
<!--
body { background-color: white; color: black; font-family: arial; font-size: 90%; }
a:link { color: blue; text-decoration: none; }
a:active { color: red; text-decoration: underline; }
a:hover { color: red; text-decoration: underline; }
a:visited { color: purple; text-decoration: none }
-->
</style>
</head>
</body bgcolor="white" text="black" link="blue" alink="red" vlink="purple">
<pre>
/////////////////////////////////////////////////////
// //
// <font color="red">P H P P a g e P r o t e c t</font> //
// Version 1.0.0 //
// //
// Copyright 2002 //
// David Broker //
// <a href="http://php.warpedweb.net/">http://php.warpedweb.net/</a> //
// All Rights Reserved //
// //
// In using this script you //
// agree to the following: //
// //
// This script may be used and modified //
// freely as long as this //
// copyright remains intact. //
// //
// You may not distibute this script, or //
// any modifications of it. //
// //
// A link must be provided on the website that //
// uses the script to: //
// <a href="http://php.warpedweb.net/">http://php.warpedweb.net/</a> //
// //
// Any breaches of these conditions //
// will result in legal action. //
// //
// This script is distributed with //
// no warranty, free of charge. //
// //
/////////////////////////////////////////////////////
</pre>
<b>Readme File for PHPPageProtect Version 1.0.0a</b>
<h3>Contents:</h3>
<ul>
<li><a href="#about">About</a>
<li><a href="#include">Included Files</a>
<li><a href="#install">Installation/Usage</a>
<li><a href="#changelog">Change log</a>
<li><a href="#todo">To do</a>
</ul>
<h2><a name="about">About</a></h2>
<p>PHPPageProtect is a user authentication system used to password protect selected pages.
<br>Pages are protected by adding a single line of PHP script at the top of the page.
<br>A web-based administration section allows for the creation of new users, deleting users, changing passwords and viewing logs.
<br>User information and logs are stored in a flatfile (text) database.</p>
<h2><a name="include">Included Files</a></h2>
Here is a list of files that should be included in this distribution:
<ol>
<li><i>readme.txt</i>
<br>This file.
<li><i>admin.php</i>
<br>The adminstration script.
<li><i>login.php</i>
<br>The script which logs in/out the user.
<li><i>protect.php</i>
<br>The script which provides the page protection.
<li><i>conf.php</i>
<br>The configuration file.
<li><i>eg.php</i>
<br>An example of a protected page.
<li><i>firstpage.php</i>
<br>The first page you see when you log on.
<li><i>log.dat</i>
<br>The file where login records are stored.
<li><i>users.dat</i>
<br>Where username/encrytped passwords are stored.
</ol>
<h2><a name="install">Installation</a></h2>
<ol>
<li><b>Requirements:</b>
<ul>
<li><i>PHP Version 4.0.2 or greater.</i>
<br>This is needed because of the functions used in the script are not valid in PHP3
<li><i>Session Support</i>
<br>Your webserver must have session support enabled and working.
<li><i>VERY basic knowledge of PHP.</i>
<br>This is required to install the script. You need to edit a few lines of the script, all of which is described in detail.
</ul>
<li><b>Configure the scripts:</b>
<ol>
<li>First open admin.php, login.php and protect.php in a text editor.
<br>Edit the $config variable to point to the config file. If the conf.php file
is in the same directory as admin.php, login.php and protect.php then you can leave these as they are.
<pre>EG: $conf = "c:\\path\\to\\conf.php";</pre>
<li>Next open conf.php in a text editor.
<br>There are several variables to edit here:
<ol>
<li>Set the administration username and password (case sensitive):
<pre>EG: $admin_username = "Username";
$admin_password = "PaSsWoRd</pre>
<li>The full server path to the users.dat file:
<pre>EG: $user_data = "c:\\path\\to\\users.dat";
$user_data = "/path/to/users.dat";</pre>
<li>The URL of the first page the user will see when they login:
<pre>EG: $first_page = "http://www.example.com/firstpage.php";</pre>
<li>The URL of the login page:
<pre>EG: $login_page = "http://www.example.com/login.php";</pre>
<li>Whether or not you wish to log user logins (true/false):
<pre>EG: $log_login = true;</pre>
<li>If you set $log_login to true, you must specify a log file path:
<pre>EG: $log_file = "c:\\path\\to\\log.dat";
$log_file = "/home/path/to/log.dat";</pre>
</ol>
</ol>
<li><b>Installing the scripts:</b>
<ol>
<li>Upload those files to your server.
<li>Change file permissions:
<br>On Unix the users.dat and log.dat files need to be writable by the webserver (usually "nobody").
<br>On Windows 9X/ME no permissions need to be changed.
<br>On Windows NT/2000 the users.dat and log.dat files need to be writeable by the webserver (usually "INET_USR" or similar)
</ol>
<li><b>Using the scripts:</b>
<br>Now we need to use the scripts.
<ul>
<li><i>Administration</i>
<ul>
<br>First point your browser to the uploaded admin script:
<pre>http://www.example.com/admin.php</pre>
Log in using the selected username and password.
<li><i>Create a new user.</i>
<br>To create a new user simple fill out the information in the "New User" form and click "Create".
<li><i>Delete a user.</i>
<br>Simply check the box next to the username you wish to delete and click "Delete".
<li><i>Change password.</i>
<br>Select the username from the list and enter the new password in the password and confirm password boxes then click change.
<li><i>View Log.</i>
<br>If you have selected to log the login attempts, the you can view the log file by clicking "View Log".
<li><i>Clear log.</i>
<br>Click the button to clear the log file (Caution: there is no undo feature).
<li>Administrator can also log on through the "login" section, but the it is not logged.
</ul>
<li><i>Protecting a Page</i>
<ul>
<li>To protect a page you must simply include this line at the very top of the page you wish to protect:
<pre><?php include("protect.php"); ?></pre>
It is very important that there are not blank lines or spaces before the above line.
<br>If protect.php is in a directory different to the one the page is in the line will need to look like this:
<pre><?php include("directory/protect.php"); ?></pre>
<br>If protect.php is in a directory above the one the page is currently in it may need to look like this:
<pre><?php include("../directory/protect.php"); ?></pre>
<li>Page protect functions:
Protect pages have access to a number of PHP functions used to display the persons name, username or logout URL.
<br>You use them in the page like this:
<pre>>?php function_name(); ?></pre>
See example.php for a protected file that uses all the functions.
<ul>
<li>print_name();
<br>Print users name, ie: "David Broker".
<li>print_username();
<br>Prints the username, ie: "david"
<li>print_logout_url();
<br>Prints the URL to logout.
<br>Example usage: <pre><a href="<?php print_logout_url(); ?>">Click here to logout</a></pre>
<li>print_first_page_url();
<br>Prints the URL of the page the user first sees when they login.
</ul>
</ul>
<li><i>Logging On/Off</i>
<ul>To login simply open login.php in your browser and enter the
username and password that you created in the Administration section.
<li>If sucessful you will be brought to the firstpage that was specifed in the configuration.
<li>If unsucessful an appropriate error message will be shown.
<li>To logout you need to have a page which call the print_logout_url() function, as shown above.
</ul>
</ul>
</ol>
<h2><a name="changelog">ChangeLog</a></h2>
<ul>
<li><i>26-01-02 V1.0.0b</i>
<ul>
<li>Fixed small session destroy bug.
<li>Removed accidental > at the end of conf.php
</ul>
<li><i>27-11-01 V1.0.0</i>
<ul>
<li>Initial Release.
<li>A user authentication system.
<li>Logon script starts/ends session.
<li>Protection script gets that session and shows page, or shows unauth message.
<li>Admin script for user admin/log viewing.
<li>Text file database. MD5 passwords.
</ul>
</ul>
<h2><a name="todo">To Do</a></h2>
<ul>
<li>User change own password.
<li>More admin options (edit user).
<li>Lost password options.
<li>More information stored on user.
<li>Email confirmation of registration.
<li>Online register requests.
<li>DB Support
</ul>
</body>
</html>