Install

To install phpFreeChat you need:

By default, you don't need a Mysql database because the system uses files to store messages and nicknames.

Quick start

Using the setup (the easy way): (not available for 1.0-betaX)

  1. Download the auto-extractible setup script: phpfreechat-x.x-setup.php (replace x.x by the lastest version)
  2. Upload the setup script on your server into a browsable directory (public directory)
  3. Browse the script with your personnal browser, it should launch a setup, then follow the steps !

    Tip: remove the setup when the install is finished for security reason.

Using the ziped archives (for those who haven't gzip module in their php):

  1. Download the zip (or tar.gz for linux users) archive: phpfreechat-x.x.zip (replace x.x by lastest version)
  2. Unzip the archive localy then upload the phpfreechat-x.x directory on your server into a browsable directory (public directory).

    Tip: if you have a SSH access, I suggest to untar the archives directly on the server usign tar xzf phpfreechat-x.x.tar.gz command.

  3. Give the write rights to phpfreechat-x.x/data/public and phpfreechat-x.x/data/private directories.

    If you are using FTP:

    CHMOD 777 phpfreechat-x.x/data/private
    CHMOD 777 phpfreechat-x.x/data/public

    If you are using SSH:

    chmod a+w phpfreechat-x.x/data/*
  4. Browse the phpfreechat-x.x directory with your browser and enjoy !

Now you need surely to customize your chat. You can take a look at the example scripts in the phpfreechat-x.x/demo directory.

Here is the minimum script required for your chat to work (inspired from demo1):

<?php

require_once "src/phpfreechat.class.php"; // adjust to your own path
$params["serverid"] = md5(__FILE__); // used to identify the chat
$chat = new phpFreeChat($params);

?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
       "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
  <head>
    <meta http-equiv="content-type" content="text/html; charset=utf-8" />
    <title>phpFreeChat demo</title>
    <?php $chat->printJavascript(); ?>
    <?php $chat->printStyle(); ?>
  </head>
  <body>
    <?php $chat->printChat(); ?>
  </body>
</html>

Advanced configuration

The chat is usable using the default configuration but a lot of options can be tweaked to customize the chat. For exemple, to change the refresh speed to 2 seconds, copy/paste this piece of code:

<?php

require_once "src/phpfreechat.class.php"; // adjust to your own path
$params["serverid"]      = md5(__FILE__);
$params["refresh_delay"] = 2000; // 2000ms = 2s
$chat = new phpFreeChat($params);

?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
       "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
  <head>
    <meta http-equiv="content-type" content="text/html; charset=utf-8" />
    <title>phpFreeChat demo</title>
    <?php $chat->printJavascript(); ?>
    <?php $chat->printStyle(); ?>
  </head>
  <body>
    <?php $chat->printChat(); ?>
  </body>
</html>

Another example, to set the initial nickname to "guest" (this can be useful when the chat is integrated into a portal or a forum which provides the login/password), copy/paste this piece of code:

<?php

require_once "src/phpfreechat.class.php"; // adjust to your own path
$params["serverid"] = md5(__FILE__);
$params["nick"]     = "guest"; // it can be useful to take nicks from a database
$chat = new phpFreeChat($params);

?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
       "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
  <head>
    <meta http-equiv="content-type" content="text/html; charset=utf-8" />
    <title>phpFreeChat demo</title>
    <?php $chat->printJavascript(); ?>
    <?php $chat->printStyle(); ?>
  </head>
  <body>
    <?php $chat->printChat(); ?>
  </body>
</html>

Thanks to these two example, you should understand how to pass parameters to the chat: $params["param-name"] = "param-value";

Now for the full parameters list (only for 0.x versions, wait for 1.0-final release for complete documentation):

serverid
This is the only mandatory parameter. It is the chat server id, "its IP" (comparable to the server host in IRC) used to identify the chat. Two chat must have different serverid. If you don't know what to write, just try : $params["serverid"] = md5(__FILE__);
nick
If you have already identified the user (forum, portal...) you can force the user's nickname here, this will skip the "Please enter your nickname" popup.
Warning : Nicknames must be encoded in UTF-8. For example, if you get nicks from a databases where they are ISO-8859-1 encoded, you must ocnvert it: $params["nick"] = iconv("ISO-8859-1", "UTF-8", $bdd_nickname); (of course, change the $bdd_nickname parameter for your needs)

("" value by default, means users must choose a nickname when s/he connect)

title
Used to change the chat title that is visible just above the messages list.

("My phpFreeChat" by default)

channel
Used to create a room. Technicaly this parameter is used to choose the data (messages + nicknames) storage destination. For a better explaination, see this FAQ entry.

(auto-generated string based on the title parameter by default)

frozen_nick
Setting this to true will forbid the user to change his/her nickname later.

(false value by default)

max_nick_len
This is the maximum nickname length, a longer nickname is forbidden.

( 15 caracteres by default)

max_text_len
This is the maximum message length, a longer message is forbidden.

( 250 characters by default)

refresh_delay
This is the time to wait between two refreshes. A refresh is a HTTP request which asks the server if there are new messages to display. If there are no new messages, then a empty HTTP response is returned.

( 5000 by default, 5000ms = 5s)

timeout
This is the time of inactivity to wait before to considere to disconnecte user (in milliseconds). A user is inactive only if he closed his chat windows. A user with a open chat window is not inactive because he sends each refresh_delay a HTTP request.

( 20000 by default, 20000ms = 20s)

max_msg
This is the message history length. When a user connects, he can see the history. The number of messages s/he can see is defined by this

(20 lines by default)

quit_on_closedwindow
Setting this to true will send a /quit command when the user close his window (doesn't work on Firefox). This parameter isn't true by default because on IE and Konqueror/Safari, reloading the window (F5) will generate the same event as closing the window which can be annoying.

(false value by default)

focus_on_connect
Setting this to true will give the focus to the input text box when connecting to the chat. It can be usefull not touch the focus when integrating the chat into an existing website because when the focus is changed, the viewport follows the focus location.

(true value by default)

connect_at_startup
Setting this to false will oblige user to click on the connect button if s/he wants to chat.

(true value by default, means when the chat web page is open, a connection to the chat is automaticaly performed)

start_minimized
Setting it to true will start the chat minimized.

(false value by default)

height
Height of the chat area.

("440px" by default)

width
Width of the chat area.

("" by default, means it's given by the CSS)

shownotice
Setting this to 0 will show nothing. Setting it to 1 will show nicknames changes. Setting it to 2 will show connect/disconnect notifications. Setting it to 3 (1+2) will show nicknames and connect/disconnect notifications.

(3 by default)

nickmarker
Setting it to false will disable nickname colorization.

(true value by default)

clock
Setting it to false will hide the date/hour column.

(true value by default)

openlinknewwindow
Setting it to true will add the target="_blank" into parsed links. This attribute is used to open the followed link in a new window.

(true value by default)

showwhosonline
Used to show/hide online users at startup.

(true value by default)

showsmileys
Used to show/hide the smiley list at startup.

(true value by default)

btn_sh_whosonline
Used to display or not the showwhosonline button.

(true value by default)

btn_sh_smileys
Used to display or not the showsmileys button.

(true value by default)

themeurl
Used to specify the theme root url (useful for url rewriting)

(this parameter is automaticaly calculated by default)

themepath
The absolute theme directory path. Sub directories must contains themes directories.

(dirname(__FILE__)."/../themes" by default)

theme
This parameter specifies which theme this chat will use.

("default" by default)

language
Used to specify the chat labels language. Accepted values are i18n/* sub directories names.

(by default this is the local server language)

output_encoding
Useful to set a sepcific encoding for chat labels. This is really useful when the Web page embedding the chat is not UTF-8 encoded. This parameter should be the same as the chat web page.

(UTF-8 by default )

container_type
Used to specify the used container. For the moment, only a file container has been written but in the future several containers (mysql, irc, msn, jabber...) will surely be available.

("File" by default)

server_script_path and server_script_url
Used to specify the script which will handle asynchronous request. Very useful when the chat (client) script is resource consuming (ex: forum or portal chat integration). server_script_url must point to the server script browable url (useful when using url rewriting).

(by default these parameters are auto-calculated)

client_script_path and client_script_url
Used to specify the script path which display the chat and load every JavaScript libraries (the client side). Useful when the php configuration is uncommon, this option can be used to force the automatic detection process. client_script_url must point to the client script browable url (useful when using url rewriting).

(by default these parameters are auto-detected)

useie7
Setting this to false will disable IE7 scripts used to improve display for the crappy Internet Explorer.

(true value by default)

ie7path
Specify the IE7 path. It's useful if you allready have a IE7 library installed and you want to save bytes on your server.

(dirname(__FILE__)."/../lib/IE7_X_X" by default)

jspath
Specify the javascript libraries path (md5, cookie ...).

(dirname(__FILE__)."/../lib/javascript" by default)

usecsstidy
Setting this to false will disable CSSTidy library, css optimisation (output size) will be disabled.

(false value by default because it make problems on strange server configurations)

csstidypath
Specify the CSS Tidy library path. It's useful if you allready have a Smarty library installed and you want to save bytes on your server.

(dirname(__FILE__)."/../lib/csstidy-X.X" by default)

xajaxpath
Specify the xajax path. It's useful if you allready have a xajax library installed and you want to save bytes on your server.

(dirname(__FILE__)."/../lib/xajax_X.X" by default);

data_private_path
Used by the filesystem container to store chat data. Used by smarty to store compiled templates. Tip: you can optimize your chat performances, see this FAQ entry. (dirname(__FILE__)."/../data/private" by default)
data_public_path and data_public_url
This path must be reachable by your web server. IE7 scripts and xajax JS compiled scripts will be stored here. data_public_url parameter can be specified to help when url rewriting is used. (dirname(__FILE__)."/../data/public" by default)
debug
For developers, setting it to true will activate logging and debuging console.

(false value by default)

debugxajax
For developers, setting it to true will activate xajax js popup used to trace communication between client and server during ajax requests. Useful to discover hidden bugs like php warnings on a ajax request.

(false value by default)

prefix
Used to prefix all javascript functions, css ids and css class in order to avoid variables overlaps.

("pfc_" by default)