How to stub SOAP in PHP

I do not usually dismiss technologies without regarding to context, but if you have modern web applicatons in mind SOAP is simply wrong, starting from its name: Simple Object Access Protocol. One of the principles of OOP (and distributed computing) is to provide as few different integration points as possible, not to provide a simple way to access private objects  of an application while trying to abstract away the programming language!

How wonderful is the world of REST (or maybe ROT) web services... But many legacy and enterprise systems that we need to integrate are only accessible via SOAP. With a bit of experience and the right testing support, SOAP web services are not technologically difficult to call from PHP code.

Testing at the unit level

To test your adapter object, you need to isolate it from the real TCP/IP stack. In order to accomplish this, it is useful to introduce one of these two abstractions:

interface SoapChannel
{
   /**
    * @return SoapClient
    */
   public function newClient($wsdl, $options = array());
} 

Since PHP code access SOAP services through the native SoapClient object, we need to substitute it with a Stub inside the context of your test suite. However, code that needs to access several different services for the integration will need to specify multiple times a wsdl or some location options: for this reason the newClient() method accept this configuration and return a SoapClient.

In the production environment, newClient() returns a real SoapClient object created with the passed parameters; in testing, it can return your own Stub or one generated by PHPUnit's getMockFromWsdl() utility method.

The other option, when the integration code is calling only one or a few different services, is to provide an Endpoint abstraction:

interface SoapEndpoint
{
   /**
    * @return array
    */
   public function call($function, array $parameters);
} 

The interface is the ultimate layer called by your code, so it's a generic abstraction employed by the Facades you introduce over external services. Let me rephrase: only one object in your code should call each different concrete SoapEndpoint, so that dependencies are shaped like:

[VodafoneFacade] -> [SoapEndpoint]
[MyObject] -> [VodafoneFacade]
[AnotherObject] -> [VodafoneFacade]

Each implementation creates its own SoapClient, hiding away details such as the WSDL file and the location of the service. This design choice reduces the extrinsic coupling (how many collaborators you have) of integration objects from:

public function __construct(SoapChannel $channel, $location) {
   $this->channel = $channel;
   $this->wsdl = ...;
   $this->options = array('location' => $location);
} 

to

public function __construct(SoapEndpoint $endpoint)
{
   $this->endpoint = $endpoint;
}

The word endpoint may sometimes cause REST developers to snicker, I agree. Also, the SoapChannel abstraction is usually much less invasive to introduce in legacy code that calculates its own configuration parameters and creates new SoapClient objects whenever needed. I advise you to introduce directly SoapEndpoint on new code.

I also advise you not to pass around SoapClient objects directly, because an interface such as SoapEndpoint has very little cost (a few lines of code) and a great potential for expansion. For example, you could introduce logging of all external requests with a Decorator object around it.

Testing at the end-to-end level

When you're testing the system at the end-to-end level, I do not advise to Stub part of your code if possible: it causes some of your integration code to never be executed inside the test suite.

What you can do instead is to create external simulators that (out of process) substitute the real web service.

On the client side, you can substitute the location option:

new SoapClient($wsdl, array('location' => 'http://localhost/simulators/vodafone.php')); 

On the server side, you can easily build a SoapServer object:

class Service
{
   public function functionName($params)
   {
     return new \stdClass;
   }
}
$server = new SoapServer($wsdl);
$server->setServiceClass('Service');
$server->handle();

The functionName is the name of the function called on SoapClient in the separate process, while the implementation uses stdClass objects as input (function parameter) and output (returned value).

By creating simulators for external service in this way, you'll be able to reach full coverage of your production code and even to reproduce production integration behavior on your machine.