|
The Contributor
Join Date: Dec 2007
Posts: 60
Thanks: 5
|
Feedback on my TwitterAPI?
Hey guys, I know I haven't posted in a long time.. but I still think about you! I swear!! Okay, okay.. I forgot about you guys 
Anyways, I would like some feedback on my TwitterAPI. It's perfect in my eyes, but then again.. I love feedback.
Please note that I did this in about.. 3 hours? I haven't had time to improve the error handling, it does need some work 
The idea of the API is to only return useful information.. if you've ever used the Twitter API, it returns a bunch of information on every query that's not needed.. and if I included it all in the cache, the cache would be like 10 times larger
PHP Code:
<?php
class TwitterAPI
{
public $caching = false;
public $cache_dir = null;
public $cache_time = 0;
private $modified = false;
private $twitter_username = null;
private $twitter_password = null;
protected $api_calls = 0;
protected $data = array(
'tweets' => null,
'tweet_lookup' => null,
'friend_tweets' => null,
'friend_ids' => null,
'public_tweets' => null,
'user_lookup' => null,
'mentioned' => null,
'followers' => null,
'follower_ids' => null,
'direct_messages' => null,
'direct_messages_sent' => null,
'rate' => null
);
static public $instance = null;
/**
* Sets default settings, and if caching is enabled, we try to load the cache file
* @param string $username (Optional) Default username
* @param string $password (Optional) Default password
* @param bool $caching (Optional) True to enable caching, false to disable
* @param string $cache_dir (Optional) Default cache directory (where we store cache files)
* @param int $cache_time (Optional) The max age of a cache file, in seconds (IE: 300 would be 5 minutes -- 60*5)
* @public
* @return nothing
*/
public function __construct($username = null, $password = null, $caching = false, $cache_dir = null, $cache_time = 0)
{
$this->twitter_username = $username;
$this->twitter_password = $password;
$this->caching = $caching;
$this->cache_dir = $cache_dir;
$this->cache_time = $cache_time;
if($caching)
{
$this->load_cache();
}
}
/**
* Gets the instance of this object, if there isn't one, then one is created and returned
* @static
* @public
* @return TwitterAPI
*/
static public function getInstance()
{
if(self::$instance === null)
{
self::$instance = new self();
}
return self::$instance;
}
/**
* Attempts to verify user credentials
* @see http://apiwiki.twitter.com/Twitter-REST-API-Method:-account*verify_credentials
* @public
* @return bool True on success or false on failure
*/
public function verifyCredentials()
{
try
{
$this->APICall('account/verify_credentials');
return true;
}
catch(TwitterException $error)
{
return false;
}
}
/**
* Quote: Ends the session of the authenticating user, returning a null cookie.
* @see http://apiwiki.twitter.com/Twitter-REST-API-Method:-account*end_session
* @public
* @return bool True on success or false on failure
*/
public function endSession()
{
if($this->APICall('account/end_session', null, 'POST') !== false)
{
return true;
}
return false;
}
/**
* Sends a direct message to a recipient (NOTE: Recipient must be on friends list)
* @see http://apiwiki.twitter.com/Twitter-REST-API-Method:-direct_messages*new
* @param string $recipient The recipient of the message
* @param string $message The message being sent to the recipient
* @public
* @return bool True on success or false on failure
*/
public function sendDirectMessage($recipient, $message)
{
if($this->APICall('direct_messages/new', array('text' => $message, 'user' => $recipient), 'POST') !== false)
{
return true;
}
return false;
}
/**
* Deletes a tweet via ID
* @see http://apiwiki.twitter.com/Twitter-REST-API-Method:-statuses*destroy
* @param int $tweet_id The tweet ID to delete
* @public
* @return bool True on success or false on failure
*/
public function deleteTweet($tweet_id)
{
if($this->APICall('statuses/destroy/'.$tweet_id, null, 'DELETE') !== false)
{
return true;
}
return false;
}
/**
* Deletes a direct message via ID
* @see http://apiwiki.twitter.com/Twitter-REST-API-Method:-direct_messages*destroy
* @param int $message_id The message ID to delete
* @public
* @return bool True on success or false on failure
*/
public function deleteDirectMessage($message_id)
{
if($this->APICall('direct_messages/destroy/'.$message_id, null, 'DELETE') !== false)
{
return true;
}
return false;
}
/**
* Sends a tweet
* @see http://apiwiki.twitter.com/Twitter-REST-API-Method:-statuses*update
* @param string $message The tweet text to post
* @param int $reply_to_id (Optional) An ID representing a tweet that you are replying to
* @public
* @return bool True on success or false on failure
*/
public function sendTweet($message, /*$shorten_urls = true, */$reply_to_id = null)
{
//
// TODO: Add support for automatically finding and replacing urls with their shortened style
//
if($this->APICall('statuses/update', array('status' => $message, 'in_reply_to_status_id' => $reply_to_id), 'POST') !== false)
{
return true;
}
return false;
}
/**
* Befriends a user by ID or screen name
* @see http://apiwiki.twitter.com/Twitter-REST-API-Method:-friendships*create
* @param string|int $user The user to befriend (either user ID or screen name, depending on $user_identifier)
* @param string $user_identifier (Default: screen_name) Tells how we identify the user, possible methods are: user_id, screen_name
* @param bool $follow_user (Optional) Allows you to follow the user after befriending
* @public
* @return bool True on success or false on failure
*/
public function addFriend($user, $user_identifier = 'screen_name', $follow_user = 'true')
{
$user_identifier = strtolower($user_identifier);
if($user_identifier !== 'screen_name' && $user_identifier !== 'user_id')
{
return false;
}
if($this->APICall('friendships/create', array($user_identifier => $user), 'POST') !== false)
{
return true;
}
return false;
}
/**
* Gets a list of friend IDs
* @see http://apiwiki.twitter.com/Twitter-REST-API-Method:-friends*ids
* @param array An array of params to pass to the API call
* @public
* @return array Returns an array of friend IDs
*/
public function getFriendIDList($params = null)
{
if($this->data['friend_ids'] === null)
{
$buffer = $this->APICall('friends/ids', $params);
// It -is- possible to not have any friends..
if(isset($buffer[0]))
{
foreach($buffer as $id)
{
$this->data['friend_ids'][] = $id;
}
}
else
{
$this->data['friend_ids'] = array();
}
$this->modified = true;
}
return $this->data['friend_ids'];
}
/**
* Gets a list of follower IDs
* @see http://apiwiki.twitter.com/Twitter-REST-API-Method:-friends*ids
* @param array An array of params to pass to the API call
* @public
* @return array Returns an array of follower IDs
*/
public function getFollowerIDList($params = null)
{
if($this->data['follower_ids'] === null)
{
$buffer = $this->APICall('followers/ids', $params);
// It -is- possible to not have any followers..
if(isset($buffer[0]))
{
foreach($buffer as $id)
{
$this->data['follower_ids'][] = $id;
}
}
else
{
$this->data['follower_ids'] = array();
}
$this->modified = true;
}
return $this->data['follower_ids'];
}
/**
* Removes a friend by their ID or username
* @see http://apiwiki.twitter.com/Twitter-REST-API-Method:-friendships*destroy
* @param string|int $friend The friend to remove (either ID or username)
* @param string $friend_identifier (Default: screen_name) Tells how we identify the friend, possible methods are: user_id, screen_name
* @public
* @return bool True on success or false on failure
*/
public function deleteFriend($friend, $friend_identifier = 'screen_name')
{
$friend_identifier = strtolower($friend_identifier);
if($friend_identifier !== 'screen_name' && $friend_identifier !== 'user_id')
{
return false;
}
if($this->APICall('friendships/destroy', array($friend_identifier => $friend), 'DELETE') !== false)
{
return true;
}
return false;
}
/**
* Checks to see if a username or ID is a friend
* @see http://apiwiki.twitter.com/Twitter-REST-API-Method:-friendships-exists
* @param string|int $friend Check to see if this user is a friend of us
* @public
* @return bool True if the friend exists, false if not
*/
public function existsFriend($friend)
{
return $this->APICall('friendships/exists', array('user_a' => $this->twitter_username, 'user_b' => $friend));
}
/**
* Returns a 200 status OK header, just a test function
* @see http://apiwiki.twitter.com/Twitter-REST-API-Method:-help*test
* @public
* @return bool True on success or false on failure
*/
public function helpTest()
{
return $this->APICall('help/test');
}
/**
* Gets a list of direct messages sent to you
* @see http://apiwiki.twitter.com/Twitter-REST-API-Method:-direct_messages
* @param string $date_format The format used in date() for times
* @param array $params (Optional) A list of parameters to pass to Twitter
* @param bool $use_href (Optional, Default: true) Turns all '@<username>' matches to links
* @public
* @return array Returns an array of direct messages
*/
public function getDirectMessages($date_format = null, $params = null, $use_href = true)
{
if($this->data['direct_messages'] === null)
{
$buffer = $this->APICall('direct_messages', $params);
foreach($buffer as $message)
{
if($use_href)
{
$message->text = preg_replace('/@([a-z0-9]+)/i', '<a href="http://www.twitter.com/$1" title="$1 on Twitter">@$1</a>', $message->text);
}
$this->data['direct_messages'][] = array(
'id' => $message->id,
'from-name' => $message->sender->name,
'from-screen_name' => $message->sender_screen_name,
'text' => $message->text,
'time' => $date_format !== null ? date($date_format, strtotime($message->created_at)) : strtotime($message->created_at)
);
}
$this->modified = true;
}
return $this->data['direct_messages'];
}
/**
* Gets a list of sent direct messages sent to you
* @see http://apiwiki.twitter.com/Twitter-REST-API-Method:-direct_messages*sent
* @param string $date_format The format used in date() for times
* @param array $params (Optional) A list of parameters to pass to Twitter
* @param bool $use_href (Optional, Default: true) Turns all '@<username>' matches to links
* @public
* @return array Returns an array of sent direct messages
*/
public function getSentDirectMessages($date_format = null, $params = null, $use_href = true)
{
if($this->data['direct_messages_sent'] === null)
{
$buffer = $this->APICall('direct_messages/sent', $params);
foreach($buffer as $message)
{
if($use_href)
{
$message->text = preg_replace('/@([a-z0-9]+)/i', '<a href="http://www.twitter.com/$1" title="$1 on Twitter">@$1</a>', $message->text);
}
$this->data['direct_messages_sent'][] = array(
'id' => $message->id,
'to-id' => $message->recipient_id,
'to-name' => $message->recipient->name,
'to-screen_name' => $message->recipient->screen_name,
'text' => $message->text,
'time' => $date_format !== null ? date($date_format, strtotime($message->created_at)) : strtotime($message->created_at)
);
}
$this->modified = true;
}
return $this->data['direct_messages_sent'];
}
/**
* Gets a list of your followers
* @see http://apiwiki.twitter.com/Twitter-REST-API-Method:-statuses*followers
* @param string $date_format The format used in date() for times
* @param array $params (Optional) A list of parameters to pass to Twitter
* @param bool $use_href (Optional, Default: true) Turns all '@<username>' matches to links
* @public
* @return array Returns an array of direct messages
*/
public function getFollowers($date_format = null, $params = null, $use_href = true)
{
if($this->data['followers'] === null)
{
$buffer = $this->APICall('statuses/followers', $params);
foreach($buffer as $follower)
{
if($use_href)
{
$follower->status->text = preg_replace('/@([a-z0-9]+)/i', '<a href="http://www.twitter.com/$1" title="$1 on Twitter">@$1</a>', $follower->status->text);
}
$this->data['followers'][] = array(
'follower-id' => $follower->id,
'follower-name' => $follower->name,
'follower-screen_name' => $follower->screen_name,
'follower-created' => $date_format !== null ? date($date_format, strtotime($follower->created_at)) : strtotime($follower->created_at),
'follower-following' => $follower->following,
'follower-followers' => $follower->followers_count,
'follower-friends' => $follower->friends_count,
'follower-favorites' => $follower->favourites_count,
'follower-tweets' => $follower->statuses_count,
'tweet-text' => $follower->status->text,
'tweet-time' => $date_format !== null ? date($date_format, strtotime($follower->status->created_at)) : strtotime($follower->status->created_at)
);
}
$this->modified = true;
}
return $this->data['followers'];
}
/**
* Gets user information about a specific user
* @see http://apiwiki.twitter.com/Twitter-REST-API-Method:-users*show
* @param string $user The user to retrieve (the id, screen name, or user-id)
* @param string $user_identifier Valid entries are: id, screen_name, and user_id
* @param string $date_format The format used in date() for times
* @public
* @return bool The only time it will return a bool is when $user_identifier is incorrect, in which case it will always be false when returned
*/
public function getUser($user, $user_identifier = 'screen_name', $date_format = null)
{
$user_identifier = strtolower($user_identifier);
if($user_identifier !== 'id' && $user_identifier !== 'screen_name' && $user_identifier !== 'user_id')
{
return false;
}
if($this->data['user_lookup'] === null || !isset($this->data['user_lookup'][$user_identifier . '-' . $user]))
{
$buffer = $this->APICall('users/show', array($user_identifier => $user));
$this->data['user_lookup'][$user_identifier . '-' . $user] = array(
'id' => $buffer->id,
'name' => $buffer->name,
'screen_name' => $buffer->screen_name,
'created' => $date_format !== null ? date($date_format, strtotime($buffer->created_at)) : strtotime($buffer->created_at),
'following' => $buffer->following,
'followers' => $buffer->followers_count,
'friends' => $buffer->friends_count,
'favorites' => $buffer->favourites_count,
'tweets' => $buffer->statuses_count,
'tweet-text' => $buffer->status->text,
'tweet-time' => $date_format !== null ? date($date_format, strtotime($buffer->status->created_at)) : strtotime($buffer->status->created_at)
);
$this->modified = true;
}
return $this->data['user_lookup'][$user_identifier . '-' . $user];
}
/**
* Gets information about a specific tweet
* @see http://apiwiki.twitter.com/Twitter-REST-API-Method:-statuses*show
* @param int $tweet_id The ID of the tweet to retrieve
* @param string $date_format The format used in date() for times
*/
public function getTweet($tweet_id, $date_format = null)
{
if($this->data['tweet_lookup'] === null || !isset($this->data['tweet_lookup'][$tweet_id]))
{
$buffer = $this->APICall('statuses/show/'.$tweet_id);
$this->data['tweet_lookup'][$tweet_id] = array(
'id' => $tweet->id,
'author' => $buffer->user->name,
'screen_name' => $buffer->user->screen_name,
'text' => $buffer->text,
'time' => $date_format !== null ? date($date_format, strtotime($buffer->created_at)) : strtotime($buffer->created_at)
);
$this->modified = true;
}
return $this->data['tweet_lookup'][$tweet_id];
}
/**
* Gets a list of your tweets
* @see http://apiwiki.twitter.com/Twitter-REST-API-Method:-statuses-user_timeline
* @param string $date_format The format used in date() for times
* @param array $params (Optional) A list of parameters to pass to Twitter
* @param bool $use_href (Optional, Default: true) Turns all '@<username>' matches to links
* @public
* @return array Returns an array of tweets
*/
public function getTweets($date_format = null, $params = null, $use_href = true)
{
if($this->data['tweets'] === null)
{
$buffer = $this->APICall('statuses/user_timeline', $params);
foreach($buffer as $tweet)
{
if($use_href)
{
$tweet->text = preg_replace('/@([a-z0-9]+)/i', '<a href="http://www.twitter.com/$1" title="$1 on Twitter">@$1</a>', $tweet->text);
}
$this->data['tweets'][] = array(
'id' => $tweet->id,
'text' => $tweet->text,
'time' => $date_format !== null ? date($date_format, strtotime($tweet->created_at)) : strtotime($tweet->created_at)
);
}
$this->modified = true;
}
return $this->data['tweets'];
}
/**
* Gets a list of public tweets
* @see http://apiwiki.twitter.com/Twitter-REST-API-Method:-statuses-public_timeline
* @param string $date_format The format used in date() for times
* @param array $params (Optional) A list of parameters to pass to Twitter
* @param bool $use_href (Optional, Default: true) Turns all '@<username>' matches to links
* @public
* @return array Returns an array of public tweets
*/
public function getPublicTweets($date_format = null, $params = null, $use_href = true)
{
if($this->data['public_tweets'] === null)
{
$buffer = $this->APICall('statuses/public_timeline', $params);
foreach($buffer as $tweet)
{
if($use_href)
{
$tweet->text = preg_replace('/@([a-z0-9]+)/i', '<a href="http://www.twitter.com/$1" title="$1 on Twitter">@$1</a>', $tweet->text);
}
$this->data['public_tweets'][] = array(
'id' => $tweet->id,
'author' => $tweet->user->name,
'screen_name' => $tweet->user->screen_name,
'text' => $tweet->text,
'time' => $date_format !== null ? date($date_format, strtotime($tweet->created_at)) : strtotime($tweet->created_at)
);
}
$this->modified = true;
}
return $this->data['public_tweets'];
}
/**
* Gets a list of your friend's tweets
* @see http://apiwiki.twitter.com/Twitter-REST-API-Method:-statuses-friends_timeline
* @param string $date_format The format used in date() for times
* @param array $params (Optional) A list of parameters to pass to Twitter
* @param bool $use_href (Optional, Default: true) Turns all '@<username>' matches to links
* @public
* @return array Returns an array of your friend's tweets
*/
public function getFriendTweets($date_format = null, $params = null, $use_href = true)
{
if($this->data['friend_tweets'] === null)
{
$buffer = $this->APICall('statuses/friends_timeline', $params);
foreach($buffer as $tweet)
{
if($use_href)
{
$tweet->text = preg_replace('/@([a-z0-9]+)/i', '<a href="http://www.twitter.com/$1" title="$1 on Twitter">@$1</a>', $tweet->text);
}
$this->data['friend_tweets'][] = array(
'id' => $tweet->id,
'author' => $tweet->user->name,
'screen_name' => $tweet->user->screen_name,
'text' => $tweet->text,
'time' => $date_format !== null ? date($date_format, strtotime($tweet->created_at)) : strtotime($tweet->created_at)
);
}
$this->modified = true;
}
return $this->data['friend_tweets'];
}
/**
* Gets a list of all the tweets which mention you
* @see http://apiwiki.twitter.com/Twitter-REST-API-Method:-statuses-mentions
* @param string $date_format The format used in date() for times
* @param array $params (Optional) A list of parameters to pass to Twitter
* @param bool $truncate_me (Optional) If set to true, and your name (@<you>) is the first word, it gets truncated
* @param bool $use_href (Optional, Default: true) Turns all '@<username>' matches to links
* @public
* @return array Returns an array of tweets which mention you
*/
public function getMentioned($date_format = null, $params = null, $truncate_me = true, $use_href = true)
{
if($this->data['mentioned'] === null)
{
$buffer = $this->APICall('statuses/mentions', $params);
foreach($buffer as $tweet)
{
if($truncate_me)
{
// Not all mentions start with @ (IE: "thanks to @JStrese my life is complete!")
if($tweet->text[0] === '@')
{
$tweet->text = substr($tweet->text, strlen($this->twitter_username)+2);
}
}
if($use_href)
{
$tweet->text = preg_replace('/@([a-z0-9]+)/i', '<a href="http://www.twitter.com/$1" title="$1 on Twitter">@$1</a>', $tweet->text);
}
$this->data['mentioned'][] = array(
'id' => $tweet->id,
'author' => $tweet->user->name,
'screen_name' => $tweet->user->screen_name,
'text' => $tweet->text,
'time' => $date_format !== null ? date($date_format, strtotime($tweet->created_at)) : strtotime($tweet->created_at)
);
}
$this->modified = true;
}
return $this->data['mentioned'];
}
/**
* Gets information (hourly rate, remaining hits, and reset time) about your API calls
* @see http://apiwiki.twitter.com/Twitter-REST-API-Method:-account*rate_limit_status
* @public
* @return array An array of information regarding your API calls
*/
public function getRateLimit()
{
$buffer = $this->APICall('account/rate_limit_status');
$this->data['rate'][] = array(
'hourly-limit' => $buffer->hourly_limit,
'hourly-remaining' => $buffer->remaining_hits,
'resets' => strtotime($buffer->reset_time)
);
return $this->data['rate'];
}
/**
* Shortens a url with the is.gd (http://is.gd/) service
* @see http://is.gd/api_info.php
* @param string $url The url to be shortened
* @public
* @static
* @return string|bool Returns string if the url is shortened, or false if there was an error
*/
public static function shortenURL($url)
{
$ch = curl_init('http://is.gd/api.php?longurl='.urlencode($url));
curl_setopt($ch, CURLOPT_HEADER, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_BINARYTRANSFER, true);
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 10);
curl_setopt($ch, CURLOPT_DNS_CACHE_TIMEOUT, 10);
$url = curl_exec($ch);
if(curl_getinfo($ch, CURLINFO_HTTP_CODE) === 200)
{
curl_close($ch);
return $url;
}
curl_close($ch);
return false;
}
/**
* Requests an API call from Twitter
* @param string $call The API call (IE: account/rate_limit_status)
* @param array $params (Optional) Extra parameters to pass along to Twitter
* @param string $method The HTTP method to issue (GET, REQUEST, POST, UPDATE, DELETE, etc) [MUST CONFORM TO API CALL]
* @final
* @private
* @return bool|array Returns false on any error, or an array of JSON data with a successful call
*/
final private function APICall($call, $params = null, $method = 'GET')
{
$ch = null;
if($params !== null)
{
$ch = curl_init('http://twitter.com/'.$call.'.json?' . http_build_query($params));
}
else
{
$ch = curl_init('http://twitter.com/'.$call.'.json');
}
curl_setopt($ch, CURLOPT_HEADER, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_BINARYTRANSFER, true);
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 10);
curl_setopt($ch, CURLOPT_DNS_CACHE_TIMEOUT, 10);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $method);
curl_setopt($ch, CURLOPT_USERPWD, $this->twitter_username . ':' . $this->twitter_password);
$data = curl_exec($ch);
$response = (int)curl_getinfo($ch, CURLINFO_HTTP_CODE);
if($response !== 200 && $response !== 304)
{
throw new TwitterException((int)$response);
}
curl_close($ch);
if($data !== false)
{
$this->api_calls += 1;
return json_decode($data);
}
return false;
}
/**
* Saves data to a cache file
* @public
* @return bool False on error, true on success
*/
public function save_cache()
{
if($this->modified && $this->cache_dir !== null && is_dir($this->cache_dir))
{
$this->data['cached_at'] = time();
file_put_contents(rtrim($this->cache_dir, '/\\').'/twitter.'.$this->twitter_username.'.txt', serialize($this->data));
return true;
}
return false;
}
/**
* Attemps to load a cache file for this username
* @public
* @return bool False on error, true on success
*/
public function load_cache()
{
if($this->cache_dir !== null && is_dir($this->cache_dir))
{
$path = rtrim($this->cache_dir, '/\\').'/twitter.'.$this->twitter_username.'.txt';
if(file_exists($path) && is_readable($path))
{
$data = unserialize(file_get_contents($path));
if((time() - (int)$data['cached_at']) < $this->cache_time)
{
$this->data = $data;
return true;
}
}
}
return false;
}
}
class TwitterException extends Exception
{
public function __construct($code)
{
switch(1)
{
case $code === 400:
$message = 'The request was invalid. This is the status code that will be returned during rate limiting.';
break;
case $code === 401:
$message = 'Authentication credentials were missing or incorrect.';
break;
case $code === 403:
$message = 'The request is understood, but it has been refused.';
break;
case $code === 404:
$message = 'The URI requested is invalid or the resource requested, such as a user, does not exists.';
break;
case $code === 406:
$message = 'Returned by the Search API when an invalid format is specified in the request.';
break;
case $code === 500:
$message = 'Something is broken. Please post to the group so the Twitter team can investigate.';
break;
case $code === 502:
$message = 'Twitter is down or being upgraded.';
break;
case $code === 503:
$message = 'The Twitter servers are up, but overloaded with requests. Try again later. The search and trend methods use this to indicate when you are being rate limited.';
break;
default:
$message = 'An unknown error occured while querying Twitter, please report this to the TwitterAPI developers.';
break;
}
parent::__construct($message, $code);
}
public function __toString()
{
return '[TwitterAPI Error (code: '.$this->code.')]: ' . $this->message;
}
}
?>
Last edited by Jay : 05-11-2009 at 05:46 PM.
|