Tag Archives: Documentation

JAXL library – List of available hooks for various XMPP events

Jaxl 2.x provides an event mechanism using which developers can register callbacks for various xmpp events inside their application code. This blog post will demonstrate how to register callbacks for required xmpp events and go through a list of all available hooks. Finally, we will discuss parameters that are passed to called back methods by Jaxl core.

Registering callback on XMPP events
Applications can register callback for various XMPP events. Jaxl core will then callback application methods (with 2 parameters) every time associated XMPP event occurs. Shown below are some sample examples for registering callbacks.

When application callback’d method is a function:

function postAuth($payload, $jaxl) {

}
$jaxl->addPlugin('jaxl_post_auth', 'postAuth');

When application callback’d method is a public static method of a class:

class MyXMPPApp {
    public static function postAuth($payload, $jaxl) {

    }
}
$jaxl->addPlugin('jaxl_post_auth', array('MyXMPPApp', 'postAuth'));

When application callback’d method is a public method inside a class:

class MyXMPPApp {
    function postAuth($payload, $jaxl) {

    }
}
$MyXMPPApp = new MyXMPPApp();
$jaxl->addPlugin('jaxl_post_auth', array($MyXMPPApp, 'postAuth'));

In all the above examples jaxl_post_auth is one of the available hook for registering callbacks.

List of available hooks
Below is a complete list of available hooks in order of their occurrence within a Jaxl instance life cycle:

Hooks for events related to instance connection and authentication steps in various modes:

  • jaxl_post_connect
  • jaxl_get_auth_mech
  • jaxl_get_facebook_key
  • jaxl_post_auth_failure
  • jaxl_post_auth
  • jaxl_post_handshake
  • jaxl_pre_shutdown
  • jaxl_post_disconnect
  • jaxl_get_empty_body

Hooks for events related to XMPP stream and stanza’s:

  • jaxl_get_stream_error
  • jaxl_get_presence
  • jaxl_get_message
  • jaxl_get_iq_get
  • jaxl_get_iq_set
  • jaxl_get_iq_error
  • jaxl_send_message
  • jaxl_send_presence

Hooks for events related to reading/writing of XMPP packets and internal packet routing:

  • jaxl_get_xml
  • jaxl_send_xml
  • jaxl_send_body
  • jaxl_pre_handler
  • jaxl_post_handler

TO-DO: Update when every hook is called inside your application life cycle and list of parameters passed for each callback. As of now you can var_dump($payload); inside your callback method.

How to write External Jabber Components in PHP using Jaxl library?

Jabber Component Protocol (XEP-0114) documents how XMPP protocol can be used to communicate between servers and “external” components over the Jabber network. XMPP components “bind” to a domain, usually a sub-domain of the main XMPP service, such as service.example.org.

All incoming stanzas addressed to that domain (to='service.example.org') or to entities on that domain (to='user@service.example.org') will be routed to your Jaxl (Jabber XMPP Library) based code. In this blog post, I will demonstrate a sample external jabber component bot written in PHP using Jaxl library.

Refer Jaxl Installation, Usage guide and Example apps if you are new to Jaxl. Demonstrated component bot code can be obtained from Jaxl@github.

Using Jabber Component Protocol
Include Jaxl implementation of XEP-0114 in your application code to setup necessary environment for using Jabber component protocol. Here is how this can be done at the top of your application code:

        // Initialize Jaxl Library
        $jaxl = new JAXL(array(
                'component' => JAXL_COMPONENT_HOST,
                'port' => JAXL_COMPONENT_PORT
        ));

        // Include required XEP's
        jaxl_require('JAXL0114', $jaxl); // Jabber Component Protocol

Register callback for XMPP events
Above we have setup the necessary environment for writing external Jabber component bots. Next we register callback for necessary XMPP events inside our componentbot class.

        // Sample Component class
        class componentbot {

        }

        // Add callbacks on various event handlers
        $componentbot = new componentbot();
        JAXLPlugin::add('jaxl_pre_handshake', array($componentbot, 'doAuth'));
        JAXLPlugin::add('jaxl_post_handshake', array($componentbot, 'postAuth'));
        JAXLPlugin::add('jaxl_get_message', array($componentbot, 'getMessage'));

