PHP SOAP

SOAP extension can be used to write SOAP Servers and Clients. It supports subsets of SOAP 1.1, SOAP 1.2 and WSDL 1.1 specifications.

Requirements

Installation

Runtime Configuration

The behaviour of these functions is affected by settings in php.ini.

soap.wsdl_cache_enabled (boolean)

enables or disables WSDL caching feature.

soap.wsdl_cache_dir (string)

sets the directory name where SOAP extension will put cache files

soap.wsdl_cache_ttl (integer)

(time to live) sets the number of second while cached file will be used instead of original one.

Predefined Constants

Classes

List of classes

is_soap_fault

(PHP 5)

checks if SOAP call was failed

Description

bool is_soap_fault(mixed obj)

This function is useful when you like to check if the SOAP call was failed, but don't like to use exceptions. To use it you must create SoapClient object with exceptions option set to zero or false. In this case SOAP method will return a special SoapFault object which encapsulate the fault details (faultcode, faultstring, faultactor and faultdetails). If exceptions is not set then SOAP call will throw an exception on error.
is_soap_fault() functions checks if the given parameter is a SoapFault object.

Example

<?php
    $client = SoapClient("some.wsdl",array("exceptions"=>0));
    $result = $client->SomeFunction(...);
    if (is_soap_fault($result)) {
        trigger_error("SOAP Fault: (faultcode: {$result->faultcode}, faultstring: {$result->faulstring})", E_ERROR);
    }
?>

Standard method that used by SOAP extension for error reporting is excptions.

<?php
    try {
        $client = SoapClient("some.wsdl");
        $result = $client->SomeFunction(...);
    } catch (SoapFault $fault) {
        trigger_error("SOAP Fault: (faultcode: {$fault->faultcode}, faultstring: {$fault->faulstring})", E_ERROR);
    }
?>

SoapClient::SoapClient

(PHP 5)

SoapClient constructor

Description

SoapClient(mixed wsdl [, array options])

The constructor allows creating SoapClient objects in WSDL or nonWSDL mode. The first case requires URI of WSDL file as first parameter and optional options array. The second case requires NULL as first parameter and options array with location and uri options set. Where location is a URL to request and uri is a target namespace of the SOAP service. style and use options has effect only on nonWSDL (in WSDL mode they comes from WSDL file). soap_version option allows to work as SOAP 1.1 or SOAP 1.2 client. Some additional optional options allow using HTTP authentication (login and password) and HTTP connection through proxy server (proxy_host, proxy_port, proxy_login and proxy_password).

Examples

    $client = new SoapClient("some.wsdl");

    $client = new SoapClient("some.wsdl",array('soap_version'   => SOAP_1_2));

    $client = new SoapClient("some.wsdl",array('login'          => "some_name",
                                               'password'       => "some_password"));

    $client = new SoapClient("some.wsdl",array('proxy_host'     => "localhost",
                                               'proxy_port'     => 8080));

    $client = new SoapClient("some.wsdl",array('proxy_host'     => "localhost",
                                               'proxy_port'     => 8080,
                                               'proxy_login'    => "some_name",
                                               'proxy_password' => "some_password"));

    $client = new SoapClient(null,array('location' => "http://localhost/soap.php",
                                        'uri'      => "http://test-uri/"));

    $client = new SoapClient(null,array('location' => "http://localhost/soap.php",
                                        'uri'      => "http://test-uri/",
                                        'style'    => SOAP_DOCUMENT,
                                        'use'      => SOAP_LITERAL));

SoapClient::__call

(PHP 5)

calls a SOAP function

Description

mixed __call(string function_name, array arguments, [array options [, mixed input_headers [, mixed &output_headers]]])

This is a low level API function to make a SOAP call. Usually in WSDL mode you can simple call SOAP functions as SoapClient methods. It is useful for nonWSDL mode when 'soapaction' is unknown, 'uri' is differ form default or when ypu like to send and/or receive SOAP Headers. To check if function call is failed check the result with is_soap_fault() function.
SOAP function may return one or several values. In the first case __call will return just the value of output parameter, in the second it will return array with named output parameters.

Examples

    $client = new SoapClient("some.wsdl");
    $client->SomeFunction($a,$b,$c);
    $client->__call("SomeFunction",array($a,$b,$c));
    $client->__call("SomeFunction",array($a,$b,$c), NULL,
                    new SoapHeader(...), $output_headers);


    $client = new SoapClient(null,array('location' => "http://localhost/soap.php",
                                        'uri'      => "http://test-uri/"));
    $client->SomeFunction($a,$b,$c);
    $client->__call("SomeFunction",array($a,$b,$c));
    $client->__call("SomeFunction",array($a,$b,$c),
                    array('soapaction' => 'some_action',
                          'uri'        => 'some_uri'));

SoapClient::__getLastRequest

(PHP 5)

returns last SOAP request

Description

string __getLastRequest()

This function works only with SoapClient which was created with trace option.

Example

<?php
    $client = SoapClient("some.wsdl", array('trace'=>1));
    $result = $client->SomeFunction(...);
    echo "REQUEST:\n".$client->__getLastRequest()."\n";
?>

SoapClient::__getLastResponse

(PHP 5)

returns last SOAP response

Description

string __getLastResponse()

This function works only with SoapClient which was created with trace option.

Example

<?php
    $client = SoapClient("some.wsdl", array('trace'=>1));
    $result = $client->SomeFunction(...);
    echo "RESPONSE:\n".$client->__getLastResponse()."\n";
?>

SoapClient::__getFunctions

(PHP 5)

