Arc90 Twitter API Service Part 1

Twitter is all the rage these days; everyone’s on it and everyone seems to love it. Not me, of course. Like most social networking tools and services I find the whole thing pretty stupid.

Twitter

And, again, I’m apparently wrong because I’ve done some digging into manipulating the Twitter API so I can use it on my client’s sites.

There are a few different libraries available for accessing the API, in all the popular programming languages, but the one I chose was the PHP Twitter API Client. Unlike all the other php libraries available this one has sick documentation. We’re talking full phpdocumentor documentation; pure geak porn here.

I wanted to document the client but it’s a really, REALLY, exhaustive codeset so I’m going to break it up into 2 different posts.

The Basics

The Arc90 API client requires the entire library be in the php include path so you’ll have to either modify the php.ini directly or use ini_set to include the library. Kinda sucks, but whatever.

The client can also return the response in a few different data formats: XML, JSON and sometimes even RSS and ATOM depending on how you call the API and whether that format is available. For the purposes of this article all the examples will be returned in JSON format.

In order for the client to work you have to have CURL installed and available to php. Most hosts already do but you never know so it’s best to check with your host if you’re not sure.

It’s also important to familiarize yourself with all the ins and outs of the Twitter API. They employ rate limiting and have some useful information for developers that’ll help make the API a little less painful.

Basic Example

The client is a full OOP service with exceptions so the basic layout of the algorithm is like the below:

<?php
//echo ini_get('include_path');
require_once 'Arc90/Service/Twitter.php';
 
$username = 'YOUR_USERNAME';
$password = 'YOUR_PASSWORD';
 
$twitter = new Arc90_Service_Twitter($username, $password);
 
try
{ 
 
	$response = $twitter->getFriendsTimeline('json');
	$return = $response->getData();
 
	// If Twitter returned an error (401, 503, etc), print status code
	if($response->isError())
	{
		echo $response->http_code;
	}
	print_r( json_decode($return) );
}
catch(Arc90_Service_Twitter_Exception $e)
{
	// Print the exception message (invalid parameter, etc)
	print $e->getMessage();
}
?>

For all additional examples I’ll only be displaying exactly what’s necessary; take that into account.

End Session

Ends the session of the authenticating user, returning a null cookie. Use this method to sign users out of client-facing applications like widgets.

1
2
3

<?php
$response = $twitter->endSession();
?>

Get Public Timeline

Returns the 20 most recent statuses from non-protected users who have set a custom user icon. This method can return JSON, XML, ATOM and RSS.

<?php
$response = $twitter->getPublicTimeline('json');
$return = $response->getData();
print_r( json_decode($return) );
?>

Get Friends Timeline

Returns the 20 most recent statuses posted by the authenticating user and that user’s friends. This method can return JSON, XML, ATOM and RSS.

If the optional $params are passed you can pare down the results.

<?php
$params = array();
$params['since'] = mktime(date("H")-4, date("i"), date("s")); //unix timestamp
$params['since_id'] = 'POST_ID_TO_USE_SINCE'; //id of post
$params['count'] = '10'; //must be < 200
$params['page'] = '1';
$response = $twitter->getFriendsTimeline('json',$params);
 
// Print the XML response
$return = $response->getData();
 
print_r( json_decode($return) );
?>

Get User Timeline

Returns the most recent statuses posted from the authenticating user based on the set options. This method can return JSON, XML, ATOM and RSS.

<?php
$params = array();
$params['since'] = mktime(date("H")-4, date("i"), date("s")); //unix timestamp
$params['id'] = 'ID_OF_USER_TO_CHECK'; //id of user to look up
$params['since_id'] = '902529454'; //id of post
$params['count'] = '10'; //must be < 200
$params['page'] = '1';
$response = $twitter->getUserTimeline('json',$params);
 
// Print the XML response
$return = $response->getData();
?>

Show Status

Returns the status for a single user based on the provided id. This method can return XML and JSON.

<?php
$response = $twitter->showStatus('ID_OF_USER_TO_CHECK','json');
$return = $response->getData();
print_r( json_decode($return) );
?>

Update Status

Updates the authenticating user’s status and returns the posted status in the requested format when successful.

<?php
$status = 'My Script Sent This Status';
$response = $twitter->updateStatus($status, $in_reply_to_status_id = 0, $format = 'json');
$return = $response->getData();
print_r( json_decode($return) );
?>

Get Replies

Returns the 20 most recent @replies (status updates prefixed with @username) for the authenticating user. Returns JSON, XML, ATOM and RSS.

<?php
$params = array();
/*
$params['page'] = '0';
$params['since'] = mktime(date("H")-4, date("i"), date("s")); //unix timestamp 4 hours ago;
$params['since_id'] = '0';
*/
$response = $twitter->getReplies('json', $params);
 
// Print the XML response
$return = $response->getData();
 
