[preface]
== Introduction
-WARNING: THIS MANUAL HAS NOT YET BEEN UPDATED TO REFLECT ALL THE CHANGES WHICH HAVE MADE IN VERSION 4. DO NOT USE FOR NOW.
+WARNING: THIS MANUAL HAS NOT YET BEEN UPDATED TO REFLECT ALL THE CHANGES WHICH HAVE MADE IN VERSION 4. *DO NOT USE* FOR NOW. You can find the API documentation at link:$$http://gggeek.github.io/phpxmlrpc/doc-4/api/index.html$$[http://gggeek.github.io/phpxmlrpc/doc-4/api/index.html]
This collection of PHP classes provides a framework for writing XML-RPC clients and servers in PHP.
The original author is Edd Dumbill of link:$$http://usefulinc.com/$$[Useful Information Company]. As of the 1.0 stable
release, the project was opened to wider involvement and moved to
- link:$$http://phpxmlrpc.sourceforge.net/$$[SourceForge]; later, to link:$$https://github.com/gggeek/phpxmlrpc$$[Github]
+ link:$$https://sourceforge.net/projects/phpxmlrpc/$$[SourceForge]; later, to link:$$https://github.com/gggeek/phpxmlrpc$$[Github]
XML-RPC is a format devised by link:$$http://www.userland.com/$$[Userland Software] for achieving remote procedure call
via XML using HTTP as the transport. XML-RPC has its own web site, link:$$http://www.xmlrpc.com/$$[www.xmlrpc.com]
-A list of XML-RPC implementations for other languages such as Perl and Python can be found on the
- link:$$http://www.xmlrpc.com/$$[www.xmlrpc.com] site.
-
=== Acknowledgements
Daniel E. Baumann
Daniel Krippner
-{empty}S. Kuip
+S. Kuip
-{empty}A. Lambert
+A. Lambert
Frederic Lecointre
demo/*:: example code for implementing both xmlrpc client and server functionality
-doc/*:: the documentation/ this manual, and the list of API changes between versions 3 and 4
-
-extras/rsakey.pem:: A test certificate key for the SSL support, which can be used to generate dummy certificates. It has
- the passphrase "test."
-
-extras/test.pl, extras/test.py:: Perl and Python programs to exercise server.php to test that some of the methods work.
+doc/*:: the documentation, including this manual, and the list of API changes between versions 3 and 4
-extras/workspace.testPhpServer.fttb:: Frontier scripts to exercise the demo server. Thanks to Dave Winer for permission
- to include these. See link:$$http://www.xmlrpc.com/discuss/msgReader$853$$[Dave's announcement of these.]
+extras/*:: php utility scripts, such as a benchmark suite and an evironment compatibility checker
lib/*:: a compatibility layer for applications which still rely on version 3 of the API
src/*:: the XML-RPC library classes. You can autoload these via Composer, or via a dedicated Autoloader class
-tests/*:: the test suite for the library, written using PhpUnit, and the configuration to run it on Travis
+tests/*:: the test suite for the library, written using PhpUnit, and the configuration to run it either on GitHub Actions or in a local Docker container
[[bugs]]
-
== Known Bugs
Known bugs are tracked using the link:$$https://github.com/gggeek/phpxmlrpc/issues$$[GitHub issue tracker]
header, mandated by the xml-rpc spec, is not validated); cookie support still involves quite a bit of coding on the
part of the user.
-Support for receiving from servers version 1 cookies (i.e. conforming to RFC 2965) is quite incomplete, and might cause
- unforeseen errors.
-
[[support]]
-
== Support
-
=== Online Support
XML-RPC for PHP is offered "as-is" without any warranty or commitment to support. However, informal advice and help is
posted to the link:$$https://github.com/gggeek/phpxmlrpc/issues$$[project's website].
* The __PHP XML-RPC interest mailing list__ is run by the original author. More details
- link:$$http://lists.gnomehack.com/mailman/listinfo/phpxmlrpc$$[can be found here].
+ link:$$https://lists.usefulinc.com/cgi-bin/mailman/listinfo/phpxmlrpc$$[can be found here].
[[jellyfish]]
-
=== The Jellyfish Book
image::progxmlrpc.s.gif[The Jellyfish Book]
Together with Simon St.Laurent and Joe Johnston, Edd Dumbill wrote a book on XML-RPC for O'Reilly and Associates on
XML-RPC. It features a rather fetching jellyfish on the cover.
-Complete details of the book are link:$$http://www.oreilly.com/catalog/progxmlrpc/$$[available from O'Reilly's web site.]
+Complete details of the book are link:$$https://www.oreilly.com/library/view/programming-web-services/0596001193/$$[available from O'Reilly's web site.]
Edd is responsible for the chapter on PHP, which includes a worked example of creating a forum server, and hooking it up
- the O'Reilly's link:$$http://meerkat.oreillynet.com/$$[Meerkat] service in order to allow commenting on news stories
+ the (now discontinued) O'Reilly's Meerkat service in order to allow commenting on news stories
from around the Web.
If you've benefited from the effort that has been put into writing this software, then please consider buying the book!
[[apidocs]]
-
== Class documentation
-[[xmlrpcval]]
-
-=== xmlrpcval
-
-This is where a lot of the hard work gets done. This class enables
- the creation and encapsulation of values for XML-RPC.
-
-Ensure you've read the XML-RPC spec at link:$$http://www.xmlrpc.com/stories/storyReader$7$$[http://www.xmlrpc.com/stories/storyReader$7]
- before reading on as it will make things clearer.
-
-The xmlrpcval class can store arbitrarily
- complicated values using the following types: ++i4 int boolean string double dateTime.iso8601 base64 array struct++
- ++null++. You should refer to the link:$$http://www.xmlrpc.com/spec$$[spec] for more information on
- what each of these types mean.
-
==== Notes on types
===== int
int: int is regarded
by this implementation as the canonical name for this type.
+The type i8 on the other hand is considered as a separate type.
+ Note that the library will never output integers as 'i8' on its own,
+ even when php is compiled in 64-bit mode.
+
===== base64
Base 64 encoding is performed transparently to the caller when
them, and uses the same encoding convention (see ...).
[[xmlrpcval-creation]]
-
-==== Creation
+==== Xmlrpcval creation
The constructor is the normal way to create an
xmlrpcval. The constructor can take these
[source, php]
----
-
$myInt = new xmlrpcval(1267, "int");
$myString = new xmlrpcval("Hello, World!", "string");
$myBool = new xmlrpcval(1, "boolean");
$myString2 = new xmlrpcval(1.24, "string"); // note: this will serialize a php float value as xmlrpc string
-
----
The fourth constructor form can be used to compose complex
[source, php]
----
-
$myArray = new xmlrpcval(
array(
new xmlrpcval("Tom"),
"struct")
),
"struct");
-
----
See the file ++vardemo.php++ in this distribution
for more examples.
-[[xmlrpcval-methods]]
-
-==== Methods
-
-===== addScalar
-
-int addScalarstring$stringValintaddScalarmixed$scalarValstring$scalartypIf $val is an empty
- xmlrpcval this method makes it a scalar
- value, and sets that value.
-
-If $val is already a scalar value, then
- no more scalars can be added and ++0++ is
- returned.
-
-If $val is an xmlrpcval of type array,
- the php value $scalarval is added as its last
- element.
-
-If all went OK, ++1++ is returned, otherwise
- ++0++.
-
-===== addArray
-
-intaddArrayarray$arrayValThe argument is a simple (numerically indexed) array. The
- elements of the array __must be xmlrpcval objects themselves__.
-
-Turns an empty xmlrpcval into an
- array with contents as specified by
- $arrayVal.
-
-If $val is an xmlrpcval of type array,
- the elements of $arrayVal are appended to the
- existing ones.
-
-See the fourth constructor form for more information.
-
-If all went OK, ++1++ is returned, otherwise
- ++0++.
-
-===== addStruct
-
-int addStructarray$assocArrayValThe argument is an associative array. The elements of the
- array __must be xmlrpcval objects themselves__.
-
-Turns an empty xmlrpcval into a
- struct with contents as specified by
- $assocArrayVal.
-
-If $val is an xmlrpcval of type struct,
- the elements of $arrayVal are merged with the
- existing ones.
-
-See the fourth constructor form for more information.
-
-If all went OK, ++1++ is returned, otherwise
- ++0++.
-
-===== kindOf
-
-string kindOf Returns a string containing "struct", "array" or "scalar"
- describing the base type of the value. If it returns "undef" it
- means that the value hasn't been initialised.
-
-===== serialize
-
-string serialize Returns a string containing the XML-RPC representation of this
- value.
-
-
-===== scalarVal
-
-mixed scalarVal If $val->kindOf() == "scalar", this
- method returns the actual PHP-language value of the scalar (base 64
- decoding is automatically handled here).
-
-===== scalarTyp
-
-string scalarTyp If $val->kindOf() == "scalar", this
- method returns a string denoting the type of the scalar. As
- mentioned before, ++i4++ is always coerced to
- ++int++.
-
-===== arrayMem
-
-xmlrpcval arrayMem int $n If $val->kindOf() == "array", returns
- the $nth element in the array represented by
- the value $val. The value returned is an
- xmlrpcval object.
-
-[source, php]
-----
-
-// iterating over values of an array object
-for ($i = 0; $i < $val->arraySize(); $i++)
-{
- $v = $val->arrayMem($i);
- echo "Element $i of the array is of type ".$v->kindOf();
-}
-
-----
-
-===== arraySize
-
-int arraySize If $val is an
- array, returns the number of elements in that
- array.
-
-===== structMem
-
-xmlrpcval structMem string $memberName If $val->kindOf() == "struct", returns
- the element called $memberName from the
- struct represented by the value $val. The
- value returned is an xmlrpcval object.
-
-===== structEach
-
-array structEach Returns the next (key, value) pair from the struct, when
- $val is a struct.
- $value is an xmlrpcval itself. See also <<structreset>>.
-
-[source, php]
-----
-
-// iterating over all values of a struct object
-$val->structreset();
-while (list($key, $v) = $val->structEach())
-{
- echo "Element $key of the struct is of type ".$v->kindOf();
-}
-
-----
-
-[[structreset]]
-
-===== structReset
-
-void structReset Resets the internal pointer for
- structEach() to the beginning of the struct,
- where $val is a struct.
-
-[[structmemexists]]
-
-===== structMemExists
-
-bool structMemExsists string $memberName Returns TRUE or
- FALSE depending on whether a member of the
- given name exists in the struct.
-
-[[xmlrpcmsg]]
-
-=== xmlrpcmsg
-
-This class provides a representation for a request to an XML-RPC
- server. A client sends an xmlrpcmsg to a server,
- and receives back an xmlrpcresp (see <<xmlrpc-client-send>>).
-
-==== Creation
-
-The constructor takes the following forms:
-
-xmlrpcmsgnew
- xmlrpcmsgstring$methodNamearray$parameterArraynullWhere methodName is a string indicating
- the name of the method you wish to invoke, and
- parameterArray is a simple php
- Array of xmlrpcval
- objects. Here's an example message to the __US state name__ server:
-
-[source, php]
-----
-
-$msg = new xmlrpcmsg("examples.getStateName", array(new xmlrpcval(23, "int")));
-
-----
-
-This example requests the name of state number 23. For more
- information on xmlrpcval objects, see <<xmlrpcval>>.
-
-Note that the parameterArray parameter is
- optional and can be omitted for methods that take no input parameters
- or if you plan to add parameters one by one.
-
-==== Methods
-
-
-===== addParam
-
-bool addParam xmlrpcval $xmlrpcVal Adds the xmlrpcval
- xmlrpcVal to the parameter list for this
- method call. Returns TRUE or FALSE on error.
-
-===== getNumParams
-
-int getNumParams Returns the number of parameters attached to this
- message.
-
-===== getParam
-
-xmlrpcval getParam int $n Gets the nth parameter in the message
- (with the index zero-based). Use this method in server
- implementations to retrieve the values sent by the client.
-
-===== method
-
-string method string method string $methNameGets or sets the method contained in the XML-RPC
- message.
-
-===== parseResponse
-
-xmlrpcresp parseResponsestring $xmlString Given an incoming XML-RPC server response contained in the
- string $xmlString, this method constructs an
- xmlrpcresp response object and returns it,
- setting error codes as appropriate (see <<xmlrpc-client-send>>).
-
-This method processes any HTTP/MIME headers it finds.
-
-===== parseResponseFile
-
-xmlrpcresp parseResponseFile file handle
- resource$fileHandleGiven an incoming XML-RPC server response on the open file
- handle fileHandle, this method reads all the
- data it finds and passes it to
- parseResponse.
-
-This method is useful to construct responses from pre-prepared
- files (see files ++demo1.xml, demo2.xml, demo3.xml++
- in this distribution). It processes any HTTP headers it finds, and
- does not close the file handle.
-
-===== serialize
-
-string
- serializeReturns the an XML string representing the XML-RPC
- message.
-
[[xmlrpc-client]]
-
-=== xmlrpc_client
-
-This is the basic class used to represent a client of an XML-RPC
- server.
-
-==== Creation
+==== Xmlrpc-client creation
The constructor accepts one of two possible syntaxes:
[source, php]
----
-
$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
[source, php]
----
-
$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).
+ HTTPS.
The transport parameter is optional, and
if omitted will default to 'http'. Allowed values are either
meaning of the different values.
-==== Methods
-
-This class supports the following methods.
-
-[[xmlrpc-client-send]]
-
-===== send
-
-This method takes the forms:
-
-xmlrpcresp send xmlrpcmsg $xmlrpc_message int $timeout string $transport array sendarray $xmlrpc_messages int $timeout string $transportxmlrpcrespsendstring$xml_payloadint$timeoutstring$transportWhere 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 link:$$http://www.php.net/xmlrpc$$[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.
-
-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]]
-
-===== multiCall
-
-This method takes the form:
-
-array multiCall 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
-
-void setAcceptedCompression 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
-
-voidsetCaCertificatestring$certificatebool$is_dirThis 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
-
-voidsetCertificatestring$certificatestring$passphraseThis 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
-
-void setCookiestring $name string $value string $path string $domain int $portThis 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
-
-voidsetCredentialsstring$usernamestring$passwordint$authtypeThis 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
-
-voidsetCurlOptionsarray$optionsThis 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
-
-void setDebugint$debugLvldebugLvl 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
-
-voidsetKeyint$keyint$keypassThis 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
-
-voidsetProxystring$proxyhostint$proxyportstring$proxyusernamestring$proxypasswordint$authtypeThis 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
-
-voidsetRequestCompressionstring$compressionmethodThis 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
-
-voidsetSSLVerifyHostint$iThis 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
-
-voidsetSSLVerifyPeerbool$iThis 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
-
-voidUseragentstring$useragentThis 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]]
-
-===== 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:
-
-
-[source, php]
-----
-
-$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.
-
-[[xmlrpcresp]]
-
-=== xmlrpcresp
-
-This class is used to contain responses to XML-RPC requests. A
- server method handler will construct an
- xmlrpcresp and pass it as a return value. This
- same value will be returned by the result of an invocation of the
- send method of the
- xmlrpc_client class.
-
-
-==== Creation
-
-xmlrpcrespnew
- xmlrpcrespxmlrpcval$xmlrpcvalxmlrpcrespnew
- xmlrpcresp0int$errcodestring$err_stringThe first syntax is used when execution has happened without
- difficulty: $xmlrpcval is an
- xmlrpcval value with the result of the method
- execution contained in it. Alternatively it can be a string containing
- the xml serialization of the single xml-rpc value result of method
- execution.
-
-The second type of constructor is used in case of failure.
- errcode and err_string
- are used to provide indication of what has gone wrong. See <<xmlrpc-server>> for more information on passing error
- codes.
-
-
-==== Methods
-
-
-===== faultCode
-
-intfaultCodeReturns the integer fault code return from the XML-RPC
- response. A zero value indicates success, any other value indicates
- a failure response.
-
-
-===== faultString
-
-stringfaultStringReturns the human readable explanation of the fault indicated
- by $resp->faultCode().
-
-
-===== value
-
-xmlrpcvalvalueReturns an xmlrpcval object containing
- the return value sent by the server. If the response's
- faultCode is non-zero then the value returned
- by this method should not be used (it may not even be an
- object).
-
-Note: if the xmlrpcresp instance in question has been created
- by an xmlrpc_client object whose
- return_type was set to 'phpvals', then a plain
- php value will be returned instead of an
- xmlrpcval object. If the
- return_type was set to 'xml', an xml string will
- be returned (see the return_type member var above for more
- details).
-
-
-===== serialize
-
-stringserializeReturns an XML string representation of the response (xml
- prologue not included).
-
[[xmlrpc-server]]
=== xmlrpc_server
[source, php]
----
-
function foo ($xmlrpcmsg) {
...
return new xmlrpcresp($some_xmlrpc_val);
"examples.myFunc1" => array("function" => "foo"),
"examples.myFunc2" => array("function" => "bar::foobar"),
));
-
----
This performs everything you need to do with a server. The single
[source, php]
----
-
function foo ($xmlrpcmsg) {
global $xmlrpcerruser; // import user errcode base value
return new xmlrpcresp(new xmlrpcval("All's fine!", "string"));
}
}
-
----
See __server.php__ in this distribution for
distribution to see what a dispatch map looks like.
[[signatures]]
-
==== Method signatures
A signature is a description of a method's return type and its
Within a server's dispatch map, each method has an array of
possible signatures. Each signature is an array of types. The first
entry is the return type. For instance, the method
+
[source, php]
----
string examples.getStateName(int)
-
----
has the signature
+
[source, php]
----
array($xmlrpcString, $xmlrpcInt)
-
----
and, assuming that it is the only possible signature for the
method, it might be used like this in server creation:
+
[source, php]
----
-
$findstate_sig = array(array($xmlrpcString, $xmlrpcInt));
$findstate_doc = 'When passed an integer between 1 and 51 returns the
"signature" => $findstate_sig,
"docstring" => $findstate_doc
)));
-
----
-
-
Note that method signatures do not allow to check nested
parameters, e.g. the number, names and types of the members of a
struct param cannot be validated.
used in method signatures as a placeholder for 'any xmlrpc
type':
-
[source, php]
----
-
$echoback_sig = array(array($xmlrpcValue, $xmlrpcValue));
$findstate_doc = 'Echoes back to the client the received value, regardless of its type';
"signature" => $echoback_sig, // this sig guarantees that the method handler will be called with one and only one parameter
"docstring" => $echoback_doc
)));
-
----
Methods system.listMethods,
server, and should not be reimplemented (see Reserved Methods
below).
-
==== Delaying the server response
You may want to construct the server, but for some reason not
[source, php]
----
-
$s = new xmlrpc_server($myDispMap, 0); // second parameter = 0 prevents automatic servicing of request
// ... some code that does other stuff here
$s->service();
-
----
Note that the service method will print
Xmlrpc requests retrieved by other means than HTTP POST bodies
can also be processed. For example:
-
[source, php]
----
-
$s = new xmlrpc_server(); // not passing a dispatch map prevents automatic servicing of request
// ... some code that does other stuff here, including setting dispatch map into server object
$resp = $s->service($xmlrpc_request_body, true); // parse a variable instead of POST body, retrieve response payload
// ... some code that does other stuff with xml response $resp here
-
----
-
==== Modifying the server behaviour
A couple of methods / class variables are available to modify
words:
[source, php]
----
-
function foo($usr_id, $out_lang='en') {
global $xmlrpcerruser;
), false);
$s->functions_parameters_type = 'phpvals';
$s->service();
-
----
There are a few things to keep in mind when using this
[[globalvars]]
-
== Global variables
Many global variables are defined in the xmlrpc.inc file. Some of
reserved for library usage.
-==== $xmlrpcI4, $xmlrpcInt, $xmlrpcBoolean, $xmlrpcDouble, $xmlrpcString, $xmlrpcDateTime, $xmlrpcBase64, $xmlrpcArray, $xmlrpcStruct, $xmlrpcValue, $xmlrpcNull
+==== $xmlrpcI4, $xmlrpcI8 $xmlrpcInt, $xmlrpcBoolean, $xmlrpcDouble, $xmlrpcString, $xmlrpcDateTime, $xmlrpcBase64, $xmlrpcArray, $xmlrpcStruct, $xmlrpcValue, $xmlrpcNull
For convenience the strings representing the XML-RPC types have
been encoded as global variables:
[source, php]
----
-
$xmlrpcI4="i4";
+$xmlrpcI8="i8";
$xmlrpcInt="int";
$xmlrpcBoolean="boolean";
$xmlrpcDouble="double";
$xmlrpcStruct="struct";
$xmlrpcValue="undefined";
$xmlrpcNull="null";
-
----
==== $xmlrpcTypes, $xmlrpc_valid_parents, $xmlrpcerr, $xmlrpcstr, $xmlrpcerrxml, $xmlrpc_backslash, $_xh, $xml_iso88591_Entities, $xmlEntities, $xmlrpcs_capabilities
=== Variables whose value can be modified
[[xmlrpc-defencoding]]
-
==== xmlrpc_defencoding
$xmlrpc_defencoding"UTF8"This variable defines the character set encoding that will be
[source, php]
----
-
<?php
include('xmlrpc.inc');
$xmlrpc_internalencoding = 'UTF-8'; // this has to be set after the inclusion above
$v = new xmlrpcval('κόÏ\83με'); // This xmlrpc value will be correctly serialized as the greek word 'kosme'
-
----
==== xmlrpcName
[[helpers]]
-
== Helper functions
XML-RPC for PHP contains some helper functions which you can use to
representations: CCYYMMDDTHH:MM:SS.
[[iso8601encode]]
-
==== iso8601_encode
stringiso8601_encodestring$time_tint$utc0Returns an ISO 8601 formatted date generated from the UNIX
includes a demonstration of this function.
[[iso8601decode]]
-
==== iso8601_decode
intiso8601_decodestring$isoStringint$utc0Returns a UNIX timestamp from an ISO 8601 encoded time and date
local timestamp.
[[arrayuse]]
-
=== Easy use with nested PHP values
Dan Libby was kind enough to contribute two helper functions that
These functions reside in __xmlrpc.inc__.
[[phpxmlrpcdecode]]
-
==== php_xmlrpc_decode
mixedphp_xmlrpc_decodexmlrpcval$xmlrpc_valarray$optionsarrayphp_xmlrpc_decodexmlrpcmsg$xmlrpcmsg_valstring$optionsReturns a native PHP value corresponding to the values found in
Example:
[source, php]
----
-
// wrapper to expose an existing php function as xmlrpc method handler
function foo_wrapper($m)
{
"function" => "foo_wrapper",
"signatures" => ...
)));
-
----
[[phpxmlrpcencode]]
-
==== php_xmlrpc_encode
xmlrpcvalphp_xmlrpc_encodemixed$phpvalarray$optionsReturns an xmlrpcval object populated with the PHP
Example:
[source, php]
----
-
// the easy way to build a complex xml-rpc struct, showing nested base64 value and datetime values
$val = php_xmlrpc_encode(array(
'first struct_element: an int' => 666,
'third: a base64 element' => new xmlrpcval('hello world', 'base64'),
'fourth: a datetime' => '20060107T01:53:00'
), array('auto_dates'));
-
----
==== php_xmlrpc_decode_xml
Example:
[source, php]
----
-
$text = '<value><array><data><value>Hello world</value></data></array></value>';
$val = php_xmlrpc_decode_xml($text);
if ($val) echo 'Found a value of type '.$val->kindOf(); else echo 'Found invalid xml';
-
----
=== Automatic conversion of php functions into xmlrpc methods (and vice versa)
[source, php]
----
-
$c = new xmlrpc_client('http://phpxmlrpc.sourceforge.net/server.php');
$function = wrap_xmlrpc_method($client, 'examples.getStateName');
else
echo "OK, state nr. $stateno is $statename";
}
-
----
[[wrap_php_function]]
-
==== wrap_php_function
arraywrap_php_functionstring$funcnamestring$wrapper_function_namearray$extra_optionsGiven a user-defined PHP function, create a PHP 'wrapper'
if ($findstate_sig)
$methods['examples.getStateName'] = $findstate_sig;
$srv = new xmlrpc_server($methods);
-
----
[[deprecated]]
-
=== Functions removed from the library
The following two functions have been deprecated in version 1.1 of
existing implementations, the following scheme has been adopted:
* If EPI-XMLRPC is not active in the current PHP installation,
- the constant ++$$XMLRPC_EPI_ENABLED$$++ will be set to
- ++$$'0'$$++
+ the constant `XMLRPC_EPI_ENABLED` will be set to
+ '0'
* If EPI-XMLRPC is active in the current PHP installation, the
- constant ++$$XMLRPC_EPI_ENABLED$$++ will be set to
- ++$$'1'$$++
-
-
+ constant `XMLRPC_EPI_ENABLED` will be set to
+ '1'
The following documentation is kept for historical
reference:
[[xmlrpcdecode]]
-
==== xmlrpc_decode
mixedx mlrpc_decode xmlrpcval $xmlrpc_val Alias for php_xmlrpc_decode.
[[xmlrpcencode]]
-
==== xmlrpc_encode
xmlrpcval xmlrpc_encode mixed $phpvalAlias for php_xmlrpc_encode.
[[debugging]]
-
=== Debugging aids
==== xmlrpc_debugmsg
[[reserved]]
-
== Reserved methods
In order to extend the functionality offered by XML-RPC servers
a method implemented by the server.
[[sysmethodsig]]
-
=== system.methodSignature
This method takes one parameter, the name of a method implemented
[source, php]
----
-
$v = $resp->value();
if ($v->kindOf() != "array") {
// then the method did not have a signature defined
}
-
----
See the __introspect.php__ demo included in this
distribution for an example of using this method.
[[sysmethhelp]]
-
=== system.methodHelp
This method takes one parameter, the name of a method implemented
[[examples]]
-
== Examples
The best examples are to be found in the sample files included with
the distribution. Some are included here.
[[statename]]
-
=== XML-RPC client: state name query
Code to get the corresponding state name from a number (1-50) from
[source, php]
----
-
$m = new xmlrpcmsg('examples.getStateName',
array(new xmlrpcval($HTTP_POST_VARS["stateno"], "int")));
$c = new xmlrpc_client("/server.php", "phpxmlrpc.sourceforge.net", 80);
print "Code: " . htmlentities($r->faultCode()) . "<BR>" .
"Reason: '" . htmlentities($r->faultString()) . "'<BR>";
}
-
----
=== Executing a multicall call
[[faq]]
-[qanda]
+[[qanda]]
== Frequently Asked Questions
==== How to send custom XML as payload of a method call::
To find out what the server is really returning to your client,
you have to enable the debug mode of the client, using
- $client->setdebug(1);
+ $client->setDebug(1);
==== How can I save to a file the xml of the xmlrpc responses received from servers?
[source, php]
----
-
$resp = $client->send($msg);
if (!$resp->faultCode())
$data_to_be_saved = $resp->serialize();
-
----
Note that this will not be 100% accurate, since the xml generated
[source, php]
----
-
$client = new xmlrpc_client($url);
$client->return_type = 'xml';
$resp = $client->send($msg);
if (!$resp->faultCode())
$data_to_be_saved = $resp->value();
-
----
Note that using this method the xml response response will not be
[source, php]
----
-
$resp = $client->send(new xmlrpcmsg('registervalue', array(new xmlrpcval('foo'), new xmlrpcval('bar'))));
if (!$resp->faultCode())
{
$val = $client->send(new xmlrpcmsg('getvalue', array(new xmlrpcval('foo')));
}
}
-
----
Server-side sessions are handled normally like in any other
[[integration]]
-
[appendix]
== Integration with the PHP xmlrpc extension
[source, php]
----
-
/*** client side ***/
$c = new xmlrpc_client('http://phpxmlrpc.sourceforge.net/server.php');
else
echo'Got response: '.htmlentities($v);
}
-
----
-
[[substitution]]
-
[appendix]
== Substitution of the PHP xmlrpc extension
[[enough]]
-
[appendix]
== 'Enough of xmlrpcvals!': new style library usage
[[debugger]]
-
[appendix]
== Usage of the debugger
either to the same directory as the debugger or somewhere in your
php include path
-
* to enable the visual value editing dialog, download the
JS-XMLRPC library, and copy somewhere in the web root files
__visualeditor.php__,
debugger file __controller.php__ and set
appropriately the variable $editorpath.
-
[[news]]
-
[appendix]
-
== Whats's new
CAUTION: not all items the following list have (yet) been fully documented, and some might not be present in any other
* improved: a specific option allows users to decide the version of SSL to use for https calls.
This is useful f.e. for the testing suite, when the server target of calls has no proper ssl certificate,
- and the cURL extension has been compiled with GnuTLS (such as on Travis VMs)
+ and the cURL extension has been compiled with GnuTLS
* improved: the function `wrap_php_function()` now can be used to wrap closures (it is now a method btw)
invoked using an unknown xmlrpc type: the error will only be written to php error log. Also
`new xmlrpcval('true', 'boolean')` is not supported anymore
-* The new function php_xmlrpc_decode_xml() will take the xml representation of either an xmlrpc request, response or
+* The new function `php_xmlrpc_decode_xml()` will take the xml representation of either an xmlrpc request, response or
single value and return the corresponding php-xmlrpc object instance
-* A new function wrap_xmlrpc_server()has been added, to wrap all (or some) of the methods exposed by a remote xmlrpc
+* A new function `wrap_xmlrpc_server()` has been added, to wrap all (or some) of the methods exposed by a remote xmlrpc
server into a php class
* A new file has been added: _verify_compat.php_, to help users diagnose the level of compliance of their php
git://git.onelab.eu / plcapi.git / blobdiff