Home » Php » web services – Handling Soap timeouts in PHP

web services – Handling Soap timeouts in PHP

Posted by: admin April 23, 2020 Leave a comment


I’m working on a project where I am verifying information from a user with a SOAP web service. I currently am taking care of errors assuming that I’m receiving responses from the web service, but also need to handle the edge cases of a service timeout or unavailability.

In the case of a timeout or service unavailability, I need to pretend that the request was successful (that the web service approved the info), but I’m not clear on what exceptions are thrown.

Some pseudo-code:

// $client is PHP's SoapClient class
try {
  $response = $client->SomeSoapRequest();
catch(SoapFault $e){
  // handle issues returned by the web service
catch(Exception $e){
  // handle PHP issues with the request

What I can’t seem to find is:

  1. Are timeouts a SoapFault? If so, what is the best way to distinguish between a timeout error and web service issues (like a type error, etc.)? I found one page that mentioned an error where the message was something to the effect of “Error loading headers”, but didn’t mention if this was a Soap fault.
  2. How is a service unavailability potentially going to happen? A PHP exception seems like it would make sense (a SoapFault would be returned from the web service where unavailability would be a socket issue or similar)?
  3. Is there an existing service (e.g. example) that I can test a timeout against? Most timeout related discussions seem to be related to preventing timeouts by extending the default timeout setting, which isn’t ideal in this situation.
How to&Answers:

1) In case of timeout, PHP throws a SoapFault exception with faultcode="HTTP" and faultstring="Error Fetching http headers".

2) In my opinion, the best way to distinguish between a timeout error and web service issues is by looking at the faultcode and faultstring members of the SoapFault class.
In particular, the faultcode element is intended for use by software to provide an algorithmic mechanism for identifying the fault.
As you can also read in a comment of the PHP manual, there is no method to read the faultcode property, so you have to access it directly (eg. $e->faultcode), because the getCode() method does not work.
The SOAP 1.1 Spec defines four possible values for the faultcode field:

  • VersionMismatch: The processing party found an invalid namespace for the SOAP Envelope element
  • MustUnderstand: An immediate child element of the SOAP Header element that was either not understood or not obeyed by the processing party contained a SOAP mustUnderstand attribute with a value of “1”
  • Client: The Client class of errors indicate that the message was incorrectly formed or did not contain the appropriate information in order to succeed. For example, the message could lack the proper authentication or payment information. It is generally an indication that the message should not be resent without change.
  • Server: The Server class of errors indicate that the message could not be processed for reasons not directly attributable to the contents of the message itself but rather to the processing of the message. For example, processing could include communicating with an upstream processor, which didn’t respond. The message may succeed at a later point in time.

In addition to those codes, PHP uses the HTTP code for identifying the errors happening at the protocol level (eg.: socket errors); for example, if you search for add_soap_fault in the ext/soap/php_http.c source code you can see when some of these kind of faults are generated.
By searching for the add_soap_fault and soap_server_fault functions in the PHP SOAP extension source files, I’ve built the following list of PHP SoapFault exceptions:

Unable to parse URL
Unknown protocol. Only http and https are allowed.
SSL support is not available in this build
Could not connect to host
Failed Sending HTTP SOAP request
Failed to create stream??
Error Fetching http headers
Error Fetching http body: No Content-Length: connection closed or chunked data
Redirection limit reached: aborting
Didn't recieve an xml document
Unknown Content-Encoding
Can't uncompress compressed response
Error build soap request

Wrong Version

A SOAP 1.2 envelope can contain only Header and Body
A SOAP Body element cannot have non Namespace qualified attributes
A SOAP Envelope element cannot have non Namespace qualified attributes
A SOAP Header element cannot have non Namespace qualified attributes
Bad Request
Body must be present in a SOAP envelope
Can't find response data
DTD are not supported by SOAP
encodingStyle cannot be specified on the Body
encodingStyle cannot be specified on the Envelope
encodingStyle cannot be specified on the Header
Error cannot find parameter
Error could not find "location" property
Error finding "uri" property
looks like we got "Body" with several functions call
looks like we got "Body" without function call
looks like we got no XML document
looks like we got XML without "Envelope" element
Missing parameter
mustUnderstand value is not boolean
SoapClient::__doRequest() failed
SoapClient::__doRequest() returned non string value
Unknown Data Encoding Style
Unknown Error

Header not understood

Couldn't find WSDL
DTD are not supported by SOAP
Unknown SOAP version
WSDL generation is not supported yet

3) To simulate the timeout condition, try with the following code:



ini_set('default_socket_timeout', 10);

