Zend_Gata は、いくつかの型のクラスを組み合わせたものです。

Google データサービスは、Atom Publishing Protocol (APP) および Atom syndication format に基づいたサービスです。 Zend_Gdata コンポーネントを用いて APP や Google サービスを扱うには、Zend_Gdata_App や Zend_Gdata そして Zend_Gdata_Spreadsheets などのサービスクラスを使用する必要があります。 サービスクラスには、サービスからデータのフィードを取得したり 新しいエントリをフィードに挿入したり 既存のエントリを更新したり削除したりといったメソッドがあります。

注意: Zend_Gdata を用いた実際に動作するサンプルプログラムが demos/Zend/Gdata ディレクトリにあります。 このサンプルはコマンドラインで動かすように作られていますが、 ウェブアプリケーション版にも簡単に書き換えられるでしょう。

Zend Framework の命名規約では、すべてのクラスは その存在位置のディレクトリ構造に基づいた名前をつける必要があります。 たとえば Spreadsheets に関する拡張クラスは Zend/Gdata/Spreadsheets/Extension/... 配下に置かれ、 その結果、クラス名は Zend_Gdata_Spreadsheets_Extension_... となります。ということは、スプレッドシートのセル要素のインスタンスを作成しようとしたら、 恐ろしく長い名前をタイプすることになるということです!

ということで、すべてのサービスクラス (Zend_Gdata_App、Zend_Gdata、Zend_Gdata_Spreadsheets など) に特別なファクトリメソッドを用意するようにしました。 これを用いることで、データモデルやクエリ、 その他のクラスのインスタンスをより簡単に作成できるようになります。 このファクトリメソッドは、マジックメソッド __call を用いて実装しています。このメソッドで、 $service->newXXX(arg1, arg2, ...) というコールをすべて処理しています。 XXX の値に基づいて、登録されているすべての 'パッケージ' からクラスを探します。 以下に例を示します。

$ss = new Zend_Gdata_Spreadsheets();

// Zend_Gdata_App_Spreadsheets_CellEntry を作成します
$entry = $ss->newCellEntry();

// Zend_Gdata_App_Spreadsheets_Extension_Cell を作成します
$cell = $ss->newCell();
$cell->setText('My cell value');
$cell->setRow('1');
$cell->setColumn('3');
$entry->cell = $cell;

// ... $entry を使用して、Google Spreadsheet の内容を更新します

継承ツリー内にある各サービス用クラス内で、 適切な 'パッケージ' (ディレクトリ) を登録します。 ファクトリメソッドは、これを使用してクラスを探します。

ほとんどの Google Data サービスは、 個人データへのアクセスやデータの保存、削除の前に Google サーバに対する認証を要求します。 Google Data の認証用に提供される実装は AuthSub および ClientLogin の二種類があります。 Zend_Gdata ではこれら両方の方式に対するインターフェイスを用意しています。

Google Data サービスに対するその他大半の問い合わせは、 認証を必要としません。

Zend_Gdata は Zend_Http_Client を用いてリクエストを google.com に送信し、結果を取得します。 ほとんどの Google Data リクエストに対する応答は Zend_Gdata_App_Feed あるいは Zend_Gdata_App_Entry クラスのサブクラスで返されます。

Zend_Gdata は、PHP アプリケーションの稼動しているホストが インターネットに直接つながっていることを想定しています。 Zend_Gdata クライアントは Google Data サーバへの接続を行います。

Zend_Gdata_App クラス、Zend_Gdata クラス、 あるいはそのサブクラスのひとつのオブジェクトを作成します。 各サブクラスではサービス固有のヘルパーメソッドを提供します。

Zend_Gdata_App のコンストラクタに渡すオプションの引数は Zend_Http_Client のインスタンスです。このパラメータを渡さなかった場合は、 Zend_Gdata はデフォルトの Zend_Http_Client オブジェクトを作成します。 これには、プライベートフィードにアクセスするための認証データは設定されていません。 Zend_Http_Client オブジェクトを自分で指定すると、 クライアントオブジェクトに対する設定オプションを指定できます。

