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.
WSClient([array options])
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 | |
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 |
"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" |
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. |
WSMessage WSClient->request (string message | WSMessage message)
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:
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:
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.
This function returns the last requested soap message as a string
This function returns the last received soap message as a string
This function returns an associative array of received http headers with header
name as the key and header value as the value
$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 (array options)
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: |
"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. |
void WSService - >reply()
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.
function echoFunction($inMessage) { $returnMessage = new WSMessage($inMessage->str); return $returnMessage; } $operations = array("echoString" => "echoFunction"); $svr = new WSService(array("operations" => $operations)); $svr->reply();
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:
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 |
"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 |
None
string str
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.
array cid2contentType
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.
$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(string code, string reason [, string role, string detail])
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. |
"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.
WSFault->__toString()
Returns the fault information as a string
string Code
SOAP fault code. SOAP fault codes are intended to provide a means by which faults are classified.
string Reason
SOAP fault reason. Provides a human readable explanation of the fault.
string Role
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(array options)
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. |
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:
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:
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")));