WSO2 WSF/PHP API

WSO2 Web Services Framework/PHP is a PHP extension that can be used to provide and consume Web services. This document covers the API of WSO2 WSF/PHP extension.

Predefined Classes

WSClient

Constructor

Constructs a new WSClient object.

Parameters:

Parameter

Description

options

An associative array of options. Both message related properties, defined for WSMessage as well as WSClient specific options defined below, can be included in the options array here. Please note that the "to" option must be specified at some level in order to convey the service endpoint to be invoked.

The following table shows the possible client specific options and related details. Please refer to the WSMessage constructor documentation for information on message level properties that can be used as options.

Option

Data Type

Value Domain

Default Value

Description

Transport Binding/Protocol Related Options

"transportURL"

string

string

none

If the soap message should be sent to a soap intermediatory while the actual WS-Addressing "to" header is containing some other endopint, this option should be specified.

"useSOAP"

boolean | double | string

TRUE | FALSE |
1.1 | 1.2 |
"1.1" | "1.2"

TRUE

Specifies whether to use SOAP bindings, or not. If FALSE, a REST style invocation will take place with the given HTTP method as specified by the "HTTPMethod" option. 1.1 or "1.1" would make the message use SOAP 1.1. 1.2 or "1.2" would make the message use SOAP 1.2. TRUE means use SOAP 1.2.

"HTTPMethod"

string
case insensitive

"GET" | "POST" | "post" | "get" | "PUT" | "put" | "DELETE" | "delete" 

"POST"

Specifies which HTTP method to be used.

XOP/MTOM Related Options

"useMTOM"

boolean | string

TRUE | FALSE | "swa"

TRUE

Indicates whether the attachments should be sent MTOM optimized or not. If TRUE, the attachments will be sent out of the SOAP message, optimized, with MIME headers in place. If FALSE, attachments will be sent within the SOAP payload, as base64 binary. If "swa" is provided then the attachments will be send following the SOAP With Attachment standards.

"responseXOP"

boolean

TRUE | FALSE

FALSE

Controls whether XOP elements in a response with MTOM are resolved into the logically equivalent straight XML infoset or not. If TRUE, the member variable "attachments" of the message returned as a result of the calling request method would be set. If FALSE, the binary content will be present in the response payload in base64 format.

WS-Addressing Related Options

"useWSA"

boolean | double | string

TRUE | FALSE |
1.0 |
"1.0" | "submission"

"1.0"

Indicates whether to use WS-Addressing. If TRUE, 1.0 or "1.0", the WS-Addressing 1.0 version will be used, if "submission" the WS-Addressing submission version will be used. When 1.0, "1.0" or "submission" is specified, the "action" must be present. If FALSE, no addressing headers will be sent.

WS-Security Related Options
"policy"                                               WSPolicy object WSPolicy object None WSPolicy Object
"securityToken" WSSecurityToken None WSSecurityToken object which contain the security related options
Proxy and SSL settings related properties
"proxyHost" string string None proxy host to be used.
"proxyPort" string string None proxy port to use.
WSDL Mode
"wsdl" file path or URL of a WSDL file FILE| URL None WSDL file can be used to invoke a Web service using dynamic invocation. In case the wsdl requiring http authentication you can set the options as an array using as follows.
array("wsdl"=>"<wsdl url>",
"httpAuthUsername"=>"<Username>",
"httpAuthPassword"=>"<Password>",
"httpAuthType"=>Basic | Digest)
These authentication options are same as below listed http authentication options.
Http Authentication
"httpAuthUsername" string string None Http Authentication Information: UserName
"httpAuthPassword" string string None Http Authentication Information: Password
"httpAuthType" string "Basic" | "Digest" None Http Authentication Information: Authentication type, use "Basic" to force basic authentication and "Digest" to force digest authentication or NULL for not forcing authentication
"timeout" int seconds None Set the WSClient timeout time. This value in seconds.  
"httpAuthType" string "Basic" | "Digest" None Http Authentication Information: Authentication type, use "Basic" to force basic authentication and "Digest" to force digest authentication or NULL for not forcing authentication
"httpHeaders" array of strings string None Allows adding Http Headers. Eg arrary("MyHttpHeader"=>"test") would add an http header as MyHttpHeader with value test.  



