TwistOAuth

Advanced PHP Twitter library.
Version 3.1.0

Requirements

• PHP version 5.3.2 or later
• libcurl (Sorry, required version is unknown)

Features

Basic:

• Using GZIP compressed connections
• Automatically decode responses
• Automatically fix weird responses
• Exception handling
• Requests for REST API
• Requests for Streaming API
• Requests using OAuth Echo
• Requests via Proxy
• Multipart requests

Abusing:

• Asynchronous Multiple requests
• Asynchronous Multiple streaming
• Direct OAuth authentication

Preparation

1. Download this library

You can choose one of the following methods.

Direct Download

Click here to save TwistOAuth.phar in your working directory.

Composer

Modify require directive in composer.json.

{
    "require": {
        "mpyw/twistoauth": "@dev"
    }
}

If you choose this, replace all

require 'TwistOAuth.phar';

into

require 'vendor/autoload.php';

in examples.

2. Register your application

You can manage your API keys in https://apps.twitter.com. Now, let's register your own application.

1. Click Create New App
2. Fill Name Description WebSite.
3. Fill Callback URL. By default, users are redirected here after successfully authenticating.
4. Read rules and check Yes, I agree.
5. Click Create your Twitter application.

NOTE: localhost is not available for Callback URL. Use 127.0.0.1 instead.

3. Change application permissions

By default, you can only read tweets but cannot post tweets. You have to configure permission settings.

1. Open detail page of your application.
2. Click Permissions Tab.
3. Select Read, Write and Access direct messages.
4. Click Update settings.

4. Note your consumer_key and consumer_secret

These parameters are identifier for your application.

1. Open detail page of your application.
2. Click API Keys Tab.
3. Note API key and API secret. They mean consumer_key and consumer_secret.

5. Generate your access_token and access_token_secret

These parameters are identifier for your account.

1. Open detail page of your application.
2. Click API Keys Tab.
3. Click Generate my access token.
4. Note Access token and Access token secret.

Contents

• Examples
• Details

FAQ

• How can I learn about Twitter API?
• Aren't there any nice authentication tools for obtaining tokens?
• How to use OAuth 2.0 authentication flow?
• What is oauth_verifier?
• What is oauth_callback?
• How to use $to in callback closure?
• Are all classes immutable?
• Why don't you use namespace?
• Tweets are already escaped... wtf!?
• User description contains unescaped &... wtf!?

How can I learn about Twitter API?

Learn from documentation.

• REST API: endpoints
• REST API: field guides
• Streaming API: endpoints and field guides

Or watch actual response. The following tool is very very useful.

• twitSandbox

Aren't there any nice authentication tools for obtaining tokens?

Try this tool.
I absolutely promise you that I never record your credentials.
But please never use if you cannot trust me even a little.

• TwistHelper

How to use OAuth 2.0 authentication flow?

Sorry, it is not available with this library. Use OAuth 1.0a instead.

What is oauth_verifier ?

It is required for calling the following methods.

• TwistOAuth::renewWithAccessToken()
• TwistOAuth::curlPostAccessToken()

You can get it after user redirecting.

$oauth_verifier = filter_input(INPUT_GET, 'oauth_verifier');

What is oauth_callback ?

It is not required, but you can apply it for calling the following methods.

• TwistOAuth::renewWithRequestToken()
• TwistOAuth::curlPostRequestToken()

There are three value types.

Name	Example Value	Authentication Type
Empty String	""	PIN or URL (Use default setting)
URL	"http://example.com/callback.php"	URL
Out-Of-Band	"oob"	PIN

WARNING:
You can only use URL if your application is configured as Browser Application.
This means Callback URL is not empty.

How to use $to in callback closure?

Use use().

$to->streaming('user', function ($status) use ($to) { ... });

How to ignore TwistException thrown?

Now your code is:

try {
    $to->post('statuses/update', array('status' => 'test'));
} catch (TwistException $e) { } // This is very lengthy!!!

To ignore all responses...

curl_exec($to->curlPost('statuses/update', array('status' => 'test'))); // Wow, cool

Are all classes immutable?

Yes.

$a = new TwistOAuth('CK', 'CS');
$b = $a->renewWithRequestToken();
var_dump($a === $b); // false

However, you can change propety values by directly calling __construct().

$obj = new TwistOAuth('a', 'b');
$obj->__construct('c', 'd'); // Break immutable rules

Why don't you use namespace?

I do not use namespace in TwistOAuth.php.
This is because to give priority to the compatibility with abraham/twitteroauth.

Tweets are already escaped... wtf!?

HTML special chars in texts of statuses are already escaped by Twitter like this.

$status->text = htmlspecialchars($status->text, ENT_NOQUOTES, 'UTF-8');

WARNING:
The flag is ENT_NOQUOTES, not ENT_QUOTES or ENT_COMPAT.
The following snippet may print broken HTML.

<input type="text" name="text" value="<?=$status->text?>">

You should do like this. Do not forget to set 4th parameter into false.

<input type="text" name="text" value="<?=htmlspecialchars(status->text, ENT_QUOTES, 'UTF-8', false)?>">

User description contains unescaped &... wtf!?

HTML special chars in others are already sanitized by Twitter like this.

$user->name        = str_replace(array('<', '>'), '', $user->name);
$user->description = str_replace(array('<', '>'), '', $user->description);

WARNING:
& is not replaced into &.
The following snippet may print broken HTML.

name: <?=$user->name?><br>

You should do like this.

name: <?=htmlspecialchars($user->name, ENT_QUOTES, 'UTF-8')?><br>