Request_Soap Class

The Request_Soap class is intended to process SOAP requests through PHP's SoapClient extension. Your PHP installation must be compiled with "--enable-soap". You can check the output of phpinfo() to see if this is the case.

Creating an instance

You can forge an instance of this class through the Request class: 

// create a Request_Soap object
$soap = Request::forge('http://soap.example.org/api/v1/this/info', 'soap');

// how to enable trace option during request creation
$soap = Request::forge('http://soap.example.org/api/v1/this/info', array('driver'=>'soap', 'trace' => true));

// note that this only creates the object, it does not execute the request!

set_params($params)

The set_params method allows you to set parameters to pass on the SOAP request call.

Static No
Parameters
Param Default Description
$params required Array of parameters for the request.
Returns Request_Soap, for chaining
Example 
// create a Request_Soap object
$soap = Request::forge('http://soap.example.org/api/v1/this/info', 'soap');

// set some parameters
$soap->set_params(array('userid' => 12, 'data' => $payload));

Please note that the format in which you have to define the parameters is dependent on the SOAP service being called. Some for example expect them to be wrapped in an array. The SOAP Request driver will pass the parameters to the service in the format you use on set_params, so make sure it is correct.

set_option($option, $value)

The set_option method allows you to define a SoapClient option to be passed to the request.

Static No
Parameters
Param Default Description
$option required SoapClient option to set.
$value required Value to set this option to.
Returns Request_Soap, for chaining
Example 
// create a Request_Soap object
$soap = Request::forge('http://soap.example.org/api/v1/this/info', 'soap');

// set the username to be used in the request
$soap->set_option('login', $username);

set_options(array $options)

The set_options method allows you to define multiple SoapClient options to be passed to the request.

Static No
Parameters
Param Default Description
$options required Array of SoapClient options and values to set.
Returns Request_Soap, for chaining
Example 
// create a Request_Soap object
$soap = Request::forge('http://soap.example.org/api/v1/this/info', 'soap');

// set a username and password to be used in the request
$soap->set_options(array(
	'login' => $username,
	'password' => $password,
	)
);

add_param($param, $value = null)

The add_param method allows you to add one or more parameters to the ones already defined.

Static No
Parameters
Param Default Description
$param required Name of the parameter to set, or an array of parameters and values.
$value 
null
 Value to be defined. Only used when $param is a string value.
Returns Request_Soap, for chaining
Example 
// create a Request_Soap object
$soap = Request::forge('http://soap.example.org/api/v1/this/info', 'soap');

// add some parameters
$soap->add_param(array('userid' => 12, 'data' => $payload));

// or add a single one
$soap->add_param('data', $payload);

set_header($header, $content = null)

The set_header method allows you to set a HTTP request header as part of the request.

Static No
Parameters
Param Default Description
$header required The name of the HTTP header entry.
$content 
null
 The header value to be set.
Returns Request_Soap, for chaining
Example 
// create a Request_Soap object
$soap = Request::forge('http://soap.example.org/api/v1/this/info', 'soap');

// pass an authentication token to the backend server
$soap->set_header('auth-token', 'WV4YaeV8QeWVVVOE');

If you need to set a header that is not in the form "Name: Value", pass the value in $header, and do not pass any content.

get_headers()

The get_headers method allows you to retrieve all currently defined HTTP request headers.

Static No
Parameters None.
Returns Array, all headers set.
Example 
// create a Request_Soap object
$soap = Request::forge('http://soap.example.org/api/v1/this/info', 'soap');

// pass an authentication token to the backend server
$soap->set_header('auth-token', 'WV4YaeV8QeWVVVOE');

// returns array('auth-token:WV4YaeV8QeWVVVOE')
$headers = $soap->get_headers();

set_auto_format($auto_format)

The set_auto_format method allows you to switch auto formatting on or off. Since 1.7.2, this is switched of by default, and when switched off, you will have to parse the cURL response yourself.

Static No
Parameters
Param Default Description
$auto_format required True if you want the returned response to be converted into an array, false if you want to access it as it is received.
Returns Request_Soap, for chaining
Example 
// create a Request_Soap object
$soap = Request::forge('http://soap.example.org/api/v1/this/info', 'soap');

// we want an array returned
$soap->set_auto_format(true);

Auto formatting has support for the following mime types:

  • application/xml
  • text/xml
  • application/json
  • text/json
  • text/csv
  • application/csv
  • application/vnd.php.serialized
so when enabled and the response is in one of these types, it will be processed automatically, and returned to your controller in the form of a PHP array.

Only enable this is the source of the data is trustworthy, and/or if you have validated the received input. JSON and serialized arrays could contain objects. Since their constructor will execute upon instantiation during auto formatting, it may lead to unintended code execution, possibly compromizing your server!

execute(array $additional_params = array())

The execute method executes the defined SOAP request.

Static No
Parameters
Param Default Description
$additional_params 
array()
 Any additional parameters you want to pass to the request.
Returns Request_Soap, for chaining
Example 
// create a Request_Soap object
$soap = Request::forge('http://soap.example.org/api/v1/this/info', 'soap');

// execute the request
$result = $soap->execute();

set_response($body, $status, $mime = null, $headers = array())

The set_response method sets the response received from the request.

