A simple wrapper for the Twitter API
Copyright (C) 2010-2012 J.M. me@mynetx.net
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.
This is the PHP version of the Codebird library. It was forked from the JScript version. Please enable the CURL and OPENSSL extensions in your PHP environment.
require_once ('codebird.php');
Codebird::setConsumerKey('YOURKEY', 'YOURSECRET'); // static, see 'Using multiple Codebird instances'
$cb = Codebird::getInstance();You may either set the OAuth token and secret, if you already have them:
$cb->setToken('YOURTOKEN', 'YOURSECRET');Or you authenticate, like this:
session_start();
if (! isset($_GET['oauth_verifier'])) {
// gets a request token
$reply = $cb->oauth_requestToken(array(
'oauth_callback' => 'http://' . $_SERVER['HTTP_HOST'] . $_SERVER['REQUEST_URI']
));
// stores it
$cb->setToken($reply->oauth_token, $reply->oauth_token_secret);
$_SESSION['oauth_token'] = $reply->oauth_token;
$_SESSION['oauth_token_secret'] = $reply->oauth_token_secret;
// gets the authorize screen URL
$auth_url = $cb->oauth_authorize();
header('Location: ' . $auth_url);
die();
} else {
// gets the access token
$cb->setToken($_SESSION['oauth_token'], $_SESSION['oauth_token_secret']);
$reply = $cb->oauth_accessToken(array(
'oauth_verifier' => $_GET['oauth_verifier']
));
$_SESSION['oauth_token'] = $reply->oauth_token;
$_SESSION['oauth_token_secret'] = $reply->oauth_token_secret;
}When you have an access token, calling the API is simple:
$reply = (array) $cb->statuses_homeTimeline();
print_r($reply);Tweeting is as easy as this:
$reply = $cb->statuses_update('status=Whohoo, I just tweeted!');For more complex parameters (see the Twitter API documentation), giving all parameters in an array is supported, too:
$params = array(
'screen_name' => 'mynetx'
);
$reply = $cb->users_show($params);When uploading files to Twitter, the array syntax is obligatory:
$params = array(
'status' => 'Look at this crazy cat! #lolcats',
'media[]' => '/home/mynetx/lolcats.jpg'
);
$reply = $cb->statuses_updateWithMedia($params);As you can see from the last example, there is a general way how Twitter’s API methods map to Codebird function calls. The general rules are:
-
For each slash in a Twitter API method, use an underscore in the Codebird function.
Example:
statuses/updatemaps toCodebird::statuses_update(). -
For each underscore in a Twitter API method, use camelCase in the Codebird function.
Example:
statuses/home_timelinemaps toCodebird::statuses_homeTimeline(). -
For each parameter template in method, use UPPERCASE in the Codebird function. Also don’t forget to include the parameter in your parameter list.
Example:
statuses/show/:idmaps toCodebird::statuses_show_ID('id=12345').
Never care about which HTTP method (verb) to use when calling a Twitter API. Codebird is intelligent enough to find out on its own.
The HTTP response code that the API gave is included in any return values.
You can find it within the return object’s httpstatus property.
The default return format for API calls is a PHP object.
For API methods returning multiple data (like statuses/home_timeline),
you should cast the reply to array, like this:
$reply = $cb->statuses_homeTimeline();
$data = (array) $reply;Upon your choice, you may also get PHP arrays directly:
$cb->setReturnFormat(CODEBIRD_RETURNFORMAT_ARRAY);Finally, if you prefer seeing an URL-encoded string as reply, use this:
$cb->setReturnFormat(CODEBIRD_RETURNFORMAT_STRING);By default, Codebird works with just one instance. This programming paradigma is called a singleton.
Getting the main Codebird object is done like this:
$cb = Codebird::getInstance();If you need to run requests to the Twitter API for multiple users at once, Codebird supports this as well. Instead of getting the instance like shown above, create a new object:
$cb1 = new Codebird;
$cb2 = new Codebird;Please note that your OAuth consumer key and secret is shared within multiple Codebird instances, while the OAuth request and access tokens with their secrets are not shared.