phpChat 1.0b, Copyright (c) 1999 by Till Gerken, till@phpwebdev.com
-------------------------------------------------------------------

This software is distributed under the terms of the license contained in
phpChat_license.txt. If you cannot find this file, you have an unofficial
and thus illegal version of phpChat. Please delete it at once and get
a fresh archive from http://www.phpwizard.net/phpChat.

phpChat is NOT free, for commercial usage you need to purchase a commercial
license. Please contact till@phpwebdev.com for details.

For general notes about this software, please see README.

1. Notes about installation
---------------------------

Before installation, I encourage you to consider a few things.

phpChat, when serving a lot of clients, will launch a lot of resident HTTPD
processes, as each client will require at least one streaming connection.
HTTPDs which include PHP as a module take up about 1-2MB of RAM each, maybe
more, maybe less, but you can take this as generic requirement.

This means, if you are serving 100 clients simultaneously, phpChat might occupy
150MB of RAM. In case your server does not offer enough free memory, it will
start running each new client from swap - a situation which results in a quick
lockup of the server, requiring HTTPD shutdown or even server reboot.

This is not a problem special to phpChat but a general problem when serving
lots of clients simultaneously. Usually, HTTPD processes are only responsible
for delivering one page, a task which is finished in a time span of seconds or
even less, but chat servers extend this time span to minutes or even hours,
resulting in a totally different server load.

Make sure that your server is equipped well enough.

2. Requirements and server configuration
----------------------------------------

As you've seen in the previous section, it is crucial to have enough RAM and
processing power (RAM being the definitively most important resource though).

To ease server load, it is best to install PHP 4. At this time, PHP 4 beta 3
was working very well with phpChat. PHP 3 is ok, too, but requires much more
resources in terms of processing time - thus, when operating under high load,
seriously consider to install PHP 4. (Note: some betas of PHP 4 are not calling
shutdown functions and leave sessions unterminated - make sure you get a copy
which works on your system)

Moreover, phpChat supports interprocess communication via shared memory and
semaphores. Enabling support for these tremendously reduces load on the
database and overall resource usage, so if you have the possibility to compile
both modules into PHP, do it!

Furthermore, you need to have MySQL and an IRC server installed. Both don't
have to be installed locally, but you will need to have access to them.

As for the IRC server, the "original" Unix IRC 2.9.x or 2.10.x were working
very well during testing, but any other brand should be ok - phpIRC has been
successfully tested on different networks (and phpIRC is responsible of the
communication with the IRC network).

3. Installation steps
---------------------

Each of the following steps is independent from all other steps, so perform
them in any order you like - just make sure that you've got everything covered.

1. Download phpIRC and set it up (you can get it from
   http://www.phpwizard.net/phpIRC)
   Preferably it should be installed into the same directory as phpChat, on
   our test server we had the following directory structure:

   htdocs/
   htdocs/chat
   htdocs/chat/phpChat
   htdocs/chat/phpChat/templates
   htdocs/chat/phpIRC

2. Install an IRC server in case you plan to run a local server and set it up
3. Install and configure phpChat as described in the next section

4. Configuration of phpChat
---------------------------

Configuration of phpChat is straight forward and very simple. All configurable
options are contained in the file configuration.inc.php3.

In case you are using a MySQL database, take a look at phpChat.mysql, it
contains the required table structures. If you just run the script in the
database, you do not have to change any of the table names below.

To change the layout of phpChat, take a look in the templates directory.

Note: If you plan to run phpChat with shared memory support, please run
      the script contained in crshmem.php3 ONCE before using phpChat,
      otherwise phpChat will not work. The script in crshmem.php3 is a
      simple injector to create the required shared memory segments and
      semaphores. This code is also available in the login script, but is
      broken - thus this beta requires crshmem.php3 to be run once. After
      you've done so, you do not need this file again until your next
      server reboot.

$chat_phpIRC_path	-	This variable contains the path to phpIRC.
				Ideally, create a directory tree as described
				in the last section. Try to put a relative path
				here.

$chat_db_host		-	Hostname or IP of your database server
$chat_db_user		-	Username for the database
$chat_db_password	-	Password for the database

$chat_db_name		-	Name of database to use
$chat_db_msg_table	-	Table name for messages
$chat_db_nick_table	-	Table name for nick names
$chat_db_session_table	-	Table name for sessions

$chat_irc_server	-	Name or IP of IRC server to use
$chat_irc_port		-	Port to access the IRC server at

$chat_irc_channel	-	Default channel to join

$chat_sleep_time	-	Interval at which to check for new
				messages from a user, specified
				in milliseconds. The higher the
				number, the lower the CPU usage,
				but the longer is the response time

$chat_browser_keep_alive-	Number of seconds after which to
				"ping" the client's browser to
				avoid time outs

$chat_session_timeout	-	Number of seconds after which to
				delete idling sessions

$chat_shm_enabled	-	1 - use shared memory
				0 - don't use shared memory
				Shared memory usage is recommended!

$chat_shm_key		-	Key to use for shared memory, only
				needs changing if another application
				is using the same key

$chat_shm_size		-	Size of shared memory segment, increase
				if you have more sessions than available
				memory, decrease if you have fewer

$chat_shm_var		-	Variable key to use in shared memory.
				Only needs changing if another application
				is using the same key.

The following definitions contain the set of supported commands by the
interpreter. Changing is only required if you want special command strings
or a different command set.

The command prefix is the character each command has to be prefixed with to
be recognized by the parser (i.e., use "/kick joe" to kick "joe")

The default quit message is contained in $chat_default_quit_msg and is
displayed whenever a user leaves the chat and does not specify another quit
message. (by typing "/quit <message>")

The defined colors are used to colorize different types of messages.

The color translation table is used to display mIRC color codes which have
evolved to become a widely accepted standard. Only output of foreground colors
is supported so far.

Furthermore, phpChat passes each message through an array of functions which
may apply translations to the output. Additionally to the color transformation,
phpChat transforms all characters to display correctly in HTML using
htmlspecialchars() as well as another function which searches for URLs and
transforms them into HTML links.

You may specify additional functions of your choice in $chat_priv_msg_tranform.

The last section in the configuration file finally includes a module which
adds simple session functionality to PHP 3. Please note that the if() statement
to include the sessions won't work with PHP 5 anymore, but as this won't be
the case anytime soon, there's no need to worry about that yet. Just make
sure you'll get an upgrade if you plan to run phpChat that long.

5. Testing phpChat
------------------

To test phpChat, simply execute chat_login.php3 using your browser, i.e.

	http://www.yourhost.com/chat/phpChat/chat_login.php3

or similar. After entering you nick name, this should take you to the chat
screen.

In case it will print an error message that it can't access the database,
make sure all your database settings are correct.

In case it will tell you that it can't create a session, make sure that your
session tables are present and accessable, in a very rare occasion it might
also be that your browser tries to access an old cached session. A reload
should fix that situation.

Last but not least, a "connection error" indicates an error during connecting
to the IRC server. This might be because of your nick already being taken
(most likely) or your server being unreachable. In case you are trying to
connect to a public server, make sure that you are not k-lined and have proper
access rights.
