Geeklog DataproxyプラグインのAPI

制作者 mystral-kk - geeklog AT mystral-kk DOT net
バージョン 1.0.3
公開日 2007-12-26

1. 概要

Dataproxyプラグインは,Geeklogのコンテンツ取得代行・キャッシュ管理を行うプラグインです(バージョン1.0では,キャッシュ管理機能は実装されていません)。通常,各プラグインが管理するデータを取得するには,それぞれSQLを組み立て,権限チェックを追加するなどの手順を踏む必要がありますが,Dataproxyプラグインを使用すれば,簡単な手順と統一されたインターフェースでコンテンツを取り出すことができます。

ご注意:Dataproxyプラグインはまだ開発初期の段階のため,下記のAPIは変更される可能性があります。

2. データソース・カテゴリ・アイテム

Dataproxyプラグインでは,コンテンツを提供する機能・プラグインをデータソースとして位置づけています。現時点でサポートされているデータソースは次の通りです。article, comments, trackbackは常に利用できます。

また,各データソースは階層的なカテゴリを持っています(staticpagesなどにはありません)。各階層にある具体的なコンテンツをアイテムと呼びます。

3. Dataproxyプラグインの利用法

Dataproxyプラグインがインストールされ,有効になっていれば,次の1行を記述するだけでDataproxyプラグインが提供するAPIを利用できます。

$dataproxy =& new Dataproxy($uid);

PHP5の場合は,次のコードを推奨します。

$dataproxy = new Dataproxy($uid);

$uidはデータを取得するユーザのID($_USER['uid'])です。デフォルト値は1(ゲストユーザの扱い)です。全データを取得する必要がある場合は,0を指定します。

4. Dataproxyクラス

Dataproxyクラスは実際にデータを取得するDataproxyDriverクラスの生成・管理を担当します。現在有効になっているプラグインを認識し,必要なDataproxyDriverクラスのインスタンスを作成します。

4.1 Dataproxyクラス - 公開メソッド

setUid($uid)

Dataproxyプラグインを使用するユーザIDをセットします。ユーザIDはDataproxyクラスのインスタンスを作成するときに指定するので,ふつう,このメソッドを呼び出す必要はありません。

getUid()

Dataproxyプラグインを使用しているユーザのIDを返します。

setEncoding($encoding)

Dataproxyプラグインの内部エンコーディングを指定します。内部エンコーディングはDataproxyクラスのインスタンスを作成するときに指定するので,ふつう,このメソッドを呼び出す必要はありません。

getEncoding()

Dataproxyプラグインの内部エンコーディングを返します。

setOptions($options)

Dataproxyプラグインに与えるオプションを連想配列の形式で指定します。オプションはDataproxyクラスのインスタンスを作成するときに指定するので,ふつう,このメソッドを呼び出す必要はありません。

getOptions()

Dataproxyプラグインに与えられているオプションを連想配列の形式で返します。

getAllSupportedDriverNames()

Dataproxyプラグインでサポートされているデータソース名の配列を返します。

getAllDriverNames()

Dataproxyプラグインで現在有効になっているデータソース名の配列を返します。サポートされているデータソースについては,上記をご覧ください。

escape($str)

文字列をHTMLとして出力できるようエスケープします。

4.2 Dataproxyクラス - 公開メンバー

以下のメンバーは,データソースオブジェクト(:DataproxyDriverクラス)へのリファレンスになっています。

5. DataproxyDriverクラス

DataproxyDriverクラスは各コンテンツのデータ・メタデータを実際に取り出すデータソースドライバの親クラスです。Dataproxyクラスが管理しますので,ユーザがデータソースドライバをインスタンス化する必要はありません。

5.1 DataproxyDriverクラス - 公開メソッド

getDriverName()

データソースドライバ名を返します。

getAllSupportedDriverNames()

Dataproxyプラグインでサポートされているデータソース名の配列を返します。サポートされているデータソースに関しては上記をご覧ください。

getAllDriverNames()

Dataproxyプラグインで現在有効になっているデータソース名の配列を返します。

getEntryPoint()

各プラグインのユーザに見えるトップページのURIを返します。staticpagesプラグインなどのようにトップページがない場合は,falseを返します。

getChildCategories($pid = false, $all_langs = false)

親カテゴリ$pidの下にあるすべての子カテゴリのメタデータを配列で返します。配列の要素は以下のようになっています。ルートカテゴリの場合は,$pidにfalseを指定して呼び出します。多言語機能を有効にしたサイトで$all_langsにtrueを指定すると,カレントユーザの言語IDを無視します。Googleサイトマップなどを作成する場合に有効です。

getAllCategories($all_langs = false)

データソースが持つすべてのカテゴリのメタデータを配列で返します。配列の要素は,getChildCategories()と同じです。多言語機能を有効にしたサイトで$all_langsにtrueを指定すると,カレントユーザの言語IDを無視します。Googleサイトマップなどを作成する場合に有効です。

getItems($category, $all_langs = false)

親カテゴリ$pidの下にあるすべてのアイテムのメタデータを配列で返します。配列の要素は以下のようになっています。ルートカテゴリの場合は,$pidにfalseを指定して呼び出します。多言語機能を有効にしたサイトで$all_langsにtrueを指定すると,カレントユーザの言語IDを無視します。Googleサイトマップなどを作成する場合に有効です。

getItemById($id, $all_langs = false)

$idで指定されたIDを持つアイテム1個分のメタデータと生データを配列で返します。配列の要素は以下のようになっています。

getAllItems($all_langs = false)

データソースが持つすべてのアイテムのメタデータを配列で返します。配列の要素は,getItems()と同じです。多言語機能を有効にしたサイトで$all_langsにtrueを指定すると,カレントユーザの言語IDを無視します。Googleサイトマップなどを作成する場合に有効です。

escape($str)

文字列をHTMLとして出力できるようエスケープします。

toUtf8($str)

$strをUTF-8に変換します。

cleanUrl($url)

与えられたURIからXSSの可能性のあるコードを取り除きます。

6. Dataproxyプラグイン利用のコーディング例

例1. 記事のメタデータを全て(カレントユーザの言語のみ)取り出す

$dataproxy =& new Dataproxy;
$item_metadata = $dataproxy->article->getAllItems();

例1. 記事のメタデータを全て(すべての言語)取り出す。

$dataproxy =& new Dataproxy;
$item_metadata = $dataproxy->article->getAllItems(true);

例2. 静的ページのメタデータを全て取り出す

$dataproxy =& new Dataproxy;
$item_metadata = $dataproxy->staticpages->getAllItems();

例3. 'foo'カテゴリの記事のメタデータを全て取り出す

$dataproxy =& new Dataproxy;
$item_metadata = $dataproxy->article->getItems('foo');

例4. 記事IDが'bar'の記事のデータを取り出す

$dataproxy =& new Dataproxy;
$item = $dataproxy->article->getItem('bar');

例5. 全データソースのアイテムのメタデータを全て取り出す

$items = array ();
$dataproxy =& new Dataproxy;
$drivers = $dataproxy->getAllDriverNames();

foreach ($drivers as $driver) {
   $items[] = $dataproxy->$driver->getAllItems();
}

7. APIの変更履歴

バージョン公開日変更点
1.0.02007-11-04初期バージョン
1.0.32007-12-26getChildCategories(), getAllCategories(), getAllCategoriesAsLinks(), getItemById(), getItems(), getItemsAsLinks), getAllItems()で,$all_langsパラメータ(オプション)を追加した。