Static No
Parameters
Param Default Description
$body required The data to be set as the response body.
$status required The HTTP status of the created response.
$mime 
null
 The mime type the data is in. This is used with auto_format to convert the body into an array.
$headers 
null
 Any HTTP response headers you want to set.
Returns Response, the created response object.
Example 
// create a Request_Soap object
$soap = Request::forge('http://soap.example.org/api/v1/this/info', 'soap');

// create a custom response (SOAP responses should always be in XML)
$soap->set_response($body, $this->response_info('http_code', 200), 'xml', array('auth-token' => 'WV4YaeV8QeWVVVOE'));

Normally you should not use this method. It is used after the request is executed to prepare the requests response object.

response()

The response method returns the current request response.

Static No
Parameters None.
Returns Response, the created response object.
Example 
// create a Request_Soap object
$soap = Request::forge('http://soap.example.org/api/v1/this/info', 'soap');

// assume some parameters and options were set, and execute
$soap->execute();

// fetch the resulting Response object
$result = $soap->response();

response_info($key = null, $default = null)

The response_info method allows you to retrieve a SOAP response value, or all response values.

Static No
Parameters
Param Default Description
$key 
null
 Specific response value to retrieve. Don't specify it when you want to retrieve all values.
$default 
null
 Value to be returned when the requested value does not exist.
Returns Mixed, depending on the data type of the requested value.
Example 
// create a Request_Soap object
$soap = Request::forge('http://soap.example.org/api/v1/this/info', 'soap');

// assume some parameters and options were set, and execute
$soap->execute();

// get the soap action executed from the response header
$size = $soap->response_info('SOAPAction', false);

This method allows access to the HTTP headers of the response.

set_function($function)

The set_function method sets the function to execute on the SoapClient.

Static No
Parameters
Param Default Description
$function required The name of the SOAP function to call.
Returns Request_Soap, for chaining
Example 
// create a Request_Soap object
$soap = Request::forge('http://soap.example.org/api/v1/this/info', 'soap');

// set the soapcall function to fetch some user data
$soap->set_function('GetUserInfo');

get_functions()

The get_functions method returns the list of functions defined in the WSDL.

Static No
Parameters None.
Returns Array of available SOAP functions
Example 
// create a Request_Soap object
$soap = Request::forge('http://soap.example.org/api/v1/this/info', 'soap');

// retrieve the SOAP function list
$functions = $soap->get_functions();

This method requires the SoapClient to work in WDSL mode.

get_request_xml()

The get_request_xml method returns the last request XML.

Static No
Parameters None.
Returns String, The last XML request
Example 
// create a Request_Soap object
$soap = Request::forge('http://soap.example.org/api/v1/this/info', 'soap');

// some code here...

// retrieve the last XML request
$request = $soap->get_request_xml();

This method requires the 'trace' option to be enabled.

get_request_headers()

The get_request_headers method returns the headers of the last request.

Static No
Parameters None.
Returns String, the SOAP headers from the last request. May contain newlines.
Example 
// create a Request_Soap object
$soap = Request::forge('http://soap.example.org/api/v1/this/info', 'soap');

// some code here...

// retrieve the headers of the last request
$headers = $soap->get_request_headers();

This method requires the 'trace' option to be enabled.

get_response_xml()

The get_response_xml method returns the last response XML.

Static No
Parameters None.
Returns String, The last XML response
Example 
// create a Request_Soap object
$soap = Request::forge('http://soap.example.org/api/v1/this/info', 'soap');

// some code here...

// retrieve the last XML response
$response = $soap->get_response_xml();

This method requires the 'trace' option to be enabled.

get_response_headers()

The get_response_headers method returns the headers of the last response.

Static No
Parameters None.
Returns String, the SOAP headers from the last response. May contain newlines.
Example 
// create a Request_Soap object
$soap = Request::forge('http://soap.example.org/api/v1/this/info', 'soap');

// some code here...

// retrieve the headers of the last response
$response = $soap->get_response_headers();

This method requires the 'trace' option to be enabled.

get_types()

The get_types method returns the list of supported types.

Static No
Parameters None.
Returns array of SOAP types, detailing all structures and types.
Example 
// create a Request_Soap object
$soap = Request::forge('http://soap.example.org/api/v1/this/info', 'soap');

// get the list of types described in the WSDL for this web service
$types = $soap->get_types();

This method requires the SoapClient to work in WDSL mode.

The set_cookie method sets the request cookie for subsequent requests.

Static No
Parameters
Param Default Description
$name required The name of the cookie.
$value 
null
 The value of the cookie. If not specified, the cookie will be deleted.
Example 
// create a Request_Soap object
$soap = Request::forge('http://soap.example.org/api/v1/this/info', 'soap');

// set an auth token as a cookie in the HTTP request header
$soap->set_cookie('auth-token', 'WV4YaeV8QeWVVVOE');

set_location($location)

The set_location method allows you to change the endpoint location.

Static No
Parameters
Param Default Description
$location required The new endpoint URL.
Example 
// create a Request_Soap object
$soap = Request::forge('http://soap.example.org/api/v1/this/info', 'soap');

// change the endpoint of the request
$soap->set_location('http://moresoap.example.org/api/v2/other/info');