TwistOAuth

Warning: This package is abandoned and no longer maintained. Use mpyw/cowitter package instead.

Advanced PHP Twitter library.
Version 3.5.2

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": "~3.0"
    }
}

If you choose this, replace all

require __DIR__ . '/TwistOAuth.phar';

into

require __DIR__ . '/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 do I use OAuth 2.0 authentication flow?
• What is oauth_verifier?
• What is oauth_callback?
• How do I 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!?
• cURL causes SSL certificate problem error in Windows!

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 the following commandline utility.

• mpyw/twhelp (Cross-compiled binaries)

How do I 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 do I use $to in callback closure?

Use use().

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

How do I 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?

This is because of the compatibility with previous versions of abraham/twitteroauth.
I believe that the prefix Twist- will never collide with any other libraries.

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>

cURL causes SSL certificate problem error in Windows!

In the past library, this problem was done with the following solution.

// You are saying, "Hey libcurl, do not certificate whether I'm really talking to Twitter."
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);

However, it makes vulnerability for man-in-the-middle attack. Your connection can be hijacked even if using the protocol https://. This attack can be committed in the following case.

• Some DNS servers' caches are poisoned. Refer to DNS spoofing
• You are connecting a public access point that an attacker launched as a trap.

The right way is to download to add CA information to your computer.

1. Download ca-bundle.crt to save in the directory, which path should not contain multibyte characters.

# Good
C:\ca-bundles\ca-bundles.crt

# Bad
C:\Users\田所浩二\Documents\証明書\ca-bundles.crt

2. Add the following definition in php.ini.

curl.cainfo="C:\ca-bundles\ca-bundles.crt"

3. Restart Apache.