クライアント側
XML_RPC2 のクライアント側での使用法
PHP5 のおかげで、XMLRPC クライアントのリクエストを簡単に XML_RPC2 で扱えるようになりました。本当に簡単に使用可能です。
まず、'XML/RPC2/Client.php' をインクルードします (これだけです)。
<?php
require_once 'XML/RPC2/Client.php';
?>
次に、オプションの連想配列を指定して XML_RPC2 を設定 (プレフィックス、 プロキシ、手動でのバックエンドの選択など...) します。
<?php
$options = array(
'prefix' => 'package.'
);
?>
三番目に、サーバの URL とオプションの配列を指定して XML_RPC2_Client オブジェクトを作成します。
<?php
$client = XML_RPC2_Client::create('http://pear.php.net/xmlrpc.php', $options);
?>
そして、サーバのメソッドをコールしてリクエストを送信します。 これは、$client オブジェクトのローカルメソッドをコールすることで行います。
<?php
$result = $client->info('XML_RPC2');
?>
この一行で、まず XMLRPC クライアントの package.info() (プレフィックス + メソッド名) メソッドへの引数 (文字列 'XML_RPC2') つきのリクエストをエンコードします。 そしてそのリクエストを HTTP でサーバに送信し、 戻されたレスポンスを PHP のネイティブ型にデコードします。 これだけのことが、たったの一行でできるのです!
もちろん、サーバのエラーを捕捉するにはこれ以外に数行追加する必要があります。 たとえばこのようになります。
<?php
try {
$result = $client->info('XML_RPC2');
print_r($result);
} catch (XML_RPC2_FaultException $e) {
// XMLRPC サーバが XMLRPC のエラーを返しました
die('Exception #' . $e->getFaultCode() . ' : ' . $e->getFaultString());
} catch (Exception $e) {
// その他のエラー (HTTP あるいはネットワークの問題など...)
die('Exception : ' . $e->getMessage());
}
?>
オプションの配列
この配列は任意で指定するものですが非常に有用です。 以下のキーが使用可能です。
| オプション | データ型 | デフォルト値 | 説明 |
|---|---|---|---|
| prefix | string | '' | XMLRPC のメソッド名の前に追加するプレフィックス |
| proxy | string | '' | HTTP リクエストに使用するプロキシ (デフォルト : プロキシなし) |
| debug | boolean | FALSE | デバッグモードか? |
| encoding | string | '' | リクエストのエンコーディング、'utf-8' あるいは 'iso-8859-1' (現時点ではこれらふたつのみを公式にサポートしています) |
| uglyStructHack | boolean | TRUE | XMLRPCEXT のバグ/仕様を回避するための汚いハック。詳細は このバグ情報 を参照ください。このハックを使用しない (現実的な) 別解は、 文字列 'xml_rpc2_ugly_struct_hack_' で始まるキーを持つ構造体を メソッドコールの引数として使用しないことです。 |
XML_RPC2_Client オブジェクトの作成
XML_RPC2_Client オブジェクトを作成するのは簡単です。次の構文を使用します。
<?php
// $XMLRPCServerURL は文字列 : たとえば 'http://pear.php.net/xmlrpc.php'
// $options はオプションの配列 : 詳細は先ほどの節を参照ください
$client = XML_RPC2_Client::create($XMLRPCServerURL, $options);
?>
XML_RPC2_Client のコンストラクタを直接コールしないでください。 静的メソッド call() をコールします。
XMLRPC がエクスポートするメソッドのコール
XML_RPC2_Client オブジェクトを作成したら、 リモートのメソッドがまるでローカルにあるかのように直接コールできます。 たとえば次のようになります。
<?php
// リモートの foo() メソッドを、引数なしでコールします
$result1 = $client->foo();
// リモートの bar() メソッドに二つの引数 (整数 : 123、文字列 : 'foo') を指定してコールします
$result2 = $client->bar(123, 'foo');
// リモートの foobar() メソッドに複雑なデータ型 (ふたつの整数、文字列、そして構造体) を指定してコールします
$result3 = $client->foobar(1, 2, 'foo', array('foo' => 1, 'bar' => 2));
?>
注意しなければならないのは、XMLRPC の仕様では、リモートのメソッド名で "." や "/" といった特殊文字が使えるということです。これらは、 PHP のメソッド名としては使用できません。これに対処するには、 オプションの配列でプレフィックスを指定する必要があります。たとえば次のようになります。
<?php
$options = array('prefix' => 'foo.');
$client = XML_RPC2_Client::create('http://...', $options);
// foo.bar() メソッドをコールします。プレフィックス 'foo.' が
// $options 配列で指定されているからです
$result = $client->bar();
?>
たいていの場合は、リクエストを行うと、 XML_RPC2 が自動的に PHP ネイティブ型を XMLRPC の型 (仕様で決められています) に変換します。 また同様に、XML_RPC2 は XML サーバからのレスポンスを PHP のネイティブ型に変換します。 しかし、二つだけ例外があります。それが 'dateTime.iso8601' および 'base64' で、これらは PHP には存在しません。
これらの二つの型を明示的に扱うには、特別なオブジェクトを使用する必要があります。 完全な例を見てみましょう。
<?php
// 標準の使用法
require_once 'XML/RPC2/Client.php';
// これらの型を扱うには、このファイルもインクルードする必要があります
require_once 'XML/RPC2/Value.php';
// 'dateTime.iso8601' オブジェクトを取得するには、まず文字列に
// iso8601 エンコードされた日付を指定する必要があります
$tmp = "20060116T19:14:03";
// そして、この静的メソッドをコールして 'dateTime.iso8601' オブジェクトを取得します
$time = XML_RPC2_Value::createFromNative($tmp, 'datetime');
// 'base64' の場合は、同じ静的メソッドに文字列を渡し、'base64' オブジェクトを取得します
$base64 = XML_RPC2_Value::createFromNative('foobar', 'base64');
// 後は、いつもどおりに XML_RPC2_Client を使用します
$options = array('prefix' => 'validator1.');
$client = XML_RPC2_Client::create('http://phpxmlrpc.sourceforge.net/server.php', $options);
$result = $client->manyTypesTest(1, true, 'foo', 3.14159, $time, $base64);
// リモートの validator1.manyTypesTest() メソッドは、渡した 6 つの引数を配列で返します
$result_datetime = $result[4]; // 'dateTime.iso8601' オブジェクト
$result_base64 = $result[5]; // 'base64' オブジェクト
// これらのオブジェクトを PHP のネイティブ型に変換するには、
// これえらのオブジェクトのパブリックプロパティを次のように使用しなければなりません
var_dump($result_datetime->scalar); // string(17) "20060116T19:14:03" を返します
var_dump($result_datetime->xmlrpc_type); // string(8) "datetime" を返します
var_dump($result_datetime->timestamp); // int(1137435243) を返します
var_dump($result_base64->scalar); // string(6) "foobar" を返します
var_dump($result_base64->xmlrpc_type); // string(6) "base64" を返します
?>
忘却曲線を使ってこの知識を確実に記憶に残す