$client = new SoapClient(null, 
    'location' => "http://localhost/soapserver.php",
    'uri'      => "http://localhost/soapserver.php",
    'trace'    => 1

try {
    echo $return = $client->__soapCall("add",array(41, 51));
} catch (SoapFault $e) {
    echo "<pre>SoapFault: ".print_r($e, true)."</pre>\n";
    //echo "<pre>faultcode: '".$e->faultcode."'</pre>";
    //echo "<pre>faultstring: '".$e->getMessage()."'</pre>";




function add($a, $b) {
  return $a + $b;


$soap = new SoapServer(null, array('uri' => 'http://localhost/soapserver.php'));


Notice the sleep call in the SoapServer.php script with a time (20) longest than the time (10) specified for the default_socket_timeout parameter in the SoapClient.php script.
If you want to simulate a service unavailability, you could for example change the location protocol from http to https in the soapclient.php script, assuming that your web server is not configured for SSL; by doing this, PHP should throw a “Could not connect to host” SoapFault.


Looks like default_socket_timeout is not taken into account when making SOAP calls over HTTPS:

Bug open at the time of writing. As a comment on the blog post Robert Ludwick referenced in a deleted answer Timing Out PHP Soap Calls (21 Oct 2009; by Published by Robert F. Ludwick) points out, the workaround the post discusses (overriding SoapClient::__doRequest() with a curl request) works around this bug also.

Another related bug is:

The code mentioned in the blog post has undergone some changes and can be found in it’s latest form with support of HTTP authentication here on Github:

In any case, the workaround shouldn’t be needed any longer as this problem has been fixed in the PHP SOAPClient extension.


From my experience, if $e->getMessage is “Error Fetching http headers”, you are dealing with a network timeout.

If $e->getMessage is something like “Cannot connect to host”, the service you are trying to reach is down.

Then there is “Looks like we got no XML document”, which is more cryptic an can mean different things.


To deal with timeouts in the service

$client = new SoapClient($wsdl, array("connection_timeout"=>10));

if(defined('RESPONSE_TIMEOUT') &&  RESPONSE_TIMEOUT != '') {
 ini_set('default_socket_timeout', RESPONSE_TIMEOUT);


I used two factors to get my SoapClient extention to throw a nice exception. The message and the time the request took to return. I think the error message “Error Fetching http headers” can also occure in some other cases, therefore the time check.

The following code should be about right

class SoapClientWithTimeout extends SoapClient {
    public function __soapCall ($params, ---) {
        $time_start = microtime(true);
        try {
            $result = parent::__soapCall ($params, ---);
        catch (Exception $e) {
            $time_request = (microtime(true)-$time_start);
                $e->getMessage() == 'Error Fetching http headers' &&
                ini_get('default_socket_timeout') < $time_request
            ) {
                throw new SoapTimeoutException(
                    'Soap request most likly timed out.'.
                    ' It took '.$time_request.
                    ' and the limit is '.ini_get('default_socket_timeout')

            // E: Not a timeout, let's rethrow the original exception
            throw $e;

        // All good, no exception from the service or PHP
        return $result;

class SoapTimeoutException extends Exception {}

I then use SoapClientWithTimeout

$client = new SoapClientWithTimeout();
try {
    $response = $client->SomeSoapRequest();
catch(SoapTimeoutException $e){
    echo 'We experienced a timeout! '. $e->getMessage();
catch(Exception $e) {
    echo 'Exception: '.$e->getMessage();

To debug your service timing out. Add the following line before calling the service

ini_set('default_socket_timeout', 1);


Simply setting the default_socket_timeout globally via the ini may not do what you want. This would affect SOAP requests, but would also affect other outgoing connections, including DB connections. Instead, override SoapClient’s __doRequest() method to make the HTTP connection yourself. You can then set your own timeout on the socket, detect it, and throw exceptions that you can trap and handle.

class SoapClientWithTimeout extends SoapClient {

    public function __construct ($wsdl, $options = null) {
        if (!$options) $options = [];

        $this->_connectionTimeout =
            ?: ini_get ('default_socket_timeout');
        $this->_socketTimeout =
            ?: ini_get ('default_socket_timeout');
        unset ($options['socket_timeout']);

        parent::__construct($wsdl, $options);

     * Override parent __doRequest to add a timeout.
    public function __doRequest (
        $request, $location, $action, $version, $one_way = 0
    ) {
        // Extract host, port, and scheme.
        $url_parts = parse_url ($location);
        $host = $url_parts['host'];
        $port =
            ?: ($url_parts['scheme'] == 'https' ? 443 : 80);
        $length = strlen ($request);

        // Form the HTTP SOAP request.
        $http_req = "POST $location HTTP/1.0\r\n";
        $http_req .= "Host: $host\r\n";
        $http_req .= "SoapAction: $action\r\n";
        $http_req .= "Content-Type: text/xml; charset=utf-8\r\n";
        $http_req .= "Content-Length: $length\r\n";
        $http_req .= "\r\n";
        $http_req .= $request;

        // Need to tell fsockopen to use SSL when requested.
        if ($url_parts['scheme'] == 'https')
            $host = 'ssl://'.$host;

        // Open the connection.
        $socket = @fsockopen (
            $host, $port, $errno, $errstr, $this->_connectionTimeout
        if (!$socket)
            throw new SoapFault (
                "Failed to connect to SOAP server ($location): $errstr"

        // Send the request.
        stream_set_timeout ($socket, $this->_socketTimeout);
        fwrite ($socket, $http_req);

        // Read the response.
        $http_response = stream_get_contents ($socket);

        // Close the socket and throw an exception if we timed out.
        $info = stream_get_meta_data ($socket);
        fclose ($socket);
        if ($info['timed_out'])
            throw new SoapFault (
                "HTTP timeout contacting $location"

        // Extract the XML from the HTTP response and return it.
        $response = preg_replace (
                \A       # Start of string
                .*?      # Match any number of characters (as few as possible)
                ^        # Start of line
                \r       # Carriage Return
                $        # End of line
            '', $http_response
        return $response;



Guess I’m little late, but in case someone is still looking for solution to timeouts in php soap client – here’s what’s worked for me:

Basicly replacing PHP SoapClient with cURL with set timeout. Just keep in mind, sometimes WS expects action specified in HTTP header. Original solution posted on that website doesn’t include that (check comments).


just use the “stream_context” to set the timeout setting also for WSDL loading (you need to set the SoapClient $options[‘connection_timeout’] before):

class SoapClient2 extends SoapClient
  public function __construct($wsdl, $options=null)
      $s_options = array(
          'http' => array(
              'timeout' => $options['connection_timeout']
      $options['stream_context'] = stream_context_create($s_options);
    parent::__construct($wsdl, $options);