PHP121 Instant Messenger (PHP121) is a free instant messenger for any website that has PHP and MySQL support. Users only require an internet browser that supports JavaScript and allows pop-ups. Flash and Java applets are not used.

1.1. Getting the Latest Release

The latest version of PHP121 is always made available to supporters first (see Supporting PHP121), then released to the public when a newer version is released. In other words, the current public release is always one version behind that of the supporter’s release.

To download PHP121, go to http://www.php121.com/download.php

1.2. Supporting Development of PHP121

Please refer to Supporting PHP121.

1.3. License

PHP121 is released free of charge, under the GPL license. For full license information, please refer to the COPYING file which is in the docs directory of the release.

1.4. Web Site

You can download the latest version, make a donation, or get help or discuss PHP121 in the forums at the PHP121 website: http://www.php121.com

2. Installing PHP121

PHP121 can be installed as a standalone service, which means it is not integrated into any other script. It can also be integrated into existing websites with ease. The default install is standalone and is the one that should be used unless you have a script that is listed in any of the other installation headings.

2.1. Requirements

In order to use PHP121, make sure your system or host meets the following requirements:

A Linux or Windows Box installed and working properly.
Apache Web Server (http://www.apache.org)
PHP version 4.2.x or better (mod_php) Apache module (http://www.php.net)
MySQL database server 4.0 or better (http://www.mysql.com)

Setup of these required packages is beyond the scope of this document and if you are unsure you should check with each of the appropriate web sites for further details.

2.2. Installing PHP121 as a standalone service (using PHP121’s user tables)

This section gives instructions on how to install PHP121 as a standalone service which will use PHP121’s user tables. This means that PHP121 will be completely separate from any other features on your website. Your users will be required to register again, even if they are registered on another part of your site.

NOTE: If you already have a user table, you may want to try Installing PHP121 as an Integrated Service (other) instead, which will allow PHP121 to use your existing user tables and remove the need for users to re-register.

1) Decompress: Untar/unzip the package

2) Move: Copy the contents (including the subdirectories) of php121/ to the desired directory on your web server (e.g. /home/paul/www/php121/)

3) Set up database: Import the contents of sql/php121.sql into your MySQL database. PHPMyAdmin is recommended, but you can also 'source' it using the MySQL console.

4) Edit configuration: Copy php121config.php-STANDALONE to php121config.php, replacing the existing file. Edit php121config.php and change all the variables to match your database configuration.

If you don't know any of these settings, contact your hosting provider or support department.

5) Set up linking page: On the page you want to link to PHP121, put this in the <HEAD> section:

var newwindow;

function poptastic(url){

newwindow=window.open(url,'name','height=500,width=200,left=20,top=20,toolbar=no,menubar=no,directories=no,location=no,scrollbars=yes,status=no,resizable=yes,fullscreen=no');

if (window.focus) {newwindow.focus()}

}

</script>

6) Create link: Create the link to PHP121 on your site. View php121index.php in a text editor to see an example of how to link to PHP121.

Use code similar to the following to create a nice contact-list sized window:

<a href="javascript:poptastic('php121im.php');">Instant Messenger</a>

7) Delete sample index: Delete php121index.php in the php121 directory as this is just a sample to show you how to link to php121 from your site.

8) Create OWNER account: Create a user account by browsing to the page with the PHP121 link and click on it. The first user to sign up will be given OWNER privileges.

- OWNERs can give users ADMIN privileges.
- ADMINs cannot edit or delete OWNERs and they cannot give ADMIN privileges to other users.
- In the "Who's online" section, OWNERs are red, ADMINs are green, and USERs are blue.

9) Supporting PHP121: Go to http://www.php121.com/donate.php to donate what you think is a fair amount for PHP121. Commercial programs that do the same thing retail for $99 or more!

10) Finished: Install complete.

If you get stuck, confused, or don't even know how to start installing PHP121, please go to http://forums.php121.com and ask your question in one of the forums.

