This is the basic class used to represent a client of an XML-RPC server.
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.
This class supports the following methods.
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.
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.
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.
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.
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.
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.
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).
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.
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
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.
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.
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.
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.
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
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.
$iTRUE. To specify custom
SSL certificates to validate the server with, use the
setCaCertificate method.
NB: direct manipulation of these variables is only recommended for advanced users.
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.
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'
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.