README

Overview

This is my attempt to address the shortcommings of the native PHP SOAP Client implementation (\SoapClient).

Usage

Instantiate

<?php
$soapClient = new \Camcima\Soap\Client($wsdl, $options, $sslVerifyPeer);

The default value of sslVerifyPeer is true, which means that SSL certificate will be verified. If WSDL file is hosted on a server that has an invalid SSL certificate or self-signed certificate, set sslVerifyPeer to false.

cURL Options

This wrapper uses cURL to issue the HTTP requests. It's possible to customize the SOAP request using cURL options.

<?php
$curlOptions = array(
    CURLOPT_CRLF => true,
    CURLOPT_SSL_VERIFYPEER => true
);
$soapClient = new \Camcima\Soap\Client($wsdl, $options);
$soapClient->setCurlOptions($curlOptions);

There are a few cURL options, however, that can't be overwritten as they are essential for the wrapper:

<?php
// Mandatory cURL Options
CURLOPT_POST => true
CURLOPT_HEADER => true

To get the cURL options currently in use:

<?php
$curlOptions = $soapClient->getCurlOptions();

Use Proxy

If you need to proxy the requests (e.g. debugging), you can use this method to set the proxy host, port and type:

<?php
$soapClient->useProxy('proxy.local', 8080, CURLPROXY_SOCKS5);

The default hostname, port and type for this methods are localhost, 8888 and CURLPROXY_HTTP, which is the default binding for Fiddler Web Debugging Proxy (http://fiddler2.com/).

Proxy Auth

If your proxy need auth, you can use this method to set proxy username and password:

<?php
$soapClient->setProxyAuth('proxy_user', 'proxy_password');

Authentication

In order to use HTTP Authentication, use SoapClient original login and password options. The cURL client will get it from there.

<?php
$soapClient = new Client($wsdlUrl, ['login' => 'joelogin', 'password' => 'joepassword']);

User Agent

It's possible to customize the User Agent used by the client:

<?php
$soapClient->setUserAgent('MyUserAgent/1.0');

Lower Cased Initial Character

When I was developing an integration with a .NET based web-service, I've noticed the name of the root element of the SOAP request payload always had the first letter lowercased. This didn't hold true for the other inner elements which had always the first letter uppercased, common for class names. I don't know if this is the norm for .NET web-services but, in any case, I've implemented an option that handles this.

<?php
$soapClient->setLowerCaseFirst(true);

The default for this setting is false.

Keep Null Properties

When you pass an object as a SOAP parameter, some of its properties could be null (or not set). The default behavior for this client is to omit these null properties when sending the request. If you need to send all properties, even when null, use this:

<?php
$soapClient->setKeepNullProperties(true);

The default for this setting is true.

Debug

In order to debug requests and responses, you need to set the debug mode to true and the debug file name and path.

<?php
$soapClient->setDebug(true);
$soapClient->setDebugLogFilePath(__DIR__ . '/../../../../log/debug.log');

Last Request Communication Log

You can get the HTTP communication log (request and response) from the last request.

<?php
$soapClient->getCommunicationLog();

Result Class Mapping

PHP native implementation of SOAP client has the ability to map the SOAP return to local classes. Unfortunately it didn't work for me as expected. So I've implemented my own version of result class mapping.

It works in two different flavors:

Using Classmap

You have to build an associative array with the result elements as keys, and the corresponding local classes as values.

<?php
$soapClient = new Client($wsdlUrl);
$soapResult = $soapClient->GetCityForecastByZIP($getForecastByZip);
$resultClassmap = array(
    'GetCityForecastByZIPResult' => '\Camcima\Soap\Test\Fixtures\GetCityForecastByZIPResult',
    'ForecastResult' => '\Camcima\Soap\Test\Fixtures\ForecastResult',
    'array|Forecast' => '\Camcima\Soap\Test\Fixtures\ForecastEntry',
    'Temperatures' => '\Camcima\Soap\Test\Fixtures\Temperatures',
    'ProbabilityOfPrecipiation' => '\Camcima\Soap\Test\Fixtures\ProbabilityOfPrecipiation'
);
$getCityForecastByZIPResult = $soapClient->mapSoapResult($soapResult, 'GetCityForecastByZIPResult', $resultClassmap, true);

The native SOAP client returns all objects as Standard Classes (StdClass) and my mapping function "casts" them to the mapped local classes. This functions is based on the property name that holds the standard class object. This works pretty well in most scenarios, but when there is an array of objects, it needs a special config:

<?php
$mapping = array(
    'array|Forecast' => '\Camcima\Soap\Test\Fixtures'
);

The name of the property which holds the array serves as the marker for the mapping. You also need to prefix this element name with array and use pipe (|) to separate them.

If we get array of simple type like

<xsd:element name="ForecastIcons" type="tns:ArrayOfString"/>

we need mapping to array, so it will extract data from item attribute (doesn't require SOAP_SINGLE_ELEMENT_ARRAYS feature in SoapClient)

<?php
$mapping = array(
    'ForecastIcons' => 'array'
);

Using Namespace

If all your result classes reside in the same namespace, there is no need to map them individually. You can tell the mapper the namespace your classes live and it will automatically determine the mapping by matching the SOAP result names with the local class names.

<?php
$resultClassNamespace = '\MyProject\SOAP\Result\\';

Skip Root Object

Sometimes, the webservice will return an object with only one property, so it doesn't make a lot of sense to create a wrapper object just for that. In that case, you can use the skipRootObject parameter in the mapSoapResult method to skip the root object and return the inner property instead.

<?php

public function mapSoapResult($soapResult, $rootClassName, array $resultClassMap = array(), $resultClassNamespace = '', $skipRootObject = false);

Improvements

I plan to include new features according to my needs. If you need a special feature you have two options:

Develop it yourself and send me a pull request. I promise to merge it ASAP.
Create an issue and wait for me to develop it. This can take some time, as I'm usually quite busy.

camcima / camcima-soap-client

Maintainers

Details