Component bot class
Finally, lets complete the missing pieces inside componentbot class.

        // Sample Component class
        class componentbot {

                function doAuth() {
                        $jaxl->log("Going for component handshake ...", 1);
                        return JAXL_COMPONENT_PASS;
                }

                function postAuth() {
                        $jaxl->log("Component handshake completed ...", 1);
                }

                function getMessage($payloads) {
                        global $jaxl;

                        // echo back
                        foreach($payloads as $payload) {
                                $jaxl->sendMessage($payload['from'], $payload['body'], $payload['to']);
                        }
                }

        }

Configure, Setup and Run
If you have a local “ejabberd” installed, add following lines inside ejabberd.cfg to make example component bot to work:

  {5559, ejabberd_service, [
                          {host, "component.localhost", [{password, "pass"}]}
                           ]},

Update jaxl.ini if you choose to have different password, port or host name above:

        // Connecting jabber server details
        define('JAXL_HOST_NAME', 'localhost');
        define('JAXL_HOST_DOMAIN', 'localhost');

        // Component bot setting
        define('JAXL_COMPONENT_HOST', 'component.'.JAXL_HOST_DOMAIN);
        define('JAXL_COMPONENT_PASS', 'pass');
        define('JAXL_COMPONENT_PORT', 5559);

Finally, run from command line:

root@ubuntu:~/usr/share/php/jaxl/app/componentbot# jaxl componentbot.php
[15008] 2010-08-24 01:40:03 - Socket opened to the jabber host localhost:5559 ...

Tail jaxl.log for details:

[15008] 2010-08-24 01:40:04 - Going for component handshake ...

[15008] 2010-08-24 01:40:04 - [[XMPPSend]] 63
<handshake>4d6c2e762d5ba5dca2cbd3a90a4deeb6a6fa0838</handshake>

[15008] 2010-08-24 01:40:05 - [[XMPPGet]]
<handshake/>

[15008] 2010-08-24 01:40:05 - Component handshake completed ...

Log into your Ejabberd with a client and send a message to anything@component.localhost – You should receive an instant response back – congratulations!

XEP 0045 – Multi User Chat (MUC) available methods in Jaxl 2.0

Jaxl 2.0.3 (Jabber XMPP Library in PHP) comes with 15 XMPP extensions including XEP-0045 a.k.a. Multi-User Chat (Conference Room). In this blog post, we will go through all the methods available for XMPP applications developed using Jaxl library.

Using MUC methods
You need to include Jaxl implementation of XEP-0045 in your application code to start using the methods listed below. Refer Jaxl Installation, Usage guide and Example apps if you are new to Jaxl. Here is how this can be done at the top of your application code:

// initialize Jaxl instance
$jaxl = new JAXL();

// include MUC XEP
jaxl_require('JAXL0045', $jaxl); // or simply $jaxl->requires('JAXL0045');

Multi-User Chat available methods:
Below is a detailed list of methods from multi-user room extension:

  • $jaxl->JAXL0045(‘joinRoom’, $jid, $roomJid.”/”.$nick, $history=0, $type=’seconds’)
  • $jaxl->JAXL0045(‘exitRoom’, $jid, $roomJid)
  • $jaxl->JAXL0045(‘kickOccupant’, $fromJid, $nick, $roomJid, $reason=FALSE, $callback=FALSE)
  • $jaxl->JAXL0045(‘getRoomConfig’, $jid, $roomJid, $callback=FALSE)
  • $jaxl->JAXL0045(‘setRoomConfig’, $jid, $roomJid, $fields, $callback=FALSE)
  • $jaxl->JAXL0045(‘grantOwnerPrivileges’, $fromJid, $toJid, $roomJid, $reason=FALSE, $callback=FALSE)
  • $jaxl->JAXL0045(‘revokeOwnerPrivileges’, $fromJid, $toJid, $roomJid, $reason=FALSE, $callback=FALSE)
  • $jaxl->JAXL0045(‘grantAdminPrivileges’, $fromJid, $toJid, $roomJid, $reason=FALSE, $callback=FALSE)
  • $jaxl->JAXL0045(‘removeAdminPrivileges’, $fromJid, $toJid, $roomJid, $reason=FALSE, $callback=FALSE)

All parameters are mandatory to be passed while calling the above available methods. To be continued as more method gets added like banUser, destroyRoom, etc.

PHP Code, Setup and Demo of Jaxl boshchat application

Jaxl 2.0 bosh support allow web developers to write real time web applications within minutes, without having any pre-requisite knowledge about the XMPP protocol itself. In this blog post, I will walk you through setup and demo of an XMPP based web chat application using Jaxl library.

