動かざることバグの如し

3分経てば忘れそうなことをメモします

UltimateOAuth.php のREADME-Japanese.md

UltimateOAuth

非常に高機能な PHPTwitterライブラリです。

English

@Version: 5.3.4
@Author : CertaiN
@License: BSD 2-Clause
@GitHub : http://github.com/certainist

[特長]

twitteroauthと使い方が非常によく似ています。
一方、このライブラリ独自の機能もあります。

項目 twitteroauth UltimateOAuth
サポートするPHPバージョン 5.2.0以降 5.2.0以降
依存 cURL, OAuth.php 無し(単一ファイル)
奇形レスポンスの自動修正 ×
画像アップロード ×
同期リクエスト
非同期リクエスト ×
疑似xAuth認証 ×
アカウント作成 ×
API制限回避 ×

[クラス・メソッド一覧]

UltimateOAuth

$uo = new UltimateOAuth(
    $consumer_key = "", $consumer_secret = "", $access_token = "", $access_token_secret = ""
);

$uo->get                   ($endpoint,                  $params = array()                       );
$uo->post                  ($endpoint,                  $params = array(), $wait_response = true);
$uo->postMultipart         ($endpoint,                  $params = array(), $wait_response = true);
$uo->OAuthRequest          ($endpoint, $method = "GET", $params = array(), $wait_response = true);
$uo->OAuthRequestMultipart ($endpoint,                  $params = array(), $wait_response = true);

$uo->directGetToken ($username, $password);

$uo->getAuthorizeURL    ($force_login = false);
$uo->getAuthenticateURL ($force_login = false);

UltimateOAuthMulti

$uom = new UltimateOAuthMulti;

$uom->enqueue ($uo, $method, $arg1, $arg2, $arg3, ...);
$uom->execute ($wait_processes = true, $use_cwd = false);

UltimateOAuthRotate

UltimateOAuthRotate クラスは __call() メソッドを用いることにより、 UltimateOAuth クラスのメソッドのうち
get(), post(), postMultipart(), OAuthRequest(), OAuthRequestMultipart()
には対応しています。

$uor = new UltimateOAuthRotate;

$uor->__call       ($name, $arguments);

$uor->register     ($name, $consumer_key, $consumer_secret);
$uor->login        ($username, $password, $return_array = false, $successively = false);
$uor->setCurrent   ($name);
$uor->getInstance  ($name);
$uor->getInstances ($type);

0. マルチリクエスト設定

UltimateOAuthConfig の定数を編集してください。

  • 無料レンタルサーバーなどで proc_open() 関数が禁止されている場合

    • USE_PROC_OPEN: FALSE
    • FULL_URL_TO_THIS_FILE: このファイル自身への 絶対URL (絶対パスでは無い)
  • proc_open() 関数が問題なく使える場合

    • USE_PROC_OPEN: TRUE (デフォルト)

1. OAuth認証

ユーザーに認証させるためには、次のステップを踏んでください。

prepare.php (ログインページに遷移させるスクリプト)

<?php

// ライブラリ読み込み
require_once('UltimateOAuth.php');

// セッション開始
session_start();

// UltimateOAuthオブジェクトを新規作成してセッションに保存
$_SESSION['uo'] = new UltimateOAuth('YOUR_CONSUMER_KEY', 'YOUR_CONSUMER_SECRET');
$uo = $_SESSION['uo'];

// リクエストトークンを取得
$res = $uo->post('oauth/request_token');
if (isset($res->errors)) {
    die(sprintf('Error[%d]: %s',
        $res->errors[0]->code,
        $res->errors[0]->message
    ));
}

// Authenticateで認証するなら
$url = $uo->getAuthenticateURL();
// Authorizeで認証するなら
// $url = $uo->getAuthorizeURL();

// Twitterのログインページに遷移
header('Location: '.$url);
exit();

ユーザーがログインを完了すると、あらかじめ指定した コールバックURLoauth_verifier を伴って遷移します。
このパラメータは Twitter Developers で事前に編集しておかなければなりません。

callback.php (ログイン後に遷移されるスクリプト)

<?php

// ライブラリ読み込み
require_once('UltimateOAuth.php');

// セッション開始
session_start();

// セッションタイムアウトチェック
if (!isset($_SESSION['uo'])) {
    die('Error[-1]: Session timeout.');
}
$uo = $_SESSION['uo'];

// oauth_verifierパラメータが存在するかチェック
if (!isset($_GET['oauth_verifier'])) {
    die('Error[-1]: No oauth_verifier');
}