$client = new Zend_Http_Client();
$client->setConfig( ...オプション... );

$gdata = new Zend_Gdata($client);

Zend Framework 1.7 以降、プロトコルのバージョン管理のサポートが追加されました。 これにより、クライアントおよびサーバで新機能をサポートしつつ、 過去との互換性を保持できるようになります。 ほとんどのサービスはバージョン管理を自前で行う必要はありませんが、 Zend_Gdata のインスタンスを直接作成する場合 (サブクラスを使わない場合) は、必要なプロトコルのバージョンを指定してサーバの機能にアクセスする必要があります。

$client = new Zend_Http_Client();
$client->setConfig( ...オプション... );

$gdata = new Zend_Gdata($client);
$gdata->setMajorProtocolVersion(2);
$gdata->setMinorProtocolVersion(null);

認証済みの Zend_Http_Client オブジェクトを作成する方法については、 認証のセクションも参照ください。

パラメータを指定することで、Zend_Gdata での問い合わせをカスタマイズできます。 クエリのパラメータは、 Zend_Gdata_Query のサブクラスを使用して指定します。 Zend_Gdata_Query クラスにはクエリパラメータを設定するメソッドが含まれ、 これを用いて GData サービスにアクセスします。 たとえば Spreadsheets のような個々のサービスでも クエリクラスを用意しており、そのサービスやフィードに合わせた独自のパラメータを定義しています。 Spreadsheets の CellQuery クラスは Cell Feed に対する問い合わせを行い、ListQuery クラスは List Feed に対する問い合わせを行います。 それぞれのフィードに対して別々のパラメータを指定できます。 GData 全体で使用できるパラメータについて、 以下で説明します。

これらの set 関数に対応する get 関数もあります。

$query = new Zend_Gdata_Query();
$query->setMaxResults(10);
echo $query->getMaxResults();   // 10 を返します

Zend_Gdata クラスでは、 特別なゲッターメソッドおよびセッターメソッドも実装しています。 つまり、パラメータの名前をクラスの仮想的なメンバとして扱うことができます。

$query = new Zend_Gdata_Query();
$query->maxResults = 10;
echo $query->maxResults;        // 10 を返します

すべてのパラメータを消去するには resetParameters() を使用します。複数のクエリで Zend_Gdata を使いまわす場合などに便利です。

$query = new Zend_Gdata_Query();
$query->maxResults = 10;
// ...フィードを取得します...

$gdata->resetParameters();      // すべてのパラメータを消去します
// ...別のフィードを取得します...

getFeed() を使用して、指定した URI からフィードを取得します。 この関数は、getFeed の二番目の引数で指定したクラスのインスタンスを返します。 このクラスのデフォルトは Zend_Gdata_Feed です。

$gdata = new Zend_Gdata();
$query = new Zend_Gdata_Query(
        'http://www.blogger.com/feeds/blogID/posts/default');
$query->setMaxResults(10);
$feed = $gdata->getFeed($query);

この後の節で、各 Google Data サービス用のヘルパークラス固有の関数について説明します。これらの関数により、 対応するサービスにあわせた適切な URI からフィードを取得できるようになります。

多くのエントリが含まれるフィードを取得した場合、 そのフィードはいくつかの「ページ」に分かれていることがあるかもしれません。 そのような場合には、各ページには次のページへのリンクが含まれることになります。 このリンクにアクセスするには getLink('next') を使用します。 この例は、フィードの次のページを取得する方法を示すものです。

function getNextPage($feed) {
    $nextURL = $feed->getLink('next');
    if ($nextURL !== null) {
        return $gdata->getFeed($nextURL);
    } else {
        return null;
    }
}

もしこのようにページに分かれているのが気に入らない場合は、 フィードの最初のページを Zend_Gdata_App::retrieveAllEntriesForFeed() に渡しましょう。そうすると、 すべてのエントリの内容をひとつのフィードにまとめてくれます。 この関数の使用法を、次の例で示します。

$gdata = new Zend_Gdata();
$query = new Zend_Gdata_Query(
        'http://www.blogger.com/feeds/blogID/posts/default');