Methods

Sends a request payload in XML format and receives a response payload in the XML format.

Parameters:

Parameter

Description

message

The request message payload to be sent. The type of the parameter can be any one of the following types:

  • string

  • WSMessage

The message payload is expected to be in valid XML format as expected by the service. If MTOM/XOP is to be used, you must use WSMessage to represent the message payload.



Return Values:

The response will be returned as a WSMessage object instance.

Throws WSFault on error.

void WSClient -> send(string payload | WSMessage message)

Sends a request message payload in XML. The invocation model is one way, hence no response will be expected.

Parameters:

Parameter

Description

message

The request message payload to be sent. The type of the parameter can be any one of the following types:

  • string

  • WSMessage

The message payload is expected to be in valid XML format as expected by the service. If MTOM/XOP is to be used, you must use WSMessage to represent the message payload.



Return Values: void

throws WSFault on error.

Member Variables

None

Example

$reqPayloadString = <<<XML
        <ns1:echoString xmlns:ns1="http://wso2.org/wsfphp/samples">
                <text>Hello World!</text>
        </ns1:echoString>
XML;

    $client = new WSClient(
        array("to"=>"http://localhost/echo_service.php"));
                                
    $resMessage = $client->request($reqPayloadString);
    
    printf("Response = %s <br>", htmlspecialchars($resMessage->str));

WSService

Constructor

Constructs a new WSService object.

Parameters:

Parameter

Description

options

An array of options. The following table shows the possible options and related details.

Option

Data Type

Value Domain

Default Value

Description

General Options:

"actions"

array

Array mapping WS-Addressing actions to service operations

None

Array mapping WS-Addressing actions to service operations.

e.g. ("uri1" => "operation1", "uri2" => "operation2")

The above basically means that the service would have two operations, "operation1" and "operation2" with WSA actions "uri1" and "uri2" respectively.

If there is an operation, with no WSA action mapping, you can specify the array as follows.

e.g. ("uri3" => "operation3", "operation4")

A user defined function implementing an operation of a service should have the following syntax:

string  function1 (WSMessage message);

"operations"

array

Array mapping operation names to functions

None

Array mapping operation names to functions.

e.g. ("operation1" => "function1", "operation2" => "function2")

The above basically means that the service would have two operations, "operation1" and "operation2" with the implementing functions "function1" and "function2" respectively.

If there is a function, with the same operation name as that of the function name, you can specify the array as follows.

e.g. ("operation3" => "function3", "function4")

The above means that there are two operations, namely "operation3" and "function4", and that they are implemented by functions "function3" and "function4" respectively

"classes"

array

Array mapping of class names to class information array

None

Array mapping of class names to class information array

e.g. ("classes" => array("foo"=>array( "operations" =>$ops, "actions"=>$actions, "args"=>$args)))

The above basically means that the service would expose the methods of class 'foo'. The methods to be exposed are provided as "operations" associative array which is an operations to functions mapping. "actions" is an array of operation to action mapping. Which is same as above defined actions options.

"args" is an array of arguments to be passed to the class constructor. If the class constructor does not accepts arguments , this options need not be specified.

"opMEP"

array

"IN_ONLY" | "IN_OUT"

IN_OUT

Array mapping operation names to the operation's message exchange pattern. This option is only required with reliable messaging for one way. By default, the "IN_OUT" message exchange pattern is assumed. If explicitly provided by the user, the "IN_ONLY" pattern will be used.

"opParams"

array

"WSMESSAGE" | "MIXED"

"MIXED" if "wsdl" option provided. "WSMESSAGE" otherwise

