18.2. Zend_XmlRpc_Client
前のページ | 第18章 Zend_XmlRpc | 次のページ

## 18.2. Zend_XmlRpc_Client

### 18.2.1. 導入

`Zend_XmlRpc_Client` の使用法は、 `SoapClient` オブジェクト (SOAP 拡張モジュール) の使用法と非常によく似ています。XML-RPC サービスのプロシージャを、単純に `Zend_XmlRpc_Client` のメソッドとしてコールすることができます。 サービスの完全なアドレスを `Zend_XmlRpc_Client` のコンストラクタで指定します。

例 18.1. 基本的な XML-RPC リクエスト

    <?php
    /**
     * framework.zend.com のサーバに接続し、使用可能なメソッドを表す
     * 配列を取得します。
     */
    require_once 'Zend/XmlRpc/Client.php';

    $server = new Zend_XmlRpc_Client('http://framework.zend.com/xmlrpc');

    print_r( $server->system->listMethods() );

    ?>

| 注意
`Zend_XmlRpc_Client` は、 リモートメソッドを可能な限りネイティブメソッドと同様に扱おうとします。 上の `system.listMethods()` のように リモートメソッドが名前空間を含んでいる場合は、 PHP 風にオブジェクトを連結して `$server->system->listMethods()` のようにコールします。

### 18.2.2. パラメータの使用

XML-RPC サービスのプロシージャの中にはパラメータが必要なものがあります。 必要なパラメータは、`Zend_XmlRpc_Client` メソッドのパラメータとして渡すことになります。 XML-RPC プロシージャのパラメータは、指定された XML-RPC 型でなければなりません。 パラメータを渡す方法は 2 通りあります。PHP のネイティブ型で渡すか、 あるいは XML-RPC 型を表す `Zend_XmlRpc_Value` オブジェクトで渡すかのいずれかです。

#### 18.2.2.1. PHP ネイティブ変数をパラメータとして渡す

パラメータは、ネイティブの PHP 型、つまり string, integer, float, boolean, array あるいは object として渡します。 このとき、PHP のネイティブ型は自動的に検出され、 以下の表にしたがって XML-RPC 型に変換されます。

表 18.1. PHP と XML-RPC の間の型変換

PHP ネイティブ型 | XML-RPC 型
--- | ---
integer | int
double | double
boolean | boolean
string | string
配列 | array
連想配列 | struct
object | array

    <?php

    /**
     *  このプロシージャには 2 つのパラメータが渡されます。
     *    - 最初のパラメータは文字列で、XML-RPC の string 型に自動的に変換されます。
     *    - 2 番目のパラメータは連想配列で、これは XML-RPC の構造体に変換されます。
     */

    $p1 = 'parameter 1';
    $p2 = array('name' => 'Joe', 'age' => 30);

    $service->serviceProcedure($p1, $p2);

    ?>

#### 18.2.2.2. `Zend_XmlRpc_Value` オブジェクトをパラメータとして渡す

パラメータを `Zend_XmlRpc_Value` オブジェクトで渡します。 パラメータに対応する XML-RPC 型を表す `Zend_XmlRpc_Value` のインスタンスを作成することができます。 XML-RPC 型を明示的に指定する主な理由としては、以下が考えられるでしょう。

- プロシージャに正しい型で渡されることを確実にしたいことがある (例えば、integer を要求しているプロシージャに対して $_GET 配列の中の文字列を渡したい場合など)。
- プロシージャが base64 型や dateTime.iso8601 型を要求していることがある (これらは PHP のネイティブ型には存在しません)。
- 自動変換が失敗することがある (例えば、空の XML-RPC 構造体をパラメータとして渡すことを考えましょう。 これは、PHP では空の配列に対応します。しかし、 空の配列をパラメータとして渡すと、それが自動変換されたときに XML-RPC の array になってしまいます。なぜなら、 からの配列は連想配列ではないからです)。

`Zend_XmlRpc_Value` オブジェクトを作成する方法は 2 通りあります。明示的に作成する (オブジェクトのコンストラクタをコールする) か、静的関数 `Zend_XmlRpc_Value::getXmlRpcValue()` を使用して XML-RPC 型の定数を指定します。