$feed = $gdata->retrieveAllEntriesForFeed($gdata->getFeed($query));

大きなフィードに対してこの関数をコールすると、 処理に時間がかかるということに注意しましょう。 set_time_limit() で PHP の実行時間制限を拡大する必要があるかもしれません。

フィードを取得したら、次はそのデータを読み込んだり そこに含まれるエントリを読み込んだりする番です。 これには各データモデルクラスのアクセス用メソッドを使用するか、 あるいはマジックメソッドを使用します。以下に例を示します。

$client = Zend_Gdata_ClientLogin::getHttpClient($user, $pass, $service);
$gdata = new Zend_Gdata($client);
$query = new Zend_Gdata_Query(
        'http://www.blogger.com/feeds/blogID/posts/default');
$query->setMaxResults(10);
$feed = $gdata->getFeed($query);
foreach ($feed as $entry) {
    // マジックメソッドを使用します
    echo 'Title: ' . $entry->title->text;
    // 定義されているアクセス用メソッドを使用します
    echo 'Content: ' . $entry->getContent()->getText();
}

エントリを取得したら、それを更新してサーバに保存できます。以下に例を示します。

$client = Zend_Gdata_ClientLogin::getHttpClient($user, $pass, $service);
$gdata = new Zend_Gdata($client);
$query = new Zend_Gdata_Query(
        'http://www.blogger.com/feeds/blogID/posts/default');
$query->setMaxResults(10);
$feed = $gdata->getFeed($query);
foreach ($feed as $entry) {
    // タイトルに 'NEW' を追加します
    echo 'Old Title: ' . $entry->title->text;
    $entry->title->text = $entry->title->text . ' NEW';

    // エントリの内容を更新します
    $newEntry = $entry->save();
    echo 'New Title: ' . $newEntry->title->text;
}

Zend_Gdata オブジェクトの関数 insertEntry() にアップロードしたいデータを指定し、 新しいエントリを Google Data サービスに保存します。

各サービス用のデータモデルクラスを使用して適切なエントリを作成し、 Google のサービスに投稿できます。 insertEntry() 関数には、 Zend_Gdata_App_Entry の子クラスに投稿内容を格納して渡します。 このメソッドは Zend_Gdata_App_Entry の子クラスを返します。 これは、サーバから返されたエントリの状態を表します。

もうひとつの方法として、そのエントリの内容を XML 構造の文字列として作成して insertEntry() 関数に渡すこともできます。

$gdata = new Zend_Gdata($authenticatedHttpClient);

$entry = $gdata->newEntry();
$entry->title = $gdata->newTitle('Playing football at the park');
$content =
    $gdata->newContent('We will visit the park and play football');
$content->setType('text');
$entry->content = $content;

$entryResult = $gdata->insertEntry($entry,
        'http://www.blogger.com/feeds/blogID/posts/default');

echo 'この結果のエントリの <id> は、' . $entryResult->id->text;

エントリを送信するには、認証済みの Zend_Http_Client を使用する必要があります。これは、 Zend_Gdata_AuthSub クラスあるいは Zend_Gdata_ClientLogin クラスを使用して作成します。

方法 1: Zend_Gdata オブジェクトの関数 delete() に削除したいエントリを指定して、Google Data サービスからデータを削除します。 フィードエントリの編集用 URL を delete() メソッドに渡します。

方法 2: あるいは、Google サービスから取得したエントリに対して $entry->delete() をコールすることもできます。

$gdata = new Zend_Gdata($authenticatedHttpClient);
// Google Data のフィード
$feedUri = ...;
$feed = $gdata->getFeed($feedUri);
foreach ($feed as $feedEntry) {
    // 方法 1 - エントリを直接削除します
    $feedEntry->delete();
    // 方法 2 - 編集用 URL を $gdata->delete()
    // に渡してエントリを削除します
    // $gdata->delete($feedEntry->getEditLink()->href);
}

エントリを削除するには、認証済みの Zend_Http_Client を使用する必要があります。これは、 Zend_Gdata_AuthSub クラスあるいは Zend_Gdata_ClientLogin クラスを使用して作成します。