「Services_Twitter」は、簡単にTwitterAPIを利用する為のPEARパッケージです。
今回の記事は、このパッケージでサポートされていないエンドポイントを使う方法の備忘録です。

Services_Twitterで利用できない物

例えば、statuses/following_timelineや、statuses/media_timeline等、
公式のREST APIドキュメントに記載されていないものは、
初期状態のServices_Twitterでは使用する事ができません。

• REST API Resources | Twitter Developers

※公式でアナウンスされていない物を使うわけですから、使用は勿論自己責任になります。

Services_Twitterにエンドポイントを追加する方法

Services_Twitterは、XMLで使用できるエンドポイントを管理していて、
そこに定義されていない物を呼びだそうとすると例外を吐く作りになっています。

api.xmlの所在

エンドポイントの定義ファイルである「api.xml」は、
PEARのインストールディレクトリ内の

data/Services_Twitter/data/api.xml

に置いてあります。
これにを追加してやれば、エンドポイントを使えるようになる仕組み。
ただ、これを直接編集するのもちょっとアレだなぁと思い…

XMLを指定してエンドポイントを追加出来るように拡張してみる

自前のxmlファイルのパスを引数に突っ込んで、
未定義のエンドポイントを足せるようにServices_Twitterクラスを拡張してみます。

書いてみた物

• Servces_Twitterを拡張して定義ファイルを追加で読み込めるようにする。 — Gist

category as $category) {
            $catName = (string)$category['name'];
            if( !is_array( $this->api[$catName] ) ){
                $this->api[$catName] = array();
            }
            foreach ($category->endpoint as $endpoint) {
                $this->api[$catName][(string)$endpoint['name']] = $endpoint;
            }
        }
    }
}

うん、ものすごくたいした拡張ではないですね。
使い方は、addAPIメソッドにXMLへのパスを突っ込むだけ。

<?php

$foo = new MY_Services_twitter();
$foo->addAPI( "/the/path/to/your/api.xml" );

試しにエンドポイントを追加してみたXML

試しにfollowing_timelinとmedias_timelineを追加する為のXMLを記述してみます。

仕様は未公開のうえ、パラメータの試験とかはやってないので、
繰り返しますがご使用は自己責任で。
以下の例のパラメータは、公式のWebサイトで使われている物を
それっぽく適当に突っ込んでいます。

<api>
    <category name="statuses">
        <endpoint name="following_timeline" method="GET" auth_required="false">
            <formats>xml,json,rss,atom</formats>
            <param name="include_entities" type="boolean" required="false" />
            <param name="include_available_feature" type="boolean" required="false" />
            <param name="contributor_details" type="boolean" required="false" />
            <param name="user_id" type="id_or_screenname" required="false" />
            <param name="screen_name" type="id_or_screenname" required="false" />
        </endpoint>
        <endpoint name="media_timeline" method="GET" auth_required="false">
            <formats>xml,json,rss,atom</formats>
            <param name="offset" type="integer" required="false" />
            <param name="count" type="integer" required="false" />
            <param name="score" type="boolean" required="false" />
            <param name="filter" type="boolean" required="false" />
            <param name="include_entities" type="boolean" required="false" />
            <param name="user_id" type="id_or_screenname" required="false" />
            <param name="screen_name" type="id_or_screenname" required="false" />
        </endpoint>
    </category>
</api>

まとめ

Services_Twitterではエンドポイントへのアクセスを__callで実装していて、
目新しかったので参考になりました。
今度機会があったら使ってみよう。オーバーロード。

• PHP: オーバーロード – Manual

Twitterが最早ただのサービスとしてではなく「プラットフォーム」として広まる中で、
これを活用したサービスの開発は我々の一つの課題となりつつあります。
anywhereを利用した認証は以前触れましたが、
今回はPHPでOAuth認証をする方法をまとめてみます。

事前準備

アプリケーションの登録

まずはTwitterでアプリケーションを登録しなければなりません。
» New Twitter Application | dev.twitter.com
※個人的にここのCaptchaはかなり手強かったです

必要事項を明記して登録すると、OAuthに必要な情報を出力してくれます。
特に必要な項目は、次の三つ。きちんと控えておきます。

• Consumer key
• Consumer secret
• Registerd OAuth Callback URL
  
  （Twitter側で認証が完了した後で戻ってくる為のページURL）

PEARパッケージのインストール

以下のパッケージが必要になりますので、インストールしておきます。

• Services_Twitter
• HTTP_OAuth

STEP:0 認証の準備

まず情報を整理して変数に突っ込んでおきましょう。
また、PEARパッケージのロードとsession_startも忘れずに。

session_start();

