Made of Everything You're Not

So, I've already gone into detail on the Arc90 Twitter API Service and it's pretty fun to work with. One small problem though; it's pretty big, complicated and, well, bulky. There's a lot you have to do to get something up and running.

Enter PHPTwitterSearch; a pretty easy to use, lightweight, Twitter API Search class. It's based on the class originally developed by David Billingham, which I admit, I didn't check out so I don't know how much it's based on.

The thing I didn't really like about the Arc90 script was how complicated the search process was. In case you didn't notice, I didn't go into any detail about the search process; for precisely because it was just to complicated. I stopped having fun when working with the search functionality.

Simplicity was what immediately drew me to PHPTwitterSearch. Here's a basic example of a search:

1
2
3
4
5
6

<?php
$query = 'findme';
$search = new SWTwitterSearch();
$search = new TwitterSearch($query);
$results = $search->results();
?>

Very, very simple. The above searches the API for $query.

Here's the best part though; for a little more complication all you have to do is chain the calls together.

1
2
3
4
5

<?php
$search = new SWTwitterSearch();
$search = new TwitterSearch();
$results = $search->from('username')->with('hashtag')->to('username2')->results();
?>

The above searches the API for tweets from "username" with the hash string "#hashtag" that was sent to the user "username2".

The class returns an array with objects that's really basic and simple.

As promised, here's the follow up to Arc90 Twitter API Service Part 1. If you haven't read that piece yet you probably should...

Here are the rest of the methods for interacting with Twitter via the Arc90 Twitter API Service.

It should be noted that nearly everything in the below is taken from the generously documented source code.

Get Messages

Returns a list of the 20 most recent direct messages sent to the authenticating user. The XML and JSON versions include detailed information about the sending and recipient users. This method can return XML< JSON, ATOM and RSS.

1
2
3
4
5
6
7
8
9
10
11
12
13

<?php
$params = array();
/*
$params = '0';
$params = mktime(date("H")-4, date("i"), date("s")); //unix timestamp;
$params = '0';
*/
$response = $twitter->getMessages('json', $params);
 
$return = $response->getData();
 
print_r( json_decode($return) );
?>

Get Sent Messages

Returns a list of the 20 most recent direct messages sent by the authenticating user.

1
2
3
4
5
6
7
8
9
10
11
12
13
14

<?php
$params = array();
/*
$params = '0';
$params = mktime(date("H")-4, date("i"), date("s")); //unix timestamp;
$params = '0';
*/
$response = $twitter->getSentMessages($format = 'json', $params);
 
// Print the XML response
$return = $response->getData();
 
print_r( json_decode($return) );
?>

Send Message

Sends a new direct message to the specified user from the authenticating user. This shows up under their "Direct Messages" section.

1
2
3
4
5
6
7
8

<?php
$text = 'Hello from my script!';
$user = 'USER_TO_SEND_TO'; //can be username or user_id
$response = $twitter->sendMessage($user, $text, 'json');
 
// Print the XML response
$return = $response->getData();
?>

Destroy Message

Destroys the direct message specified in the required ID parameter. The authenticating user must be the recipient of the specified direct message.

1
2
3
4
5
6
7
8
9

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

Create Friendship

Befriends the user specified in the ID parameter as the authenticating user. Returns the befriended user in the requested format when successful.

1
2
3
4
5
6
7
8
9

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

Destroy Friendship

Discontinues friendship with the user specified in the ID parameter as the authenticating user.

1
2
3
4
5
6
7
8
9

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

Check if Friendship Exists

Tests if a friendship exists between two users.

1
2
3
4
5
6
7

<?php
$user_a = 'USER_1';
$user_b = 'USER_2';
$response = $twitter->friendshipExists($user_a, $user_b, $format ='json');
$return = $response->getData();
print_r( json_decode($return) );
?>

Update Location

Updates the location attribute of the authenticating user, as displayed on the side of their profile and returned in various API methods. Please note this is not normalized, geocoded, or translated to latitude/longitude at this time.

1
2
3
4
5
6

<?php
$location = 'Home';
$response = $twitter->updateLocation($location,'json');
$return = $response->getData();
print_r( json_decode($return) );
?>

Update Delivery Device

Sets which device Twitter delivers updates to for the authenticating user. $device Must be one of: sms, im, none.

Sending 'none' as the device parameter will disable IM or SMS updates.

1
2
3
4
5

<?php
$device = 'sms';
$response = $twitter->updateDeliveryDevice($device, 'json');
$return = $response->getData();
?>

Update Profile Colors

Sets one or more hex values that control the color scheme of the authenticating user's profile page on twitter.com. These values are also returned in the /users/show API method.

At least one of the $params is required.

1
2
3
4
5
6
7
8
9
10

<?php
$params = '#FFFFFF';
$params = '#000000';
$params = '#CCCCCC';
$params = '#999999';
$params = '#FFFFFF';
 
$response = $twitter->updateProfileColors($params, $format ='json');
$return = $response->getData();
?>

Update Profile Image

Updates the authenticating user's profile image. Image must be a valid GIF, JPG, or PNG image of less than 700 kilobytes in size. Images with width larger than 500 pixels will be scaled down.

1
2
3
4
5
6
7

<?php
$image = '/path/to/image/'; //Local file path of the image to be uploaded
$response = $twitter->updateProfileImage($image, $format ='json');
$return = $response->getData();
print_r( json_decode($return) );
 
?>

Update Profile Background Image

Updates the authenticating user's profile background image. Image must be a valid GIF, JPG, or PNG image of less than 800 kilobytes in size. Images with width larger than 2048 pixels will be scaled down.

1
2
3
4
5
6