表 18.2. `Zend_XmlRpc_Value` オブジェクトと対応する XML-RPC 型

XML-RPC 型 | 対応する `Zend_XmlRpc_Value` 定数 | `Zend_XmlRpc_Value` オブジェクト
--- | --- | ---
int | `Zend_XmlRpc_Value::XMLRPC_TYPE_INTEGER` | `Zend_XmlRpc_Value_Integer`
double | `Zend_XmlRpc_Value::XMLRPC_TYPE_DOUBLE` | `Zend_XmlRpc_Value_Double`
boolean | `Zend_XmlRpc_Value::XMLRPC_TYPE_BOOLEAN` | `Zend_XmlRpc_Value_Boolean`
string | `Zend_XmlRpc_Value::XMLRPC_TYPE_STRING` | `Zend_XmlRpc_Value_String`
base64 | `Zend_XmlRpc_Value::XMLRPC_TYPE_BASE64` | `Zend_XmlRpc_Value_Base64`
dateTime.iso8601 | `Zend_XmlRpc_Value::XMLRPC_TYPE_DATETIME` | `Zend_XmlRpc_Value_DateTime`
array | `Zend_XmlRpc_Value::XMLRPC_TYPE_ARRAY` | `Zend_XmlRpc_Value_Array`
struct | `Zend_XmlRpc_Value::XMLRPC_TYPE_STRUCT` | `Zend_XmlRpc_Value_Struct`

    <?php

    /**
     *  このプロシージャには 2 つのパラメータが渡されます。
     *    - 最初のパラメータは XML-RPC の base64 型で、静的関数
     *      Zend_XmlRpc_Value::getXmlRpcValue() を使用して作成します。
     *    - 2 番目のパラメータは XML-RPC の構造体で、これは 明示的に作成します。
     */

    $p1 = Zend_XmlRpc_Value::getXmlRpcValue('encoded string', Zend_XmlRpc_Value::XMLRPC_TYPE_BASE64);
    $p2 = new Zend_XmlRpc_Value_Struct(array('name' => 'Joe', 'age' => 30));

    $service->serviceProcedure($p1, $p2);

    ?>

| 注意
この場合もパラメータの値は PHP の変数で渡していますが、 指定した型に PHP の変換機能によって変換されます (もし `Zend_XmlRpc_Value_Integer` オブジェクトの値として文字列が渡されたら、 `(int)$value` を使用して変換されます)。

#### 18.2.2.3. XML 文字列を XML-RPC パラメータとしてパースする

この方式によるパラメータ渡しは `Zend_XmlRpc` パッケージで内部的に使用されているもので、推奨されません。

それでもこの方式を使用したいというのなら、静的関数 `Zend_XmlRpc_Value::getXmlRpcValue()` を使用して XML 文字列をパースし、対応する XML-RPC 型を表す `Zend_XmlRpc_Value` オブジェクトに格納してください。 `Zend_XmlRpc_Value::getXmlRpcValue()` 関数は 2 つのパラメータ、XML 文字列と `Zend_XmlRpc_Value::XML_STRING` 定数を受け取ります。

### 18.2.3. パラメータの型指定

XML-RPC と SOAP ウェブサービスの主な違いは WSDL ファイルの存在です。 SOAP プロトコルは通常 WSDL ファイルを使用しており、 ここにウェブサービスのインターフェイスが記述されています。 このインターフェイスにより、SOAP クライアントがサーバに送信するパラメータの型、 サーバから返される型を知ることができるのです。 WSDL ファイルがなければ、それらの型を知るのは難しくなるでしょう。

XML-RPC プロトコルでは、`system.methodSignature` という名前の特別なプロシージャを使用することでこの問題を解決します。 このプロシージャは、プロシージャ名をパラメータとして受け取り、 そのプロシージャのシグネチャを返します。シグネチャには、 必須パラメータの型および返り値の型が含まれます。

| 注意
すべての XML-RPC サーバが `system.methodSignature` プロシージャをサポートしているわけではありません。 サポートしていないサーバの場合は、型指定を使用することはできません。