// アクセストークン取得
$res = $uo->post('oauth/access_token', array(
    'oauth_verifier' => $_GET['oauth_verifier']
));
if (isset($res->errors)) {
    die(sprintf('Error[%d]: %s',
        $res->errors[0]->code,
        $res->errors[0]->message
    ));
}

// アプリケーションのメインページに遷移
header('Location: main.php');
exit();

main.php (メインページ)

<?php

// ライブラリ読み込み
require_once('UltimateOAuth.php');

// セッション開始
session_start();

// セッションタイムアウトチェック
if (!isset($_SESSION['uo'])) {
    die('Error[-1]: Session timeout.');
}
$uo = $_SESSION['uo'];

// ツイートしてみましょう
$uo->post('statuses/update', 'status=テストツイート!');

備考1:
アクセストークンとアクセストークンシークレットを既に所持している場合は、
以下のようにするだけでログイン済みのように出来ます。

<?php

require_once('UltimateOAuth.php');

$uo = new UltimateOAuth($consumer_key, $consumer_secret, $access_token, $access_token_secreet);

備考2:
認証済みのUltimateOAuthオブジェクトを文字列として保存・復元したい場合は、
serialize() 関数と unserialize() 関数をご利用ください。


2-1. UltimateOAuthクラス詳細

UltimateOAuth::__construct()

UltimateOAuthインスタンスを生成します。

$uo = new UltimateOAuth;
$uo = new UltimateOAuth($consumer_key, $consumer_secret);
$uo = new UltimateOAuth($consumer_key, $consumer_secret, $access_token, $access_token_secret);

引数

  • (string) [$consumer_key]
    省略された場合は公式アプリからランダムなものが選択されます。
  • (string) [$consumer_secret]
    省略された場合は公式アプリからランダムなものが選択されます。
  • (string) [$access_token]
    後で認証を行わない場合はここで指定が必要です。
  • (string) [$access_token]
    後で認証を行わない場合はここで指定が必要です。

UltimateOAuth::OAuthRequest()

リクエストにはこのメソッドが主体として使われます。

$uo->OAuthRequest($endpoint, $method = "GET", $params = array(), $wait_response = true);

引数

  • (string) $endpoint
    APIドキュメントをご覧ください。
    例:
    statuses/update, 1.1/statuses/update, https://api.twitter.com/1.1/statuses/update.json

  • (string) [$method]
    POST または GET 。 大文字小文字を区別しません。 デフォルトは GET です。

  • (mixed) [$params]
    クエリ文字列 または 連想配列
    例: php $params = 'status=TestTweet'; $params = array('status' => 'TestTweet'); ファイルをアップロードするには: php $params = '@image=' . $filename; $params = array('@image' => $filename); $params = array('image' => base64_encode(file_get_contents($filename)));

    注意:
    statuses/update_with_media にはこのメソッドを用いることは出来ません。
    代わりに UltimateOAuth::postMultipart() をご使用ください。

  • (boolean) [$wait_resposne]
    デフォルトは TRUE です。
    詳細は下記。

返り値

  • リクエストが成功した場合、デコードされたJSONデータが返されます。
    多くの場合は stdClass として返されます。
    一部のエンドポイントは 配列 として返されます。
    例: statuses/home_timeline, users/lookup
    一部のエンドポイントは クエリ文字列 を取得しますが、自動的に stdClass に変換されます。
    例: oauth/request_token, oauth/access_token

  • 失敗時には エラーオブジェクト が返されます。
    下記のような構造を持っています。

    • (integer) $response->errors[0]->code
      HTTPステータスコード 。 エラーコードでは無い。
      既に存在しているエラーコードはHTTPステータスコードで上書きされます。
      ローカルでエラーが発生した場合、多くの場合は -1 となります。

    • (string) $response->errors[0]->message
      エラーメッセージ。

  • $wait_responseFALSE のとき、 レスポンスを待たず直ちに NULL を返します。


UltimateOAuth::get()
UltimateOAuth::post()

UltimateOAuth::OAuthRequest() のラッパーメソッド

$uo->get($endpoint, $params);
$uo->post($endpoint, $params, $wait_response);

UltimateOAuth::postMultipart()
UltimateOAuth::OAuthRequestMultipart()

主に statuses/update_with_media に対して用いられます。
postMultipart()OAuthRequestMultipart() は完全に同一のものです。

$uo->postMultipart($endpoint, $params, $wait_response);
$uo->OAuthRequestMultipart($endpoint, $params, $wait_response);

