• Specify "@param base64Binary $file" or "@return base64Binary" (case-sensitive) to trigger automatic encoding and decoding of binary arguments (such as images) at the client and server.

• This is a significant enhancement which enables PHP web services to process eg. authentication or payment credentials supplied in headers, without having to modify every method of your web services to deal with authentication or other metadata that should preferably be supplied in headers.
• To create a SOAP header processor in a PHP SOAP server, define methods in your web service class with the same names as the header elements you wish to process. The header methods will be called in document order followed by the body method, using a single instance of the class (the same instance will persist over each method call).
• For automatic WSDL generation, specify that a method processes a SOAP header by including @internal soapheader before the method definition. To specify that a particular web service method requires certain SOAP headers, include @internal soaprequires FirstHeader SecondHeader .... (space-delimited list of header method names).
• You can also create derived classes to facilitate encapsulation of SOAP header processing. This is desirable to avoid code repitition when you have several web service methods which use the same set of headers. To implement this, define a base class which processes your headers, and derive from it to create a web service class with your web service methods.
• Limitations: The WSDL specification says that <soap:header> binding elements don't have to use the same <message> as those used by the <operation> being bound. My implementation only allows the same to be used. This should have no effect on your services in practice.
• Limitations: .NET generates SOAP headers whose element names are the type names of their arguments. This means each header must include (and optionally return) precisely one argument; additionally the argument must be a complexType for the web service to import properly into Visual Studio. This also means that the PHP 5 method name which processes the header must be the same as the type name of its argument, eg. public function LoginObject($loginobject) where $loginobject is of type LoginObject. PHP 5 doesn't have the element naming, argument count or complexType restrictions, but in order to produce interoperable WSDL and eliminate the possibility of duplicate <part> names in a single <message> (where the arguments to a header and body method have the same name), my implementation co-erces part names representing headers to be the name of the type used as the argument, not the name of the argument itself. Therefore, if you use my implementation to generate WSDL, you must follow the .NET limitations, even if your client is PHP. Again, in practice, this should only be a minor inconvenience.
• Access from .NET: In .NET languages such as C# and VB.NET, SOAP headers are available as read/write properties of the web service proxy class generated when your WSDL is imported into Visual Studio.

• Background: The original release of wsdl-writer-0.3 only scans the top level of types used (ie. the arguments and return parameters of each method). If any such argument or return parameter has properties which are themselves complexTypes or arrays of complexTypes (such as objects which have other objects or arrays of objects as public member variables), these are also needed in the <types> section to fully define the parent type.
• Example: If you have a web service with returns an array of Foo, and Foo has properties of class types Bar and Baz, and Bar has a property of type array of string, the following types will be defined in the WSDL file: ArrayOfFoo, Foo, Bar, Baz and ArrayOfstring (the original release code would only include Foo and its type definition would be empty).

Other bug fixes:

• Command-line WSDL generation now works correctly
• Multiple complexType class definitions in the same file which have some properties with the same name could cause the <types> section of the WSDL file to be generated incorrectly. This has been fixed.
• Constructors and PHP magic methods will be excluded from the generated WSDL
• SOAP servers using SOAP sessions may have a constructor in their web service classes to initialise new sessions to default values, so this exclusion is important
• Strict Standards warnings in PHP 5 fixed

Processing SOAP headers in a PHP SOAP server

Here is an example of a web service class which processes headers and a body method:

 
// To be supplied as a SOAP header element - remember that individual headers must
// consist of exactly one complexType argument, so basic xsd types must be boxed in a class
class WrappedString
{
    /** @var string Data */
    public $data;
    
    public function __construct($s)
    {
        $this->data = $s;
    }
}

// Login credentials to be supplied as a SOAP header
class LoginObject
{
    /** @var int Login */
    public $login;
    /** @var int Password */
    public $password;
    
    public function __construct($l, $p)
    {
        $this->login = $l;
        $this->password = $p;
    }
}

// Arbitrary object returned by the test web service method
// to prove that the header data was stored in the same class instance
class TestObject
{
    /** @var string Result string */
    public $result;
    /** @var int Demo session key */
    public $sessionkey;
    
    public function __construct($r, $k)
    {
        $this->result = $r;
        $this->sessionkey = $k;
    }
}

class MethodWithHeaders
{
    public $sessionKey;

    /**
     * HeaderA SOAP header
     *
     * To process a SOAP header, create a function with the same name
as the header's complexType.
     * Returned values will be sent back to the client as a SOAP response header.
     * This example returns the string in a response header, converted to uppercase.
     *
     * @param WrappedString $string Input string
     * @return WrappedString Capitalised string
     * @internal soapheader
     */
    public function WrappedString($string)
    {
        return new WrappedString(strtoupper($string->data));
    }
    
    /**
     * HeaderB SOAP header
     *
     * You don't have to return a value - you can store the details sent
     * in the header for later use.
     *
     * @param LoginObject $loginobject Username and password
     * @internal soapheader
     */
    public function LoginObject($loginobject)
    {
        $this->sessionKey = $loginobject->login * $loginobject->password;
    }
    
    /**
     * Some test web service
     *
     * Body function - shows that a single MethodWithHeaders object
     * instantiation is used for all the headers and the body method,
     * because $this->sessionKey hasn't been declared static.
     *
     * @param string $string Input string
     * @return TestObject Input string and demo session key based on
header fields
     * @internal soaprequires WrappedString LoginObject
     */
    public function testfunction($string)
    {
        return new TestObject($string, $this->sessionKey);
    }
}

NOTE: Ironically the type hinting introduced into PHP 5.1 causes PHP SOAP servers to fail, so you should not use type hinting in your web service method or header prototypes.

Supplying SOAP headers and accessing SOAP response headers in a PHP web service client

The following code calls the server example above. Some items in [square brackets] require substitution as appropriate.

// Create SOAP client using only WSDL
$headersClient = new SoapClient("[Location of WSDL file]"); 

// Create headers (use same element name and type name
// for .NET interoperability - not required for PHP)
$headerA = new SoapHeader('[Namespace URI of WrappedString]',
                 'WrappedString', new WrappedString('some test string')); 
$headerB = new SoapHeader('[Namespace URI of LoginObject]',
                 'LoginObject', new LoginObject(14, 3)); 
$headersClient->__setSoapHeaders(array($headerA, $headerB)); 

// Standard call which passes input headers
// but doesn't offer access to output headers
$headersClient->testfunction("Echo me!")); 

// Call which allows access to output headers
// (input headers persist until changed)
$headersClient->__soapCall('testfunction', array("Echo me again!"),
                           null, null, $outputHeaders); 
print_r($outputHeaders);

Note you need to include definitions of WrappedString or LoginObject in the client code.

Final notes

The changes to wsdl-writer and examples above have been tested against PHP 5.1.1 and Visual Studio .NET 2003 (.NET Framework 1.1). For general usage examples please refer to the examples supplied with the source code.

I hope you find this code useful!

Please send feedback using the contact page or use the comment form below.