# PHP SOAP

## Introduction

Warning
This extension is EXPERIMENTAL. The behaviour of this extension -- including the names of its functions and anything else documented about this extension -- may change without notice in a future release of PHP. Use this extension at your own risk.

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

This extension makes use of the GNOME XML library. Download and install this library. You will need at least libxml-2.5.4.

## Installation

This extension is only available if PHP was configured with --enable-soap.

## Runtime Configuration

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

Name | Default | Changeable
--- | --- | ---
soap.wsdl_cache_enabled | "1" | PHP_INI_ALL
soap.wsdl_cache_dir | "/tmp" | PHP_INI_ALL
soap.wsdl_cache_ttl | 86400 | PHP_INI_ALL

Here is a short explanation of the configuration directives.

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

The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.

Constant | Value | Description
--- | --- | ---
SOAP_1_1 (integer) | 1 | SOAP version - SOAP 1.1. Can be used as an option in SoapClient and SoapServer constructors.
SOAP_1_2 (integer) | 2 | SOAP version - SOAP 1.2. Can be used as an option in SoapClient and SoapServer constructors.
SOAP_FUNCTIONS_ALL (integer) | 999 | Allows to export all defined functions with SoapClient::addFunction
SOAP_PERSISTENCE_SESSION (integer) | 1 | Allows making class passed to SoapServer::setClass persistent for a PHP session.
SOAP_PERSISTENCE_REQUEST (integer) | 2 | Allows making class passed to SoapServer::setClass non-persistent for a PHP session.
SOAP_ENCODED (integer) | 1 | Can be passed as style option to SoapClient constructor in nonWSDL mode.
SOAP_LITERAL (integer) | 2 | Can be passed as style option to SoapClient constructor in nonWSDL mode.
SOAP_RPC (integer) | 1 | Can be passed as use option to SoapClient constructor in nonWSDL mode.
SOAP_DOCUMENT (integer) | 2 | Can be passed as use option to SoapClient constructor in nonWSDL mode.
SOAP_ACTOR_NEXT (integer) | 1 | Can be passed as actor to SoapHeader constructor.
SOAP_ACTOR_NONE (integer) | 2 | Can be passed as actor to SoapHeader constructor
SOAP_ACTOR_UNLIMATERECEIVER (integer) | 3 | Can be passed as actor to SoapHeader constructor
UNKNOWN_TYPE (integer) | 999998 | Encoding for unknown type. Can be passed to SoapVar constructor.
XSD_STRING (integer) | 101 | Encoding for standard XMLSchema string type. Can be passed to SoapVar constructor.
XSD_BOOLEAN (integer) | 102 | Encoding for standard XMLSchema boolen type. Can be passed to SoapVar constructor.
XSD_DECIMAL (integer) | 103 | Encoding for standard XMLSchema decimal type. Can be passed to SoapVar constructor.
XSD_FLOAT (integer) | 104 | Encoding for standard XMLSchema float type. Can be passed to SoapVar constructor.
XSD_DOUBLE (integer) | 105 | Encoding for standard XMLSchema double type. Can be passed to SoapVar constructor.
XSD_DURATION (integer) | 106 | Encoding for standard XMLSchema duration type. Can be passed to SoapVar constructor.
XSD_DATETIME (integer) | 107 | Encoding for standard XMLSchema dateTime type. Can be passed to SoapVar constructor.
XSD_TIME (integer) | 108 | Encoding for standard XMLSchema time type. Can be passed to SoapVar constructor.
XSD_DATE (integer) | 109 | Encoding for standard XMLSchema data type. Can be passed to SoapVar constructor.
XSD_GYEARMONTH (integer) | 110 | Encoding for standard XMLSchema gYearMonth type. Can be passed to SoapVar constructor.
XSD_GYEAR (integer) | 111 | Encoding for standard XMLSchema gYear type. Can be passed to SoapVar constructor.
XSD_GMONTHDAY (integer) | 112 | Encoding for standard XMLSchema gMonthDay type. Can be passed to SoapVar constructor.
XSD_GDAY (integer) | 113 | Encoding for standard XMLSchema gDay type. Can be passed to SoapVar constructor.
XSD_GMONTH (integer) | 114 | Encoding for standard XMLSchema gMonth type. Can be passed to SoapVar constructor.
XSD_HEXBINARY (integer) | 115 | Encoding for standard XMLSchema hexBinary type. Can be passed to SoapVar constructor.
XSD_BASE64BINARY (integer) | 116 | Encoding for standard XMLSchema base64Binary type. Can be passed to SoapVar constructor.
XSD_ANYURI (integer) | 117 | Encoding for standard XMLSchema anyURI type. Can be passed to SoapVar constructor.
XSD_QNAME (integer) | 118 | Encoding for standard XMLSchema QName type. Can be passed to SoapVar constructor.
XSD_NOTATION (integer) | 119 | Encoding for standard XMLSchema NOTATION type. Can be passed to SoapVar constructor.
XSD_NORMALIZEDSTRING (integer) | 120 | Encoding for standard XMLSchema normalizedString type. Can be passed to SoapVar constructor.
XSD_TOKEN (integer) | 121 | Encoding for standard XMLSchema token type. Can be passed to SoapVar constructor.
XSD_LANGUAGE (integer) | 122 | Encoding for standard XMLSchema language type. Can be passed to SoapVar constructor.
XSD_NMTOKEN (integer) | 123 | Encoding for standard XMLSchema NMTOKEN type. Can be passed to SoapVar constructor.
XSD_NAME (integer) | 124 | Encoding for standard XMLSchema Name type. Can be passed to SoapVar constructor.
XSD_NCNAME (integer) | 125 | Encoding for standard XMLSchema NCName type. Can be passed to SoapVar constructor.
XSD_ID (integer) | 126 | Encoding for standard XMLSchema ID type. Can be passed to SoapVar constructor.
XSD_IDREF (integer) | 127 | Encoding for standard XMLSchema IDREF type. Can be passed to SoapVar constructor.
XSD_IDREFS (integer) | 128 | Encoding for standard XMLSchema IDREFS type. Can be passed to SoapVar constructor.
XSD_ENTITY (integer) | 129 | Encoding for standard XMLSchema ENTITY type. Can be passed to SoapVar constructor.
XSD_ENTITIES (integer) | 130 | Encoding for standard XMLSchema ENTITIES type. Can be passed to SoapVar constructor.
XSD_INTEGER (integer) | 131 | Encoding for standard XMLSchema integer type. Can be passed to SoapVar constructor.
XSD_NONPOSITIVEINTEGER (integer) | 132 | Encoding for standard XMLSchema nonPositiveInteger type. Can be passed to SoapVar constructor.
XSD_NEGATIVEINTEGER (integer) | 133 | Encoding for standard XMLSchema negativeInteger type. Can be passed to SoapVar constructor.
XSD_LONG (integer) | 134 | Encoding for standard XMLSchema long type. Can be passed to SoapVar constructor.
XSD_INT (integer) | 135 | Encoding for standard XMLSchema int type. Can be passed to SoapVar constructor.
XSD_SHORT (integer) | 136 | Encoding for standard XMLSchema short type. Can be passed to SoapVar constructor.
XSD_BYTE (integer) | 137 | Encoding for standard XMLSchema byte type. Can be passed to SoapVar constructor.
XSD_NONNEGATIVEINTEGER (integer) | 138 | Encoding for standard XMLSchema nonNegativeInteger type. Can be passed to SoapVar constructor.
XSD_UNSIGNEDLONG (integer) | 139 | Encoding for standard XMLSchema unsignedLong type. Can be passed to SoapVar constructor.
XSD_UNSIGNEDINT (integer) | 140 | Encoding for standard XMLSchema unsignedInt type. Can be passed to SoapVar constructor.
XSD_UNSIGNEDSHORT (integer) | 141 | Encoding for standard XMLSchema unsignedShort type. Can be passed to SoapVar constructor.
XSD_UNSIGNEDBYTE (integer) | 142 | Encoding for standard XMLSchema unsignedByte type. Can be passed to SoapVar constructor.
XSD_POSITIVEINTEGER (integer) | 143 | Encoding for standard XMLSchema positiveInteger type. Can be passed to SoapVar constructor.
XSD_NMTOKENS (integer) | 144 | Encoding for standard XMLSchema NMTOKENS type. Can be passed to SoapVar constructor.
XSD_ANYTYPE (integer) | 145 | Encoding for standard XMLSchema anyType type. Can be passed to SoapVar constructor.
SOAP_ENC_ARRAY (integer) | 300 | Encoding for SOAP Array type. Can be passed to SoapVar constructor.
SOAP_ENC_OBJECT (integer) | 301 | Encoding for SOAP Struct type. Can be passed to SoapVar constructor.
XSD_1999_TIMEINSTANT (integer) | 401 | Encoding for old XMLSchema timeInstant type. Can be passed to SoapVar constructor.
XSD_NAMESPACE (string) |  | The XML Schema namespace.
XSD_1999_NAMESPACE (string) |  | The old XML Schema namespace.