引数

  • (string) $endpoint
    例: statuses/update_with_media

  • (string) [$params]
    例: php $params = '@media[]=' . $filename; $params = array('@media[]' => $filename); $params = array('media[]' => file_get_contents($filename));

  • (boolean) [$wait_response]
    UltimateOAuth::OAuthRequest() のものと同一です。
    デフォルトは TRUE です。

返り値

  • UltimateOAuth::OAuthRequest() のものと同一です。

UltimateOAuth::directGetToken()

あたかもOAuth認証xAuth 認証のように行えるメソッドです。
これは 疑似xAuth 認証と呼ばれます。

$uo->directGetToken($username, $password);

引数

返り値

  • oauth/access_token を用いたときの UltimateOAuth::OAuthRequest() のものと同一です。

UltimateOAuth::getAuthenticateURL()
UltimateOAuth::getAuthorizeURL()

<?php
$uo->getAuthenticateURL($force_login);
$uo->getAuthorizeURL($force_login);

引数

  • (boolean) $force_login
    既にログイン済みのユーザーを再認証させるかどうか。
    デフォルトは FALSE です。

返り値

  • URL文字列。

備考: AuthenticateAuthorize の違いは?

Authenticate Authorize
新規ユーザー Twitterに遷移 Twitterに遷移
ログイン済みユーザー Twitterに遷移、但しアプリケーション設定で
Allow this application to be used to Sign in with Twitter,
にチェックを入れた場合は、設定したコールバックにすぐ遷移する
Twitterに遷移

2-2. UltimateOAuthMultiクラス詳細

複数のリクエストを 並列処理 で高速に行えます。


UltimateOAuthMulti::__construct()

UltimateOAuthMultiインスタンスを生成します。

$uom = new UltimateOAuthMulti;

UltimateOAuthMulti::enqueue()

新しいジョブを追加します。

$uom->enqueue($uo, $method, $arg1, $arg2, ...);

引数

  • (UltimateOAuth) $uo
    UltimateOAuth オブジェクト。

  • (string) $method
    メソッド名。 HTTPメソッドではなく クラスメソッド を意味します。
    例: post

  • (mixed) [$arg1], [$arg2], [...]
    例: 'statuses/update', 'status=TestTweet'

注意

バイナリデータを引数に含むことは出来ません。
その場合は @ プレフィックスをつけてファイルへのパスを指定するようにしてください。
例: 'status=test&@media[]=test.jpg'


UltimateOAuthMulti::execute()

全てのジョブを実行します。
実行後ジョブはすべて消去されます。

$uom->execute($wait_processes, $use_cwd);

引数

  • (boolean) [$wait_processes]
    同期リクエストを行うかどうか。 デフォルトは TRUE です。

  • (boolean) [$use_cwd]
    (ファイルパス指定の起点に)カレントワーキングディレクトリを使うか、このライブラリが存在するディレクトリを使うか。
    デフォルトは FALSE (UltimateOAuth.phpのディレクトリ) です。
    USE_PROC_OPEN == False のときにこのオプションは TRUE に出来ません。

返り値

  • 実行結果の 配列

2-3. UltimateOAuthRotateクラス詳細

簡単に API規制回避 を行えます。
さらに下記のような、 非常に役に立つ 隠しエンドポイント を利用できるようになります。

  • GET activity/about_me
    自分に関するアクティビティを取得。
  • GET activity/by_friends
    フレンドに関するアクティビティを取得。
  • GET statuses/:id/activity/summary
    指定されたツイートに関するアクティビティを取得。
  • GET conversation/show/:id
    指定されたツイートを含む会話を取得。
  • POST friendships/accept
    指定されたフォローリクエストを受理する。
  • POST friendships/deny
    指定されたフォローリクエストを拒否する。
  • POST friendships/accept_all
    全てのフォローリクエストを受理する。
  • POST account/generate
    アカウントを作成する。

UltimateOAuthRotate::__construct()

UltimateOAuthRotateインスタンスを生成します。

$uor = new UltimateOAuthRotate;

UltimateOAuthRotate::register()

あなた自身がTwitterに登録したアプリケーションを登録します。

$uor->register($name, $consumer_key, $consumer_secret);

引数

  • (string) $name
    公式アプリの名前と重複しなければどんな名前でもOKです。識別用として使われます。
    例: my_app_01

  • (string) $consumer_key

  • (string) $consumer_secret

返り値

  • 結果を TRUEFALSE で返します。

UltimateOAuthRotate::login()

登録されたアプリケーション全てでログインします。
このメソッドは内部的に UltimateOAuthMulti クラスを利用しています。

$uor->login($username, $password, $return_array, $successively);

