Home

Getting started

EpiTwitter lets you asynchronously integrate with Twitter’s REST API using OAuth as the authentication mechanism. This means you can make non-blocking curl requests to Twitter’s API on behalf of another user without having them hand over their username and password.

Efficiently using asynchronous curl

EpiTwitter was carefully written to maximize the efficiency of making HTTP web service requests. Knowing that curl calls are expensive, we don’t want to wait around idly while we could be doing other work. This is especially true if you need to make multiple calls on a single page. Ideally, you could fire off several requests in parallel instead of doing them one at a time.

The key to using EpiTwitter efficiently is to delay accessing the results for as long as possible. Initiating the call fires off the HTTP request and immediately returns control back to you without blocking. The call continues to work in the background until you need the results. For the best performance it’s advised to initiate the calls as early as possible and only block by accessing the results as late as possible. The implementation details depend greatly on your framework.

Creating an application on Twitter

To start off, you’ll need to create an application on Twitter. They will give you a consumer key and a consumer secret. Copy and paste this into your site’s configuration file since you’ll be needing them later. The rest of the information is embedded in EpiTwitter.

  define('TWITTER_CONSUMER_KEY', 'your_consumer_key');
  define('TWITTER_CONSUMER_SECRET', 'your_consumer_secret');

Dependencies

EpiTwitter has 2 dependencies including EpiOAuth and EpiCurl. EpiOAuth handles all of the authentication and url signing required to make valid requests to any OAuth provider, in this case Twitter. EpiCurl handles the asynchronous/non-blocking curl requests out to the API.

Class methods

EpiTwitter has only 2 methods, __construct and __call. The constructor takes a minimum of 2 parameters and a maximum of 4. The first two parameters are the consumer key and consumer secret. The last 2 are the OAuth token and OAuth secret which is what you’ll end up storing in your database for each Twitter account your users have granted you permission to acces.

The __call method handles the majority of the remaining invocations. There’s a simple naming pattern used to determine the proper method you want to call for a given API endpoint. Let’s start with the most common first example of validating a set of credentials.

Documentation on Twitter’s site.

  $twitterObj = new EpiTwitter(TWITTER_CONSUMER_KEY, TWITTER_CONSUMER_SECRET, $userToken, $userSecret);
  $userInfo = $twitterObj->get_accountVerify_credentials();
  // access keys directly
  echo "Your Twitter username is {$userInfo->screen_name}";
  // access response text
  echo $userInfo->responseText;
  // access response as an array
  var_dump($userInfo->result);

Understanding method names

EpiTwitter’s method names directly map to API endpoints. In the example above, the method name get_accountVerify_credentials consists of the HTTP method (get_) and the url path (account/verifycredentials). Simply follow these rules to determine the proper method name.

1. The first part is the HTTP method (in lowercase) specified by the API docs (i.e. get, post) get
2. Follow the method with an underscore get_
3. The second half of the method name is the URI path. This is entirely lowercase except for when there needs to be a / which is denoted by a capital letter get_accountVerify_credentials
4. The method takes an associative array as a list of parameters to be sent along with the request get_accountVerify_credentials(array('name'=>'value'))

  /* GET -> /followers/ids.json?screen_name=yahoo */
  $twtObj->get_followersIds(array('screen_name' => 'yahoo'));

  /* POST -> /statuses/update.json?status=This+is+my+new+status */
  $twtObj->post_statusesUpdate(array('status' => 'This is my new status'));

  /* GET -> /users/show/123456789.json */
  $method = "get_usersShow{$userId}"; // $userId = 123456789
  $twtObj->$method();

Accessing the response

All calls to Twitter APIs return an object with properties. The properties are named identical to what is in the response and dimensions of 2 or more are exposed as arrays. For example, the following JSON response is from the verify credentials API.

  {
    screen_name: "jmathai",
    name: "Jaisen Mathai",
    status: {
      text: "My last status",
      created_at: "Thu Apr 09 15:00:07 +0000 2009"
    },
  }

Each of these values can be accessed the following ways.

  // Access properties directly as member variables
  $userInfo->screen_name;
  $userInfo->name;
  $userInfo->status->text;
  $userInfo->status->created_at;

  // Access properties as an array through the response property
  $userInfo->response['screen_name'];
  $userInfo->response['name'];
  $userInfo->response['status']['text'];
  $userInfo->response['status']['created_at'];

A note on enumerated lists

Some responses are returned as an enumerated list. Since PHP requires that object properties start with [a-Z_] you can’t use $resp->0->screen_name. Given the following JSON response, you can use either of the methods described below.

  [
    {
        screen_name: "jmathai",
        name: "Jaisen Mathai"
        ...
    },
    {
        screen_name: "jmathai",
        name: "Jaisen Mathai"
        ...
    },
    ...
  ]

  // Access properties via the response array
  $firstFollower = $resp[0]->screen_name

  // Loop over the response as an an array
  foreach($resp as $follower){
      echo $follower->screen_name;
  }