Get the code
Follow the following steps to download and install this sample web application on your systems:

  • Clone the development branch of Jaxl library
    root@ubuntu:~/git# git clone git@github.com:abhinavsingh/JAXL.git
    root@ubuntu:~/git# cd JAXL/
    root@ubuntu:~/git/JAXL#

    If you are not familiar with git, simply visit JAXL@github, click Download Source and extract under ~/git/JAXL directory on your system

  • Once inside Jaxl source directory, build the latest development package
    root@ubuntu:~/git/JAXL# ./build.sh
    building...
  • Install Jaxl library (view installation detail and options)
    root@ubuntu:~/git/JAXL# ./build.sh install
    uninstalling old package...
    installing...

Setup web chat application
Jaxl library is default installed under /usr/share/php/jaxl folder. Application code for our web chat application can be found under /usr/share/php/jaxl/app/boshchat folder.

Follow these steps to setup web chat application on your system:

  • I assume you have http://localhost/ configured on your local web server and it runs out of /var/www folder. Create following symlinks:
    root@ubuntu:~/git/JAXL# cd /var/www
    root@ubuntu:/var/www# ln -s /usr/share/php/jaxl/app/boshchat/boshchat.php index.php
    root@ubuntu:/var/www# ln -s /usr/share/php/jaxl/app/boshchat/jaxl.ini jaxl.ini
    root@ubuntu:/var/www# ln -s /usr/share/php/jaxl/env/jaxl.js jaxl.js
    root@ubuntu:/var/www# ln -s /usr/bin/jaxl jaxl.php

    Edit/Remove #!/usr/bin/env php inside jaxl.php if it causes any problem on your system.

  • Open and edit jaxl.ini
    define('JAXL_BOSH_COOKIE_DOMAIN', false);
  • I assume you have access to XMPP over Bosh enabled jabber server. Ejabberd users can verify this by hitting http://localhost:5280/http-bind in the browser
  • Open and edit index.php
    define('BOSHCHAT_ADMIN_JID', 'admin@localhost');

    All messages sent using this web chat application will be routed to BOSHCHAT_ADMIN_JID

Ready for the demo
To run this example web chat application, visit http://localhost in your browser window. Enter a username/password already registered on your jabber server and press connect.

Login as BOSHCHAT_ADMIN_JID using a desktop client, so that you can receive messages sent from the browser on your desktop client.

Below is a screenshot when I logged in as “abhinavsingh” from browser and BOSHCHAT_ADMIN_JID was set to “jaxl@jaxl.im”:

Facebook chat connect with X-FACEBOOK-PLATFORM using Jaxl 2.0

Facebook chat provides two authentication mechanisms for authenticating chat client users. DIGEST-MD5 require chat client users to enter their username and password, while X-FACEBOOK-PLATFORM can be used to provide better user experience by using simple Facebook Platform authentication. In this blog post, I will demonstrate how to use Jaxl library for X-FACEBOOK-PLATFORM authentication.

Echobot using X-FACEBOOK-PLATFORM
Setup Jaxl library on your system and edit packaged sample echobot application with facebook user account details. Alternately you can also specify connecting user details inside jaxl.ini configuration file.

        $jaxl = new JAXL(array(
                'user'=>'fbUsername',
                'pass'=>'', // Not required, we will use user session key instead
                'host'=>'chat.facebook.com',
                'domain'=>'chat.facebook.com'
        ));

Add callback for hook jaxl_get_facebook_key:

JAXLPlugin::add('jaxl_get_facebook_key', array($echobot, 'getFacebookKey'));

Complete getFacebookKey method inside echobot application, which should return back following key information:

function getFacebookKey() {
                        return array(
                                '', // Your application secret key
                                '', // Your application api key
                                '' // Connecting user session key
                        );
                }

Update doAuth method to use X-FACEBOOK-PLATFORM auth mechanism:

                function doAuth($mechanism) {
                        global $jaxl;
                        $jaxl->auth("X-FACEBOOK-PLATFORM");
                }

Finally, run echobot from command line:

root@ubuntu:/usr/share/php/jaxl/app/echobot# jaxl echobot.php
[1942] 2010-08-08 05:35:10 - Socket opened to the jabber host chat.facebook.com:5222 ...
[1942] 2010-08-08 05:35:11 - Performing Auth type: X-FACEBOOK-PLATFORM
[1942] 2010-08-08 05:35:26 - Auth completed...

XEP 0133 – Service Administration available methods in Jaxl 2.0

