Chatr Readme

Chatr is a simple, easy-to-install chatroom for your site. Using PHP and Javascript to create an AJAX/PHP chatroom with minimal server requirements.

Since Chatr is relatively simple, it's quite easy to extend or develop into what you need. You can get started by cloning or forking our gihub repository. If you fix a bug or add a feature you think would be good to have in Chatr, please fork the github project, commit your changes, and create a pull request.


1. Upload the files to your server in a new folder.

2. Make this folder writable by the webserver user.

3. Open install.php in your browser, fill in each of the fields, and click submit.

4. Congratulations, your installation should now work. You may want to change permissions to remove write capability to all but the. txt files. Now, you may login to your new chatroom!

Configuration Options

Config.php is created by running containing the following parameters:

$email_addr - If this is set to anything other than none, Chatr will send an email whenever someone enters the chat room.

$admin and $admin_num - these are id numbers that the chat client sends your server to signify they are the admin user. During installation a 4 digit number is generated that is used for the first part of each of these fields and to give the text files somewhat random names. To increase security you can make these more random.

$maxlines - this is how many lines of text will be displayed in the buffer window. When a user enters the room they'll be able to see this amount of history in the chat room. All users see the same amount of text in the main chat area. If you set this to a large number, you'll increase the amount of bandwidth that your Chatr will use. This is because this whole file is sent every 2 seconds or so.

$timeout - after this many seconds of not receiving a ping, a user will be timed out. It's as close as we can get to having a user leave short of requiring them to click a button to exit. You probably don't want to change this value though if you're looking for a more aggressive logout, you could set it to something between 31 and 59 seconds(the client pings every 30 seconds by default).

The rest of the parameters are fairly self-explanatory. If you want to increase the security of your Chatr installation you could specify more complicated filenames for the pings, buffer and users files. Chatr creates these files if they do not exist so renaming them right in config.php is a perfectly fine thing to do.


If it still doesn't work after submitting the form in install.php, check that the config.php was created. If config.php doesn't exist, make sure your webserver has write access to chatr's folder.

This chat is designed to be simple above all else and not to hammer your web server too hard. Therefore don't expect it to be irc or AIM or something more than what it is.

The Scripts

buffertext.php - if called with a valid user this script returns the latest chat text that should be displayed in the main chat window.
chat.php - presents the user interface after login.php has been called by a submit on index.php
config.php - contains some of the configurable parameters for your installation
index.php - the introductory page with the login form, a submit here redirects to login.php to validate the input and start the chat session
install.php - presents some installation questions and posts to install2.php
install2.php - checks the input from install.php and creates config.php(requires write permissions).
login.php - validates the username and checks the password if the username is a variation on the admin username
ping.php - updates a users entry in the pings text file to keep them logged in
posttext.php - processes user input during chat so they can say something in the chat room
status.php - runs timeout.php and returns the number of users in the chat room. Include into another page on your site for best effect.
timeout.php - checks the pings file and users file for timed out users. Removes timed out users from the users file.
userlist.php - returns the list of active users to be displayed by the chat client


Version 0.7 - 10/8/2006

Version 0.6 - 10/7/2006

Version 0.5 - 1/12/2006

Version 0.4 - 12/31/2005

Version 0.3 - 12/23/2005

Version 0.2 - 12/22/2005

One user had a bug in their installation after editing the chat.php file. Their edited version had multiple paragraph tags with the same id(i.e. stats, charcount). This is known to cause Internet Explorer users to time out 90 seconds after joining at least with IE versions 6.00.2800 and 6.00.2600.