2.3. Installing PHP121 as a PHPNuke Integrated Service

This section gives instructions on how to install PHP121 as a PHPNuke integrated service. This means that PHP121 will:

use PHPNuke’s user table so users do not need to re-register.
use PHPNuke’s sessions, so users do not need to login again.
disable its account management functions (create / delete account, etc) as these will be handled by PHPNuke.
have a link in the modules block on the PHPNuke homepage
show user status in the “User Info” block. A red man will appear for offline chat status, and a green man will appear for online chat status.

1) Decompress: Untar/unzip the package

2) Move: Copy the contents (including the subdirectories) of php121/ to the top level PHPNuke directory on your web server (e.g. /home/paul/www/ ), NOT to a subdirectory (like /home/paul/www/modules/)

3) Set up database: Import the contents of sql/php121-nuke.sql into your MySQL database. PHPMyAdmin is recommended, but you can also 'source' it using the MySQL console.

4) Edit configuration: Copy php121config.php-PHPNUKE to php121config.php, replacing the existing file. Edit php121config.php and change all the variables to match your database configuration.

If you don't know any of these settings, contact your hosting provider or support department.

5) Set up blocks: Go into the Administration area of PHPNuke (admin.php) and then the BLOCKS page. Make sure that block-User_Info is activated. If it isn't in the list, then add it using the form. The filename you want is User Info. You can leave everything else blank. Now that you have the User Info block, you probably don't need the Who's online block. You can disable this block.

6) Edit Javascript: Edit includes/javascript.php and add the following at the bottom of the file, before the "?>" :

echo "<script type=\"text/javascript\">\n";

echo "<!--\n";

echo "var newwindow;\n";

echo "function poptastic(url){\n";

echo

"newwindow=window.open(url,'name','height=400,width=200,left=20,top=20,toolbar=no,menubar=no,directories=no,location=no,scrollbars=no,status=no,resizable=yes,fullscreen=no');\n";

echo "if (window.focus) {newwindow.focus()}\n";

echo "}\n";

echo "//-->\n";

echo "</SCRIPT>\n\n";

7) Now it's time to integrate it into PHPNuke. I have included 2 blocks - block-Modules.php and block-User_Info.php in the integration/phpnuke directory of the release. The Modules block simply contains a link to PHP121 at the top of the modules list. The User Info block contains a link to PHP121 and icons beside each online user to show their messenger status. You have a choice: just to copy the provided blocks into your blocks directory, or edit your blocks yourself. The copy option is the easiest and won't break anything (but make a backup anyway!). The edit option is necessary if your files have been customised.

COPY OPTION:

8) Backup your blocks/block-Modules.php and blocks/block-User_Info.php files, or just rename them to block-Modules.php.orig and block-User_Info.php.orig

9) Copy the block files provided in this distribution to the blocks folder of your PHPNuke installation. You are then ready to use PHP121. Simply log into PHPNuke and you can load the Instant Messenger by clicking on the link in the User Info block or Modules block.

EDIT OPTION:

2 changes must be made to both the modules block and the user info block as follows:

BLOCK-MODULES.PHP Change 1 of 2:

Find:

global $prefix, $db, $admin;

Replace with:

global $prefix, $db, $admin, $user;

BLOCK-MODULES.PHP Change 2 of 2:

Find:

/* Now we make the Modules block with the correspondent links */

After, add:

//***PHP121***

if (is_user($user)){

$content .= "<strong><big>·</big></strong> <a href=\"javascript:poptastic('php121im.php');\">Instant Messenger</a><br>\n";

}

//***END PHP121***

BLOCK-USER_INFO.PHP Change 1 of 2:

Find (around line 38):

$result = $db->sql_query("SELECT uname, guest FROM $prefix"._session." WHERE guest='0'");

$member_online_num = $db->sql_numrows($result);

$who_online_now = "";

$i = 1;

