xmlrpc_client
Prev | Chapter 7. Class documentation | Next

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

#### 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");
    $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.

Prev | Up | Next
xmlrpcmsg | Home | xmlrpcresp