## Classes

#### List of classes

SoapClient
SoapServer
SoapParam
SoapVar
SoapHeader
SoapFault

#### SoapClient class

A SOAP client, that allows calling remote methods on SOAP WebService over HTTP or HTTPS.

SoapClient -- SoapClient constructor
__call -- calls a SOAP function
__getLastRequest -- returns last SOAP request
__getLastResponse -- returns last SOAP response
__getFunctions -- returns list of SOAP functions
__getTypes -- returns list of SOAP types

#### SoapServer class

This class can be used to build SOAP WebServices, which can be accessed from remote SOAP clients over HTTP or HTTPS.

SoapServer -- SoapServer constructor
addFunction -- adds one or several functions those will handle SOAP requests
setClass -- sets class which will handle SOAP requests
getFunctions -- returns list of defined functions
setPersistence -- sets persistence mode of SoapServer
handle -- handles a SOAP request

#### SoapParam class

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.

SoapParam -- SoapParam constructor

#### SoapVar classes

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.

SoapVar -- SoapVar constructor

#### SoapHeader class

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.

SoapHeader -- SoapHeader constructor

#### SoapFault class

SoapFault is a special class that can be used for error reporting during handling of SOAP request. It is derived form standard PHP Exception class, so it can be used to throw exceptions in server side and to catch tham on client side.