while ($session = $db->sql_fetchrow($result)) {

if (isset($session["guest"]) and $session["guest"] == 0) {

if ($i < 10) {

$who_online_now .= "0$i: <A HREF=\"modules.php?name=Your_Account&op=userinfo&username=$session[uname]\">$session[uname]</a><br>\n";

} else {

$who_online_now .= "$i: <A HREF=\"modules.php?name=Your_Account&op=userinfo&username=$session[uname]\">$session[uname]</a><br>\n";

}

$who_online_now .= ($i != $member_online_num ? " " : "");

$i++;

}

Replace with:

//******PHP121******

$sql = "SELECT $prefix"._session.".uname, $prefix"._session.".guest, $user_prefix"._users.".user_id, $user_prefix"._users.".user_from, $user_prefix"._users.".user_chatting FROM $prefix"._session.", $user_prefix"._users." WHERE $prefix"._session.".guest=0 AND $prefix"._session.".uname = $user_prefix"._users.".username";

$result = $db->sql_query($sql);

$member_online_num = $db->sql_numrows($result);

$who_online_now = "";

$i = 1;

while ($session = $db->sql_fetchrow($result)) {

if (isset($session["guest"]) and $session["guest"] == 0) {

if ($i < 10) {

if ($session["user_chatting"]!=0 && $session["user_chatting"]!=NULL && (time()-$session["user_chatting"]) < 90 ) {

$who_online_now .= "0$i: <A HREF=\"modules.php?name=Forums&file=profile&mode=viewprofile&u=$session[user_id]\">".$session[uname]."</a>  <a href=\"#\" onClick=\"window.open('php121sendim.php?to=$session[user_id]','$session[user_id]','left=20,top=20,width=600,height=500,toolbar=0,resizeable=0');\"><img src=\"images/blocks/ur-registered.gif\" height=\"14\" width=\"17\" border=0></a><br>\n";

} else {

$who_online_now .= "0$i: <A HREF=\"modules.php?name=Forums&file=profile&mode=viewprofile&u=$session[user_id]\">".$session[uname]."</a>  <a href=\"modules.php?name=Private_Messages&file=index&mode=post&u=$session[user_id]\"><img src=\"images/blocks/ur-admin.gif\" height=\"14\" width=\"17\" border=0></a><br>";

}

} else {

if ($session["user_chatting"]!=0 && $session["user_chatting"]!=NULL && (date("U")-date("U",strtotime($session["user_chatting"])) < 90 )) {

$who_online_now .= "$i: <A HREF=\"modules.php?name=Forums&file=profile&mode=viewprofile&u=$session[user_id]\">".$session[uname]."</a>  <a href=\"#\" onClick=\"window.open('php121sendim.php?to=$session[user_id]','$session[user_id]','left=20,top=20,width=600,height=500,toolbar=0,resizeable=0');\"><img src=\"images/blocks/ur-registered.gif\" height=\"14\" width=\"17\" border=0></a><br>\n";

} else {

$who_online_now .= "$i: <A HREF=\"modules.php?name=Forums&file=profile&mode=viewprofile&u=$session[user_id]\">".$session[uname]."</a>  <a href=\"modules.php?name=Private_Messages&file=index&mode=post&u=$session[user_id]\"><img src=\"images/blocks/ur-admin.gif\" height=\"14\" width=\"17\" border=0></a><br>";

}

$who_online_now .= ($i != $member_online_num ? " " : "");

$i++;

}

//******END PHP121******

BLOCK-USER_INFO.PHP Change 2 of 2:

Find:

if (is_user($user)) {

$content .= "<br><img src=\"images/blocks/group-4.gif\" height=\"14\" width=\"17\"> "._BWEL.", <b>$uname</b>.<br>\n<hr>\n";

Replace with:

//***PHP121***

$content .= "<br><img src=\"images/blocks/group-4.gif\" height=\"14\" width=\"17\"> "._BWEL.", <b>$uname</b>.<br><A HREF=\"javascript:poptastic('php121im.php');\"> Show Instant Messenger</a><br>\n<hr>\n";

//***END PHP121***

10) Supporting PHP121: Go to http://www.php121.com/donate.php to donate what you think is a fair amount for PHP121. Commercial programs that do the same thing retail for $99 or more!

11) Finished: Install complete.

If you get stuck, confused, or don't even know how to start installing PHP121, please go to http://forums.php121.com and ask your question in one of the forums.

2.4. Installing PHP121 as an Integrated Service (other)

This section gives instructions on how to install PHP121 as a standalone service which will use your existing user tables. This means that PHP121 will:

use your existing user table so users do not need to re-register.
give you the option to disable its account management functions (create / delete account, etc) as these are probably handled by your website already.

1) Decompress: Untar/unzip the package

2) Move: Copy the contents (including the subdirectories) of php121/ to the desired directory on your web server (e.g. /home/paul/www/php121/)

