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

"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"

"POST"

Specifies which HTTP method to be used.

XOP/MTOM Related Options

"useMTOM"

boolean

TRUE | FALSE

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.

"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
"proxy_host" string string None proxy host to be used.
"proxy_port" 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



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

  • domDocument

  • 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.



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

  • domDocument

  • 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://php.axis2.org/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 | domDocument 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

"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"

"WSMESSAGE"

This option specifies what a PHP function corresponding to the service operation would accept as arguments. This option is only required when writing a service to use in the WSDL mode. By default, the WSMESSAGE is assumed, which means that each function would have a single parameter of the type WSMessage.

"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.

XOP/MTOM Related Options

"useMTOM"

boolean

TRUE | FALSE

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.

"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
"securityToken" WSSecurityToken Object WSSecurityToken None WSSecurityToken object which contains the security related options



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

  • domDocument

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"

string

A URI

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

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"

string

A URI

None

xs:anyURI

WS-Addressing From. A URI indicating where the response or request came from.  (Note: This doesn't support reference parameters.)

"replyTo"

string

A URI

None

xs:anyURI

WS-Addressing ReplyTo. A URI indicating where the response should be sent to. The default value is the anonymous URI (depending on the version). (Note: This doesn't support reference parameters.)

"faultTo"

string

A URI

None

xs:anyURI

WS-Addressing FaultTo. A URI indicating where the fault should be sent to in case of an error. (Note: This doesn't support reference parameters.)

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.



Methods

None

Member Variables

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

Stores the last SOAP request or response payload sent in the message as a domDocument

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.


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.

An array of SOAP Header objects being sent or being received.

Example

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

    $reqMessage = new WSMessage($reqPayloadString,
        array("to"=>"http://localhost/echo_service_addr.php",
              "action" => "http://php.axis2.org/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

"reason"

string

Reason string

None

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

"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.



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.

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

  • domDocument

  • 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

  • domDocument

  • 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")));