Chapter 5. Class documentation

Table of Contents
xmlrpc_client
xmlrpcmsg
xmlrpcresp
xmlrpcval
xmlrpc_server

xmlrpc_client

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

Creation

The constructor has the following syntax:

$client=new xmlrpc_client($server_path, $server_hostname, $server_port);

Here's an 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 "send" method below.)

Methods

This class supports the following methods.

send

This method takes the form:

$response=$client->send($xmlrpc_message, $timeout, $server_method);

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

The $timeout is optional, and will be set to 0 (wait forever) if omitted. This timeout value is passed to fsockopen().

The server_method parameter is optional, and if omitted will default to 'http'. The only other valid value is 'https', which will use an SSL HTTP connection to connect to the remote server. Note that your PHP must have the "curl" extensions compiled in in order to use this feature. 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.2 or greater is required for SSL functionality. PHP 4.0.6 has a bug which prevents SSL working.

If the value of $response is 0 rather than an xmlrpcresp object, then this signifies an I/O error has occured. You can find out what the I/O error was from the values $client->errno and $client->errstring.

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.

setCredentials

$client->setCredentials($username, $password);

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.

setCertificate

$client->setCertificate($certificate, $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).

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" extensions to be compiled into your installation of PHP.

setSSLVerifyPeer

$client->setSSLVerifyPeer($i);

This method defines whether connections made to XMLRPC 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.

setSSLVerifyHost

$client->setSSLVerifyHost($i);

This method defines whether connections made to XMLRPC 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.

setDebug

$client->setDebug($debugOn);

$debugOn is either 0 or 1 depending on whether you require the client to print debugging information to the browser. The default is not to output this information.

The debugging information includes the raw data returned from the XML-RPC server it was querying, and the PHP value the client attempts to create to represent the value returned by the server. This option can be very useful when debugging servers as it allows you to see exactly what the server returns.