David Goodwin

The following is effectively an online version of a talk I gave to phpwm in July 2008.

Disclaimer!

I'm no great expert on the inner workings of these protocols....there are probably secret manuals on SOAP/XmlRpc etc I/we failed to read somewhere

This is just a documentation of what I/we as “newbies” found ...

What?

SOAP and XmlRpc protocols to allow for remote procedure calls. In other words, you could for example "expose" a service using XmlRpc for customers/the public to interact with. This allows them to hook into your system, and use it as they see fit.

If you are interested in this, you might also want to look at the SCA SDO module in PECL. Although aware of it, for some unknown reason, we didn't investigate using it.

• SOAP – once stood for Simple Object Access Protocol
• XMLRPC – XML Remote Procedure Call[s]

Both are Cross platform, language agnostic means of executing remote code.

SOAP is really now just called "SOAP", I think they've dropped the "Simple..." bit from the name as it can be anything but simple.

Examples of usage

• Distributed applications
• Web services (Amazon, MSN, Yahoo etc)
• Proprietary applications
• Integration between Python/Java/.Net/PHP etc

What is XMLRPC?

• “Lightweight” version of SOAP
• Does not support as rich data types
• (Some of the SOAP-ites developed it)
• Not standardised [by committee]
• Zend_XmlRpc_(Server|Client)
• PHP5 has an xmlrpc extension
• Transparent to the end user

SOAP

• Standardised (W3C)
• Successor to XMLRPC?
• Headers can contain authentication details
• WSDL File....
• Developed by Microsoft, W3C etc

Transport layer

• Both work over HTTP[S] (Firewalls etc)
• Both involve/use XML (Verbose? Bulky?)
• Both work through POST requests
• (Internet application layer as a transport layer...)

As PHP developers, the above should be nothing new or scary - it's building upon familiar concepts we use (XML, POST, HTTP)

XMLRPC – Data types supported

• Array
• Struct (Assoc. Array)
• Integer
• Boolean
• Double
• String
• Base64 (useful for binary data)
• Date/Time

Note, there is no support for Objects - as you can probably imagine it's likely to be difficult to take an object from e.g. Java and access it from PHP - what about logic held within the object etc?

SOAP – Data types supported