3) Set up database: Import the contents of sql/php121.sql into your MySQL database. PHPMyAdmin is recommended, but you can also 'source' it using the MySQL console.

5) Set up linking page: On the page you want to link to PHP121, put this in the <HEAD> section:

var newwindow;

function poptastic(url){

newwindow=window.open(url,'name','height=500,width=200,left=20,top=20,toolbar=no,menubar=no,directories=no,location=no,scrollbars=yes,status=no,resizable=yes,fullscreen=no');

if (window.focus) {newwindow.focus()}

}

</script>

<a href="javascript:poptastic('php121im.php');">Instant Messenger</a>

7) Delete sample index: Delete php121index.php in the php121 directory as this is just a sample to show you how to link to php121 from your site.

8) Prepare your user table for PHP121: Edit sql/alter_existing_usertable.sql and change the name of the user table on the first line of code.

For example: Your user table is called "my_big_user_table", therefore you want to change:

ALTER TABLE `users` ADD `php_user_chatting` INT( 11 ) DEFAULT '0' NOT NULL ,

to:

ALTER TABLE `my_big_user_table` ADD `php_user_chatting` INT( 11 ) DEFAULT '0' NOT NULL ,

9) Import the contents of the new sql/alter_existing_usertable.sql into your MySQL database.

10) Decide which username to give OWNER privileges to. Edit this user's database record and change their php121_level to 3

11) Supporting PHP121: Go to http://www.php121.com/donate.php to donate what you think is a fair amount for PHP121. Commercial programs that do the same thing retail for $99 or more!

12) Finished: Install complete.

If you get stuck, confused, or don't even know how to start installing PHP121, please go to http://forums.php121.com and ask your question in one of the forums.

2.5. Upgrading PHP121

Upgrading PHP121 is not difficult, as long as you have a non-customized installation. If you have edited the PHP121 source code to add your own feature, you will need to re-add your feature after upgrading to the new version.

1) Update the database structure: New versions of PHP121 may need to update the database structure. If there is a database update required for the release, you will need to import the required SQL file(s) in the SQL directory.

The database update files are named in this way:
INSTALL_TYPE-dbupdate-VERSION_FROM-VERSION_TO.sql

If you are skipping one or more version releases in the upgrade (i.e. upgrading from 1.1 to 1.3), you need to import each database update in turn, e.g. 1.1 to 1.2, then 1.2 to 1.3.

For example, if upgrading from Standalone 1.3 to 1.4, we must import php121-dbupdate-1.3-1.4.sql using the MySQL console, or a web based interface such as PHPMyAdmin. If it was a PHPNuke integration update, the file would start with phpnuke-dbupdate.

Note: The updates will be for standard PHP121 installations that use the standard PHP121 tables. If you are using an existing user table, you will need to edit the update files and change the table names where required. Otherwise, the update will not complete successfully.

2) Backup php121config.php: The next stage will overwrite the php121config.php file, so you need to backup your existing configuration to be able to re-enter the correct values in the new configuration file. Copy it to a folder other than the php121 installation folder.

Note: You cannot simply copy the old configuration file into the updated installation directory. New releases are likely to have more options in the configuration file.

