Installation

With Composer

The recommended and easy as pie method is Composer. Setup require in your projects composer.json file. Latest release:

composer require abraham/twitteroauth

Import the TwitterOAuth class.

require "vendor/autoload.php";

use Abraham\TwitterOAuth\TwitterOAuth;

Start making API requests.

$connection = new TwitterOAuth(CONSUMER_KEY, CONSUMER_SECRET, $access_token, $access_token_secret);
$content = $connection->get("account/verify_credentials");

Version support

PHP versions listed as "active support" or "security fixes only" are supported.

The old fashioned way

Download the latest release and unpack in a twitteroauth directory. Require the autoloader that will in turn require the TwitterOAuth classes automatically.

require "twitteroauth/autoload.php";

use Abraham\TwitterOAuth\TwitterOAuth;

Start making API requests.

$connection = new TwitterOAuth(CONSUMER_KEY, CONSUMER_SECRET, $access_token, $access_token_secret);
$content = $connection->get("account/verify_credentials");

Authorization flow

This site is a working example. Sign in with Twitter to see the flow.

Usage

Unlike many Twitter API libraries, TwitterOAuth doesn't provide a custom function for every API method. Instead there are a couple of generic functions so that as Twitter adds features to the API you don't need to update the library. Here is an example of GET statues/home_timeline.

HTTP
GET https://api.twitter.com/1.1/statuses/home_timeline.json?count=25&exclude_replies=true
TwitterOAuth
$statuses = $connection->get("statuses/home_timeline", ["count" => 25, "exclude_replies" => true]);

Methods

TwitterOAuth provides a couple of minimalist wrappers around Twitter's API methods.

OAuth

Only used when authorizing access to a users account. Includes API methods like POST oauth/request_token and POST oauth/access_token.

Example
$access_token = $connection->oauth("oauth/access_token", ["oauth_verifier" => "nMznkpFRTMCuNMsmALzel9FgPlmWQDWg"]);

URL

This is a special wrapper that doesn't hit the API. It builds the URL where users will authorize access to their account at. Only used for GET oauth/authorize and GET oauth/authenticate.

Example
$url = $connection->url("oauth/authorize", ["oauth_token" => "EaQLH34YD8pgKkUiSp8RbjjOgNxIYVh7"]);

GET

API methods that are HTTP GET requests. E.g. GET search/tweets.

HTTP
GET https://api.twitter.com/1.1/search/tweets.json?q=twitterapi
TwitterOAuth
$statuses = $connection->get("search/tweets", ["q" => "twitterapi"]);

POST

API methods that are HTTP POST requests. E.g. POST statuses/update.

HTTP
POST https://api.twitter.com/1.1/statuses/update.json?status=hello%20world
TwitterOAuth
$statues = $connection->post("statuses/update", ["status" => "hello world"]);

Media

Upload images using POST media/upload.

$connection = new TwitterOAuth(CONSUMER_KEY, CONSUMER_SECRET, $access_token, $access_token_secret);
$media1 = $connection->upload('media/upload', ['media' => '/path/to/file/kitten1.jpg']);
$media2 = $connection->upload('media/upload', ['media' => '/path/to/file/kitten2.jpg']);
$parameters = [
    'status' => 'Meow Meow Meow',
    'media_ids' => implode(',', [$media1->media_id_string, $media2->media_id_string])
];
$result = $connection->post('statuses/update', $parameters);

Streaming

Streaming is not currently supported.

Proxy

HTTP proxy support can be enabled like this.

$connection = new TwitterOAuth(CONSUMER_KEY, CONSUMER_SECRET, $access_token, $access_token_secret);
$connection->setProxy([
    'CURLOPT_PROXY' => '127.0.0.0',
    'CURLOPT_PROXYUSERPWD' => '',
    'CURLOPT_PROXYPORT' => 8080,
]);

Error handling

After every request you should validate it was a success.

$statues = $connection->post("statuses/update", ["status" => "hello world"]);
if ($connection->getLastHttpCode() == 200) {
    // Tweet posted succesfully
} else {
    // Handle error case
}

Changing timeout settings

If you experience any timeout errors you can change the default timeout settings for cURL.

$connection = new TwitterOAuth(CONSUMER_KEY, CONSUMER_SECRET, $access_token, $access_token_secret);
$connection->setTimeouts(10, 15);

The first parameter corresponds to the timeout for the connect phase and the second to the maximum time the request is allowed to take.