<?php
$image = '/path/to/image/'; //Local file path of the image to be uploaded
$response = $twitter->updateProfileBackgroundImage($image, $format ='json');
$return = $response->getData();
print_r( json_decode($return) );
?>

Update Profile

Sets values that users are able to set under the "Account" tab of their settings page. Only the parameters specified will be updated; to only update the "name" attribute, for example, only include that parameter in your request.

At least one of the $params is required.

1
2
3
4
5
6
7
8
9
10
11

<?php
$params = 'Name_TO_Use';
$params = 'Email_To_Use';
$params = 'URL_TO_Use';
$params = 'Location_TO_Use';
$params = 'Description_TO_Use';
 
$response = $twitter->updateProfile($params, $format ='json');
$return = $response->getData();
print_r( json_decode($return) );
?>

Get Favorites

Returns the 20 most recent favorite statuses for the authenticating user or user specified by the ID parameter.

1
2
3
4
5
6
7
8
9

<?php
$params = 'ID_TO_Use';//The ID or screen name of the user for whom to request a list of favorite statuses.
$params = '0';
 
$response = $twitter->getFavorites($format ='json', $params );
$return = $response->getData();
print_r( json_decode($return) );
 
?>

Create Favorite

Favorites the status specified in the ID parameter as the authenticating user. Returns the favorite status when successful.

1
2
3
4
5
6
7

<?php
$id = 'ID_TO_Use'; //The ID of the status to favorite
 
$response = $twitter->createFavorite($id, $format ='json');
$return = $response->getData();
print_r( json_decode($return) );
?>

Destroy Favorite

Un-favorites the status specified in the ID parameter as the authenticating user. Returns the un-favorited status in the requested format when successful.

1
2
3
4
5
6
7

<?php
$id = 'ID_TO_Use'; //The ID of the status to favorite
 
$response = $twitter->destroyFavorite($id, $format ='json');
$return = $response->getData();
print_r( json_decode($return) );
?>

Follow

Enables notifications for updates from the specified user to the authenticating user. Returns the specified user when successful.

NOTE: The Notification Methods require the authenticated user to already be friends with the specified user. Otherwise the error "there was a problem following the specified user" will be returned.

1
2
3
4
5
6
7

<?php
$id = 'ID_TO_Use'; //The ID or screen name of the user to follow
 
$response = $twitter->follow($id, $format ='json');
$return = $response->getData();
print_r( json_decode($return) );
?>

Leave

Disables notifications for updates from the specified user to the authenticating user. Returns the specified user when successful.

NOTE: The Notification Methods require the authenticated user to already be friends with the specified user. Otherwise the error "there was a problem following the specified user" will be returned.

1
2
3
4
5
6
7

<?php
$user = 'ID_TO_Use'; //The ID or screen name of the user to leave
 
$response = $twitter->leave($user, $format ='json');
$return = $response->getData();
print_r( json_decode($return) );
?>

Block

Blocks the user specified in the ID parameter as the authenticating user. Returns the blocked user in the requested format when successful.

1
2
3
4
5
6
7

<?php
$id = 'ID_TO_Use'; //The ID or screen name of the user to block
 
$response = $twitter->block($id, $format ='json');
$return = $response->getData();
print_r( json_decode($return) );
?>

Un-Block

Un-blocks the user specified in the ID parameter as the authenticating user. Returns the un-blocked user in the requested format when successful.

1
2
3
4
5
6
7

<?php
$id = 'ID_TO_Use'; //The ID or screen name of the user to block
 
$response = $twitter->unblock($user, $format ='json');
$return = $response->getData();
print_r( json_decode($return) );
?>

Graph Friends

Returns an array of numeric IDs for every user the specified user is following.

1
2
3
4
5
6
7

<?php
$user = 'ID_TO_Use'; //ID or screen_name of the user to retrieve the friends ID list for
 
$response = $twitter->graphFriends($format ='json', $user );
$return = $response->getData();
print_r( json_decode($return) );
?>

Graph Followers

Returns an array of numeric IDs for every user the specified user is followed by.

1
2
3
4
5
6
7

<?php
$user = 'ID_TO_Use'; //ID or screen_name of the user to retrieve the followers ID list for
 
$response = $twitter->graphFollowers($format ='json', $user );
$return = $response->getData();
print_r( json_decode($return) );
?>

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.

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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

<?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.

1
2
3
4
5

<?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.

1
2
3
4
5
6
7
8
9
10
11
12
13

<?php
$params = array();
$params = mktime(date("H")-4, date("i"), date("s")); //unix timestamp
$params = 'POST_ID_TO_USE_SINCE'; //id of post
$params = '10'; //must be < 200
$params = '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.

1
2
3
4
5
6
7
8
9
10
11
12

<?php
$params = array();
$params = mktime(date("H")-4, date("i"), date("s")); //unix timestamp
$params = 'ID_OF_USER_TO_CHECK'; //id of user to look up
$params = '902529454'; //id of post
$params = '10'; //must be < 200
$params = '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.

1
2
3
4
5

<?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.

1
2
3
4
5
6

<?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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

<?php
$params = array();
/*
$params = '0';
$params = mktime(date("H")-4, date("i"), date("s")); //unix timestamp 4 hours ago;
$params = '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.

1
2
3
4
5
6

<?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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14

<?php
$params = array();
/*
$params = 'ID_OF_USER_TO_GET_FRIENDS_FOR';
$params = '0';
$params = mktime(date("H")-4, date("i"), date("s")); //unix timestamp;
$params = 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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

<?php
$params = array();
/*
$params = 'ID_OF_USER_TO_GET_FRIENDS_FOR';
$params = '0';
$params = 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:

614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630

/**
 * 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.

1
2
3
4
5
6
7
8
9

<?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.