//                AbleLogger - Visitor Tracking and Stats
//
//       Author:  Dan Kaplan
//        Email:  dan@abledesign.com
//     Web Site:  http://AbleDesign.com
//  Description:  A PHP/MySQL program to provide a simple way to follow user
//                visitation patterns throughout your site.
//       Version: 1.00
// Last Modified: 11/27/03
//
// COPYRIGHT NOTICE:
//
// Copyright 2003 AbleDesign.  All Rights Reserved.
//
// This program is distributed freely and carries no guarantees.   It may be
// modified but not redistributed, so long as this copyright notice and the
// header above remain intact.  By using this program you agree to
// indemnify AbleDesign from any liability.

Thank you for choosing AbleLogger.  AbleLogger is a PHP4/MySQL program which provides a streamlined interface for logging visits to your website and tracking visitation patterns or specific users.

AbleLogger is not intended to be an all-encompassing stats package, rather a tracking tool to provide the level of useful analysis missing in many full-scale stats packages.  AbleLogger is best used in conjunction with a full featured stats package that displays things like page views and bandwidth by month, top referers, browser stats, most popular pages, error pages, etc.


Contents of this distribution (one hyphen represents a directory, four hyphens represent a file):

 - AbleLogger
 ---- log.php - the file that does the logging of page views
 ---- view_stats.php - your administrative file for tracking visitation patterns
 ---- readme.txt - This file; documentation.  Please print this file as a reference or keep it close at hand when installing AbleLogger.

 - includes
 ---- dbConnect.inc - Configuration file for connecting to MySQL



Table of Contents:

  I.  Requirements
 II.  Database Creation
III.  Setup
 IV.  Features
  V.  Use and Customization
 VI.  Contact Information (Help)
VII.  Change History
VIII. Trouble Shooting

=================
I. Requirements:

1) PHP4 - http://www.php.net/
2) MySQL - http://www.mysql.com/
3) FTP access to your web server (for installation)
   For help with FTP:  http://www.aota.net/FTP/index.php3

If your web host does not provide PHP4 and MySQL, AbleDesign offers web hosting for your entire site or remote hosting of your AbleLogger installation.  Please visit http://AbleDesign.com/services/hosting.php for details.

Recommended: (4 may be replaced by 4a or 4b below)
4) Telnet access to your web server (for issuing certain MySQL commands)
   For help with telnet:  http://www.aota.net/Telnet/index.php3

Recommended:
4a) MySQLMan - http://www.gossamer-threads.com/scripts/mysqlman/
4b) or phpMyAdmin - http://www.htmlwizard.net/projects/phpMyAdmin/
(MySQLMan is Perl based, phpMyAdmin is PHP based - both serve the same purpose)
Very powerful and free tools to assist in the administration of your MySQL database(s).  This will provide a graphical interface and eliminate the need to do installation/setup work from the command line (telnet) environment.


=================
II. Database Creation:

Either via MySQLMan or phpMyAdmin (strongly recommended method), or from the command line (telnet -- you will need to log into the MySQL server if it resides on a different server than your site, contact your web host for instructions), begin by creating the AbleLogger table in the desired database.

Recommended Method:  Through MySQLMan or phpMyAdmin, Copy the CREATE TABLE command below into the SQL query window:

CREATE TABLE AbleLogger (
  ID int(10) unsigned NOT NULL auto_increment,
  IP varchar(15) default NULL,
  Referer varchar(255) default NULL,
  Timestamp int(10) unsigned NOT NULL default '0',
  DateFlag date default '0000-00-00',
  User_Agent varchar(75) default NULL,
  FileName varchar(255) default NULL,
  PRIMARY KEY  (ID),
  KEY ip_index (IP),
  KEY date_index (DateFlag)
) TYPE=MyISAM;

	Note 1:  With MySQLMan, once you have logged in, you will need to click on the database you wish to access in the body of the page, then "SQL Monitor" in the Database toolbar at the top.  The CREATE TABLE commands below will be entered in the "Run SQL query/queries" textbox.  Press "Go" after you copy them in.  They may be submitted one at a time or all together.

	Note 2:  With phpMyAdmin, you will be taken to the "Run SQL query/queries on database ____" input box as soon as you select a database.  Enter the commands in this input area and press "Go".

It is recommended that you do not change the names of the tables (i.e. 'Downloads' and 'Users'), although you may do so if you wish (such as if you must install AbleLogger in the same database as another program which uses the same table names).  Be sure to also change the corresponding $table_name variables in log.php and view_stats.php to reflect your new table names.


