Permalink
Find file
8a5bca6 Jul 3, 2016
@abraham @olivertappin @magkopian @kinoute
186 lines (131 sloc) 6.67 KB
{% extends "base.html" %}
{% block content %}
<div class="page-header">
<h1>TwitterOAuth</h1>
<p class="lead">The most popular PHP library for use with the Twitter OAuth REST API.</p>
</div>
<h2>Installation <a href="https://github.com/abraham/twitteroauth-demo/blob/master/templates/index.html"><span class="glyphicon glyphicon-edit small" aria-hidden="true" title="Edit this page on GitHub"></span></a></h2>
<div class="btn-group" role="group" aria-label="...">
<button class="btn btn-default" type="button" data-toggle="collapse" data-target="#install-composer" aria-expanded="true" aria-controls="install-composer">Composer install</button>
<button class="btn btn-default" type="button" data-toggle="collapse" data-target="#install-manual" aria-expanded="false" aria-controls="install-manual">Manual install</button>
</div>
<div class="collapse in" id="install-composer">
<h4>With Composer</h4>
<p>The recommended and easy as pie method is <a href="https://getcomposer.org/">Composer</a>. Setup require in your projects composer.json file. Latest release: <a href="https://packagist.org/packages/abraham/twitteroauth"><img src="https://img.shields.io/packagist/v/abraham/twitteroauth.svg"></a></p>
<pre>
composer require abraham/twitteroauth
</pre>
<p>Import the TwitterOAuth class.</p>
<pre>
require "vendor/autoload.php";
use Abraham\TwitterOAuth\TwitterOAuth;
</pre>
<p>Start making API requests.</p>
<pre>
$connection = new TwitterOAuth(CONSUMER_KEY, CONSUMER_SECRET, $access_token, $access_token_secret);
$content = $connection->get("account/verify_credentials");
</pre>
</div>
<h4>Version support</h4>
<p>PHP versions <a href="https://secure.php.net/supported-versions.php">listed</a> as "active support" or "security fixes only" are supported.</p>
<div class="collapse" id="install-manual">
<h4>The old fashioned way</h4>
<p>Download the <a href="https://github.com/abraham/twitteroauth/releases">latest release</a> and unpack in a <code>twitteroauth</code> directory. Require the autoloader that will in turn require the TwitterOAuth classes automatically.</p>
<pre>
require "twitteroauth/autoload.php";
use Abraham\TwitterOAuth\TwitterOAuth;
</pre>
<p>Start making API requests.</p>
<pre>
$connection = new TwitterOAuth(CONSUMER_KEY, CONSUMER_SECRET, $access_token, $access_token_secret);
$content = $connection->get("account/verify_credentials");
</pre>
</div>
<h2>Authorization flow</h2>
<p>This site is a working example. <a href="/redirect.php"><img src="/images/sign-in-with-twitter-link.png" alt="Sign in with Twitter" title="Sign in with Twitter" /></a> to see the flow.</p>
<h2>Usage</h2>
<p>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 <a href="https://dev.twitter.com/rest/reference/get/statuses/home_timeline">GET statues/home_timeline</a>.</p>
<b>HTTP</b>
<pre>
GET https://api.twitter.com/1.1/statuses/home_timeline.json?count=25&exclude_replies=true
</pre>
<b>TwitterOAuth</b>
<pre>
$statuses = $connection->get("statuses/home_timeline", ["count" => 25, "exclude_replies" => true]);
</pre>
<h2>Methods</h2>
<p>TwitterOAuth provides a couple of minimalist wrappers around Twitter's API methods.</p>
<h3>OAuth</h3>
<p>Only used when authorizing access to a users account. Includes API methods like <a href="https://dev.twitter.com/oauth/reference/post/oauth/request_token">POST oauth/request_token</a> and <a href="https://dev.twitter.com/oauth/reference/post/oauth/access_token">POST oauth/access_token</a>.</p>
<b>Example</b>
<pre>
$access_token = $connection->oauth("oauth/access_token", ["oauth_verifier" => "nMznkpFRTMCuNMsmALzel9FgPlmWQDWg"]);
</pre>
<h3>URL</h3>
<p>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 <a href="https://dev.twitter.com/oauth/reference/get/oauth/authorize">GET oauth/authorize</a> and <a href="https://dev.twitter.com/oauth/reference/get/oauth/authorize">GET oauth/authenticate</a>.</p>
<b>Example</b>
<pre>
$url = $connection->url("oauth/authorize", ["oauth_token" => "EaQLH34YD8pgKkUiSp8RbjjOgNxIYVh7"]);
</pre>
<h3>GET</h3>
<p>API methods that are HTTP GET requests. E.g. <a href="https://dev.twitter.com/rest/reference/get/search/tweets">GET search/tweets</a>.</p>
<b>HTTP</b>
<pre>
GET https://api.twitter.com/1.1/search/tweets.json?q=twitterapi
</pre>
<b>TwitterOAuth</b>
<pre>
$statuses = $connection->get("search/tweets", ["q" => "twitterapi"]);
</pre>
<h3>POST</h3>
<p>API methods that are HTTP POST requests. E.g. <a href="https://dev.twitter.com/rest/reference/post/statuses/update">POST statuses/update</a>.</p>
<b>HTTP</b>
<pre>
POST https://api.twitter.com/1.1/statuses/update.json?status=hello%20world
</pre>
<b>TwitterOAuth</b>
<pre>
$statues = $connection->post("statuses/update", ["status" => "hello world"]);
</pre>
<h3>Media</h3>
<p>Upload images using <a href="https://dev.twitter.com/rest/reference/post/media/upload">POST media/upload</a>.</p>
<pre>
$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);
</pre>
<h3>Streaming</h3>
<p>Streaming is not currently supported.</p>
<h3>Proxy</h3>
<p>HTTP proxy support can be enabled like this.</p>
<pre>
$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,
]);
</pre>
<h2>Error handling</h2>
<p>After every request you should validate it was a success.</p>
<pre>
$statues = $connection->post("statuses/update", ["status" => "hello world"]);
if ($connection->getLastHttpCode() == 200) {
// Tweet posted succesfully
} else {
// Handle error case
}
</pre>
<h3>Changing timeout settings</h3>
<p>If you experience any timeout errors you can change the default timeout settings for cURL.</p>
<pre>
$connection = new TwitterOAuth(CONSUMER_KEY, CONSUMER_SECRET, $access_token, $access_token_secret);
$connection->setTimeouts(10, 15);
</pre>
<p>The first parameter corresponds to the timeout for the connect phase and the second to the maximum time the request is allowed to take.</p>
{% endblock %}