spacer
spacer

PHP SOAP

Introduction

PHP SOAP is included with PHP 5 making it the simplest SOAP tool kit to set-up.

Creating a Service Proxy

For SOAP services providing a WSDL document, a service proxy object can be generated from the WSDL at runtime, allowing access to the current service interface.

For example using the WSDbfetch RPC/encoded SOAP service (examples/SOAP/PHP-SOAP/wsdbfetch_php_soap.php):

// WSDbfetch WSDL URL
$wsdlUrl = 'http://www.ebi.ac.uk/ws/services/WSDbfetch?wsdl';
// Default option values
$query = 'uniprot:wap_rat';
$format = 'fasta';
$style = 'raw';
 
try {
  // Get a service proxy from the WSDL
  $proxy = new SoapClient($wsdlUrl);
 
  // Perform the query
  $result = $proxy->fetchData($query, $format, $style);
  // Output the result
  echo $result;
}
// Catch SoapFault exceptions, and report the message.
catch(SoapFault $ex) {
  echo 'SoapFault: ';
  if($ex->getMessage() != '') echo $ex->getMessage();
  else echo $ex;
  echo "\n";
}

When using RPC/encoded SOAP services the parameters to a SOAP operation can be provided positionally (e.g. $proxy→fetchData($query, $format, $style);). In contrast document/literal wrapped SOAP services require the wrapping objects to be used for request and response. For example using the WSDbfetch document/literal wrapped SOAP service (examples/SOAP/PHP-SOAP/wsdbfetch_doclit_php_soap.php):

// WSDbfetch WSDL URL
$wsdlUrl = 'http://www.ebi.ac.uk/ws/services/WSDbfetchDoclit?wsdl';
// Default option values
$query = 'uniprot:wap_rat';
$format = 'fasta';
$style = 'raw';
 
try {
  // Get a service proxy from the WSDL
  $proxy = new SoapClient($wsdlUrl);
 
  // Perform the query
  $res = $proxy->fetchData(array(
                                 'query' => $query,
                                 'format' => $format,
                                 'style' => $style
                          ));
  $result = $res->fetchDataReturn;
  // Output the result
  echo $result;
}
// Catch SoapFault exceptions, and report the message.
catch(SoapFault $ex) {
  echo 'SoapFault: ';
  if($ex->getMessage() != '') echo $ex->getMessage();
  else echo $ex;
  echo "\n";
}

Complex Data Structures

The methods in the WSDbfetch service all use simple string parameters. Many of the other EMBL-EBI services use more complex input structures. For example to submit a job to the FASTA (SOAP) service (examples/SOAP/PHP-SOAP/fasta_php_soap.php):

Create a structure containing the various parameters and the input sequence to be passed to the run method:

  // Input parameters
  $params = array(
		  'email' => $email, // User e-mail address.
                  'title' => $title, // Optional job title.
                  'parameters' => array(
		    'program' => 'fasta', // Program to perform search
		    'database' => array( // Database(s) to search
                      'pdb'
                    ),
		    'scores' => 10, // Number of hit summary scores
		    'alignments' => 10, // Number of hit alignments
                    'stype' => 'protein', // Sequence type
                    'sequence' => $querySequence // Query sequence
                  )
		  );
 
  // Submit the job
  echo 'Sumbit job...', "\n";
  $res = $proxy->run($params);
  if($message_trace) soapTrace($proxy); // Output message trace.
  $jobId = $res->jobId;
  echo 'Job ID: ', $jobId, "\n";

The run method returns a job identifier which can be used with the getStatus method to get the status of the job (e.g. RUNNING, FINISHED or ERROR) and the getResult method to get the results of the job (assuming the out output is available):

  // Poll till job finishes
  $status = 'PENDING';
  while(strcmp($status, 'RUNNING') == 0 || strcmp($status, 'PENDING') == 0) {
    sleep(5);
    $res = $proxy->getStatus(array('jobId' => $jobId));
    if($message_trace) soapTrace($proxy); // Output message trace.
    $status = $res->status;
    echo 'Job status: ', $status, "\n";
  }
 
  // Get the main result
  $res = $proxy->getResult(array(
				'jobId' => $jobId,
				'type' => 'out'
				)
                          );
  if($message_trace) soapTrace($proxy); // Output message trace.
  $result = $res->output;
  echo $result;

SOAP Message Trace

It is useful when debugging a client to be able to see the actual SOAP messages exchanged. PHP SOAP provides a trace option which can be used to enable access to these messages:

  $options = array(
		   'trace' => true
                  );
  $proxy = new SoapClient($wsdlUrl, $options);
 
  // Output SOAP message trace data.
  function soapTrace($proxy) {
    echo "REQUEST:\n" . $proxy->__getLastRequest() . "\n";
    echo "RESPONSE:\n" . $proxy->__getLastResponse() . "\n";
  }
 
  // Submit the job
  $res = $proxy->run($params);
  soapTrace($proxy); // Output SOAP messages
  $jobId = $res->jobId;
  echo "$jobId\n";

HTTP Proxies

In some environments it is necessary to configure an HTTP proxy before a client can connect to external services. PHP SOAP supports setting proxy information via options to the SoapClient constructor:

  $options = array(
	           'proxy_host' => 'proxy.example.org',
	           'proxy_port' => 8080,
		   );
  $proxy = new SoapClient($wsdlUrl, $options);

HTTP User-Agent

HTTP clients usually provide information about what they are, this allows services to handle specific clients differently if necessary, and gives service providers information about how their services are being used. By default PHP SOAP sets the HTTP User-Agent header (see RFC2616 section 14.43) to something like PHP-SOAP/5.1.6, where the version number (5.1.6) is the version of PHP. If additional identification of the client is required the a more specific product token (see RFC2616 section 3.8) should be added to the beginning of the User-Agent string:

  // Modify the user-agent to add a more specific prefix (see RFC2616 section 14.43)
  $uname  = posix_uname();
  $userAgent = 'Example-Client/1.0 (' . $uname['sysname'] . ') PHP-SOAP/' . phpversion();
  $options = array(
                   'user_agent' => $userAgent
                  );
  $proxy = new SoapClient($wsdlUrl, $options);

Note: while the HTTP specification does not define a limit on the size of HTTP headers, web server implementations often do limit the maximum size of an HTTP header to 8KB or 16KB. If the server limit for an HTTP header is exceeded a “400 Bad Request” will be returned by the server.

HTTP Compression

PHP SOAP provides support for on the fly compression of HTTP requests and decompression of HTTP responses, which can save bandwidth and improve the performance of data transfers between the client and the web service. To enable HTTP compression add the compression option when creating the service proxy. For example:

  $options = array(
		   'compression' => true
		   );
  $proxy = new SoapClient($wsdlUrl, $options);

Sample Clients

Most SOAP Web Services at EMBL-EBI have sample clients which provide command-line access to the service and example code. For PHP some of the clients are based on PHP-SOAP.

Document/literal SOAP

RPC/encoded SOAP

Service Sample client
WSDbfetch wsdbfetch_cli_php_soap.php


Up PHP Contents Contents
 
tutorials/06_programming/php/soap/php-soap.txt · Last modified: 2014/04/03 12:43 by hpm
spacer
spacer