SoapFault -- SoapFault constructor

#### Table of Contents

is_soap_fault -- checks if SOAP call was failed
SoapClient::SoapClient -- SoapClient constructor
SoapClient::__call -- calls a SOAP function
SoapClient::__getLastRequest -- returns last SOAP request
SoapClient::__getLastResponse -- returns last SOAP response
SoapClient::__getFunctions -- returns list of SOAP functions
SoapClient::__getTypes -- returns list of SOAP types
SoapServer::SoapServer -- SoapServer constructor
SoapServer::addFunction -- adds one or several functions those will handle SOAP requests
SoapServer::setClass -- sets class which will handle SOAP requests
SoapServer::getFunctions -- returns list of defined functions
SoapServer::setPersistence -- sets persistence mode of SoapServer
SoapServer::handle -- handles a SOAP request
SoapParam::SoapParam -- SoapParam constructor
SoapVar::SoapVar -- SoapVar constructor
SoapHeader::SoapHeader -- SoapHeader constructor
SoapFault::SoapFault -- SoapFault constructor

## 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])

It allows creating SoapServer objects in WSDL or nonWSDL mode. In the first case wsdl must be set to URI of WSDL file. In the second wsdl must be set to null and uti option must be set. Additional options allow setting a default SOAP version (soap_version) and actor URI (actor).

#### 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/"));

## SoapServer::addFunction

(PHP 5)

adds one or several functions those will handle SOAP requests

### Description

void addFunction(mixed functions)

Exports one or more functions for remote clients. To export one function pass function name into functions parameter as string. To export several functions pass an array of function names and to export all functions pass a special constant SOAP_FUNCTIONS_ALL.
Functions must receive all input arguments in the same order as defined in WSDL file (They should not receive any output parameters as arguments) and return one or more values. To return several values they must return array with named output parameters.

#### Examples

        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 [, ...])

Exports all methods from specified class. Additional parameters will be passed to default class constructor during object creation. The object can be maiden persistent across request for a given PHP session with SoapServer::setPersistence method.

#### Examples

        $server->setClass("foo");

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

## SoapServer::getFunctions

(PHP 5)

returns list of defined functions

### Description

array getFunctions()

## SoapServer::setPersistence

(PHP 5)

sets persistence mode of SoapServer

### Description

void setPersistence(int mode)

This function allows saving data between requests in PHP session. It works only with server that exports functions form class (see SoapServer:setCalss).

#### 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])

It processes a SOAP request, call necessary functions, and send response back. It assumes request in input parameter or in global $HTTP_RAW_POST_DATA PHP variable if the argument is omitted.

#### 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]]]])

This class is useful when you like to send SOAP fault response from PHP handler.
faultcode, faultstring, faultactor and details are standard elements of SOAP Fault;
faultname is an optional parameter that can be used to select proper fault encoding from WSDL.
headerfault is an optional parameter that can be used during SOAP header handling to report error in response header.

#### 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();
    ?>