print_r( json_decode($return) );
 
?>

Destroy Status

Destroys the status specified by the required ID parameter. The authenticating user must be the author of the specified status.

<?php
$id = 'ID_OF_STATUS_TO_DESTROY';
$response = $twitter->destroyStatus($id, 'json');
$return = $response->getData();
print_r( json_decode($return) );
?>

Get Friends

Returns the 20 most recent statuses from non-protected users who have set a custom user icon. This method can return ATOM and RSS.

<?php
$params = array();
/*
$params['id'] = 'ID_OF_USER_TO_GET_FRIENDS_FOR'; 
$params['page'] = '0';
$params['since'] = mktime(date("H")-4, date("i"), date("s")); //unix timestamp;
$params['lite'] = TRUE; //removes status
*/
$response = $twitter->getFriends('json', $params);
 
// Print the XML response
$return = $response->getData();
print_r( json_decode($return) );
?>

Get Followers

Returns the authenticating user’s followers, each with current status inline. They are ordered by the order in which they joined Twitter (this is going to be changed). This method can return ATOM and RSS.

<?php
$params = array();
/*
$params['id'] = 'ID_OF_USER_TO_GET_FRIENDS_FOR'; 
$params['page'] = '0';
$params['lite'] = TRUE; //removes status
*/
$response = $twitter->getFollowers('json', $params);
 
// Print the XML response
$return = $response->getData();
 
print_r( json_decode($return) );
 
?>

Show User

According to the source code on this method:

/**
 * Returns extended information for a given user, specified by ID, screen name, or email.
 *
 * This information includes design settings, so third party developers can theme their widgets
 * according to a given user's preferences.
 * 
 * You must be properly authenticated to request the page of a protected user.
 *
 * The API allows a user to be identified by ID, screen name, or email.
 * Any of these fields may be provided using the $id parameter.
 *
 * A user ID must be passed as an integer.
 * A screen name or an email address must be passed as a string.
 *
 * Show data for a user with an ID of 123: showUser(123)
 * Show data for a user with a screen name of 123: showUser("123")
 */

Can return in XML or JSON.

<?php
$id = 'SCREEN_NAME_ID_OR_EMAIL_OF_USER_TO_CHECK';
$response = $twitter->showUser($id, 'json');
 
// Print the XML response
$return = $response->getData();
 
print_r( json_decode($return) );
?>

Be sure to check out Part 2 of the series for details on the remaining methods and functionality.

Tags: php, twitter, twitter api

This entry was written by Eric Lamb and posted on Monday, April 27th, 2009 at 5:21 am and is filed under Code, Programming. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.

Twitter Search says:

May 26, 2009 at 4:58 pm

thats great that you are talking about the twitter api,a good example of searching with the twitter api is on twiogle.com because you can search on twitter and google at the same time.

tom says:

May 29, 2009 at 8:18 am

Error in the 1st example:

Parse error: syntax error, unexpected ‘{‘ in test.php on line 11

Which is:
getFriendsTimeline(‘json’);
$return = $response->getData();

// If Twitter returned an error (401, 503, etc), print status code
if($response->isError())
{
echo $response->http_code;
}
print_r( json_decode($return) );
}
catch(Arc90_Service_Twitter_Exception $e)
{
// Print the exception message (invalid parameter, etc)
print $e->getMessage();
}
?>

May 29, 2009 at 8:19 am

the error is with the try catch block – blows up on the {

May 29, 2009 at 8:32 am

errors with creating a friendship using the arc90 service

Parse error: syntax error, unexpected T_CONST, expecting T_OLD_FUNCTION or T_FUNCTION or T_VAR or ‘}’ in /Arc90/Service/Twitter.php on line 74

Eric Lamb says:

May 29, 2009 at 8:56 am

Hi Tom,

What version of PHP are you using man? I reran all the above and I didn’t have any issues.

Thanks for pointing out your issues.

Eric

May 29, 2009 at 9:14 am

it looks like the server is running
PHP Version 4.4.9
System Linux infong 2.4 #1 SMP Tue Dec 18 22:34:10 UTC 2007 i686 GNU/Linux
Build Date Aug 12 2008 13:27:58

what version of php is required?

May 29, 2009 at 9:28 am

To use the

try {

} catch {

}

format you’ve got to have at least php 5.

The same goes for the Arc90 library as well man.

Unless there’s a reason you’re running php 4.4 you should really upgrade regardless of the above; php 5 has some really cool toys in it

Contact your host and they should be able to handle upgrading php for you.

Umair Jabbar says:

July 28, 2009 at 8:45 pm

This seems to be a good tutorial
any thing for OAuth and twitter ?

Kishan says:

January 2, 2010 at 5:58 pm

Hi,
Do I need an authentication by OAuth or something to use this?
I can’t see any response with these examples (not even an error)..

Regards,
Kishan

Made of Everything You're Not