xmlrpc_client

This is the basic class used to represent a client of an XML-RPC server.

Creation

The constructor accepts one of two possible syntaxes:

xmlrpc_clientnew xmlrpc_client(string$server_url);
 
xmlrpc_clientnew xmlrpc_client(string$server_path,
 string$server_hostname,
 int$server_port80,
 string$transport'http');
 

Here are a couple of usage examples of the first form:


$client = new xmlrpc_client("http://phpxmlrpc.sourceforge.net/server.php");
$another_client = new xmlrpc_client("https://james:bond@secret.service.com:443/xmlrpcserver?agent=007");

The second syntax does not allow to express a username and password to be used for basic HTTP authorization as in the second example above, but instead it allows to choose whether xmlrpc calls will be made using the HTTP 1.0 or 1.1 protocol.

Here's another example client set up to query Userland's XML-RPC server at betty.userland.com:


$client = new xmlrpc_client("/RPC2""betty.userland.com"80);

The server_port parameter is optional, and if omitted will default to 80 when using HTTP and 443 when using HTTPS (see the xmlrpc_client->send method below).

The transport parameter is optional, and if omitted will default to 'http'. Allowed values are either 'http', 'https' or 'http11'. Its value can be overridden with every call to the send method. See the send method below for more details about the meaning of the different values.

Methods

This class supports the following methods.

send

This method takes the forms:

xmlrpcrespsend(xmlrpcmsg$xmlrpc_message,
 int$timeout,
 string$transport);
 
arraysend(array$xmlrpc_messages,
 int$timeout,
 string$transport);
 
xmlrpcrespsend(string$xml_payload,
 int$timeout,
 string$transport);
 

Where xmlrpc_message is an instance of xmlrpcmsg (see xmlrpcmsg), and response is an instance of xmlrpcresp (see xmlrpcresp).

If xmlrpc_messages is an array of message instances, responses will be an array of response instances. The client will try to make use of a single system.multicall xml-rpc method call to forward to the server all the messages in a single HTTP round trip, unless $client->no_multicall has been previously set to TRUE (see the multicall method below), in which case many consecutive xmlrpc requests will be sent.

The third syntax allows to build by hand (or any other means) a complete xmlrpc request message, and send it to the server. xml_payload should be a string containing the complete xml representation of the request. It is e.g. useful when, for maximal speed of execution, the request is serialized into a string using the native php xmlrpc functions (see the php manual on xmlrpc).

The timeout is optional, and will be set to 0 (wait for platform-specific predefined timeout) if omitted. This timeout value is passed to fsockopen(). It is also used for detecting server timeouts during communication (i.e. if the server does not send anything to the client for timeout seconds, the connection will be closed).

The transport parameter is optional, and if omitted will default to the transport set using instance creator or 'http' if omitted. The only other valid values are 'https', which will use an SSL HTTP connection to connect to the remote server, and 'http11'. Note that your PHP must have the "curl" extension compiled in order to use both these features. Note that when using SSL you should normally set your port number to 443, unless the SSL server you are contacting runs at any other port.

Warning

PHP 4.0.6 has a bug which prevents SSL working.

In addition to low-level errors, the XML-RPC server you were querying may return an error in the xmlrpcresp object. See xmlrpcresp for details of how to handle these errors.

multiCall

This method takes the form:

arraymultiCall(array$messages,
 int$timeout,
 string$transport,
 bool$fallback);
 

This method is used to boxcar many method calls in a single xml-rpc request. It will try first to make use of the system.multicall xml-rpc method call, and fall back to executing many separate requests if the server returns any error.

msgs is an array of xmlrpcmsg objects (see xmlrpcmsg), and response is an array of xmlrpcresp objects (see xmlrpcresp).

The timeout and transport parameters are optional, and behave as in the send method above.

The fallback parameter is optional, and defaults to TRUE. When set to FALSE it will prevent the client to try using many single method calls in case of failure of the first multicall request. It should be set only when the server is known to support the multicall extension.