// [1] ライブラリのロード
require_once("Services/Twitter.php");
require_once("HTTP/OAuth/Consumer.php");

// [2] URL情報
$request_token_url = "http://api.twitter.com/oauth/request_token";
$access_token_url = "http://api.twitter.com/oauth/access_token";
$authorize_url = "http://api.twitter.com/oauth/authorize";

// [3] アプリケーションの情報
$consumer_key = "<貴方のConsumer Key>";
$consumer_secret = "<貴方のConsumer Secret>";
$callback_url = "<貴方のCallback URL>";

2 URL情報は共通です。
3 アプリケーションの情報は各々固有な物になるので、
登録時にもらったキーと設定したURLを格納します。

STEP1: 「リクエストトークン」を取得

まずはじめにHTTP_OAuthを介して「リクエストトークン」を頂き、
Twitterの認証用のURLを取得します。
そして必要とあらば、リダイレクトさせてあげます。

// [1] インスタンス生成
$consumer = new HTTP_OAuth_Consumer( $consumer_key, $consumer_secret );

// [2] getRequestTokenでリクエストトークンを取得
$consumer->getRequestToken( $request_token_url, $callback_url );

// [3] getToken/getTokenSecretで、トークンをセッションに保存
$_SESSION["request_token"] = $consumer->getToken();
$_SESSION["request_token_secret"] = $consumer->getTokenSecret();

// [4] getAuthorizeUrlでURLを取得
$auth_url = $consumer->getAuthorizeUrl( $authorize_url );

// [5] 必要とあらばリダイレクト
header( "Location: " . $auth_url );

STEP:2 Twitter側でアプリケーションの使用を「許可」する

認証用のURLに飛ばすとユーザにはこんなページが表示されます。
「許可する」をクリックすると、アプリケーション登録時に設定した「Callback URL」に、
パラメータにトークンを携えて戻ってきてくれます。

こんな感じに。

http://www.example.com/?oauth_token=<トークン>&oauth_verifier=<トークン>

STEP:3 「アクセストークン」を取得する

今度は、STEP2で飛ばされた先の「Callback URL」での処理となります。
ユーザがパラメータに携えてきたトークンを元に、「アクセストークン」を取得します。
STEP1とは別スクリプトになるケースも多いと思いますが、（その前提で書いています）
STEP:0での変数が必要になるので忘れずにロード/格納しておきましょう。

// [1] インスタンスの生成
$consumer = new HTTP_OAuth_Consumer( $consumer_key, $consumer_secret );

// [2] セッションに保存しておいたリクエストトークンを$consumerにセットする
$consumer->setToken( $_SESSION["request_token"] );
$consumer->setTokenSecret( $_SESSION["request_token_secret"] );

// [3] getAccessTokenでアクセストークンを取得
$consumer->getAccessToken( $access_token_url, $_GET["verifier"] );

// [4] セッションにアクセストークンを保存
$_SESSION["access_token"] = $consumer->getToken();
$_SESSION["access_token_secret"] = $consumer->getTokenSecret();

パラメータで渡されたトークンは、3の第二引数で使用されます。
4で生成されたアクセストークンが最終的なトークンとなります。（お疲れ様でした！）

STEP:4 貰った「アクセストークン」でAPIにアクセス

いよいよアクセストークンを元に、TwitterAPIにアクセスします。
今まで通りにHTTP_OAuth_Consumerクラスを用いるのですが、
コンストラクタの第3/第4引数にアクセストークンを渡す点に注意です。

// [1] コンシューマインスタンスを生成
$consumer = new HTTP_OAuth_Consumer(
    $consumer_key,
    $consumer_secret,
    $_SESSION["access_token"],
    $_SESSION["access_token_secret"]
);
// [2] Twitterインスタンスを生成し、コンシューマを渡す
$twitter = new Services_Twitter;
$twitter->setOAuth($consumer);

これで$twitterにTwitterAPIを使う能力が備わったはずです。（なんかかっこいい）
試しにその能力を奮ってみましょう。

// ユーザのホームタイムラインを出力してみる
$timeline = $twitter->statuses->home_timeline();
foreach($tl as $t){
    echo $t->text;
    echo "<br />";
}

連々とツイートが表示されたら成功です。
実際に$twitterにどのような力が備わるのかについては、
公式のTwitterAPIドキュメントをご参照ください。
cf) Twitter API Wiki / Twitter API Documentation

まとめ

とにかくトークンがいっぱい飛び交うので気がとーくんなります。
今後使う機会も多くなって来ると思うので、覚えておかねば…。

2010/10/25

URLをhttpsからhttpに変更。SSLを使う場合は別途設定が必要になります。
PHPでTwitter APIのOAuthを使う方法まとめ – 頭ん中