Jaxl 2.0 implements more than 10 XMPP extensions including XEP-0133 a.k.a. Service Administration. In this blog post, we will go through all the methods available for use in XMPP applications developed using Jaxl.

Using Service administration methods
You need to include Jaxl implementation of XEP-0133 in your application code to start using below listed available methods. Here is how this can be done at the top of your application code:

// initialize jaxl instance
$jaxl = new JAXL();

// include service administration
$jaxl->requires('JAXL0133'); // or jaxl_require('JAXL0133', $jaxl);

Service administration available methods
Below is a detailed list of methods from service administration extension:

  • $jaxl->JAXL0133(‘addUser’, $user, $domain, $callback)
  • $jaxl->JAXL0133(‘deleteUser’, $user, $domain, $callback)
  • $jaxl->JAXL0133(‘disableUser’, $user, $domain, $callback)
  • $jaxl->JAXL0133(‘reEnableUser’, $user, $domain, $callback)
  • $jaxl->JAXL0133(‘endUserSession’, $user, $domain, $callback)
  • $jaxl->JAXL0133(‘getUserPassword’, $user, $domain, $callback)
  • $jaxl->JAXL0133(‘changeUserPassword’, $user, $domain, $callback)
  • $jaxl->JAXL0133(‘getUserRoster’, $user, $domain, $callback)
  • $jaxl->JAXL0133(‘getUserLastLoginTime’, $user, $domain, $callback)
  • $jaxl->JAXL0133(‘getUserStatistics’, $user, $domain, $callback)
  • $jaxl->JAXL0133(‘editBlacklist’, $user, $domain, $callback)
  • $jaxl->JAXL0133(‘editWhitelist’, $user, $domain, $callback)
  • $jaxl->JAXL0133(‘getUserCount’, $user, $domain, $callback, $type)
  • $jaxl->JAXL0133(‘getUserList’, $user, $domain, $callback, $type)
  • $jaxl->JAXL0133(‘sendAnnouncementToActiveUsers’, $user, $domain, $callback)
  • $jaxl->JAXL0133(‘setMOTD’, $user, $domain, $callback)
  • $jaxl->JAXL0133(‘editMOTD’, $user, $domain, $callback)
  • $jaxl->JAXL0133(‘deleteMOTD’, $user, $domain, $callback)
  • $jaxl->JAXL0133(‘setWelcomeMessage’, $user, $domain, $callback)
  • $jaxl->JAXL0133(‘deleteWelcomeMessage’, $user, $domain, $callback)
  • $jaxl->JAXL0133(‘editAdminList’, $user, $domain, $callback)
  • $jaxl->JAXL0133(‘restartService’, $user, $domain, $callback)
  • $jaxl->JAXL0133(‘shutdownService’, $user, $domain, $callback)

Examples
All the methods expects 3 parameters as defined below:

  • $user: An associative array containing information about the user on whose account service administrative actions need to be taken
  • $domain: Jabber domain to which $user belongs
  • $callback: Specify where do you want to receive success/failure of executed service administration command
  • $type: Required by getUserCount and getUserList methods. Allowed values are registered, disabled, online, active and idle.

$user array MUST correspond to the fields in the request form for executing service administration commands.

Here is how to add a new user using XEP-0133:

$user = array(
        'jid' => 'newuser',
        'pass' => 'password',
        'email' => 'newuser@email.com',
        'fname' => 'Hello',
        'lname' => 'World'
);

$jaxl->JAXL0133('addUser', $user, 'jaxl.im', array($this, 'postAddUser'));

Your application code must have a methods named ‘postAddUser’ which will be called back by Jaxl core, when it finishes executing the command.

Jaxl 2.0 Core classes, available methods and directory structure

In this blog post we will dig deep into the core of Jaxl 2.0 – An XMPP framework written in PHP. Specifically, we will go through Jaxl core directory structure. Towards the end we will get familiar with various core classes and their available methods (e.g. $jaxl->sendMessage()), that developers can use in their XMPP applications.

Core Directory Structure
Now that you have the source code, lets get familiar with the Jaxl directory structure. Downloaded source code consists of following 5 directories:

  • xmpp: Contain core stack which implements XMPP rfc’s. All files follow naming convention like xmpp.*.php
  • core: Contains core stack which manages the library workflow. Also provides an xpath based XML parser, an event mechanism and various other utilities to the framework. All files follow naming convention like jaxl.*.php
  • xep: Contains implemented XMPP extensions (XEP’s). All files follow naming convention like jaxl.XEP-NUMBER.php
  • env: Contains Jaxl main() file jaxl.php, Jaxl core configuration file jaxl.conf and application environment setup file jaxl.ini. For bosh application developers jaxl.js is a must include from this directory.
  • app: Contains example applications which comes packed with Jaxl library

