Twitter OAuth using PHP to make your own twitter web client

My last post on twitter was an introduction on how to use twitter, a lot of things have changed since then but that post just covers a few basics to get you started. This post is for developers on how to build your own twitter web client - which means instead of using twitter.com or any other client out there (echofon, chromed bird, TweetDeck, etc.) to tweet, you can make your own app to work with twitter. More specifically this post shows how to use OAuth to tweet using PHP.

OAuth (Open Authentication) is an authenticating protocol that allows internet users to approve an application to act on their behalf without the need for the user to share their password with the application. With OAuth the service provider (Twitter) issues tokens and it involves the exchange of tokens/keys and signing of requests thus making it a secure protocol. Twitter uses OAuth and Basic Auth (username and password used for authentication) but on 16-August-2010 Twitter is ending support for basic auth, which means all apps will have to start using OAuth.

Implementing the OAuth protocol is a daunting task but luckily there are tons of libraries out there which makes life easy for us. Download abraham's twitteroauth library for PHP which I have used in the steps below.

Step 1: Register your application
Register a twitter application here and make sure to choose the settings as below:

Note down your CONSUMER_KEY and CONSUMER_SECRET, we will need this to identify our application to twitter.

Step 2: Use Twitter OAuth Library for PHP
Copy the directory twitteroauth which have the two files (OAuth.php and twitteroauth.php) from abraham's twitteroauth source to your working directory.
Create two files index.php and callback.php in your working directory

index.php:

session_start();
require_once 'twitteroauth/TwitterOAuth.php';
define("CONSUMER_KEY", "xxx");
define("CONSUMER_SECRET", "xxx");

Replace "xxx" with the token from the last step.

Step 3: Get Request Token
Continuing the code from the last step, here we use our consumer tokens to get request tokens from twitter. Twitter returns request tokens for temporary use - oauth_token and oauth_token_secret which is unique for every request and we save these in session variables for use in the next step.

index.php:

$connection = new TwitterOAuth(CONSUMER_KEY, CONSUMER_SECRET);
$request_token = $connection->getRequestToken();
$_SESSION['oauth_token'] = $request_token['oauth_token'];
$_SESSION['oauth_token_secret'] = $request_token['oauth_token_secret'];

Step 4: Send user for authorization
In this step we use our request tokens from the previous step to build the Authorization URL where the user will be redirected. The user is redirected to a page where if the user is not signed in it will be asked to sign in and then the user can grant or deny access to the application.

index.php:

$url = $connection->getAuthorizeURL($request_token);
header('Location: ' . $url);

Step 5: Exchange Request Token for Access Token
Once the user allows access in the previous step, they will be redirected to our callback page. Here twitter will return the oauth_token that we sent earlier, to make sure it is of the same session we compare this to the one we had earlier saved in session variable. Now we use the request tokens we got in Step 4 to exchange for Access token which is unique to every user (this token can be used for tweeting on behalf of the user for future requests).

callback.php:

session_start();
require_once 'twitteroauth/TwitterOAuth.php';
define("CONSUMER_KEY", "xxx");
define("CONSUMER_SECRET", "xxx");
if (isset($_REQUEST['oauth_token']) && $_SESSION['oauth_token'] !== $_REQUEST['oauth_token']) {
echo 'Session expired';
}
else {
$connection = new TwitterOAuth(CONSUMER_KEY, CONSUMER_SECRET, $_SESSION['oauth_token'], $_SESSION['oauth_token_secret']);
$token_credentials = $connection->getAccessToken();

Replace "xxx" with the token from the step 1

Step 6: Tweet on user's behalf
Finally we can use our access tokens from the previous step to tweet on behalf of the user
callback.php:

$connection = new TwitterOAuth(CONSUMER_KEY, CONSUMER_SECRET, $token_credentials['oauth_token'], $token_credentials['oauth_token_secret']);
$tweetmsg = 'Hello World, I am tweeting from my own twitter app!';
$result = $connection->post('statuses/update', array('status' => $tweetmsg));
$httpCode = $connection->http_code;
if ($httpCode == 200) {
$resultmsg = 'Tweet Posted: '.$tweetmsg;
}
else {
$resultmsg = 'Could not post Tweet. Error: '.$httpCode.' Reason: '.$result->error;
}
}

That's it! This is just the basics to get you started on building a full featured client. If you are migrating from basic auth to OAuth and have only a single user's account to manage, then in step1 you can choose the app type as client, get your access token from the My Access Token link after registering your app, skip steps 2,3,4,5 and go directly to step6 where you replace the token_credentials with your account's access token.