Get lyrics for any song using XMPP and PHP right into your IM – Add [email protected]

XMPP is soon finding it’s way into real time applications other than just chat. I have combined JAXL (Jabber XMPP client library written in PHP) and the API from lyricsfly.com to build a real time chat bot which can assist you with lyrics for any song. You can start using it by simply adding [email protected] to your IM account (e.g. Gtalk, Jabber etc). In this blog post, I will explain in brief the working of lyricsfly bot and how you can integrate XMPP into your own application.

Try out [email protected]
Follow the following steps to get the bot working for you:

  • Login to your gtalk account using any of the IM available
  • Press Add Contact
  • Add [email protected] as your chat buddy
  • Send a chat message in following format “Song Title – Song Artist” e.g. “one – metallica”
  • You should see something like this: lyricsfly@gtalkbots.com Demo for "one-metallica"

Working of [email protected] with Jaxl
Here is in brief the working of lyricsfly bot using Jaxl client library:

  • When someone sends a message like “one – metallica” to the bot, eventMessage() method is called inside jaxl.class.php
  • eventMessage then extracts the song title and artist name from the message using PHP explode. Filter the title and artist names for allowed characters.
  • eventMessage also calls lyricsfly API and fetch the lyrics. Finally it sends the lyrics as message to requester.
  • eventMessage also uses memcached to cache the lyrics. It decreases both response time and load on lyricsfly servers
  • Bot also keeps a count of number of queries from a particular user. Since it is still under development, currently there is a limit on number of lyrics you can fetch in a single day.

Making your own custom bot

  • Checkout latest from the trunk
    sabhinav$ svn checkout http://jaxl.googlecode.com/svn/trunk/ jaxl-read-only
  • Edit config file with your bot username, password and jabber servers
  • Run from command like
    php index.php
  • To customize the bot modify eventMessage and eventPresence methods of Jaxl class inside jaxl.class.php

For a full fledged running bot example code, edit index.php and include jaxl4dzone.class.php instead of jaxl.class.php and re-run the bot.

Have fun and enjoy singing songs along with the lyrics.

How to use JAXL (Jabber XMPP Library in PHP) to import Gtalk contacts of any user

JAXL is an open source Jabber XMPP Client library written in PHP. It provides a self titled class JAXL which implements XMPP protocol. It can be extended to write custom event handler for every message or presence received. Developers are using JAXL for developing real time applications. Checkout 5 exciting gaming bots you can make using JAXL.

However one thing which goes un-noticed is that JAXL can also be used to import Gtalk contacts of any user. This is infact one of the very first thing which JAXL class do, after successful authentication with the Gtalk servers i.e. import the authenticated user contact list. In this blog post I will demo a sample script to import any user contact list from google servers.