This option specifies what a PHP function corresponding to the service operation would accept as arguments. If the 'wsdl' option is set this option is default to MIXED, otherwise it is default to WSMESSAGE. If you are using the service for WSDL Generations with the use of doc comments, you have to set this parameter to MIXED explicitly. .

"RESTMapping"

array

Array mapping of operations to HTTPMethod and Location

None

Array mapping of Operations to its corresponding HTTPMethod and Location.

When exposing an operation as a REST style operation, it is required to map an operation to an HTTPMethod. Also a unique url that maps to the operation should be specified. Here the first portion of the url will be same for all operations defined for a given operations and it will be the service url. The last portion of it will be the string specified in RESTLocation attribute. This string can be a string as well as a matching pattern.

Consider we have an operation foo defined in our web service which we want to expose as a REST operation with the url http://test.org/foo_service.php/fooOp and with HTTPMethod POST.Assume that the service url is ttp://test.org/foo_service.php.

e.g. ("RESTMapping" => array("foo"=>array( "HTTPMethod" =>"POST", "RESTLocation"=>"fooOp")));

"wsdl"

A file path or a URL pointing to implementing a service's WSDL

FILE | URL

none

This option is used to specify the WSDL file of the service.

 

"serviceName"  string string none This option is used to specify the name for service in WSDL generation

XOP/MTOM Related Options

"useMTOM"

boolean | string

TRUE | FALSE | "swa"

TRUE

Indicates whether the attachments should be sent MTOM optimized or not. If TRUE, attachments will be sent out of the SOAP message, optimized, and with MIME headers in place. If FALSE, attachments will be sent within the SOAP payload, as base64 binary. If "swa" is provided then the attachments will be send following the SOAP With Attachment standards.

"requestXOP"

boolean

TRUE | FALSE

FALSE

Controls whether XOP elements in a request with MTOM are resolved into the logically equivalent straight XML infoset or not. If TRUE, the member variable "attachments" of the WSMessage object passed to the function implementing the operation will be set. If FALSE, the binary content will be present in the response payload in base64 format.

WS-Security Related options

"policy"

WSPolicy Object

WSPolicy Object

None

WSPolicy object which represents Service or client Policy.
"securityToken" WSSecurityToken Object WSSecurityToken None WSSecurityToken object which contains the security related options.
opPolicies array mixed none This option can be used to specify operation level policies. For example consider we wanted to set the policy for an operation foo. Then it would be like
"opPolicies"=>array("foo"=>$policy);
$policy is a WSPolicy object.
useOwnSTS boolean boolean FALSE When this option is set to true, a security enabled service can act as a security token service in addition to providing the service functionality.



Methods

Sends the reply in response to a client invocation. Here, the service will process the request, call the necessary methods and send a response back.

Parameters: void

Return Values: void

Throws WSFault on error.


Member Variables

None

Example

function echoFunction($inMessage) {
 
    $returnMessage = new WSMessage($inMessage->str);
 
    return $returnMessage;
}
 
$operations = array("echoString" => "echoFunction");
 
$svr = new WSService(array("operations" => $operations));
        
$svr->reply();

WSMessage

The WSMessage class represents a message passed between a client and a service. This class encapsulates the XML payload in various formats, the WS-Addressing action information related to the message, the MTOM attachment data, and other properties related to a message.

Constructor

Constructs a new WSMessage object.

Parameters:

Parameter

Description

payload

Request payload being sent or being received. The type of the parameter can be any one of the following types:

  • string

The payload is expected to be in valid XML format as expected by the service.

properties

An array of properties.

The following table shows the possible message level properties and related details.

Option

Data Type

Value Domain

Default Value

Description

General Properties:

"to"

Mixed

String or an array

None

A URI representing the endpoint URI of the service to be consumed. This must be present on the client side. In case WS-Addressing is in use, this will be used as the WSA To header. Additionaly in case of addressing, you can set reference parameters using the following array of options as following sample code.

array("address"=>"to URL", "referenceParameters"=>array of xml strings)

