Alexey Zakhlestin's Blog

Programming for Mac and Web

Work With TwitterData in PHP


I recently created a small library for working with twitterdata in PHP. Sources are available from GitHub: php-twitterdata

Here’s the description from Twitter Data site:

Twitter Data is a simple, open, semi-structured format for embedding machine-readable, yet human-friendly, data in Twitter messages. This data can then be transmitted, received, and interpreted in real time by powerful new kinds of applications built on the Twitter platform. Here is an example Twitter Data message:

I love the #twitterdata proposal! $vote +1

The part with the dollar sign, $vote +1, is a piece of data embedded using the Twitter Data format.

To use php-twitterdata library, download it into the sub-direcory in your project’s directory (or any other place you like) and init the autoloader:

require ‘php-twitterdata/autoload.php’;

PHP API provided by php-twitterdata has 2 layers. On lower level, there are 3 classes: TwitterData_Message, TwitterData_Frame and TwitterData_Tuple which correspond to parts of data-enabled twitter-message. Message can consist of several Frames, Frame can consist of several Tuples and a “subject”. Objects of each of these classes can be created programmatically and combined in hierarchy. Each of them has “magic” __toString() method, so, to export them as a valid twitter-message, you just need to put objects in string context. Something like this:

$tuple = new TwitterData_Tuple(‘foo’, ‘bar’);
$frame = new TwitterData_Frame(‘Hello, world!’, array($tuple));
echo $frame;

and the result will be: Hello, world! $foo bar

If you need to parse Twitter Data messages you should use TwitterData_Parser class. It is a SAX-style parser, with DOM-style export. If all you need is a hierarchy of objects, use it like this:

$parser = new TwitterData_Parser($text_from_twitter);
$message = $parser->export(); // $message is object of TwitterData_Message class

Otherwise, you can specify another handler-class as a second parameter of constructor. Such class has to implement TwitterData_Parser_CallbackInterface.

Does it all sound too complex? No problem!

php-twitterdata library also includes high-level interface, which consists of 2 simple functions: TwitterData::array_to_TwitterData() and TwitterData::TwitterData_to_array(). First one converts associative array into the string, which can be inserted into twitter-message, and second one takes message-string received from twitter and returns associative array parsed out of tuples from the first frame of message (If you need to get all possible data from message, you will still need to use low-level API).

Example of high-level API:

TwitterData::TwitterData_to_array(‘Hello, world! $foo bar’);
// array(‘foo’ => ‘bar’);

$message = ‘Hello, world! ‘.TwitterData::array_to_TwitterData(array(‘foo’ => ‘bar’));
// Hello, world! $foo bar

Library has unit-tests, which cover all examples provided on Twitter Data site both on Introduction page and on Examples page and is licensed under MIT-style license.