`Zend_XmlRpc_Client` では、`system.methodSignature` プロシージャを使用することで、ある種の 'WSDL' ファイルを XML-RPC サーバ用に実装しています。 要求を受けると、`Zend_XmlRpc_Client` は XML-RPC サーバ上の全プロシージャの一覧を調べ、 それらのシグネチャを調べたうえでそれを XML ファイル (SOAP の WSDL ファイルに似た形式です) に保存します。 同じ XML-RPC サーバを再度使用する際には、その XML ファイルを指定すると、`Zend_XmlRpc_Client` がプロシージャのパラメータの型を判定します。

プロシージャのシグネチャの XML ファイルを作成するには `Zend_XmlRpc_Client::__getMethodsXml()` 関数をコールします (この関数は、シグネチャのデータを含む XML 文字列を返します)。 既存のシグネチャ XML ファイルを使用するには、 `Zend_XmlRpc_Client` コンストラクタのパラメータとして XML データを渡すか、あるいは `Zend_XmlRpc_Client::__setMethodsXml()` 関数をコールします。

例 18.2. 型指定を使用した XML-RPC サービスのコール

    <?php

    /**
     * XML-RPC サーバに接続し、シグネチャファイルを保存します
     * (SOAP の WSDL ファイルと同等の XML-RPC 版になります)
     */
    require_once 'Zend/XmlRpc/Client.php';

    $service = new Zend_XmlRpc_Client('http://www.example.org/xmlrpc');

    file_put_contents('/tmp/xmlrpc-signatures/example.xml', $service->__getMethodsXml());

    /* $service オブジェクトは、XML-RPC サーバのすべてのシグネチャを含むようになります。
       serviceProcedure がコールされると、そのパラメータ ($param) は
       プロシージャのシグネチャに応じて適切に型変換されます。
     */
    $service->serviceProcedure($param);

    ?>

    <?php

    /**
     * 既存のシグネチャファイルを使用して XML-RPC サーバに接続します。これにより、
     * プロシージャに渡すパラメータの型が適切に変換されるようになります。
     */
    require_once 'Zend/XmlRpc/Client.php';

    $signature_file_xml = file_get_contents('/tmp/xmlrpc-signatures/example.xml');
    $service = new Zend_XmlRpc_Client('http://www.example.org/xmlrpc', 'namespace', $signature_file_xml);

    /* $service オブジェクトは、XML-RPC サーバのすべてのシグネチャを含むようになります。
       serviceProcedure がコールされると、そのパラメータ ($param) は
       プロシージャのシグネチャに応じて適切に型変換されます。
     */
    $service->serviceProcedure($param);

    ?>

### 18.2.4. 応答の取得

XML-RPC プロシージャは、 XML-RPC 型の値を返します。 XML-RPC プロシージャをコールする `Zend_XmlRpc_Client` メソッドは、 返される XML-RPC 型を PHP のネイティブ型に変換したものを返します。

要求したプロシージャの返り値を取得するには、 `Zend_XmlRpc_Client::__getResponse()` 関数を使用します。 `__getResponse()` 関数は、返り値の型を示すパラメータを受け取ります。 応答内容として指定できるオプションは以下のとおりです。

- `Zend_XmlRpc_Client::RESPONSE_PHP_NATIVE` - プロシージャの返り値を、PHP のネイティブ型として返します (XML-RPC 型を PHP 型に変換します)。
- `Zend_XmlRpc_Client::RESPONSE_XML_STRING` - XML-RPC の応答を、XML 文字列形式で返します。
- `Zend_XmlRpc_Client::RESPONSE_ZXMLRPC_OBJECT` - XML-RPC 型を表す `Zend_XmlRpc_Value` オブジェクトを返します。

    <?php

    $service->serviceProcedure();

    $response = $service->__getResponse();
    // $response は、XML-RPC 型の返り値を PHP 変数に変換したものです

    $response = $service->__getResponse(ZXmlRpcClient::RESPONSE_XML_STRING);
    // $response は、プロシージャの返り値を表す XML を含む文字列です

    $response = $service->__getResponse(ZXmlRpcClient::RESPONSE_ZXMLRPC_OBJECT);
    // $response は、XML-RPC 型の返り値を表す Zend_XmlRpc_Value インスタンスです

    ?>

前のページ | 上に戻る | 次のページ
第18章 Zend_XmlRpc | ホーム | 付録 A. Zend Framework PHP 標準コーディング規約