引数と返り値

  • (string) $username
    スクリーンネーム またはEメールアドレス。

  • (string) $password
    パスワード。

  • (string) [$return_array]
    レスポンスを 配列 として返すか、全て成功したかどうかを ブール値 で返すか。
    デフォルトは FALSE (ブール値で返す) です。

  • (boolean) [$successively]
    逐次ログイン処理を行うか、UltimateOAuthMultiクラスを用いて並列処理で行うか。
    デフォルトは FALSE (UltimateOAuthMultiクラスを利用) です。


UltimateOAuthRotate::setCurrent()

POST リクエストで使われるアプリケーションを選択。
GETリクエストは無関係。

$uor->setCurrent($name);

引数

  • (string) $name
    例: my_app_01

返り値

  • 結果を TRUEFALSE で返します。

UltimateOAuthRotate::getInstance($name)

指定されたUltimateOAuthインスタンスクローン を取得します。

$uor->getInstance($name);

引数

  • (string) $name
    例: my_app_01

返り値


UltimateOAuthRotate::getInstances()

全てのUltimateOAuthインスタンスクローン を取得します。

$uor->getInstances($type);

引数

返り値

  • UltimateOAuthオブジェクトの 配列 を返します。

UltimateOAuthRotate::__call()

UltimateOAuthメソッドをマジックメソッド __call() を用いてコールします。

例:

$uor->get('statuses/home_timeline');

3. その他の例

アカウント作成

重要

このライブラリはレスポンスヘッダーに含まれるコンテンツのうち、
x-twitter-new-account-oauth-access-tokenx-twitter-new-account-oauth-secret
をプロパティとして返り値のプロパティに適用します。
これには $response->access_token$response->access_token_secret でアクセスすることが出来ます。

サンプル

<?php

// このライブラリを読み込む
require_once('UltimateOAuth.php');

// UltimateOAuthRotateからアカウント作成が可能なインスタンスを取得
$uor = new UltimateOAuthRotate;
$base = $uor->getInstance('Twitter for Android Sign-Up');

// 自分自身をまず認証させる
$base->directGetToken('Your screen_name', 'Your password');

// アカウントを作成する
$random_string = substr(md5(mt_rand()), 0, 15);
$res = $base->post('account/generate', array(
    'name'        => 'HAHAHAHA',
    'screen_name' => $random_string,
    'password'    => 'test1234',
    'email'       => $random_string . '@examples.com',
));

// エラーチェック
if (isset($res->errors)) {
    die(sprintf('Error[%d]: %s',
        $res->errors[0]->code,
        $res->errors[0]->message
    ));
}

// テストツイート
$tmp = $uor->getInstance('Twitter for Android');
$uo = new UltimateOAuth($tmp->consumer_key, $tmp->consumer_secret, $res->access_token, $res->access_token_secret);
$uo->post('statuses/update', 'status=HAHAHAHA!!!!');

カーソルを追跡する

いくつかのエンドポイントでは全ての結果を得るためにカーソルを追跡する必要があります。

サンプル

全フォロワーのうち250人のスクリーンネームを抽選します。

<?php

// このライブラリを読み込む
require_once('UltimateOAuth.php');

// インスタンス生成
$uo = new UltimateOAuth('CK', 'CS', 'AT', 'AS');

// 初期化
$cursor = '-1';
$result = array();
$screen_names = array();

// カーソルを追跡しながらフォロワーの全user_idを取得
do {
    $res = $uo->get('followers/ids', 'stringify_ids=1&cursor=' . $cursor);
    if (isset($res->errors)) {
        die(sprintf('Error[%d]: %s',
            $res->errors[0]->code,
            $res->errors[0]->message
        ));
    }
    $result += array_flip($res->ids);
    $cursor = $res->next_cursor_str;
} while ($cursor);

// 250個以内で抽選
$count = count($result);
$result = $count <= 250 ? array_keys($result) : array_rand($result, 250);

// それらのuser_idに対応するscreen_nameを取得
for ($i = 0; $i < 250; $i += 100) {
    $res = $uo->get('users/lookup', 'user_id=' . implode(',', array_slice($result, $i, 100)));
    if (isset($res->errors)) {
        die(sprintf('Error[%d]: %s',
            $res->errors[0]->code,
            $res->errors[0]->message
        ));
    }
    foreach ($res as $user) {
        $screen_names[] = $user->screen_name;
    }
}

// 出力
print_r($screen_names);

URLやメンションをエンティティ情報をもとにリンクする

こちらのライブラリをお使いください。
TwitterText