Core Classes and Available Methods
Below is a detailed list of all the core classes and available methods in developer land space:

JAXL
This class is located inside core/jaxl.class.php and extends base XMPP class. Following is a list of methods available:

  • __construct($config=array()) : Constructor accepts following configuration parameters. Passed parameters will overwrite corresponding jaxl.ini values:
    $config = array(
        'user'=>'', // JAXL_USER_NAME
        'pass'=>'', // JAXL_USER_PASS
        'host'=>'', // JAXL_HOST_NAME
        'port'=>'', // JAXL_HOST_PORT
        'domain'=>'', // JAXL_HOST_DOMAIN
        'component'=>'', // JAXL_COMPONENT_HOST
        'logPath'=>'', // JAXL_LOG_PATH
        'logRotate'=>'', // false or second in which to rotate log
        'logLevel'=>'', // JAXL_LOG_LEVEL
        'pidPath'=>'', // JAXL_PID_PATH
        'boshHost'=>'', // JAXL_BOSH_HOST
        'boshPort'=>'', // JAXL_BOSH_PORT
        'boshSuffix'=>'', // JAXL_BOSH_SUFFIX
        'resource'=>'', // connecting user resource identifier
        'streamTimeout'=>'', // connecting stream timeout
        'sigh'=>'', // boolean to forcible enable/disable sigh term
        'dumpStat'=>'', // false or numeric specifying second after which to dump stat
    );
  • auth($type) : Performs authentication with the jabber server. DIGEST-MD5, PLAIN, X-FACEBOOK-PLATFORM and ANONYMOUS are the supported auth $type
  • setStatus($status=FALSE, $show=FALSE, $priority=FALSE, $caps=FALSE) : Update the status of connected jabber user. Pass $caps=TRUE for sending entity capability information while setting connected user status.
  • subscribe($toJid)
  • subscribed($toJid)
  • unsubscribe($toJid)
  • unsubscribed($toJid)
  • getRosterList($callback=FALSE) : Fetch roster list for the connected user. See example usage inside echobot application.
  • addRoster($jid, $group, $name=FALSE)
  • updateRoster($jid, $group, $name=FALSE, $subscription=FALSE)
  • deleteRoster($jid)
  • sendMessage($to, $message, $from=FALSE, $type=’chat’)
  • sendMessages($to, $from, $child, $type)
  • sendPresence($to, $from, $child, $type)
  • $jaxl->requires($class) : It is an alternative for jaxl_require($class, $jaxl).
  • $jaxl->xml->xmlize($xml) : Use this method to convert raw XML string into an array.
  • $jaxl->log($log, $level) : Use this method for logging purposes

JAXLPlugin
This class is located inside core/jaxl.plugin.php. Following is a list of methods available:

  • add($hook, $callback, $priority=10) : Register callback on available hooks
  • remove($hook, $callback) : Un-register callback on a previously registered hooks using add method

JAXLCron
This class is located inside core/jaxl.cron.php. Use this call methods to run periodic background jobs. Following is a list of methods available:

  • add($callback, $interval) : $callback methods is called every $interval second
  • delete($callback, $interval) : Removes a previously registered cron job

JAXLUtil
This class is located inside core/jaxl.util.php. Following is a list of methods available:

  • isWin() : Window OS detection, return bool
  • getTime()
  • getBareJid($jid)
  • splitJid($jid)
  • curl($url, $type=’GET’, $headers=FALSE, $data=FALSE, $user=FALSE, $pass=FALSE)

More methods might get added in future and will be updated here.

Using available XEP methods
Once have included required XEP class inside your application code, either by using jaxl_require('JAXLxxxx', $jaxl) or by calling $jaxl->requires('JAXLxxxx'), you can start using the available methods inside included XEP class as follows:

$jaxl->JAXLxxxx('methodName', $param1, $param2, ....);

e.g. If you want to call joinRoom methods of Multi-User Chat XEP-0045, you can do so by calling

$jaxl->JAXL0045('joinRoom', $jid, $roomJid.'/'.$nick, $history, $seconds)

. DO-NOT call the method like JAXL0045::joinRoom(…)