returns list of SOAP functions

Description

array __getFunctions()

This function works only in WSDL mode.

Example

<?php
    $client = SoapClient("some.wsdl");
    var_dump($client->__getFunctions());
?>

SoapClient::__getTypes

(PHP 5)

returns list of SOAP types

Description

array __getTypes()

This function works only in WSDL mode.

Example

<?php
    $client = SoapClient("some.wsdl");
    var_dump($client->__getTypes());
?>

SoapServer::SoapServer

(PHP 5)

SoapServer constructor

Description

SoapServer(mixed wsdl [, array options])

Examples

    $server = new SoapServer("some.wsdl");

    $server = new SoapServer("some.wsdl",array('soap_version'=>SOAP_1_2));

    $server = new SoapServer("some.wsdl",array('actor'=>"http://example.org/ts-tests/C"));

    $server = new SoapServer(null,array('uri'=>"http://test-uri/"));

    function func($inputString) {
        return $inputString;
    }
    $server->addFunction("echoString");

    function echoTwoStrings($inputString1, $inputString2) {
        return array("outputString1"=>$inputString1,"outputString2"=>$inputString2);
    }
    $server->addFunction(array("echoString","echoTwoStrings"));

    $server->addFunction(SOAP_FUNCTIONS_ALL);

SoapServer::setClass

(PHP 5)

sets class which will handle SOAP requests

Description

void setClass(string class_name [, ...])

Examples

    $server->setClass("foo");

    $server->setClass("foo", $arg1, $arg2);

SoapServer::setPersistence

(PHP 5)

sets persistence mode of SoapServer

Description

void setPersistence(int mode)

Examples

    $server->setpersistence(SOAP_PERSISTENCE_SESSION);

    $server->setpersistence(SOAP_PERSISTENCE_REQUEST);

SoapServer::handle

(PHP 5)

handles a SOAP request

Description

void handle([string soap_envelope])

Example

<?php
    function test($x) {
        return $x;
    }

    $server = new SoapServer(null,array('uri'=>"http://test-uri/"));
    $server->addFunction("test");
    $server->handle();
?>

SoapParam::SoapParam

(PHP 5)

SoapParam constructor

Description

SoapParam(mixed data, string name)

SoapParam is a special low-level class for naming parameters and return values in nonWSDL mode. It is just a data holder and it has not any special method except constructor. The constructor takes data to pass or return and name. It is possible to pass parameter directly as PHP value, but in this case it will be named as paramN and SOAP Service may not understand it.

Example

<?php
    $client = new SoapClient(null,array('location' => "http://localhost/soap.php",
                                        'uri'      => "http://test-uri/"));
    $client->SomeFunction(new SoapParam($a,"a"),
                          new SoapParam($b,"b"),
                          new SoapParam($c,"c"));
?>

SoapVar::SoapVar

(PHP 5)

SoapVar constructor

Description

SoapVar(mixed data, int encoding [, string type [, string type_ns [, string name [, string name_ns]]]])

SoapVar is a special low-level class for encoding parameters and return values in nonWSDL mode. It is just a data holder and it has not any special method except constructor. It is useful when you like to set type property in SOAP request or response. The constructor takes data to pass or return, encoding ID to encode it (see XSD_... constants) and as option type name and namespace and value name and namespace.

Example

<?php
    class SOAPStruct {
    	function SOAPStruct($s, $i, $f) {
    		$this->varString = $s;
    		$this->varInt = $i;
    		$this->varFloat = $f;
    	}
    }
    $client = new SoapClient(null,array('location' => "http://localhost/soap.php",
                                        'uri'      => "http://test-uri/"));
    $struct = new SOAPStruct('arg',34,325.325);
    $soapstruct = new SoapVar($struct,SOAP_ENC_OBJECT,"SOAPStruct","http://soapinterop.org/xsd");
    $client->echoStruct(new SoapParam($soapstruct, "inputStruct"));
?>

SoapHeader::SoapHeader

(PHP 5)

SoapHeader constructor

Description

SoapHeader(string name_ns, string name [, mixed data [, bool must_understand [, mixed actor]]])

SoapHeader is a special low-level class for passing or returning SOAP headers. It is just a data holder and it has not any special method except constructor. It can be used in SoapClient::__call method to pass SOAP header or in SOAP header handler to return header in SOAP response. name_ns and name are namespace and name of the SOAP header element. data is a SOAP header's content. It can be a PHP value or SoapVar object. must_understand and actor are values for mustUnderstand and actor attributes of this SOAP Header element.

Example

<?php
    $client = new SoapClient(null,array('location' => "http://localhost/soap.php",
                                        'uri'      => "http://test-uri/"));
    $client->__call("echoVoid",NULL,NULL,
                    new SoapHeader('http://soapinterop.org/echoheader/',
                                   'echoMeStringRequest',
                                   'hello world'));
?>

SoapFault::SoapFault

(PHP 5)

SoapFault constructor

Description

SoapFault(string faultcode, string faultstring [, string faultactor [, mixed details [, string faultname [, mixed headerfault]]]])

Example

<?php
    function test($x) {
        return new SoapFault("Server","Some error message");
    }

    $server = new SoapServer(null,array('uri'=>"http://test-uri/"));
    $server->addFunction("test");
    $server->handle();
?>

It is possible to use PHP exception mechanism to throw SOAP Fault.

<?php
    function test($x) {
        throw new SoapFault("Server","Some error message");
    }

    $server = new SoapServer(null,array('uri'=>"http://test-uri/"));
    $server->addFunction("test");
    $server->handle();
?>