Making a Twitter/OAuth PHP robot

Update 11/10/12
Twitter has switched off the non-versioned API endpoints, which means urls of the form
http://twitter.com/statuses/user_timeline
no longer work. Instead, the URLS have to be
https://api.twitter.com/1.1/statusus/user_timeline.
This change was slated for July this year, and I should have done it months ago! Anyway, The code below has been updated accordingly. Please see this post on the Twitter development blog for more info, including full details of the retired endpoints.

Update 05/11/10
Twitter has switched status ID generator to 'Snowflake', which means IDs are now 64 bit unsigned integers. PHP's JSON parser can't handle > 53 bits, so I had to change the robot to use [id_str] instead. The changes are highlighted in red in the code extracts. Please see this post on Twitter-development-talkfor more info.

Update 04/09/10
Twitter has now deprecated basic auth, so you have to use OAuth. Shadowfax had a couple of issues with these instruction on CentOS, and has posted how he did it, so it might be worth a look there if these aren't working for you.

Largely for fun, but partly because Twitter is going to has deprecated basic auth, I decided it was time to learn how to do OAuth.

My sources for this page are a combination of the following:

• kovshenin's excellent articles on Twibots
• rasmas's blog on using pecl/oauth
• And, of course, The PHP OAuth documentation.

The main motivation for this is that I have a little Twitter robot (or twibot) that

• Tweets the BBC forecast for my region once a day
• Re-tweets any met office weather warnings for my region.

This robot has evolved from a simple shell script, to a Perl app, to a combination shell script and C libcurl app, and now a PHP script. The common factor has been the use of basic auth...

The first bit to sort out is the OAuth bit. There's masses of stuff on the web on how OAuth works - the important bits are:

1. Your need to be register an app (your bot) with Twitter, and be supplied with a Consumer Token, which needs to be stored safely.
2. Your bot needs to use this consumer token to contact twitter, and obtain a Request Token.
3. This request token is then used in conjunction with a twitter account to obtain an Access token, which needs to be stored safely. (At this point the request token is discarded).
4. The access token is used by the bot to posts tweets 'as' the twitter account used in step 3.

It is worth noting that with the signing method Twitter uses, each token us make up of two files, a key file and a secret file.

Clear? :)

Don't worry - I'll go through each stage in turn, with code. (Codeand commandline extracts are shown in white boxes.The two actual PHP files are shown in white boxes with black text and black border.)

Step 1 - Register an application

1. Go to https://dev.twitter.com/apps
2. Create a new application. This process has changed since I last did it, but if offered the choice you want a Client application type, and Read & Write (assuming you want to post updates).

You are now shown an Application Details page, which gives you your consumer key and consumer secret. These need to be available to your bot, but must be kept secret from everyone else.

I do this by having a simple PHP include file that sets up a couple of variables:

Step 2 - Get a request token

We now use the consumer token to get a request token (which we later trade in for an access token for a specific account).

First of all, set up PHP with the OAuth extension. On Fedora, this looks like this:

Now we need some PHP to connect to twitter and get the request token:

If we run this, we will see a link that we need to copy and paste into a browser, that will allow us to activate the request token into an access token.

Do this, and twitter will prompt you for a log in. Login the account that you wish your bot to post to. Twitter will then give you an activation PIN which you need for the next step...

Step 3 - Get an access token

We now need to fire a request off to twitter for an access token, for which we use the code below:

If we run this, you will get an access token for the specific account.

On a housekeeping note, I rolled up both these activities into a single file called oauth.php, as follows:

With the following usage:

Step 4 - The Twibot

Steps 1, 2, and 3 are one-time operations (unless the access token expires, or you want to use a different account) - and now for the easy bit.

The robot itself is a simple PHP script called periodically (via cron, for example), that does whatever magic you want it to do.

A sample robot that will post a very simple "Oauth test" as the status update is below. The only 'gotcha' here is that the method of the fetch needs to be OAUTH_HTTP_METHOD_POST when submitting updates. Thus with a robot that reads and writes, you would need to switch between fetches that use OAUTH_HTTP_METHOD_GET and OAUTH_HTTP_METHOD_POST.

My robot is going to do the two things mentioned at the top - tweet the RSS weather from the beeb, and retweet all posts from @metofficeYorks.

The RSS bit is fairly straightforward. Download and decode the RSS XML, and bounce it back up. My code here is a little bit ugly, as it makes lots of assumptions about the content of the feed, but it's worked for over a year now!

The next part is a bit more tricky. We need to get a note of the last status we retweeted. I should use a database for this, but I'm just using the file system.

The only clever bit is that it globs all files ending ".id", and uses the basename as the twitter account to check/retweet, and the content as the previous status id. You also need to reverse the status array to make retweets appear in the same order as they were originally tweeted.

Now, wrap that all up into a single file, which takes an optional argument telling it whether or not to do the RSS update.

The final bit is to wrap it up into something that can be called from cron, and then adding some logging and error handling. This is left as an exercise for the reader. :)