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 |
||||
"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" |
"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" |
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 |
WSMessage WSClient->request (string message | domDocument 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 | domDocument message | 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.
$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 (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 |
"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 |
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" |
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 |
"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. |
None
string str
Stores the last SOAP request or response payload sent in the message as an XML string.
domDocument dom
Stores the last SOAP request or response payload sent in the message as a domDocument
array attachments
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.
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 headers
An array of SOAP Header objects being sent or being received.
$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(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. |
"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. |
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.
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")));