"referenceParameters"  are addressing options.

WS-Addressing Related Properties:

"action"

string

A URI

None

xs:anyURI
The WS-A action to use when constructing the WS-A headers. A URI representing the WSA action that helps uniquely identify the operation to be invoked. This is also used as the SOAP Action regardless of whether the useWSA option is specified or not.

"from"

Mixed

String or an array

None

WS-Addressing From. A URI indicating where the response or request came from (xs:anyURI). You can set reference parameters using the following array of options.

array("address"=>"from URL", "referenceParameters"=>array of xml strings)

"replyTo"

string

A URI

None

WS-Addressing ReplyTo. A URI indicating where the response should be sent to. The default value is the anonymous URI (depending on the version). You can set reference parameters using the following array of options.

array("address"=>"replyTo URL", "referenceParameters"=>array of xml strings)

"faultTo"

string

A URI

None

WS-Addressing FaultTo. A URI indicating where the fault should be sent to in case of an error. You can set reference parameters using the following array of options.

array("address"=>"faultTo URL", "referenceParameters"=>array of xml strings)

"WSAMustUnderstand"

bool

boolean vlaue

FALSE

mustUndertsand attribute can be added to addressing headers by setting this option to TRUE.

XOP/MTOM Related Properties:

"defaultAttachmentContentType"

string

MTOM content type

"application/octet-stream"

Specify a default MTOM content type to be used with MTOM attachments. You can also specify xmlmime:contentType on the xop:Include element, which will override this setting.

"attachments"

array

array

NONE

This is an associative array which maps the string value specified in the xml to the matching binary string. If attachment caching is enabled, you can set the file name instead of the binary string.

Custom SOAP Headers

"inputHeaders"

array of WSHeader objecs

array of WSHeader objecs

NONE

When an array of WSHeader objects is set to the options array, these headers will be present on the outgoing SOAP Envelope.

REST

"contentType"

string

string

NONE

When exposing an operation in REST Style,you can get/set media type of the content using this attribute of WSMessage


 

Methods

None

Member Variables

Stores the last SOAP request or response payload sent in the message as an XML string.

An associative array, containing the information on the binary attachments, e.g., array("cid1" => $image)) Here "cid1" is the ID mentioned in the <XOP:Include> element, and $image contains the string representation of the binary content to be sent or being received. If attachment caching is enabled, and the received attachment is larger that 1 Mb, then it will be saved to the location defined in wsf.attachment_cache_dir and in the value stored will be the filename.


An associative array, containing the mapping of cid (content ID) to its corresponding     attachment. When an attachment is received, this property will be present in the WSMessage object. array inputHeaders

An array of WSHeader objects (corresponds to Soap Headers ) being sent.

Example

$reqPayloadString = <<<XML
        <ns1:echo xmlns:ns1="http://wso2.org/wsfphp/samples">
                <text>Hello World!</text>
        </ns1:echo>
XML;

    $reqMessage = new WSMessage($reqPayloadString,
        array("to"=>"http://localhost/echo_service_addr.php",
              "action" => "http://wso2.org/wsfphp/samples/echoString"));
              
    $client = new WSClient(array("useWSA" => TRUE));
                                
    $resMessage = $client->request($reqMessage);
    
    printf("Response = %s \n", $resMessage->str);
 

WSFault

Constructor

Constructs a new WSFault object.

Parameters:

Option

Data Type

Value Domain

Default Value

Description

"code"

string

An error code string

None

SOAP fault code. SOAP fault codes are intended to provide a means by which faults are classified.
Please see SOAP 1.2 spec for more information.This is a mandatory option.

"reason"

string

Reason string

None

SOAP fault reason. Provides a human readable explanation of the fault.This is a mandatory option.

"role"

string

Role string

None

SOAP fault role. Identifies the role in which the SOAP processing node was operating at the time the fault occurred.

"detail"

string

Detail string

None

SOAP Fault detail. Contains application specific error information.