As per XMLRPC + any others you wish to define in your WSDL file.... (Objects etc - at least I'm assuming it allows this)

Error Reporting

Both sort-of-support Exceptions (“Faults”)

"Imaginary" Scenario

$customer has an application (and database) which they wish to give their customers access to (although they didn't word it as such).

“We need to allow $y to be able to integrate with our system to do $x”

My immediate thought was "XMLRPC / SOAP....?"

Initial discussion on the phpwm mailing list, also raised the idea of REST.

XMLRPC or SOAP or REST

• XMLRPC – Simple, great PHP5 support (via Zend Framework)
• SOAP – WSDL bafflement/avoidance (no ZF then)
• REST – Seems pointless (I don't want to write view layer code)

Initial investigation of REST implied that I would need to write a 'view layer' which would probably be returning XML. On one hand it involves GET requests as well (so perhaps better caching can take place?) - but I really didn't see why anyone would use REST over e.g. XMLRPC/SOAP - considering the extra work required both when developing the API and when consuming it.

Structure

At a simplistic level, we split the structure into three layers - the backend logic (talking to DB, performing validation and business logic), the SOAP (or XMLRPC) service and finally and the client. Some example code follows.

App Logic

• Not hard coded to a transport (could use “locally”)
• Easier unit testing
• Normal PHP5 “stuff”
• Has appropriate authentication checks.

XMLRPC / SOAP Interface

Our initial implementation was XMLRPC only, as this seemed the easiest to use. Coming from a web development background, we wanted to use e.g. sessions to capture authentication details, and allow for persistence across requests. The Zend XmlRpc library does allow this (once you set a cookie jar, which takes about 4 lines of code). Unfortunately, it doesn't see that many other libraries in other languages do support cookies (easily?), so this approach has lost favour over time.

We had the same issue with HTTP authentication as with cookies - namely, asking an employee to write a Java (or Python) XMLRPC client that interacted with the service resulted in about a day of lost time.

Therefore, the only workable approach appears to be to make the first two parameters of each method call the username and password of the client. Ugly, but will always work.

• Initially unsure of which was the best approach - So support them all?
• How to do authentication? Cookies? user/pass parameters at the start of each method call ?
• SOAP has some sort of header authentication support, but no one seems to have used/documented it for me to find...

From an XMLRPC point of view, we ended up having the following server URLs -

• server_session_auth.php
• server_manual_auth.php
• server_http_auth.php

ARGH! Thankfully there is minimal duplication of code between the session and http auth variants, but because the manual auth approach requires two parameters to be added to all method calls, we had to write a proxy class to accommodate this. This is a slight maintenance annoyance, and if the API grows much more, we'll write something to generate this code for us.

We've now (effectively) dropped them all apart from “server_manual_auth.php”

Session and HTTP auth were VERY easy to write though; manual_auth is a pain; but adopting ONE approach makes support easier.

SOAP Interfaces

• Php5's ext/soap doesn't support namespaces, so
• Separate URL/PHP file per back end object
• Stuck with “manual_auth” approach for this
• Was able to reuse all of the XMLRPC proxy code :-)
• Quick win - it took a handful of hours to write the server, a test client and get it working.

Performance

• Kind of sucks
• $server(s) are in Australia, we're in the UK.... Customers are everywhere.
• We “batched” together the “addNewItem()” method into an explicit “addOneThousandNewItems()” method which helped.
• Could “bulk” up; but HTTP/PHP POST size limitations?

Obviously you'll want to use deflate/gzip compression on calls/responses....

Sample Code....(xmlrpc server)

require_once('Zend/XmlRpc/Server.php');
require_once('ModuleXProxy.php');
$server = new Zend_XmlRpc_Server();
$server->setClass('ModuleXProxy', 'name.space');
echo $server->handle();

Note, you can set namespaces using the Zend XmlRpc client, this is great as we have many backend models, but they can all be combined into one server URL.

ModuleXProxy.php

PHPDoc comments VERY IMPORTANT (and annoyingly case sensitive!)

require_once('ModuleX.php');
class ModuleXProxy {

    public function __construct() {
        $this->real = new ModuleX();
    }

    /**
     * @param string $username
     * @param string $password
     * @param string $foo
     * @return boolean success indicator
     */
    public function doSomething($username, $password, $foo) {
      if(authenticated($username, $password)) {
       return $this->real->doSomething($foo);
     }
     throw new AuthenticationException(“....”);
}

Client...

require_once('Zend/XmlRpc/Client.php');
$xmlrpcclient = new Zend_XmlRpc_Client(“http://somewhere/server.php”)
$proxy = $xmlrpcclient->getProxy('name.space');
$result = $proxy->doSomething($username, $password, $whatever);

Compared to "local" usage of the server object (ModuleX) there is only one difference - the username/password parameters. Hence it's quite transparent and seamless.

4 lines of code.... seems easy enough to me! Might want Exception try/catch in the real world.

SOAP Server

require_once('ModuleXProxy.php');
$options = array('uri' => 'urn:http://dom.ain/soap/modulex',
                 'soap_version' => SOAP_1_2,
                );
$server = new SoapServer(null, $options);
$server->setClass('ModuleXProxy');
$server->handle();

Note – we're not using a WSDL file....

SOAP Client

$client = new SoapClient(null, 
    array(
        'location' => 'http://dom.ain/soap/path/to/server.php', 
        'uri'      => 'urn:http://dom.ain/soap/modulex', 
        'soap_version' => SOAP_1_2));

$result = $client->__soapCall('doSomething', array($user, $pass, $something)));

For some reason, the __call() function in the SoapClient object is marked as deprecated in the API; I've no idea why, as it would be far nicer an API (for clients) if it could be used. Obviously as a client you could write a wrapper which makes it transparent using the __call() magic method, but this seems needless work to me.

Short summary - Less code, but shame it doesn't natively support __call() etc

Zend Framework

• Zend_Soap is under development.... which is why we didn't use it
• Zend_XmlRpc namespaces - a great feature/idea.

The Zend Frameworks' XmlRpc library saved us a lot of time, and it's worked really well. Hopefully it will get faster performance in the future, although we don't really notice it as having bad performance. (The initial implementation of a caching feature, as per the documentation resulted in it taking longer to respond to requests! Bug ticket created etc.)

Technorati Tags: php5 soap xmlrpc zend framework