Importing Gtalk contacts using JAXL

  1. Download and extract jaxl-1.0.4.rar
  2. Edit config.ini.php and update credentials of the user whose contact list we are trying to import:
      $key = array("prod"=>array("user"=>"mailsforabhinav",
                                 "pass"=>"xxxxxx",
                                 "host"=>"talk.google.com",
                                 "port"=>5222,
                                 "domain"=>"gmail.com"
                                ),
    
  3. Open jaxl.class.php and modify the code as below:
        function setStatus() {
          // Set a custom status or use $this->status
          $this->sendStatus($this->status);
          print "Setting Status...n";
          print_r($this->rosterlist); // Print the contact list on the console
          print "Donen";
          exit;
        }
    
  4. Finally run from command line to retrieve gtalk contacts of the authenticated user.
    php index.php

One can easily modify the above code to save user contacts in a database.
Also one can echo json_encode($this->rosterlist) in response to an Ajax call from the browser.

Enjoy and leave your comments.

Programatically control your google mails using JAXL v 1.0.4

Google has released an API for almost all of their products including maps, feedburner and gadgets. However one of the API’s which every developer would have loved to make use of is “Google Mail API” which is still missing (available for premium google apps user only). Here in this post I would demonstrate how one can programatically control his/her google mails using JAXL without being a premium user of google mail account.

For those who have landed on this post straight and have little knowledge about what JAXL is “JAXL stands for Jabber XMPP Library and for fun you may call it Just Another XMPP Library. It is written in PHP and can be downloaded from http://code.google.com/p/jaxl“. To know more about JAXL, read the introductory post here. If you want to dig deep and know how JAXL works, read the gtalk case study here. Finally, after reading this post you may also want to check how you can fetch any social networking feed right into your gtalk messenger using JAXL.

Version 1.0.4 of JAXL included support for “Gmail Notification Extension of XMPP“. If you are a daily Gtalk user like me, then you have surely seen this extension in action. Just recall Gtalk notifying you of a new mail in your inbox, through a pop-up in the bottom right corner. Also those who see this in action everyday will agree with me that this notification comes even before the mail has actually appeared in you inbox. Simply because of the PUSH technology used by XMPP protocol.

So why would you in first place be interested in accessing your google mails programatically. A quick thought on this brings me to the following real life scenarios:

  • Suppose your are out of vacation and you want to set a custom auto-reply message for your family and friends, while you want to set a general out-of-office message for your colleagues. The limitation in gmail is that you can’t really do this. Further in this post, I will show you how can you achieve this using JAXL.
  • Suppose you are a google app user and your company has organized an online programming contest. Further you want to mail each question to the contestants only if they has answered the previous question. JAXL provide you a way to access key information about your incoming mails like: sender email id, subject, number of threads in the mail, time at which mail was sent, mail url and mail snippet. Which is enough for you to code a bot which can check for incoming mail and then send in next question to the contestant who sent this mail
    1. Further there can be a thousand use cases where you would you like to have such a control over you google mails but before discussing them, lets see a demonstration on how can we use JAXL to achieve this.

      Sending Custom Auto-Reply Mails using JAXL
      Along with extendable functions like eventMessage() and eventPresence(), JAXL’s latest version now also provide another extendable function called eventNewEMail(). So everytime you receive a new mail(s) in your google account, the control is passed to this function along with all informations about the incoming mails.

      Various data passed to this function are:

      • $total: Tells you about total number of unread mails.
      • $thread: The thread id of all the unread threads. Note: In Gmail you have threads in your inbox which can contain more than a single mail.
      • $url: The mail.google.com url for the new mail
      • $participation: This can be 0, 1 or 2. 0 indicates that you have not participated, 1 indicates that you are one of the many recipients and 2 indicates that you are the sole recipient for messages in this thread
      • $message: The number of messages in the thread. For instance you can have more than one unread mail in a thread.
      • $date: A timestamp of the most recent unread message, in milliseconds since the UNIX epoch
      • $senders: Email Id of all the senders in the current thread
      • $labels: Label if any to which this mail thread belongs to
      • $subject: The subject of the mail threads
      • $snippet: The mail snippet of the incoming mail

      So thats a lot of information really, with which we can automate things to a certain extent. Lets see how I use it to send custom auto-reply mails when I am out on vacation. Here is the extendable jaxl class for gmail:

      jaxl4gmail.class.php (Download)

        /* Include PHP Mailer Class */
        include_once("class.phpmailer.php");
      
        /* Include XMPP Class */
        include_once("xmpp.class.php");
      
        class JAXL extends XMPP {
      
          /* Define custom mail groups */
          var $family = array("[email protected]","[email protected]");
          var $colleague = array("[email protected]","[email protected]");
      
          /* Define custom mail subject and message */
          var $familySubject = "Hi, Will get back to you";
          var $familyMessage = "Hey, I am currently out on vacation at my grannies house in Delhi. I will return back home by next monday.
      Reach out to me at +91-987654321.

      With Love,
      Abhinav Singh"; /* Define custom mail subject and message */ var $colleagueSubject = "[Auto-Reply] Out of Office"; var $colleagueMessage = "Hi, I am on vacation in my village with very limited access to internet and phone. I will return back home by next monday.

      Regards,
      Abhinav Singh"; function eventMessage($fromJid, $content, $offline = FALSE) { } function eventPresence($fromJid, $status, $photo) { } function eventNewEMail($total,$thread,$url,$participation,$messages,$date,$senders,$labels,$subject,$snippet) { // We only want to send auto-reply message to latest sender $sender = $senders[0]; // Check if the user lie in any category, and send appropriate mail if(in_array($sender["address"],$this->family)) { $mail = new PHPMailer(); $mail->From = "[email protected]"; $mail->FromName = "Your Name"; $mail->Subject = $this->familySubject; $mail->MsgHTML($this->familyMessage."

      Powered by Jaxl http://code.google.com/p/jaxl"); $mail->IsHTML(true); $mail->AddAddress($sender["address"],$sender["name"]); if(!$mail->Send()) $this->logger->logger("Error occured while sending mail to ".$sender["address"]); else $this->logger->logger("Mail sent successfully to ".$sender["address"]); } else if(in_array($sender["address"],$this->colleague)) { $mail = new PHPMailer(); $mail->From = "[email protected]"; $mail->FromName = "Your Name"; $mail->Subject = $this->colleagueSubject; $mail->MsgHTML($this->colleagueMessage."

      Powered by Jaxl http://code.google.com/p/jaxl"); $mail->IsHTML(true); $mail->AddAddress($sender["address"],$sender["name"]); if(!$mail->Send()) $this->logger->logger("Error occured while sending mail to ".$sender["address"]); else $this->logger->logger("Mail sent successfully to ".$sender["address"]); } else { // Do nothing, will handle later on $this->logger->logger("No handler for this email id..."); } } function setStatus() { print "Setting Status...n"; $this->sendStatus("Available"); print "Requesting new mails...n"; $this->getNewEMail(); print "Donen"; } }

      The only variables you would like to change in above class are:

      1. $family : An array of email id of your family member
      2. $colleague : An array of email id of your colleagues
      3. $familySubject : Subject with which you want to send mails to your family members
      4. $familyMessage : Mail message which you want to send to you family
      5. $colleagueSubject : Subject with which you want to send mails to your colleagues
      6. $colleagueMessage : Mail message which you want to send to you colleagues

      For further customization, you may want to add more groups and their respective subjects and messages.

      Further you may want to create your own custom bots using JAXL for one of the other use case described above. Join official JAXL Google Group for future updates and enhancements.

      Do let me know if you build any custom bot using JAXL, I will be more than happy to list your bot on official JAXL google code page.

      Enjoy!

Introducing JAXL – Open Source Jabber XMPP Library

Introduction

JAXL stands for “Jabber XMPP Library“. For fun, it stands for “Just Another XMPP Library

This library currently supports following features:

  • Connect to a Jabber Server (e.g. Gtalk)
  • TLS Encryption
  • DIGEST-MD5 and PLAIN authentication mechanisms
  • Roster Support

Library comes with the following class files:

  1. config.ini.php : Holds your jabber account and mysql connection information
  2. mysql.class.php : Basic MySQL connection class used to insert received messages and presence into MySQL database
  3. logger.class.php : A very basic logger class which allows you to log all XML stanza’s send and received from jabber server
  4. xmpp.class.php : Base XMPP class library which implements the XMPP protocol
  5. jaxl.class.php : JAXL class which extends XMPP class library. Should be the starting point for your application.
  6. index.php : After building your application in jaxl.class.php, you finally initializa and call your methods here

Source Code
JAXL is hosted at Google Code. Checkout full source code from here:
http://code.google.com/p/jaxl

Google Groups
jaxl
Visit this group

How to use JAXL:
JAXL Client Library is highly structured. There is a base XMPP class library (xmpp.class.php) and a JAXL class library (jaxl.class.php) which is derived from the base XMPP class library.

Base XMPP class library implements the XMPP protocol and it also provides you with two extendable methods named eventMessage() and eventPresence(). These methods are internally called when a message or presence XML Stanza is received from the Jabber server.

Jaxl.class.php must be the starting point for all your applications. Simply customize the eventMessage() and eventPresence() Method for your application. Other methods which might interest you while customizing them are:

  1. sendMessage($jid,$message) : For sending message to a particular Jid
  2. sendStatus() : To set your status message
  3. roster(‘get’) : To get list of roster
  4. roster(‘add’,$jid) : Add a new contact in roster list
  5. roster(‘remove’,$jid) : Remove a contact from roster list
  6. roster(‘update’,$jid,$name,$groups) : Update a particular contact in roster
  7. subscribe($jid) : Subscribe for presence of a particular $jid

This library includes the following files:

Config File (config.ini.php)
You specify all your jabber account username and password in this file. For development environment keep $env = “devel” and for production simply change it to $env = “prod”

  // Set an enviornment
  $env = "prod";

  // Log Level for logger class
  $logEnable = TRUE;

  // Log in MySQL database
  $logDB = FALSE;

  $key = array("prod"=>array("user"=>"myproductionuser",
                             "pass"=>"password",
                             "host"=>"talk.google.com",
                             "port"=>5222,
                             "domain"=>"gmail.com"
                            ),
              "devel"=>array("user"=>"mydevelopmentuser",
                             "pass"=>"password",
                             "host"=>"localhost",
                             "port"=>5222,
                             "domain"=>"localhost"
                            )
              );

  $db = array("prod"=>array("dbuser"=>"root",
                            "dbpass"=>"password",
                            "dbhost"=>"localhost",
                            "dbname"=>"jaxl"
                           ),
             "devel"=>array("dbuser"=>"root",
                            "dbpass"=>"password",
                            "dbhost"=>"localhost",
                            "dbname"=>"jaxl"
                           )
             );


MySQL Class (mysql.class.php)
This is a basic MySQL connection class used to insert received messages and presence into MySQL database

Base XMPP Class (xmpp.class.php)
You should not worry about this class. Until and unless you are aware of what are you trying to achieve you should not touch this class file.

Logger Class (logger.class.php)
This is a basic logger class. It help you log XML send to and received from jabber server. Might prove helpful in debugging and if you are interested in learning the core of XMPP Protocol.

Extended JAXL Class (jaxl.class.php)
You will be customizing eventMessage() and eventPresence() methods here.

    function eventMessage($fromJid, $content, $offline = FALSE) {
      if($offline) {
        $this->sendMessage($fromJid,"Hi, Thanks for your offline message");
      }
      else {
        $this->sendMessage($fromJid,"Hi, Thanks for your message");
      }

      if($this->logDB) {
        // Save the message in the database
        $timestamp = date('Y-m-d H:i:s');
        $query = "INSERT INTO message (FromJid,Message,Timestamp) value ('$fromJid','$content','$timestamp')";
        $this->mysql->setData($query);
      }
    }

    function eventPresence($fromJid, $status, $photo) {
      // Change your status message to your friend's status
      $this->sendStatus($status);

      if($this->logDB) {
        // Save the presence in the database
        $timestamp = date('Y-m-d H:i:s');
        $query = "INSERT INTO presence (FromJid,Status,Timestamp) value ('$fromJid','$status','$timestamp')";
        $this->mysql->setData($query);
      }
    }

In above example I have done 4 things:

  • Sends back a message saying “Hi, Thanks for your offline message”, when I receive a offliner.
  • Sends back a message saying “Hi, Thanks for your message”, when I receive an IM from my friend.
  • Change my status message, as and when I receive a status update from my friends.
  • Save messages and presence into database if $logDB = TRUE in config.ini.php

Final Call (index.php)

  /* Include Key file */
  include_once("config.ini.php");

  /* Include JAXL Class */
  include_once("jaxl.class.php");

  /* Create an instance of XMPP Class */
  $jaxl = new JAXL($key[$env]['host'],    // Jabber Server Hostname
                   $key[$env]['port'],    // Jabber Server Port
                   $key[$env]['user'],    // Jabber User
                   $key[$env]['pass'],    // Jabber Password
                   $key[$env]['domain'],  // Jabber Domain
                   $db[$env]['dbhost'],   // MySQL DB Host
                   $db[$env]['dbname'],   // MySQL DB Name
                   $db[$env]['dbuser'],   // MySQL DB User
                   $db[$env]['dbpass'],   // MySQL DB Pass
                   $logEnable,            // Enable Logging
                   $logDB                 // Enable MySQL Inserts
                  );

  try {
    /* Initiate the connection */
    $jaxl->connect();

    /* Communicate with Jabber Server */
    while($jaxl->isConnected) {
      $jaxl->getXML();
    }
  }
  catch(Exception $e) {
    die($e->getMessage());
  }

Instant Messenger Powered by JAXL
I am pleased to announce 3 months after release of JAXL, 1st Instant Messenger powered by JAXL. Currently the instant messenger is in testing phase and will be released after some 3-4 weeks of thorough testing. Meanwhile here is the first clip shot:

Disclaimer
Currently this library is being developed and used at Gtalkbots.com . Though it is thoroughly tested and being used, I still recommend not to use it on production servers. Mainly, since it is heavily customized for Gtalkbot’s usage. I am releasing it, as I see it of use for the community worldwide. If you want to use it, use at your own risk. Let me know of any changes you make to this library. In future I look to make this library more generic.

Enjoy and let me know of any bugs, feedbacks, enhancements or any abuse you may want to pass through if it doesn’t work for you 😛

You should be running index.php using command line and not browser (recommended). This class is currently highly customized for Gtalkbots usage and works perfectly with Gtalk Servers.