code and reason are mandatory arguments for WSFault constructor.

Methods


Member Variables

SOAP fault code. SOAP fault codes are intended to provide a means by which faults are classified.

SOAP fault reason. Provides a human readable explanation of the fault.

SOAP fault role. Identifies the role in which the SOAP processing node was operating at the time the fault occurred.

SOAP fault detail. Contains application specific error information.


Contains the received SOAP fault as an XML string.

WSHeader

Constructor

Constructs a new WSHeader object.

Parameters:

Option

Data Type

Value Domain

Default Value

Description

"ns"

string

Soap Header's namespace uri

None

namespace uri

"prefix"

string

Soap Header's namespace prefix

None

namespace prefix string

"name"

string

Soap Header element's localname

None

Header element localname

"data"

mixed

string or an array of WSHeader objecs

None

If an string is provided it will be taken as the text value of the xml header element. If an array of WSHeader objects is provided, they will be added as the child elements of the parent WSHeader object.

"mustUnderstand"

boolean

true | false

None

specify whether to add mustUnderstand attribute to the Soap Header or not

"role"

int

WS_SOAP_ROLE_NEXT | WS_SOAP_ROLE_NONE |WS_SOAP_ROLE_ULTIMATE_RECEIVER

None

Soap Header role value.

Predefined Functions

Sends a request, invoking a service and receives the response. Adheres to the Out-In message exchange pattern.

Parameters:

Parameter

Description

payload

Request payload to be sent. The type of the parameter can be any one of the following types:

  • string

  • WSMessage

The payload is expected to be in valid XML format as expected by the service. If MTOM/XOP is to be used, you must use WSMessage to represent the payload.

options

An associative array of options. Both message specific options, defined for WSMessage as well as client specific options defined for WSClient can be included in the options array. Please refer to the WSClient() constructor method for more information on the available options.



Return Values:

WSMessage object instance representing a response.

Throws WSFault on error.


Example

$reqPayloadString = <<<XML
    <ns1:echoString xmlns:ns1="http://php.wsf.wso2.net/samples">
        <text>Hello World!</text>
    </ns1:echoString>
XML;

    $resMessage = ws_request($reqPayloadString, 
                        array("to"=>"http://localhost/echo_service.php"));
    
    printf("Response = %s <br>", htmlspecialchars($resMessage->str));

Sends a request, invoking a service. Adheres to the Out-Only message exchange pattern, hence expects no response. However, throws an WSFault instance in case of errors.

Parameters:

Parameter

Description

payload

Request payload to be sent. The type of the parameter can be any one of the following types:

  • string

  • WSMessage

The payload is expected to be in valid XML format as expected by the service. If MTOM/XOP is to be used, one must use WSMessage to represent the payload.

options

An associative array of options. Both message specific options, defined for WSMessage as well as client specific options defined for WSClient can be included in the options array. Please refer to the WSClient() constructor method for more information on available options.



Return Values:

void

Throws WSFault on error.


Example

$reqPayloadString = <<<XML
        <ns1:notifyString xmlns:ns1="http://php.wsf.wso2.net/samples">
                <text>Hello World!</text>
        </ns1:notifyString>
XML;
 
    ws_send($reqPayloadString,
               array("to"=>"http://localhost/reply_notify_service.php"));

Receives a request, processes the request and sends the resulting response. By default, this method adheres to the In-Out message exchange pattern, however it is also possible to have the In-Only message exchange pattern, depending on the nature of the operation being invoked.

Parameters:

Parameter

Description

options

An associative array of options. Both message specific options, defined for WSMessage as well as service specific options defined for WSService can be included in the options array here. Please refer to the WSService() constructor method for more information on the available options.

Return Values:

void

Throws WSFault on error.


Example

function echoFunction($inMessage) {
    $returnMessage = new WSMessage($inMessage->str);
    return $returnMessage;
}

ws_reply(array("operations" => array("echoString" => "echoFunction")));