=================
III. Setup:

Via ftp or telnet (your choice), create a new directories on your web server, preferably above root level (so that it is not viewable from the web; it will contain sensitive password information, so you want it to be separate from the actual program in case there is an error and program code is echoed to the web browser) and call it:

	includes

You may change the name of this directory, just be sure to set the paths to dbConnect.inc appropriately in log.php and view_stats.php.  Open dbConnect.inc and change HOSTNAME, USERNAME, and PASSWORD to the correct settings for your MySQL login.  This is what connects the PHP script to the MySQL database.  Finally, upload dbConnect.inc to the 'includes' directory.

The following variables should also be set in log.php and view_stats.php before beginning.  The variables not mentioned in this section are optional and are discussed in Part V Customization.

Change the following line to reflect the full path to the dbConnect.inc file, as specified above:
	include("/path/to/includes/dbConnect.inc");

Replace name_of_your_db with the name of the database your AbleLogger table is in.  If your server does not work with the database name prefixed to the table name, you can comment out the second of the three lines.  If you wish to name the AbleLogger table something other than "AbleLogger," change the table name in the third of the three lines:
	$db_name = "name_of_your_db";	// name of the database
	$table_name = $db_name .".";	// table name, with the database name optionally prefixed
	$table_name .= "AbleLogger";	// table name, with the database name optionally prefixed

Change this to reflect the number of hours your local time differs from the server time.  Negative if your time is earlier than server time, zero if they are the same, and unsigned (i.e. 2 for 2 hours ahead) if you are ahead of server time.
	$timezone_offset = -3;	// hours difference between server time and local time

In the Detailed view by IP address, you can change the max number of characters to show for the Referer string.  Doing so keeps the display from becoming overly crowded with long URLs.  The default is 45 characters (view_stats.php only):
	$referer_max = 45;	// max number of characters to display for referer string; anything extra will be "..."

Finally, upload log.php and view_stats.php wherever you want them on the server.  They do not need to be located in the same place.  It is recommended that you place view_stats.php in a secret location, unless you want people viewing your site stats!  You can rename it anything you want, so long as it is a *.php file.  It is also recommended that you .htaccess password protect the directory you place view_stats.php in.  If you are not familiar with .htaccess password protection, here is a tutorial:

	http://faq.web2010.com/htaccess.htm


=================
IV. Features:

Below are some features of AbleLogger:

- overview by day of IP Addresses, number of pages viewed, duration of visit (start and end time), and browser info
- detailed view by IP shows user agent, referer, day and time of each page view, time difference between page views, page visited, and browser info
- search by IP address


=================
V. Use and Customization:

Individual items in this section are denoted by opening and closing tags, << and >> respectively.

<<
Adding the Logging to your site:
To begin logging visitors, simply call log.php from any PHP page.

	include("/path/to/log.php");

Replace '/path/to' with your actual server path to the directory you installed log.php in.
>>


<<
Avoiding multiple database connection attempts:
If you are calling AbleLogger (log.php) on a page already containing a database connection, you may not need to use AbleLogger's database call.  To eliminate the second connection to the database, use the $mysql_connected option in the file calling log.php, i.e.:

	$mysql_connected = TRUE;
	include("/path/to/log.php");

That will tell it to skip the database connection in log.php.
>>


<<
Backing up your database:
If you wish to make periodic backups of your database (it's debatable how long you want to keep visitation data around), please take a look at Backup DB, our point and click MySQL backup and restore utility:

	http://abledesign.com/programs/BackupDB/
>>


=================
VI. Contact Information:

  Author: Dan Kaplan
   Email: design@abledesign.com
Web Site: http://AbleDesign.com

Installation, customization, MySQL/PHP site hosting, and general web design help is available.  Please visit http://AbleDesign.com for details.

Online support is provided at:  http://AbleDesign.com/forum/


=================
VII. Change History:

11/19/03 - Version 1.00 released


=================
VIII. Trouble Shooting:


<<
Interference between AbleLogger and another database-accessing script on the page being logged:

If the page calling log.php also connects to MySQL for other uses and is connecting a database different from the one AbleLogger is in, you will have interference between the two scripts.  The solution is to prefix all table names in your database queries with the database name.  For example, let's day AbleLogger's table is installed in db_2 and is being called by a PHP script who's database is in db_1.  The queries in that script should be of the form:

	SELECT * FROM db_1.mytable WHERE ...
>>