setAcceptedCompression

voidsetAcceptedCompression(string$compressionmethod);
 

This method defines whether the client will accept compressed xml payload forming the bodies of the xmlrpc responses received from servers. Note that enabling reception of compressed responses merely adds some standard http headers to xmlrpc requests. It is up to the xmlrpc server to return compressed responses when receiving such requests. Allowed values for compressionmethod are: 'gzip', 'deflate', 'any' or null (with any meaning either gzip or deflate).

This requires the "zlib" extension to be enabled in your php install. If it is, by default xmlrpc_client instances will enable reception of compressed content.

setCaCertificate

voidsetCaCertificate(string$certificate,
 bool$is_dir);
 

This method sets an optional certificate to be used in SSL-enabled communication to validate a remote server with (when the server_method is set to 'https' in the client's construction or in the send method and SetSSLVerifypeer has been set to TRUE).

The certificate parameter must be the filename of a PEM formatted certificate, or a directory containing multiple certificate files. The is_dir parameter defaults to FALSE, set it to TRUE to specify that certificate indicates a directory instead of a single file.

This requires the "curl" extension to be compiled into your installation of PHP. For more details see the man page for the curl_setopt function.

setCertificate

voidsetCertificate(string$certificate,
 string$passphrase);
 

This method sets the optional certificate and passphrase used in SSL-enabled communication with a remote server (when the server_method is set to 'https' in the client's construction or in the send method).

The certificate parameter must be the filename of a PEM formatted certificate. The passphrase parameter must contain the password required to use the certificate.

This requires the "curl" extension to be compiled into your installation of PHP. For more details see the man page for the curl_setopt function.

Note: to retrieve information about the client certificate on the server side, you will need to look into the environment variables which are set up by the webserver. Different webservers will typically set up different variables.

setCookie

voidsetCookie(string$name,
 string$value,
 string$path,
 string$domain,
 int$port);
 

This method sets a cookie that will be sent to the xmlrpc server along with every further request (useful e.g. for keeping session info outside of the xml-rpc payload).

$value is optional, and defaults to null.

$path, $domain and $port are optional, and will be omitted from the cookie header if unspecified. Note that setting any of these values will turn the cookie into a 'version 1' cookie, that might not be fully supported by the server (see RFC2965 for more details).

setCredentials

voidsetCredentials(string$username,
 string$password,
 int$authtype);
 

This method sets the username and password for authorizing the client to a server. With the default (HTTP) transport, this information is used for HTTP Basic authorization. Note that username and password can also be set using the class constructor. With HTTP 1.1 and HTTPS transport, NTLM and Digest authentication protocols are also supported. To enable them use the constants CURLAUTH_DIGEST and CURLAUTH_NTLM as values for the authtype parameter.

setCurlOptions

voidsetCurlOptions(array$options);
 

This method allows to directly set any desired option to manipulate the usage of the cURL client (when in cURL mode). It can be used eg. to explicitly bind to an outgoing ip address when the server is multihomed

setDebug

voidsetDebug(int$debugLvl);
 

debugLvl is either 0, 1 or 2 depending on whether you require the client to print debugging information to the browser. The default is not to output this information (0).

The debugging information at level 1includes the raw data returned from the XML-RPC server it was querying (including bot HTTP headers and the full XML payload), and the PHP value the client attempts to create to represent the value returned by the server. At level2, the complete payload of the xmlrpc request is also printed, before being sent t the server.

This option can be very useful when debugging servers as it allows you to see exactly what the client sends and the server returns.

setKey

voidsetKey(int$key,
 int$keypass);
 

This method sets the optional certificate key and passphrase used in SSL-enabled communication with a remote server (when the transport is set to 'https' in the client's construction or in the send method).

This requires the "curl" extension to be compiled into your installation of PHP. For more details see the man page for the curl_setopt function.

setProxy

voidsetProxy(string$proxyhost,
 int$proxyport,
 string$proxyusername,
 string$proxypassword,
 int$authtype);
 

This method enables calling servers via an HTTP proxy. The proxyusername, proxypassword and authtype parameters are optional. Authtype defaults to CURLAUTH_BASIC (Basic authentication protocol); the only other valid value is the constant CURLAUTH_NTLM, and has effect only when the client uses the HTTP 1.1 protocol.

NB: CURL versions before 7.11.10 cannot use a proxy to communicate with https servers.

setRequestCompression

voidsetRequestCompression(string$compressionmethod);
 

This method defines whether the xml payload forming the request body will be sent to the server in compressed format, as per the HTTP specification. This is particularly useful for large request parameters and over slow network connections. Allowed values for compressionmethod are: 'gzip', 'deflate', 'any' or null (with any meaning either gzip or deflate). Note that there is no automatic fallback mechanism in place for errors due to servers not supporting receiving compressed request bodies, so make sure that the particular server you are querying does accept compressed requests before turning it on.

This requires the "zlib" extension to be enabled in your php install.

setSSLVerifyHost

voidsetSSLVerifyHost(int$i);
 

This method defines whether connections made to XML-RPC backends via HTTPS should verify the remote host's SSL certificate's common name (CN). By default, only the existence of a CN is checked. $i should be an integer value; 0 to not check the CN at all, 1 to merely check for its existence, and 2 to check that the CN on the certificate matches the hostname that is being connected to.

setSSLVerifyPeer

voidsetSSLVerifyPeer(bool$i);
 

This method defines whether connections made to XML-RPC backends via HTTPS should verify the remote host's SSL certificate, and cause the connection to fail if the cert verification fails. $i should be a boolean value. Default value: TRUE. To specify custom SSL certificates to validate the server with, use the setCaCertificate method.

setSSLVersion

voidsetSSLVersion(int$i);
 

This method sets the SSL version to be used when making https calls. See the PHP manual for CURLOPT_SSLVERSION for a description of the allowed values.

setUserAgent

voidUseragent(string$useragent);
 

This method sets a custom user-agent that will be used by the client in the http headers sent with the request. The default value is built using the library name and version constants.

Variables

NB: direct manipulation of these variables is only recommended for advanced users.

no_multicall

This member variable determines whether the multicall() method will try to take advantage of the system.multicall xmlrpc method to dispatch to the server an array of requests in a single http roundtrip or simply execute many consecutive http calls. Defaults to FALSE, but it will be enabled automatically on the first failure of execution of system.multicall.

request_charset_encoding

This is the charset encoding that will be used for serializing request sent by the client.

If defaults to NULL, which means using US-ASCII and encoding all characters outside of the ASCII range using their xml character entity representation (this has the benefit that line end characters will not be mangled in the transfer, a CR-LF will be preserved as well as a singe LF).

Valid values are 'US-ASCII', 'UTF-8' and 'ISO-8859-1'

return_type

This member variable determines whether the value returned inside an xmlrpcresp object as results of calls to the send() and multicall() methods will be an xmlrpcval object, a plain php value or a raw xml string. Allowed values are 'xmlrpcvals' (the default), 'phpvals' and 'xml'. To allow the user to differentiate between a correct and a faulty response, fault responses will be returned as xmlrpcresp objects in any case. Note that the 'phpvals' setting will yield faster execution times, but some of the information from the original response will be lost. It will be e.g. impossible to tell whether a particular php string value was sent by the server as an xmlrpc string or base64 value.

Example usage:


$client = new xmlrpc_client("phpxmlrpc.sourceforge.net/server.php");
$client->return_type 'phpvals';
$message = new xmlrpcmsg("examples.getStateName", array(new xmlrpcval(23"int")));
$resp $client->send($message);
if (
$resp->faultCode()) echo 'KO. Error: '.$resp->faultString(); else echo 'OK: got '.$resp->value();

For more details about usage of the 'xml' value, see Appendix A.