marcus welz

The WSDL Blower: The state of SOAP in Zend Framework 1.6

There are all kinds of ways to expose APIs as web services. SOAP, XML-RPC, REST, JSON-RPC. Out of all of these, SOAP is arguably the most complex, but also one of the oldest ways to expose an API (I remember preliminary SOAP and WSDL support in Delphi 6, circa 2001).

Exposing an API as a web service in Zend Framework is fairly straight forward, in fact it is (or should be) as easy as one, two, three:

1. Pick your favorite style (Zend_Soap_Server, Zend_XmlRpc_Server, Zend_Rest_Server, Zend_Json_Server).
2. Define a properly documented class with the methods and business logic that you want to expose.
3. Let your Zend_*_Server::handle(); everything else.

That's pretty much it. Of course each Zend_*_Server has its own settings and options that you can (and sometimes must) configure. XML-RPC is also the only server that supports namespaces.

If you decide on using SOAP, there are a few things to watch out for.

1. The WSDL generator doesn't let you set the TargetNamespace attribute explicitly. This becomes an issue when you're working with different environments (development, testing, staging, production, etc.) since the URL of the service determines the namespace. And that makes automatic code generation based on the WSDL problematic. I've contributed a patch to address this, as part of ZF-4117.
2. Zend_Soap_Client contains a bug that prevents it from properly proxying method calls. Instead, it'll end up recursing infinitely, or at least 100 times before PHP detects the issue and kills it. The quick fix of removing a single underscore froma method call is outlined in ZF-4152.
3. Zend_Soap_Server doesn't properly turn Exceptions into SoapFaults (due to lack of typecasting) as described in ZF-3958. You can still throw SoapFaults explicitly, but that's just bad form since your class shouldn't be SOAP specific. After all, you may decide to also expose it as XML-RPC or what have you, and then the SoapFault, while it might still work properly, is semantically incorrect.
4. While Zend_Soap_Server and Zend_Soap_Client are mostly wrappers for the native PHP SoapClient and SoapServer classes, PHP itself lacks WSDL generation which Zend_Soap_AutoDiscovery provides in conjunction with Zend_Soap_Wsdl. Unfortunately the notion of "array of datatype" is not supported, since arrays in PHP are simply declared as "array" and can contain anything. Zend Studio's WSDL generator supports the syntax of "string[]" to specify an array of strings, and this works with complex types as well. "User[]" is an array of User objects. The issue is outlined in ZF-3900, to which I didn't provide one, but two patches, neither of which actually do what I thought they'd do (go me!). However, I have put together an embarrassing hack (Zend_Soap_Wsdl arrayOfType patch) that finally does work — at least for me. So far I haven't worked up the courage to submit it to JIRA. Not one of my finest moments.

I doubt most of these issues will hang around for long, but if you're developing something SOAPy with ZF1.6, you'll like encounter at least one of them.