3) Update the php121 files: Copy the contents of the php121 directory within the new release folder to the location of your existing installation directory, overwriting all existing files.

4) Edit new php121config.php: Edit the new php121config.php file, using your backup for guidance on username, password, and database name.

Read the whole configuration file, as it is likely to be different to the one you upgraded from.

5) Read the release notes: For any extra steps that may or may not be required, look at the release notes with the new release, if there are any.

3. Tutorial

3.1. PHP121 as a Standalone Service

After installing PHP121, you will have an OWNER account created and ready to be used.

Go to the URL of the page you added the link to PHP121, or if you want to use the default link page, point your browser to the php121index.php file.

You will be prompted to log in. Log in with the OWNER account created in the Installation section.

3.1.1. Contact List

When logged in, you will see the main PHP121 screen – the contact list:

Figure 1 - The PHP121 Contact List

At the top of the contact list, the custom title is displayed that you set up in the configuration file.

Below the title, the “Updated:” line displays the time of the last refresh of the contact list. By default, this is every 10 seconds. Users can click on the hyperlinked “Updated:” text to force a refresh of the contact list.

The next line shows which user you are logged on as.

Below this, 3 options are displayed for administrators (2 for normal users):

Options – Allows the user to edit or delete their account. The edit screen displays user chat-related options, such as turning emoticons on/off, displaying timestamps in messages, etc.
Logout – Logs out the current user.
Admin (not visible to normal users) – Displays administration-related options, such as editing another user’s settings, deleting a user, or editing the system time zone or default language.

Refer to 3.1.2. Options screen and 3.1.3. Administration Options for more information.

The contact list has 3 main sections:

Current chats – displays the name of the person(s) you are currently talking to. A chat will appear here if at least one person is in the chat. This is useful if you get disconnected from the internet and have to reconnect, which may take time, and your friend is still online in the room waiting for you. In this case, you can just click on their name in the “Current Chats” list to display the chat room.
Recent chats – After a few seconds of both people leaving the chat room, it will be seen as a finished chat and will be moved to the “Recent Chats” list. This enables you to rejoin the chat for a while afterwards to view the contents of the chat again. After a longer period of time of not being viewed, it will be removed from the “Recent Chats” list.

Who’s Online – Shows the names of the users who are currently online. Users in red are administrators, those in green are moderators (like an administrator, but with less power), and those in blue are normal users.

3.1.1.1. Starting a Chat

To start a chat with someone, click on their username in the “Who’s Online” list. A request will be sent to them (Figure 2), with the option of accepting or denying your chat request. If accepted, the request window will turn into the chat room, and if denied, you will be informed. The request will also time out if the other user does not respond (i.e. they are away from the computer). You will also be informed if this is the case.

Figure 2 - An Incoming Chat Request

3.1.1.2. Blocking a User

Beside each user (except yourself), there is a “Block” option in the “Who’s Online” list. Click this to stop the user from contacting you. The block option will now become an “Unblock” option and show the user’s name in italics. Click the “Unblock” option to allow the user to contact you again.

Figure 3 - The "Who's Online" List with Block option

3.1.2. Options screen

Figure 4 - The PHP121 "Edit User" Options screen

Clicking “Options” on the Contact List will display the PHP121 options screen, which has user chat options, such as changing their password, and editing settings such as emoticons, beeping on new messages, bringing the chat window to the front on new messages, changing the time zone, showing timestamps in chats, and changing their language.

3.1.3. Administration Options

Figure 5 - Administration Menu

Clicking “Admin” on the Contact List will display the Administration options which shown in Figure 4.

Clicking “Edit PHP121 System Config” will show options to edit the System Options, such as time zone and default language.

The “Edit Users” option allows administrators to change users’ passwords, turn their emoticons on or off, ban them, and change their user level.

“Delete User” deletes a user, which is irreversible.

3.1.3.1. Emoticon Administration

PHP121 allows users to add emoticon PAKs which are PHPBB format. You can download extra PAKs from the PHP121 download page: http://www.php121.com/download.php

