Zend_XmlRpc_Server は、完全な機能を有した XML-RPC サーバです。 www.xmlrpc.com で提示されている仕様 に準拠しています。 さらに system.multicall() メソッドを実装しており、 リクエストをまとめる (boxcarring of requests) ことができます。 もっとも基本的な使用例は次のとおりです。 setClass('My_Service_Class'); echo $server->handle(); ]]> Zend_XmlRpc_Server はさまざまなコンポーネントで構成されています。 サーバ自身からリクエスト、レスポンス、fault オブジェクトなど広範囲に広がっています。 Zend_XmlRpc_Server を起動するには、 まずサーバにひとつ以上のクラスか関数をアタッチする必要があります。 アタッチするには setClass() メソッドおよび addFunction() メソッドを使用します。 起動させたら、次に Zend_XmlRpc_Request オブジェクトを Zend_XmlRpc_Server::handle() に渡します。 もし渡さなかった場合は、Zend_XmlRpc_Request_Http のインスタンスを作成して php://input からの入力を受け取ります。 Zend_XmlRpc_Server::handle() は、 リクエストメソッドに応じて適切なハンドラに処理を振り分けます。 そして、 Zend_XmlRpc_Response を継承したオブジェクトか Zend_XmlRpc_Server_Fault オブジェクトを返します。 これらのオブジェクトはどちらも __toString() メソッドを実装しており、妥当な XML-RPC XML レスポンスを直接出力できます。 For maximum performance it is recommended to use a simple bootstrap file for the server component. Using Zend_XmlRpc_Server inside a Zend_Controller is strongly discouraged to avoid the overhead. Services change over time and while webservices are generally less change intense as code-native APIs, it is recommended to version your service. Do so to lay grounds to provide compatibility for clients using older versions of your service and manage your service lifecycle including deprecation timeframes.To do so just include a version number into your URI. It is also recommended to include the remote protocol name in the URI to allow easy integration of upcoming remoting technologies. http://myservice.ws/1.0/XMLRPC/. Most of the time it is not sensible to expose business objects directly. Business objects are usually small and under heavy change, because change is cheap in this layer of your application. Once deployed and adopted, web services are hard to change. Another concern is I/O and latency: the best webservice calls are those not happening. Therefore service calls need to be more coarse-grained than usual business logic is. Often an additional layer in front of your business objects makes sense. This layer is sometimes referred to as Remote Facade. Such a service layer adds a coarse grained interface on top of your business logic and groups verbose operations into smaller ones. Zend_XmlRpc_Server では、開発者が関数やクラスメソッドを XML-RPC メソッドとしてアタッチできるようになっています。 アタッチされるメソッドの情報は Zend_Server_Reflection を使用して取得し、関数やメソッドのコメントブロックから メソッドのヘルプ文とシグネチャを取得します。 XML-RPC の型は必ずしも PHP の型と一対一対応しているわけではありません。 しかし、@param や @return の行をもとに、できるだけ適切な型を推測しようとします。 XML-RPC の型の中には、直接対応する PHP の型がないものもありますが、 その場合は PHPDoc の中で XML-RPC の型のヒントを指定します。 たとえば次のような型が該当します。 dateTime.iso8601 ... 'YYYYMMDDTHH:mm:ss' 形式の文字列 base64 ... base64 エンコードされたデータ struct ... 任意の連想配列 ヒントを指定するには、次のようにします。 PhpDocumentor はパラメータや返り値の型を検証しません。 そのため、これが API ドキュメントに影響を及ぼすことはありません。 しかし、このヒントは必須です。メソッドがコールされた際に、 この情報をもとにサーバで検証を行うからです。 パラメータや返り値で複数の型を指定してもかまいません。 XML-RPC の仕様では、system.methodSignature は すべてのメソッドシグネチャ (すなわちパラメータと返り値の組み合わせ) の配列を返すことになっています。 複数指定する方法は、通常の PhpDocumentor の場合と同様に '|' 演算子を使用します。 複数のシグネチャを定義すると、それを利用する開発者を混乱させてしまいます。 物事を簡単にするために、 XML-RPC サービスのメソッドは単純なシグネチャだけを持つべきでしょう。 XML-RPC には名前空間の概念があります。基本的に、これは 複数の XML-RPC メソッドをドット区切りの名前空間でまとめるものです。 これにより、さまざまなクラスで提供されるメソッド名の衝突を避けることができます。 例として、XML-RPC サーバは 'system' 名前空間でこれらのメソッドを提供することが期待されています。 system.listMethods system.methodHelp system.methodSignature 内部的には、これらは Zend_XmlRpc_Server の同名のメソッドに対応しています。 自分が提供するメソッドに名前空間を追加したい場合は、 関数やクラスをアタッチする際のメソッドで名前空間を指定します。 setClass('My_Service_Class', 'myservice'); // 関数 'somefunc' は funcs.somefunc としてアクセスするようにします $server->addFunction('somefunc', 'funcs'); ]]> ほとんどの場合は、 Zend_XmlRpc_Server や Zend_XmlRpc_Request_Http に含まれるデフォルトのリクエスト型を使用するでしょう。 しかし、XML-RPC を CLI や GUI 環境などで動かしたい場合もあるでしょうし、 リクエストの内容をログに記録したい場合もあるでしょう。 そのような場合には、Zend_XmlRpc_Request を継承した独自のリクエストオブジェクトを作成します。 注意すべき点は、getMethod() メソッドと getParams() メソッドを必ず実装しなければならないということです。 これらは、XML-RPC サーバがリクエストを処理する際に必要となります。 リクエストオブジェクトと同様、Zend_XmlRpc_Server は独自のレスポンスオブジェクトを返すこともできます。 デフォルトでは Zend_XmlRpc_Response_Http オブジェクトが返されます。 これは、XML-RPC で使用される適切な Content-Type HTTP ヘッダを送信します。独自のオブジェクトを使用する場面としては、 レスポンスをログに記録したり、 あるいはレスポンスを標準出力に返したりといったことが考えられます。 独自のレスポンスクラスを使用するには、handle() をコールする前に Zend_XmlRpc_Server::setResponseClass() を使用します。 Zend_XmlRpc_Server は、配送先のメソッドで発生した例外を捕捉します。 例外を捕捉した場合は、XML-RPC の fault レスポンスを生成します。 しかし、デフォルトでは、例外メッセージとコードは fault レスポンスで用いられません。これは、 あなたのコードを守るための判断によるものです。 たいていの例外は、コードや環境に関する情報を必要以上にさらけ出してしまいます (わかりやすい例だと、データベースの抽象化レイヤの例外を想像してみてください)。 しかし、例外クラスをホワイトリストに登録することで、 fault レスポンス内で例外を使用することもできます。 そうするには、 Zend_XmlRpc_Server_Fault::attachFaultException() を使用して例外クラスをホワイトリストに渡します。 他のプロジェクトの例外を継承した例外クラスを利用するのなら、 一連のクラス群を一度にホワイトリストに登録することもできます。 Zend_XmlRpc_Server_Exceptions は常にホワイトリストに登録されており、 固有の内部エラー (メソッドが未定義であるなど) を報告できます。 ホワイトリストに登録されていない例外が発生した場合は、 コード '404'、メッセージ 'Unknown error' の falut レスポンスを生成します。 たくさんのクラスを XML-RPC サーバインスタンスにアタッチすると、 リソースを大量に消費してしまいます。各クラスを調べるために リフレクション API を (Zend_Server_Reflection 経由で) 使用する必要があり、 使用できるすべてのメソッドのシグネチャをサーバクラスに提供します。 使用するリソースの量を軽減するために、Zend_XmlRpc_Server_Cache を用いてリクエスト間でサーバ定義をキャッシュできます。 __autoload() と組み合わせることで、これはパフォーマンスを劇的に向上させます。 使用例は次のようになります。 setClass('My_Services_Glue', 'glue'); // glue. 名前空間 $server->setClass('My_Services_Paste', 'paste'); // paste. 名前空間 $server->setClass('My_Services_Tape', 'tape'); // tape. 名前空間 Zend_XmlRpc_Server_Cache::save($cacheFile, $server); } echo $server->handle(); ]]> この例では、スクリプトと同じディレクトリにある xmlrpc.cache からサーバの定義を取得しようとします。取得できなかった場合は、 必要なサービスクラスを読み込み、 それをサーバのインスタンスにアタッチし、 そしてその定義を新しいキャッシュファイルに記録します。 以下のいくつかの使用例で、開発者が使用できるオプションを説明します。 各使用例は、それまでに紹介した例に追加していく形式になります。 次の例は関数を XML-RPC メソッドとしてアタッチし、 受け取ったコールを処理します。 addFunction('md5Value'); echo $server->handle(); ]]> 次の例は、クラスのパブリックメソッドを XML-RPC メソッドとしてアタッチします。 setClass('Services_Comb'); echo $server->handle(); ]]> The following example illustrates how to attach a class' public methods and passing arguments to its methods. This can be used to specify certain defaults when registering service classes. setClass('Services_PricingService', 'pricing', new ProductRepository(), new PurchaseRepository()); ]]> The arguments passed at setClass() at server construction time are injected into the method call pricing.calculate() on remote invokation. In the example above, only the argument $purchaseId is expected from the client. Zend_XmlRpc_Server allows to restrict argument passing to constructors only. This can be used for constructor dependency injection. To limit injection to constructors, call sendArgumentsToAllMethods and pass FALSE as an argument. This disables the default behavior of all arguments being injected into the remote method. In the example below the instance of ProductRepository and PurchaseRepository is only injected into the constructor of Services_PricingService2. sendArgumentsToAllMethods(false); $server->setClass('Services_PricingService2', 'pricing', new ProductRepository(), new PurchaseRepository()); ]]> setClass() allows to register a previously instantiated object at the server. Just pass an instance instead of the class name. Obviously passing arguments to the constructor is not possible with pre-instantiated objects. 次の例は、複数のクラスをそれぞれの名前空間でアタッチします。 setClass('Services_Comb', 'comb'); // メソッドをコールするには comb.* とします $server->setClass('Services_Brush', 'brush'); // メソッドをコールするには brush.* とします $server->setClass('Services_Pick', 'pick'); // メソッドをコールするには pick.* とします echo $server->handle(); ]]> 次の例は、Services_Exception の派生クラスに対して そのコードとメッセージを falut レスポンスで報告させるようにします。 setClass('Services_Comb', 'comb'); // メソッドをコールするには comb.* とします $server->setClass('Services_Brush', 'brush'); // メソッドをコールするには brush.* とします $server->setClass('Services_Pick', 'pick'); // メソッドをコールするには pick.* とします echo $server->handle(); ]]> Some use cases require to utilize a custom request object. For example, XML/RPC is not bound to HTTP as a transfer protocol. It is possible to use other transfer protocols like SSH or telnet to send the request and response data over the wire. Another use case is authentication and authorization. In case of a different transfer protocol, one need to change the implementation to read request data. 次の例は、独自のリクエストオブジェクトを作成し、 それをサーバに渡して処理します。 setClass('Services_Comb', 'comb'); // メソッドをコールするには comb.* とします $server->setClass('Services_Brush', 'brush'); // メソッドをコールするには brush.* とします $server->setClass('Services_Pick', 'pick'); // メソッドをコールするには pick.* とします // リクエストオブジェクトを作成します $request = new Services_Request(); echo $server->handle($request); ]]> 次の例は、独自のレスポンスクラスを作成し、 それをレスポンスとして返します。 setClass('Services_Comb', 'comb'); // メソッドをコールするには comb.* とします $server->setClass('Services_Brush', 'brush'); // メソッドをコールするには brush.* とします $server->setClass('Services_Pick', 'pick'); // メソッドをコールするには pick.* とします // リクエストオブジェクトを作成します $request = new Services_Request(); // 独自のレスポンスを使用します $server->setResponseClass('Services_Response'); echo $server->handle($request); ]]> 次の例は、リクエスト間でサーバ定義をキャッシュします。 setClass('Services_Comb', 'comb'); // メソッドをコールするには comb.* とします $server->setClass('Services_Brush', 'brush'); // メソッドをコールするには brush.* とします $server->setClass('Services_Pick', 'pick'); // メソッドをコールするには pick.* とします // キャッシュに保存します Zend_XmlRpc_Server_Cache::save($cacheFile, $server); } // リクエストオブジェクトを作成します $request = new Services_Request(); // 独自のレスポンスを使用します $server->setResponseClass('Services_Response'); echo $server->handle($request); ]]> サーバーのキャッシュファイルは、ドキュメントルートの外部に配置されるべきです。 Zend_XmlRpc_Server uses DOMDocument of PHP extension ext/dom to generate it's XML output. While ext/dom is available on a lot of hosts it is not exactly the fastest. Benchmarks have shown, that XmlWriter from ext/xmlwriter performs better. If ext/xmlwriter is available on your host, you can select a the XmlWriter-based generator to leaverage the performance differences. Performance is determined by a lot of parameters and benchmarks only apply for the specific test case. Differences come from PHP version, installed extensions, webserver and operating system just to name a few. Please make sure to benchmark your application on your own and decide which generator to use based on your numbers. This optimization makes sense for the client side too. Just select the alternate XML generator before doing any work with Zend_XmlRpc_Client.