After downloading the file, extract the .pak file and emoticons to a directory under the php121smilies directory. E.g. phpsmilies/cutesmilies/

The directory name will be the name of your new emoticon pak.

Next, click on “Add Emoticons” in the administration menu, and input the name of the PAK file, relative to the php121smilies directory. E.g. cutesmilies/smilies.pak

Click on Add PAK.

Your new emoticons will now appear in the emoticons menu in the chat window.

3.1.4. The Chat Window

When a chat is accepted, both users will enter the chat room – as long as there are no pop-up blockers installed on either computer. If there are pop-up blockers, they will severely interfere with the functionality of PHP121.

The chat window will appear as shown in Figure 6.

Figure 6 - The Chat Window

The top frame is used for sending messages, and the bottom frame displays the chat messages with the most recent being at the top.

Clicking on the smiley face (emoticon) shown at the top right will display the available emoticons that can be used in chats. Clicking an emoticon in this list will send it to the send message text box automatically.

To send a message, type it into the text box and click on “Send”, or just press the Enter key on the keyboard.

The chat window will check for new messages when a new message is sent, or after every 5 seconds, whichever is sooner. If there are newer messages, the chat text will be updated.

Depending on options set in the Options screen, the look and behaviour of the chat window will differ. For example, in Figure 6 timestamps are enabled. Other features that can be turned on or off are described in 3.1.2. Options screen.

To leave a chat, simply close the current chat window.

Figure 7 - A Sample Chat

3.2. PHP121 as a PHPNuke Integrated Service

PHP121 operates almost identically when integrated into PHPNuke as it does as a standalone application.

This section will only describe the differences between the two. For a basic tutorial, refer to 3.1 - PHP121 as a Standalone Service.

This section will assume you are using the suggested settings in php121config.php of:

$integration = “phpnuke”
$acctman = 0
The correct database settings for using the PHPNuke user table (usually nuke_users)

All account management functions will be disabled. This means users cannot delete their accounts, and cannot create a login via PHP121.

PHP121 will use PHPNuke sessions, so the user does not need to login to PHP121 directly.

3.2.1. The User Info Block

It is recommended that you use the User Info block that is supplied with PHP121, as set out in the installation instructions.

When activated, this block will look similar to Figure 8.

Figure 8 - The User Info Block with PHP121 Integration

Icons appear next to each user. Red indicates that the user is logged into PHPNuke, but does not have the PHP121 Contact List open. Green indicates that they are logged into PHPNuke and have the PHP121 Contact List open and ready to receive chat requests.

To open the Contact List, click on the “Show Instant Messenger” link which is just below the “Welcome, (username)” line. Be sure not to have any pop-up blockers installed on your computer. A green icon will then appear next to your name (you will need to refresh the PHPNuke page to see this).

To send a message to another user, you can:

Without logging into PHP121, click on the green icon next to the person.
While logged into PHP121, either click on the green icon next to the person, OR
Click on the person’s name in the PHP121 “Who’s Online” list.

Clicking on a red icon will redirect you to the Private Messages page so you can send a normal private message.

To log out of PHP121, just close the PHP121 contact list. Your status will change to offline (red icon) after a few minutes.

3.3. PHP121 as an Integrated Service (other)

The operation of PHP121 when installed as an Integrated Service for any other application than PHPNuke is as described in 3.1 - PHP121 as a Standalone Service.

4. Supporting PHP121

PHP121 is released free of charge, under the GPL license, to allow everyone to make use of it and freely distribute it. However, the latest version is only available to supporters of PHP121, which is not allowed to be distributed.

Currently, there are 2 ways to become an official supporter of PHP121:

Donate $10 or more (whatever you think is a fair amount for the script)
Make a new language translation for PHP121 and contribute it to the next version of PHP121. If you would like to do this, please email me at paul@php121.com

To become a supporter of PHP121 by donating money, please go to http://www.php121.com/donate.php