3 :keywords: xmlrpc, ,xml, rpc, webservices, http
6 :source-highlighter: highlightjs
12 NB: THIS MANUAL HAS NOT YET BEEN UPDATED TO REFLECT ALL THE CHANGES WHICH HAVE MADE IN VERSION 4.
15 XML-RPC is a format devised by link:$$http://www.userland.com/$$[Userland Software] for achieving
16 remote procedure call via XML using HTTP as the transport. XML-RPC has its
17 own web site, link:$$http://www.xmlrpc.com/$$[www.xmlrpc.com]
19 This collection of PHP classes provides a framework for writing
20 XML-RPC clients and servers in PHP.
22 Main goals of the project are ease of use, flexibility and
25 The original author is Edd Dumbill of link:$$http://usefulinc.com/$$[Useful Information Company]. As of the
26 1.0 stable release, the project was opened to wider involvement and moved
27 to link:$$http://phpxmlrpc.sourceforge.net/$$[SourceForge]; later, to link:$$https://github.com/gggeek/phpxmlrpc$$[Github]
29 A list of XML-RPC implementations for other languages such as Perl
30 and Python can be found on the link:$$http://www.xmlrpc.com/$$[www.xmlrpc.com] site.
70 Ernest MacDougal Campbell III
108 Przemyslaw Wroblewski
110 Bruno Zanetti Melotti
114 == System Requirements
116 The library has been designed with goals of scalability and backward
117 compatibility. As such, it supports a wide range of PHP installs. Note
118 that not all features of the lib are available in every
121 The __minimum supported__ PHP version is
124 If you wish to use HTTPS or HTTP 1.1 to communicate with remote
125 servers, you need the "curl" extension compiled into your PHP
128 The "xmlrpc" native extension is not required to be compiled into
129 your PHP installation, but if it is, there will be no interference with
130 the operation of this library.
134 == Files in the distribution
137 the XML-RPC classes. include() this in
138 your PHP files to use the classes.
141 the XML-RPC server class. include() this
142 in addition to xmlrpc.inc to get server functionality
144 lib/xmlrpc_wrappers.php::
145 helper functions to "automagically" convert plain php
146 functions to xmlrpc services and vice versa
148 demo/server/proxy.php::
149 a sample server implementing xmlrpc proxy
152 demo/server/server.php::
153 a sample server hosting various demo functions, as well as a
154 full suite of functions used for interoperability testing. It is
155 used by testsuite.php (see below) for unit testing the library, and
156 is not to be copied literally into your production servers
158 demo/client/client.php, demo/client/agesort.php,
159 demo/client/which.php::
160 client code to exercise some of the functions in server.php,
161 including the interopEchoTests.whichToolkit
164 demo/client/wrap.php::
165 client code to illustrate 'wrapping' of remote methods into
168 demo/client/introspect.php::
169 client code to illustrate usage of introspection capabilities
170 offered by server.php.
172 demo/client/mail.php::
173 client code to illustrate usage of an xmlrpc-to-email gateway
174 using Dave Winer's XML-RPC server at userland.com.
176 demo/client/zopetest.php::
177 example client code that queries an xmlrpc server built in
181 examples of how to construct xmlrpcval types
183 demo/demo1.xml, demo/demo2.xml, demo/demo3.xml::
184 XML-RPC responses captured in a file for testing purposes (you
185 can use these to test the
186 xmlrpcmsg->parseResponse() method).
188 demo/server/discuss.php,
189 demo/client/comment.php::
190 Software used in the PHP chapter of <<jellyfish>> to provide a comment server and allow the
191 attachment of comments to stories from Meerkat's data store.
193 test/testsuite.php, test/parse_args.php::
194 A unit test suite for this software package. If you do
195 development on this software, please consider submitting tests for
199 A (very limited) benchmarking suite for this software package.
200 If you do development on this software, please consider submitting
201 benchmarks for this suite.
203 test/phpunit.php, test/PHPUnit/*.php::
204 An (incomplete) version PEAR's unit test framework for PHP.
205 The complete package can be found at link:$$http://pear.php.net/package/PHPUnit$$[http://pear.php.net/package/PHPUnit]
207 test/verify_compat.php::
208 Script designed to help the user to verify the level of
209 compatibility of the library with the current php install
211 extras/test.pl, extras/test.py::
212 Perl and Python programs to exercise server.php to test that
213 some of the methods work.
215 extras/workspace.testPhpServer.fttb::
216 Frontier scripts to exercise the demo server. Thanks to Dave
217 Winer for permission to include these. See link:$$http://www.xmlrpc.com/discuss/msgReader$853$$[Dave's announcement of these.]
220 A test certificate key for the SSL support, which can be used
221 to generate dummy certificates. It has the passphrase "test."
226 == Known bugs and limitations
228 This started out as a bare framework. Many "nice" bits haven't been
229 put in yet. Specifically, very little type validation or coercion has been
230 put in. PHP being a loosely-typed language, this is going to have to be
231 done explicitly (in other words: you can call a lot of library functions
232 passing them arguments of the wrong type and receive an error message only
233 much further down the code, where it will be difficult to
236 dateTime.iso8601 is supported opaquely. It can't be done natively as
237 the XML-RPC specification explicitly forbids passing of timezone
238 specifiers in ISO8601 format dates. You can, however, use the <<iso8601encode>> and <<iso8601decode>> functions
239 to do the encoding and decoding for you.
241 Very little HTTP response checking is performed (e.g. HTTP redirects
242 are not followed and the Content-Length HTTP header, mandated by the
243 xml-rpc spec, is not validated); cookie support still involves quite a bit
244 of coding on the part of the user.
246 If a specific character set encoding other than US-ASCII, ISO-8859-1
247 or UTF-8 is received in the HTTP header or XML prologue of xml-rpc request
248 or response messages then it will be ignored for the moment, and the
249 content will be parsed as if it had been encoded using the charset defined
250 by <<xmlrpc-defencoding>>
252 Support for receiving from servers version 1 cookies (i.e.
253 conforming to RFC 2965) is quite incomplete, and might cause unforeseen
264 XML-RPC for PHP is offered "as-is" without any warranty or
265 commitment to support. However, informal advice and help is available
266 via the XML-RPC for PHP website and mailing list and from
269 * The __XML-RPC for PHP__ development is hosted
270 on link:$$https://github.com/gggeek/phpxmlrpc$$[github.com/gggeek/phpxmlrpc].
271 Bugs, feature requests and patches can be posted to the link:$$https://github.com/gggeek/phpxmlrpc/issues$$[project's website].
273 * The __PHP XML-RPC interest mailing list__ is
274 run by the author. More details link:$$http://lists.gnomehack.com/mailman/listinfo/phpxmlrpc$$[can be found here].
276 * For more general XML-RPC questions, there is a Yahoo! Groups
277 link:$$http://groups.yahoo.com/group/xml-rpc/$$[XML-RPC mailing list].
279 * The link:$$http://www.xmlrpc.com/discuss$$[XML-RPC.com] discussion
280 group is a useful place to get help with using XML-RPC. This group
281 is also gatewayed into the Yahoo! Groups mailing list.
285 === The Jellyfish Book
287 image::progxmlrpc.s.gif[The Jellyfish Book]
288 Together with Simon St.Laurent and Joe
289 Johnston, Edd Dumbill wrote a book on XML-RPC for O'Reilly and
290 Associates on XML-RPC. It features a rather fetching jellyfish on the
293 Complete details of the book are link:$$http://www.oreilly.com/catalog/progxmlrpc/$$[available from O'Reilly's web site.]
295 Edd is responsible for the chapter on PHP, which includes a worked
296 example of creating a forum server, and hooking it up the O'Reilly's
297 link:$$http://meerkat.oreillynet.com/$$[Meerkat] service in
298 order to allow commenting on news stories from around the Web.
300 If you've benefited from the effort that has been put into writing
301 this software, then please consider buying the book!
306 == Class documentation
312 This is where a lot of the hard work gets done. This class enables
313 the creation and encapsulation of values for XML-RPC.
315 Ensure you've read the XML-RPC spec at link:$$http://www.xmlrpc.com/stories/storyReader$7$$[http://www.xmlrpc.com/stories/storyReader$7]
316 before reading on as it will make things clearer.
318 The xmlrpcval class can store arbitrarily
319 complicated values using the following types: ++i4 int boolean string double dateTime.iso8601 base64 array struct++
320 ++null++. You should refer to the link:$$http://www.xmlrpc.com/spec$$[spec] for more information on
321 what each of these types mean.
327 The type i4 is accepted as a synonym
328 for int when creating xmlrpcval objects. The
329 xml parsing code will always convert i4 to
331 by this implementation as the canonical name for this type.
335 Base 64 encoding is performed transparently to the caller when
336 using this type. Decoding is also transparent. Therefore you ought
337 to consider it as a "binary" data type, for use when you want to
338 pass data that is not 7-bit clean.
342 The php values ++true++ and
343 ++1++ map to ++true++. All other
344 values (including the empty string) are converted to
349 Characters <, >, ', ", &, are encoded using their
350 entity reference as &lt; &gt; &apos; &quot; and
351 &amp; All other characters outside of the ASCII range are
352 encoded using their character reference representation (e.g.
353 &#200 for é). The XML-RPC spec recommends only encoding
354 ++< &++ but this implementation goes further,
355 for reasons explained by link:$$http://www.w3.org/TR/REC-xml#syntax$$[the XML 1.0 recommendation]. In particular, using character reference
356 representation has the advantage of producing XML that is valid
357 independently of the charset encoding assumed.
361 There is no support for encoding ++null++
362 values in the XML-RPC spec, but at least a couple of extensions (and
363 many toolkits) do support it. Before using ++null++
364 values in your messages, make sure that the responding party accepts
365 them, and uses the same encoding convention (see ...).
367 [[xmlrpcval-creation]]
371 The constructor is the normal way to create an
372 xmlrpcval. The constructor can take these
376 xmlrpcval xmlrpcvalnew
377 xmlrpcval string $stringVal xmlrpcvalnew
378 xmlrpcval mixed $scalarVal string$scalartyp xmlrpcvalnew
379 xmlrpcval array $arrayVal string $arraytyp The first constructor creates an empty value, which must be
380 altered using the methods addScalar,
381 addArray or addStruct before
384 The second constructor creates a simple string value.
386 The third constructor is used to create a scalar value. The
387 second parameter must be a name of an XML-RPC type. Valid types are:
388 "++int++", "++boolean++",
389 "++string++", "++double++",
390 "++dateTime.iso8601++", "++base64++" or
398 $myInt = new xmlrpcval(1267, "int");
399 $myString = new xmlrpcval("Hello, World!", "string");
400 $myBool = new xmlrpcval(1, "boolean");
401 $myString2 = new xmlrpcval(1.24, "string"); // note: this will serialize a php float value as xmlrpc string
405 The fourth constructor form can be used to compose complex
406 XML-RPC values. The first argument is either a simple array in the
407 case of an XML-RPC array or an associative
408 array in the case of a struct. The elements of
409 the array __must be xmlrpcval objects themselves__.
411 The second parameter must be either "++array++"
419 $myArray = new xmlrpcval(
421 new xmlrpcval("Tom"),
422 new xmlrpcval("Dick"),
423 new xmlrpcval("Harry")
428 $myStruct = new xmlrpcval(
430 "name" => new xmlrpcval("Tom", "string"),
431 "age" => new xmlrpcval(34, "int"),
432 "address" => new xmlrpcval(
434 "street" => new xmlrpcval("Fifht Ave", "string"),
435 "city" => new xmlrpcval("NY", "string")
443 See the file ++vardemo.php++ in this distribution
446 [[xmlrpcval-methods]]
452 int addScalarstring$stringValintaddScalarmixed$scalarValstring$scalartypIf $val is an empty
453 xmlrpcval this method makes it a scalar
454 value, and sets that value.
456 If $val is already a scalar value, then
457 no more scalars can be added and ++0++ is
460 If $val is an xmlrpcval of type array,
461 the php value $scalarval is added as its last
464 If all went OK, ++1++ is returned, otherwise
469 intaddArrayarray$arrayValThe argument is a simple (numerically indexed) array. The
470 elements of the array __must be xmlrpcval objects themselves__.
472 Turns an empty xmlrpcval into an
473 array with contents as specified by
476 If $val is an xmlrpcval of type array,
477 the elements of $arrayVal are appended to the
480 See the fourth constructor form for more information.
482 If all went OK, ++1++ is returned, otherwise
487 int addStructarray$assocArrayValThe argument is an associative array. The elements of the
488 array __must be xmlrpcval objects themselves__.
490 Turns an empty xmlrpcval into a
491 struct with contents as specified by
494 If $val is an xmlrpcval of type struct,
495 the elements of $arrayVal are merged with the
498 See the fourth constructor form for more information.
500 If all went OK, ++1++ is returned, otherwise
505 string kindOf Returns a string containing "struct", "array" or "scalar"
506 describing the base type of the value. If it returns "undef" it
507 means that the value hasn't been initialised.
511 string serialize Returns a string containing the XML-RPC representation of this
517 mixed scalarVal If $val->kindOf() == "scalar", this
518 method returns the actual PHP-language value of the scalar (base 64
519 decoding is automatically handled here).
523 string scalarTyp If $val->kindOf() == "scalar", this
524 method returns a string denoting the type of the scalar. As
525 mentioned before, ++i4++ is always coerced to
530 xmlrpcval arrayMem int $n If $val->kindOf() == "array", returns
531 the $nth element in the array represented by
532 the value $val. The value returned is an
538 // iterating over values of an array object
539 for ($i = 0; $i < $val->arraySize(); $i++)
541 $v = $val->arrayMem($i);
542 echo "Element $i of the array is of type ".$v->kindOf();
549 int arraySize If $val is an
550 array, returns the number of elements in that
555 xmlrpcval structMem string $memberName If $val->kindOf() == "struct", returns
556 the element called $memberName from the
557 struct represented by the value $val. The
558 value returned is an xmlrpcval object.
562 array structEach Returns the next (key, value) pair from the struct, when
564 $value is an xmlrpcval itself. See also <<structreset>>.
569 // iterating over all values of a struct object
571 while (list($key, $v) = $val->structEach())
573 echo "Element $key of the struct is of type ".$v->kindOf();
582 void structReset Resets the internal pointer for
583 structEach() to the beginning of the struct,
584 where $val is a struct.
588 ===== structMemExists
590 bool structMemExsists string $memberName Returns TRUE or
591 FALSE depending on whether a member of the
592 given name exists in the struct.
598 This class provides a representation for a request to an XML-RPC
599 server. A client sends an xmlrpcmsg to a server,
600 and receives back an xmlrpcresp (see <<xmlrpc-client-send>>).
604 The constructor takes the following forms:
607 xmlrpcmsgstring$methodNamearray$parameterArraynullWhere methodName is a string indicating
608 the name of the method you wish to invoke, and
609 parameterArray is a simple php
611 objects. Here's an example message to the __US state name__ server:
616 $msg = new xmlrpcmsg("examples.getStateName", array(new xmlrpcval(23, "int")));
620 This example requests the name of state number 23. For more
621 information on xmlrpcval objects, see <<xmlrpcval>>.
623 Note that the parameterArray parameter is
624 optional and can be omitted for methods that take no input parameters
625 or if you plan to add parameters one by one.
632 bool addParam xmlrpcval $xmlrpcVal Adds the xmlrpcval
633 xmlrpcVal to the parameter list for this
634 method call. Returns TRUE or FALSE on error.
638 int getNumParams Returns the number of parameters attached to this
643 xmlrpcval getParam int $n Gets the nth parameter in the message
644 (with the index zero-based). Use this method in server
645 implementations to retrieve the values sent by the client.
649 string method string method string $methNameGets or sets the method contained in the XML-RPC
654 xmlrpcresp parseResponsestring $xmlString Given an incoming XML-RPC server response contained in the
655 string $xmlString, this method constructs an
656 xmlrpcresp response object and returns it,
657 setting error codes as appropriate (see <<xmlrpc-client-send>>).
659 This method processes any HTTP/MIME headers it finds.
661 ===== parseResponseFile
663 xmlrpcresp parseResponseFile file handle
664 resource$fileHandleGiven an incoming XML-RPC server response on the open file
665 handle fileHandle, this method reads all the
666 data it finds and passes it to
669 This method is useful to construct responses from pre-prepared
670 files (see files ++demo1.xml, demo2.xml, demo3.xml++
671 in this distribution). It processes any HTTP headers it finds, and
672 does not close the file handle.
677 serializeReturns the an XML string representing the XML-RPC
684 This is the basic class used to represent a client of an XML-RPC
689 The constructor accepts one of two possible syntaxes:
692 xmlrpc_clientstring$server_urlxmlrpc_clientnew
693 xmlrpc_clientstring$server_pathstring$server_hostnameint$server_port80string$transport'http'Here are a couple of usage examples of the first form:
699 $client = new xmlrpc_client("http://phpxmlrpc.sourceforge.net/server.php");
700 $another_client = new xmlrpc_client("https://james:bond@secret.service.com:443/xmlrpcserver?agent=007");
704 The second syntax does not allow to express a username and
705 password to be used for basic HTTP authorization as in the second
706 example above, but instead it allows to choose whether xmlrpc calls
707 will be made using the HTTP 1.0 or 1.1 protocol.
709 Here's another example client set up to query Userland's XML-RPC
710 server at __betty.userland.com__:
715 $client = new xmlrpc_client("/RPC2", "betty.userland.com", 80);
719 The server_port parameter is optional,
720 and if omitted will default to 80 when using HTTP and 443 when using
721 HTTPS (see the <<xmlrpc-client-send>> method
724 The transport parameter is optional, and
725 if omitted will default to 'http'. Allowed values are either
727 'http11'. Its value can be overridden with every call
728 to the send method. See the
729 send method below for more details about the
730 meaning of the different values.
735 This class supports the following methods.
737 [[xmlrpc-client-send]]
741 This method takes the forms:
743 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
744 xmlrpcmsg (see <<xmlrpcmsg>>),
745 and response is an instance of
746 xmlrpcresp (see <<xmlrpcresp>>).
748 If xmlrpc_messages is an array of
749 message instances, ++responses++ will be an array of
750 response instances. The client will try to make use of a single
751 ++system.multicall++ xml-rpc method call to forward to the
752 server all the messages in a single HTTP round trip, unless
753 ++$$$client->no_multicall$$++ has been previously set to
754 ++TRUE++ (see the multicall method below), in which case
755 many consecutive xmlrpc requests will be sent.
757 The third syntax allows to build by hand (or any other means)
758 a complete xmlrpc request message, and send it to the server.
759 xml_payload should be a string containing the
760 complete xml representation of the request. It is e.g. useful when,
761 for maximal speed of execution, the request is serialized into a
762 string using the native php xmlrpc functions (see link:$$http://www.php.net/xmlrpc$$[the php manual on xmlrpc]).
764 The timeout is optional, and will be
765 set to ++0++ (wait for platform-specific predefined
766 timeout) if omitted. This timeout value is passed to
767 fsockopen(). It is also used for detecting
768 server timeouts during communication (i.e. if the server does not
769 send anything to the client for timeout
770 seconds, the connection will be closed).
772 The transport parameter is optional,
773 and if omitted will default to the transport set using instance
774 creator or 'http' if omitted. The only other valid values are
775 'https', which will use an SSL HTTP connection to connect to the
776 remote server, and 'http11'. Note that your PHP must have the "curl"
777 extension compiled in order to use both these features. Note that
778 when using SSL you should normally set your port number to 443,
779 unless the SSL server you are contacting runs at any other
782 In addition to low-level errors, the XML-RPC server you were
783 querying may return an error in the
784 xmlrpcresp object. See <<xmlrpcresp>> for details of how to handle these
791 This method takes the form:
793 array multiCall array $messages int $timeout string $transport bool $fallback This method is used to boxcar many method calls in a single
794 xml-rpc request. It will try first to make use of the
795 ++system.multicall++ xml-rpc method call, and fall back to
796 executing many separate requests if the server returns any
800 xmlrpcmsg objects (see <<xmlrpcmsg>>), and response is an
801 array of xmlrpcresp objects (see <<xmlrpcresp>>).
804 transport parameters are optional, and behave
805 as in the send method above.
807 The fallback parameter is optional, and
808 defaults to TRUE. When set to
809 FALSE it will prevent the client to try using
810 many single method calls in case of failure of the first multicall
811 request. It should be set only when the server is known to support
812 the multicall extension.
814 ===== setAcceptedCompression
816 void setAcceptedCompression string $compressionmethod This method defines whether the client will accept compressed
817 xml payload forming the bodies of the xmlrpc responses received from
818 servers. Note that enabling reception of compressed responses merely
819 adds some standard http headers to xmlrpc requests. It is up to the
820 xmlrpc server to return compressed responses when receiving such
821 requests. Allowed values for
822 compressionmethod are: 'gzip', 'deflate',
823 'any' or null (with any meaning either gzip or deflate).
825 This requires the "zlib" extension to be enabled in your php
826 install. If it is, by default xmlrpc_client
827 instances will enable reception of compressed content.
829 ===== setCaCertificate
831 voidsetCaCertificatestring$certificatebool$is_dirThis method sets an optional certificate to be used in
832 SSL-enabled communication to validate a remote server with (when the
833 server_method is set to 'https' in the
834 client's construction or in the send method and
835 SetSSLVerifypeer has been set to
838 The certificate parameter must be the
839 filename of a PEM formatted certificate, or a directory containing
840 multiple certificate files. The is_dir
841 parameter defaults to FALSE, set it to
843 certificate indicates a directory instead of
846 This requires the "curl" extension to be compiled into your
847 installation of PHP. For more details see the man page for the
848 curl_setopt function.
853 voidsetCertificatestring$certificatestring$passphraseThis method sets the optional certificate and passphrase used
854 in SSL-enabled communication with a remote server (when the
855 server_method is set to 'https' in the
856 client's construction or in the send method).
858 The certificate parameter must be the
859 filename of a PEM formatted certificate. The
860 passphrase parameter must contain the
861 password required to use the certificate.
863 This requires the "curl" extension to be compiled into your
864 installation of PHP. For more details see the man page for the
865 curl_setopt function.
867 Note: to retrieve information about the client certificate on
868 the server side, you will need to look into the environment
869 variables which are set up by the webserver. Different webservers
870 will typically set up different variables.
874 void setCookiestring $name string $value string $path string $domain int $portThis method sets a cookie that will be sent to the xmlrpc
875 server along with every further request (useful e.g. for keeping
876 session info outside of the xml-rpc payload).
878 $value is optional, and defaults to
881 $path, $domain and $port are optional,
882 and will be omitted from the cookie header if unspecified. Note that
883 setting any of these values will turn the cookie into a 'version 1'
884 cookie, that might not be fully supported by the server (see RFC2965
889 voidsetCredentialsstring$usernamestring$passwordint$authtypeThis method sets the username and password for authorizing the
890 client to a server. With the default (HTTP) transport, this
891 information is used for HTTP Basic authorization. Note that username
892 and password can also be set using the class constructor. With HTTP
893 1.1 and HTTPS transport, NTLM and Digest authentication protocols
894 are also supported. To enable them use the constants
896 CURLAUTH_NTLM as values for the authtype
902 voidsetCurlOptionsarray$optionsThis method allows to directly set any desired
903 option to manipulate the usage of the cURL client (when in cURL
904 mode). It can be used eg. to explicitly bind to an outgoing ip
905 address when the server is multihomed
910 void setDebugint$debugLvldebugLvl is either ++0, 1++ or 2 depending on whether you require the client to
911 print debugging information to the browser. The default is not to
912 output this information (0).
914 The debugging information at level 1includes the raw data
915 returned from the XML-RPC server it was querying (including bot HTTP
916 headers and the full XML payload), and the PHP value the client
917 attempts to create to represent the value returned by the server. At
918 level2, the complete payload of the xmlrpc request is also printed,
919 before being sent t the server.
921 This option can be very useful when debugging servers as it
922 allows you to see exactly what the client sends and the server
928 voidsetKeyint$keyint$keypassThis method sets the optional certificate key and passphrase
929 used in SSL-enabled communication with a remote server (when the
930 transport is set to 'https' in the client's
931 construction or in the send method).
933 This requires the "curl" extension to be compiled into your
934 installation of PHP. For more details see the man page for the
935 curl_setopt function.
940 voidsetProxystring$proxyhostint$proxyportstring$proxyusernamestring$proxypasswordint$authtypeThis method enables calling servers via an HTTP proxy. The
942 proxypassword and authtype
943 parameters are optional. Authtype defaults to
944 CURLAUTH_BASIC (Basic authentication protocol);
945 the only other valid value is the constant
946 CURLAUTH_NTLM, and has effect only when the
947 client uses the HTTP 1.1 protocol.
949 NB: CURL versions before 7.11.10 cannot use a proxy to
950 communicate with https servers.
953 ===== setRequestCompression
955 voidsetRequestCompressionstring$compressionmethodThis method defines whether the xml payload forming the
956 request body will be sent to the server in compressed format, as per
957 the HTTP specification. This is particularly useful for large
958 request parameters and over slow network connections. Allowed values
959 for compressionmethod are: 'gzip', 'deflate',
960 'any' or null (with any meaning either gzip or deflate). Note that
961 there is no automatic fallback mechanism in place for errors due to
962 servers not supporting receiving compressed request bodies, so make
963 sure that the particular server you are querying does accept
964 compressed requests before turning it on.
966 This requires the "zlib" extension to be enabled in your php
970 ===== setSSLVerifyHost
972 voidsetSSLVerifyHostint$iThis method defines whether connections made to XML-RPC
973 backends via HTTPS should verify the remote host's SSL certificate's
974 common name (CN). By default, only the existence of a CN is checked.
976 integer value; 0 to not check the CN at all, 1 to merely check for
977 its existence, and 2 to check that the CN on the certificate matches
978 the hostname that is being connected to.
981 ===== setSSLVerifyPeer
983 voidsetSSLVerifyPeerbool$iThis method defines whether connections made to XML-RPC
984 backends via HTTPS should verify the remote host's SSL certificate,
985 and cause the connection to fail if the cert verification fails.
986 $i should be a boolean
987 value. Default value: TRUE. To specify custom
988 SSL certificates to validate the server with, use the
989 setCaCertificate method.
994 voidUseragentstring$useragentThis method sets a custom user-agent that will be
995 used by the client in the http headers sent with the request. The
996 default value is built using the library name and version
1002 NB: direct manipulation of these variables is only recommended
1008 This member variable determines whether the multicall() method
1009 will try to take advantage of the system.multicall xmlrpc method to
1010 dispatch to the server an array of requests in a single http
1011 roundtrip or simply execute many consecutive http calls. Defaults to
1012 FALSE, but it will be enabled automatically on the first failure of
1013 execution of system.multicall.
1016 ===== request_charset_encoding
1018 This is the charset encoding that will be used for serializing
1019 request sent by the client.
1021 If defaults to NULL, which means using US-ASCII and encoding
1022 all characters outside of the ASCII range using their xml character
1023 entity representation (this has the benefit that line end characters
1024 will not be mangled in the transfer, a CR-LF will be preserved as
1025 well as a singe LF).
1027 Valid values are 'US-ASCII', 'UTF-8' and 'ISO-8859-1'
1033 This member variable determines whether the value returned
1034 inside an xmlrpcresp object as results of calls to the send() and
1035 multicall() methods will be an xmlrpcval object, a plain php value
1036 or a raw xml string. Allowed values are 'xmlrpcvals' (the default),
1037 'phpvals' and 'xml'. To allow the user to differentiate between a
1038 correct and a faulty response, fault responses will be returned as
1039 xmlrpcresp objects in any case. Note that the 'phpvals' setting will
1040 yield faster execution times, but some of the information from the
1041 original response will be lost. It will be e.g. impossible to tell
1042 whether a particular php string value was sent by the server as an
1043 xmlrpc string or base64 value.
1051 $client = new xmlrpc_client("phpxmlrpc.sourceforge.net/server.php");
1052 $client->return_type = 'phpvals';
1053 $message = new xmlrpcmsg("examples.getStateName", array(new xmlrpcval(23, "int")));
1054 $resp = $client->send($message);
1055 if ($resp->faultCode()) echo 'KO. Error: '.$resp->faultString(); else echo 'OK: got '.$resp->value();
1059 For more details about usage of the 'xml' value, see Appendix
1066 This class is used to contain responses to XML-RPC requests. A
1067 server method handler will construct an
1068 xmlrpcresp and pass it as a return value. This
1069 same value will be returned by the result of an invocation of the
1071 xmlrpc_client class.
1077 xmlrpcrespxmlrpcval$xmlrpcvalxmlrpcrespnew
1078 xmlrpcresp0int$errcodestring$err_stringThe first syntax is used when execution has happened without
1079 difficulty: $xmlrpcval is an
1080 xmlrpcval value with the result of the method
1081 execution contained in it. Alternatively it can be a string containing
1082 the xml serialization of the single xml-rpc value result of method
1085 The second type of constructor is used in case of failure.
1086 errcode and err_string
1087 are used to provide indication of what has gone wrong. See <<xmlrpc-server>> for more information on passing error
1096 intfaultCodeReturns the integer fault code return from the XML-RPC
1097 response. A zero value indicates success, any other value indicates
1103 stringfaultStringReturns the human readable explanation of the fault indicated
1104 by $resp->faultCode().
1109 xmlrpcvalvalueReturns an xmlrpcval object containing
1110 the return value sent by the server. If the response's
1111 faultCode is non-zero then the value returned
1112 by this method should not be used (it may not even be an
1115 Note: if the xmlrpcresp instance in question has been created
1116 by an xmlrpc_client object whose
1117 return_type was set to 'phpvals', then a plain
1118 php value will be returned instead of an
1119 xmlrpcval object. If the
1120 return_type was set to 'xml', an xml string will
1121 be returned (see the return_type member var above for more
1127 stringserializeReturns an XML string representation of the response (xml
1128 prologue not included).
1134 The implementation of this class has been kept as simple to use as
1135 possible. The constructor for the server basically does all the work.
1136 Here's a minimal example:
1142 function foo ($xmlrpcmsg) {
1144 return new xmlrpcresp($some_xmlrpc_val);
1148 function foobar($xmlrpcmsg) {
1150 return new xmlrpcresp($some_xmlrpc_val);
1154 $s = new xmlrpc_server(
1156 "examples.myFunc1" => array("function" => "foo"),
1157 "examples.myFunc2" => array("function" => "bar::foobar"),
1162 This performs everything you need to do with a server. The single
1163 constructor argument is an associative array from xmlrpc method names to
1164 php function names. The incoming request is parsed and dispatched to the
1165 relevant php function, which is responsible for returning a
1166 xmlrpcresp object, that will be serialized back
1170 ==== Method handler functions
1172 Both php functions and class methods can be registered as xmlrpc
1175 The synopsis of a method handler function is:
1177 xmlrpcresp $resp = function (xmlrpcmsg $msg)
1179 No text should be echoed 'to screen' by the handler function, or
1180 it will break the xml response sent back to the client. This applies
1181 also to error and warning messages that PHP prints to screen unless
1182 the appropriate parameters have been set in the php.in file. Another
1183 way to prevent echoing of errors inside the response and facilitate
1184 debugging is to use the server SetDebug method with debug level 3 (see
1185 ...). Exceptions thrown duting execution of handler functions are
1186 caught by default and a XML-RPC error reponse is generated instead.
1187 This behaviour can be finetuned by usage of the
1188 exception_handling member variable (see
1191 Note that if you implement a method with a name prefixed by
1192 ++system.++ the handler function will be invoked by the
1193 server with two parameters, the first being the server itself and the
1194 second being the xmlrpcmsg object.
1196 The same php function can be registered as handler of multiple
1199 Here is a more detailed example of what the handler function
1206 function foo ($xmlrpcmsg) {
1207 global $xmlrpcerruser; // import user errcode base value
1209 $meth = $xmlrpcmsg->method(); // retrieve method name
1210 $par = $xmlrpcmsg->getParam(0); // retrieve value of first parameter - assumes at least one param received
1211 $val = $par->scalarval(); // decode value of first parameter - assumes it is a scalar value
1216 // this is an error condition
1217 return new xmlrpcresp(0, $xmlrpcerruser+1, // user error 1
1218 "There's a problem, Captain");
1220 // this is a successful value being returned
1221 return new xmlrpcresp(new xmlrpcval("All's fine!", "string"));
1227 See __server.php__ in this distribution for
1228 more examples of how to do this.
1230 Since release 2.0RC3 there is a new, even simpler way of
1231 registering php functions with the server. See section 5.7
1235 ==== The dispatch map
1237 The first argument to the xmlrpc_server
1238 constructor is an array, called the __dispatch map__.
1239 In this array is the information the server needs to service the
1240 XML-RPC methods you define.
1242 The dispatch map takes the form of an associative array of
1243 associative arrays: the outer array has one entry for each method, the
1244 key being the method name. The corresponding value is another
1245 associative array, which can have the following members:
1248 * ++function++ - this
1249 entry is mandatory. It must be either a name of a function in the
1250 global scope which services the XML-RPC method, or an array
1251 containing an instance of an object and a static method name (for
1252 static class methods the 'class::method' syntax is also
1256 * ++signature++ - this
1257 entry is an array containing the possible signatures (see <<signatures>>) for the method. If this entry is present
1258 then the server will check that the correct number and type of
1259 parameters have been sent for this method before dispatching
1263 * ++docstring++ - this
1264 entry is a string containing documentation for the method. The
1265 documentation may contain HTML markup.
1268 * ++$$signature_docs$$++ - this entry can be used
1269 to provide documentation for the single parameters. It must match
1270 in structure the 'signature' member. By default, only the
1271 documenting_xmlrpc_server class in the
1272 extras package will take advantage of this, since the
1273 "system.methodHelp" protocol does not support documenting method
1274 parameters individually.
1277 * ++$$parameters_type$$++ - this entry can be used
1278 when the server is working in 'xmlrpcvals' mode (see ...) to
1279 define one or more entries in the dispatch map as being functions
1280 that follow the 'phpvals' calling convention. The only useful
1281 value is currently the string ++phpvals++.
1283 Look at the __server.php__ example in the
1284 distribution to see what a dispatch map looks like.
1288 ==== Method signatures
1290 A signature is a description of a method's return type and its
1291 parameter types. A method may have more than one signature.
1293 Within a server's dispatch map, each method has an array of
1294 possible signatures. Each signature is an array of types. The first
1295 entry is the return type. For instance, the method
1298 string examples.getStateName(int)
1305 array($xmlrpcString, $xmlrpcInt)
1309 and, assuming that it is the only possible signature for the
1310 method, it might be used like this in server creation:
1314 $findstate_sig = array(array($xmlrpcString, $xmlrpcInt));
1316 $findstate_doc = 'When passed an integer between 1 and 51 returns the
1317 name of a US state, where the integer is the index of that state name
1318 in an alphabetic order.';
1320 $s = new xmlrpc_server( array(
1321 "examples.getStateName" => array(
1322 "function" => "findstate",
1323 "signature" => $findstate_sig,
1324 "docstring" => $findstate_doc
1331 Note that method signatures do not allow to check nested
1332 parameters, e.g. the number, names and types of the members of a
1333 struct param cannot be validated.
1335 If a method that you want to expose has a definite number of
1336 parameters, but each of those parameters could reasonably be of
1337 multiple types, the array of acceptable signatures will easily grow
1338 into a combinatorial explosion. To avoid such a situation, the lib
1339 defines the global var $xmlrpcValue, which can be
1340 used in method signatures as a placeholder for 'any xmlrpc
1347 $echoback_sig = array(array($xmlrpcValue, $xmlrpcValue));
1349 $findstate_doc = 'Echoes back to the client the received value, regardless of its type';
1351 $s = new xmlrpc_server( array(
1352 "echoBack" => array(
1353 "function" => "echoback",
1354 "signature" => $echoback_sig, // this sig guarantees that the method handler will be called with one and only one parameter
1355 "docstring" => $echoback_doc
1360 Methods system.listMethods,
1362 system.methodSignature and
1363 system.multicall are already defined by the
1364 server, and should not be reimplemented (see Reserved Methods
1368 ==== Delaying the server response
1370 You may want to construct the server, but for some reason not
1371 fulfill the request immediately (security verification, for instance).
1372 If you omit to pass to the constructor the dispatch map or pass it a
1373 second argument of ++0++ this will have the desired
1374 effect. You can then use the service() method of
1375 the server class to service the request. For example:
1381 $s = new xmlrpc_server($myDispMap, 0); // second parameter = 0 prevents automatic servicing of request
1383 // ... some code that does other stuff here
1389 Note that the service method will print
1390 the complete result payload to screen and send appropriate HTTP
1391 headers back to the client, but also return the response object. This
1392 permits further manipulation of the response, possibly in combination
1393 with output buffering.
1395 To prevent the server from sending HTTP headers back to the
1396 client, you can pass a second parameter with a value of
1397 ++TRUE++ to the service
1398 method. In this case, the response payload will be returned instead of
1399 the response object.
1401 Xmlrpc requests retrieved by other means than HTTP POST bodies
1402 can also be processed. For example:
1408 $s = new xmlrpc_server(); // not passing a dispatch map prevents automatic servicing of request
1410 // ... some code that does other stuff here, including setting dispatch map into server object
1412 $resp = $s->service($xmlrpc_request_body, true); // parse a variable instead of POST body, retrieve response payload
1414 // ... some code that does other stuff with xml response $resp here
1419 ==== Modifying the server behaviour
1421 A couple of methods / class variables are available to modify
1422 the behaviour of the server. The only way to take advantage of their
1423 existence is by usage of a delayed server response (see above)
1428 This function controls weather the server is going to echo
1429 debugging messages back to the client as comments in response body.
1430 Valid values: 0,1,2,3, with 1 being the default. At level 0, no
1431 debug info is returned to the client. At level 2, the complete
1432 client request is added to the response, as part of the xml
1433 comments. At level 3, a new PHP error handler is set when executing
1434 user functions exposed as server methods, and all non-fatal errors
1435 are trapped and added as comments into the response.
1438 ===== allow_system_funcs
1440 Default_value: TRUE. When set to FALSE, disables support for
1441 System.xxx functions in the server. It
1442 might be useful e.g. if you do not wish the server to respond to
1443 requests to System.ListMethods.
1446 ===== compress_response
1448 When set to TRUE, enables the server to take advantage of HTTP
1449 compression, otherwise disables it. Responses will be transparently
1450 compressed, but only when an xmlrpc-client declares its support for
1451 compression in the HTTP headers of the request.
1453 Note that the ZLIB php extension must be installed for this to
1454 work. If it is, compress_response will default to
1458 ===== exception_handling
1460 This variable controls the behaviour of the server when an
1461 exception is thrown by a method handler php function. Valid values:
1462 0,1,2, with 0 being the default. At level 0, the server catches the
1463 exception and return an 'internal error' xmlrpc response; at 1 it
1464 catches the exceptions and return an xmlrpc response with the error
1465 code and error message corresponding to the exception that was
1466 thron; at 2 = the exception is floated to the upper layers in the
1470 ===== response_charset_encoding
1472 Charset encoding to be used for response (only affects string
1475 If it can, the server will convert the generated response from
1476 internal_encoding to the intended one.
1478 Valid values are: a supported xml encoding (only UTF-8 and
1479 ISO-8859-1 at present, unless mbstring is enabled), null (leave
1480 charset unspecified in response and convert output stream to
1481 US_ASCII), 'default' (use xmlrpc library default as specified in
1482 xmlrpc.inc, convert output stream if needed), or 'auto' (use
1483 client-specified charset encoding or same as request if request
1484 headers do not specify it (unless request is US-ASCII: then use
1485 library default anyway).
1488 ==== Fault reporting
1490 Fault codes for your servers should start at the value indicated
1491 by the global ++$xmlrpcerruser++ + 1.
1493 Standard errors returned by the server include:
1495 ++1++ Unknown method:: Returned if the server was asked to dispatch a method it
1498 ++2++ Invalid return payload:: This error is actually generated by the client, not
1499 server, code, but signifies that a server returned something it
1500 couldn't understand. A more detailed error report is sometimes
1501 added onto the end of the phrase above.
1503 ++3++ Incorrect parameters:: This error is generated when the server has signature(s)
1504 defined for a method, and the parameters passed by the client do
1505 not match any of signatures.
1507 ++4++ Can't introspect: method unknown:: This error is generated by the builtin
1508 system.* methods when any kind of
1509 introspection is attempted on a method undefined by the
1512 ++5++ Didn't receive 200 OK from remote server:: This error is generated by the client when a remote server
1513 doesn't return HTTP/1.1 200 OK in response to a request. A more
1514 detailed error report is added onto the end of the phrase
1517 ++6++ No data received from server:: This error is generated by the client when a remote server
1518 returns HTTP/1.1 200 OK in response to a request, but no
1519 response body follows the HTTP headers.
1521 ++7++ No SSL support compiled in:: This error is generated by the client when trying to send
1522 a request with HTTPS and the CURL extension is not available to
1525 ++8++ CURL error:: This error is generated by the client when trying to send
1526 a request with HTTPS and the HTTPS communication fails.
1528 ++9-14++ multicall errors:: These errors are generated by the server when something
1529 fails inside a system.multicall request.
1531 ++100-++ XML parse errors:: Returns 100 plus the XML parser error code for the fault
1532 that occurred. The faultString returned
1533 explains where the parse error was in the incoming XML
1537 ==== 'New style' servers
1539 In the same spirit of simplification that inspired the
1540 xmlrpc_client::return_type class variable, a new
1541 class variable has been added to the server class:
1542 functions_parameters_type. When set to 'phpvals',
1543 the functions registered in the server dispatch map will be called
1544 with plain php values as parameters, instead of a single xmlrpcmsg
1545 instance parameter. The return value of those functions is expected to
1546 be a plain php value, too. An example is worth a thousand
1551 function foo($usr_id, $out_lang='en') {
1552 global $xmlrpcerruser;
1556 if ($someErrorCondition)
1557 return new xmlrpcresp(0, $xmlrpcerruser+1, 'DOH!');
1562 'picture' => new xmlrpcval(file_get_contents($picOfTheGuy), 'base64')
1566 $s = new xmlrpc_server(
1568 "examples.myFunc" => array(
1569 "function" => "bar::foobar",
1570 "signature" => array(
1571 array($xmlrpcString, $xmlrpcInt),
1572 array($xmlrpcString, $xmlrpcInt, $xmlrpcString)
1576 $s->functions_parameters_type = 'phpvals';
1581 There are a few things to keep in mind when using this
1584 to return an xmlrpc error, the method handler function must
1585 return an instance of xmlrpcresp. The only
1586 other way for the server to know when an error response should be
1587 served to the client is to throw an exception and set the server's
1588 exception_handling memeber var to 1;
1590 to return a base64 value, the method handler function must
1591 encode it on its own, creating an instance of an xmlrpcval
1594 the method handler function cannot determine the name of the
1595 xmlrpc method it is serving, unlike standard handler functions that
1596 can retrieve it from the message object;
1598 when receiving nested parameters, the method handler function
1599 has no way to distinguish a php string that was sent as base64 value
1600 from one that was sent as a string value;
1602 this has a direct consequence on the support of
1603 system.multicall: a method whose signature contains datetime or base64
1604 values will not be available to multicall calls;
1606 last but not least, the direct parsing of xml to php values is
1607 much faster than using xmlrpcvals, and allows the library to handle
1608 much bigger messages without allocating all available server memory or
1609 smashing PHP recursive call stack.
1616 Many global variables are defined in the xmlrpc.inc file. Some of
1617 those are meant to be used as constants (and modifying their value might
1618 cause unpredictable behaviour), while some others can be modified in your
1619 php scripts to alter the behaviour of the xml-rpc client and
1623 === "Constant" variables
1628 $xmlrpcerruser800The minimum value for errors reported by user
1629 implemented XML-RPC servers. Error numbers lower than that are
1630 reserved for library usage.
1633 ==== $xmlrpcI4, $xmlrpcInt, $xmlrpcBoolean, $xmlrpcDouble, $xmlrpcString, $xmlrpcDateTime, $xmlrpcBase64, $xmlrpcArray, $xmlrpcStruct, $xmlrpcValue, $xmlrpcNull
1635 For convenience the strings representing the XML-RPC types have
1636 been encoded as global variables:
1642 $xmlrpcBoolean="boolean";
1643 $xmlrpcDouble="double";
1644 $xmlrpcString="string";
1645 $xmlrpcDateTime="dateTime.iso8601";
1646 $xmlrpcBase64="base64";
1647 $xmlrpcArray="array";
1648 $xmlrpcStruct="struct";
1649 $xmlrpcValue="undefined";
1654 ==== $xmlrpcTypes, $xmlrpc_valid_parents, $xmlrpcerr, $xmlrpcstr, $xmlrpcerrxml, $xmlrpc_backslash, $_xh, $xml_iso88591_Entities, $xmlEntities, $xmlrpcs_capabilities
1656 Reserved for internal usage.
1659 === Variables whose value can be modified
1661 [[xmlrpc-defencoding]]
1663 ==== xmlrpc_defencoding
1665 $xmlrpc_defencoding"UTF8"This variable defines the character set encoding that will be
1666 used by the xml-rpc client and server to decode the received messages,
1667 when a specific charset declaration is not found (in the messages sent
1668 non-ascii chars are always encoded using character references, so that
1669 the produced xml is valid regardless of the charset encoding
1672 Allowed values: ++"UTF8"++,
1673 ++"ISO-8859-1"++, ++"ASCII".++
1675 Note that the appropriate RFC actually mandates that XML
1676 received over HTTP without indication of charset encoding be treated
1677 as US-ASCII, but many servers and clients 'in the wild' violate the
1678 standard, and assume the default encoding is UTF-8.
1681 ==== xmlrpc_internalencoding
1683 $xmlrpc_internalencoding"ISO-8859-1"This variable defines the character set encoding
1684 that the library uses to transparently encode into valid XML the
1685 xml-rpc values created by the user and to re-encode the received
1686 xml-rpc values when it passes them to the PHP application. It only
1687 affects xml-rpc values of string type. It is a separate value from
1688 xmlrpc_defencoding, allowing e.g. to send/receive xml messages encoded
1689 on-the-wire in US-ASCII and process them as UTF-8. It defaults to the
1690 character set used internally by PHP (unless you are running an
1691 MBString-enabled installation), so you should change it only in
1692 special situations, if e.g. the string values exchanged in the xml-rpc
1693 messages are directly inserted into / fetched from a database
1694 configured to return UTF8 encoded strings to PHP. Example
1702 include('xmlrpc.inc');
1703 $xmlrpc_internalencoding = 'UTF-8'; // this has to be set after the inclusion above
1704 $v = new xmlrpcval('κόÏ
\83με'); // This xmlrpc value will be correctly serialized as the greek word 'kosme'
1710 $xmlrpcName"XML-RPC for PHP"The string representation of the name of the XML-RPC
1711 for PHP library. It is used by the client for building the User-Agent
1712 HTTP header that is sent with every request to the server. You can
1713 change its value if you need to customize the User-Agent
1719 $xmlrpcVersion"2.2"The string representation of the version number of
1720 the XML-RPC for PHP library in use. It is used by the client for
1721 building the User-Agent HTTP header that is sent with every request to
1722 the server. You can change its value if you need to customize the
1726 ==== xmlrpc_null_extension
1728 When set to TRUE, the lib will enable
1729 support for the <NIL/> (and <EX:NIL/>) xmlrpc value, as
1730 per the extension to the standard proposed here. This means that
1731 <NIL/> and <EX:NIL/> tags received will be parsed as valid
1732 xmlrpc, and the corresponding xmlrpcvals will return "null" for
1736 ==== xmlrpc_null_apache_encoding
1738 When set to ++TRUE++, php NULL values encoded
1739 into xmlrpcval objects get serialized using the
1740 ++<EX:NIL/>++ tag instead of
1741 ++<NIL/>++. Please note that both forms are
1742 always accepted as input regardless of the value of this
1750 XML-RPC for PHP contains some helper functions which you can use to
1751 make processing of XML-RPC requests easier.
1756 The XML-RPC specification has this to say on dates:
1760 [[wrap_xmlrpc_method]]
1761 Don't assume a timezone. It should be
1762 specified by the server in its documentation what assumptions it makes
1767 Unfortunately, this means that date processing isn't
1768 straightforward. Although XML-RPC uses ISO 8601 format dates, it doesn't
1769 use the timezone specifier.
1771 We strongly recommend that in every case where you pass dates in
1772 XML-RPC calls, you use UTC (GMT) as your timezone. Most computer
1773 languages include routines for handling GMT times natively, and you
1774 won't have to translate between timezones.
1776 For more information about dates, see link:$$http://www.uic.edu/year2000/datefmt.html$$[ISO 8601: The Right Format for Dates], which has a handy link to a PDF of the ISO
1777 8601 specification. Note that XML-RPC uses exactly one of the available
1778 representations: CCYYMMDDTHH:MM:SS.
1784 stringiso8601_encodestring$time_tint$utc0Returns an ISO 8601 formatted date generated from the UNIX
1785 timestamp $time_t, as returned by the PHP
1788 The argument $utc can be omitted, in
1789 which case it defaults to ++0++. If it is set to
1790 ++1++, then the function corrects the time passed in
1791 for UTC. Example: if you're in the GMT-6:00 timezone and set
1792 $utc, you will receive a date representation
1793 six hours ahead of your local time.
1795 The included demo program __vardemo.php__
1796 includes a demonstration of this function.
1802 intiso8601_decodestring$isoStringint$utc0Returns a UNIX timestamp from an ISO 8601 encoded time and date
1803 string passed in. If $utc is
1804 ++1++ then $isoString is assumed
1805 to be in the UTC timezone, and thus the result is also UTC: otherwise,
1806 the timezone is assumed to be your local timezone and you receive a
1811 === Easy use with nested PHP values
1813 Dan Libby was kind enough to contribute two helper functions that
1814 make it easier to translate to and from PHP values. This makes it easier
1815 to deal with complex structures. At the moment support is limited to
1816 int, double, string,
1817 array, datetime and struct
1818 datatypes; note also that all PHP arrays are encoded as structs, except
1819 arrays whose keys are integer numbers starting with 0 and incremented by
1822 These functions reside in __xmlrpc.inc__.
1826 ==== php_xmlrpc_decode
1828 mixedphp_xmlrpc_decodexmlrpcval$xmlrpc_valarray$optionsarrayphp_xmlrpc_decodexmlrpcmsg$xmlrpcmsg_valstring$optionsReturns a native PHP value corresponding to the values found in
1829 the xmlrpcval $xmlrpc_val,
1830 translated into PHP types. Base-64 and datetime values are
1831 automatically decoded to strings.
1833 In the second form, returns an array containing the parameters
1835 xmlrpcmsg_val, decoded
1838 The options parameter is optional. If
1839 specified, it must consist of an array of options to be enabled in the
1840 decoding process. At the moment the only valid option are
1842 ++$$dates_as_objects$$++. When the first is set, php
1843 objects that have been converted to xml-rpc structs using the
1844 php_xmlrpc_encode function and a corresponding
1845 encoding option will be converted back into object values instead of
1846 arrays (provided that the class definition is available at
1847 reconstruction time). When the second is set, XML-RPC datetime values
1848 will be converted into native dateTime objects
1851 ____WARNING__:__ please take
1852 extreme care before enabling the decode_php_objs
1853 option: when php objects are rebuilt from the received xml, their
1854 constructor function will be silently invoked. This means that you are
1855 allowing the remote end to trigger execution of uncontrolled PHP code
1856 on your server, opening the door to code injection exploits. Only
1857 enable this option when you have complete trust of the remote
1864 // wrapper to expose an existing php function as xmlrpc method handler
1865 function foo_wrapper($m)
1867 $params = php_xmlrpc_decode($m);
1868 $retval = call_user_func_array('foo', $params);
1869 return new xmlrpcresp(new xmlrpcval($retval)); // foo return value will be serialized as string
1872 $s = new xmlrpc_server(array(
1873 "examples.myFunc1" => array(
1874 "function" => "foo_wrapper",
1882 ==== php_xmlrpc_encode
1884 xmlrpcvalphp_xmlrpc_encodemixed$phpvalarray$optionsReturns an xmlrpcval object populated with the PHP
1885 values in $phpval. Works recursively on arrays
1886 and objects, encoding numerically indexed php arrays into array-type
1887 xmlrpcval objects and non numerically indexed php arrays into
1888 struct-type xmlrpcval objects. Php objects are encoded into
1889 struct-type xmlrpcvals, excepted for php values that are already
1890 instances of the xmlrpcval class or descendants thereof, which will
1891 not be further encoded. Note that there's no support for encoding php
1892 values into base-64 values. Encoding of date-times is optionally
1893 carried on on php strings with the correct format.
1895 The options parameter is optional. If
1896 specified, it must consist of an array of options to be enabled in the
1897 encoding process. At the moment the only valid options are
1898 encode_php_objs, ++$$null_extension$$++
1901 The first will enable the creation of 'particular' xmlrpcval
1902 objects out of php objects, that add a "php_class" xml attribute to
1903 their serialized representation. This attribute allows the function
1904 php_xmlrpc_decode to rebuild the native php objects (provided that the
1905 same class definition exists on both sides of the communication). The
1906 second allows to encode php ++NULL++ values to the
1907 ++<NIL/>++ (or
1908 ++<EX:NIL/>++, see ...) tag. The last encodes any
1909 string that matches the ISO8601 format into an XML-RPC
1916 // the easy way to build a complex xml-rpc struct, showing nested base64 value and datetime values
1917 $val = php_xmlrpc_encode(array(
1918 'first struct_element: an int' => 666,
1919 'second: an array' => array ('apple', 'orange', 'banana'),
1920 'third: a base64 element' => new xmlrpcval('hello world', 'base64'),
1921 'fourth: a datetime' => '20060107T01:53:00'
1922 ), array('auto_dates'));
1926 ==== php_xmlrpc_decode_xml
1928 xmlrpcval | xmlrpcresp |
1929 xmlrpcmsgphp_xmlrpc_decode_xmlstring$xmlarray$optionsDecodes the xml representation of either an xmlrpc request,
1930 response or single value, returning the corresponding php-xmlrpc
1931 object, or ++FALSE++ in case of an error.
1933 The options parameter is optional. If
1934 specified, it must consist of an array of options to be enabled in the
1935 decoding process. At the moment, no option is supported.
1941 $text = '<value><array><data><value>Hello world</value></data></array></value>';
1942 $val = php_xmlrpc_decode_xml($text);
1943 if ($val) echo 'Found a value of type '.$val->kindOf(); else echo 'Found invalid xml';
1947 === Automatic conversion of php functions into xmlrpc methods (and vice versa)
1949 For the extremely lazy coder, helper functions have been added
1950 that allow to convert a php function into an xmlrpc method, and a
1951 remotely exposed xmlrpc method into a local php function - or a set of
1952 methods into a php class. Note that these comes with many caveat.
1955 ==== wrap_xmlrpc_method
1957 stringwrap_xmlrpc_method$client$methodname$extra_optionsstringwrap_xmlrpc_method$client$methodname$signum$timeout$protocol$funcnameGiven an xmlrpc server and a method name, creates a php wrapper
1958 function that will call the remote method and return results using
1959 native php types for both params and results. The generated php
1960 function will return an xmlrpcresp object for failed xmlrpc
1963 The second syntax is deprecated, and is listed here only for
1964 backward compatibility.
1966 The server must support the
1967 system.methodSignature xmlrpc method call for
1968 this function to work.
1970 The client param must be a valid
1971 xmlrpc_client object, previously created with the address of the
1972 target xmlrpc server, and to which the preferred communication options
1975 The optional parameters can be passed as array key,value pairs
1976 in the extra_options param.
1978 The signum optional param has the purpose
1979 of indicating which method signature to use, if the given server
1980 method has multiple signatures (defaults to 0).
1983 protocol optional params are the same as in the
1984 xmlrpc_client::send() method.
1986 If set, the optional new_function_name
1987 parameter indicates which name should be used for the generated
1988 function. In case it is not set the function name will be
1991 If the ++$$return_source$$++ optional parameter is
1992 set, the function will return the php source code to build the wrapper
1993 function, instead of evaluating it (useful to save the code and use it
1994 later as stand-alone xmlrpc client).
1996 If the ++$$encode_php_objs$$++ optional parameter is
1997 set, instances of php objects later passed as parameters to the newly
1998 created function will receive a 'special' treatment that allows the
1999 server to rebuild them as php objects instead of simple arrays. Note
2000 that this entails using a "slightly augmented" version of the xmlrpc
2001 protocol (ie. using element attributes), which might not be understood
2002 by xmlrpc servers implemented using other libraries.
2004 If the ++$$decode_php_objs$$++ optional parameter is
2005 set, instances of php objects that have been appropriately encoded by
2006 the server using a coordinate option will be deserialized as php
2007 objects instead of simple arrays (the same class definition should be
2008 present server side and client side).
2010 __Note that this might pose a security risk__,
2011 since in order to rebuild the object instances their constructor
2012 method has to be invoked, and this means that the remote server can
2013 trigger execution of unforeseen php code on the client: not really a
2014 code injection, but almost. Please enable this option only when you
2015 trust the remote server.
2017 In case of an error during generation of the wrapper function,
2018 FALSE is returned, otherwise the name (or source code) of the new
2021 Known limitations: server must support
2022 system.methodsignature for the wanted xmlrpc
2023 method; for methods that expose multiple signatures, only one can be
2024 picked; for remote calls with nested xmlrpc params, the caller of the
2025 generated php function has to encode on its own the params passed to
2026 the php function if these are structs or arrays whose (sub)members
2027 include values of type base64.
2029 Note: calling the generated php function 'might' be slow: a new
2030 xmlrpc client is created on every invocation and an xmlrpc-connection
2031 opened+closed. An extra 'debug' param is appended to the parameter
2032 list of the generated php function, useful for debugging
2041 $c = new xmlrpc_client('http://phpxmlrpc.sourceforge.net/server.php');
2043 $function = wrap_xmlrpc_method($client, 'examples.getStateName');
2046 die('Cannot introspect remote method');
2049 $statename = $function($a);
2050 if (is_a($statename, 'xmlrpcresp')) // call failed
2052 echo 'Call failed: '.$statename->faultCode().'. Calling again with debug on';
2053 $function($a, true);
2056 echo "OK, state nr. $stateno is $statename";
2061 [[wrap_php_function]]
2063 ==== wrap_php_function
2065 arraywrap_php_functionstring$funcnamestring$wrapper_function_namearray$extra_optionsGiven a user-defined PHP function, create a PHP 'wrapper'
2066 function that can be exposed as xmlrpc method from an xmlrpc_server
2067 object and called from remote clients, and return the appropriate
2068 definition to be added to a server's dispatch map.
2070 The optional $wrapper_function_name
2071 specifies the name that will be used for the auto-generated
2074 Since php is a typeless language, to infer types of input and
2075 output parameters, it relies on parsing the javadoc-style comment
2076 block associated with the given function. Usage of xmlrpc native types
2077 (such as datetime.dateTime.iso8601 and base64) in the docblock @param
2078 tag is also allowed, if you need the php function to receive/send data
2079 in that particular format (note that base64 encoding/decoding is
2080 transparently carried out by the lib, while datetime vals are passed
2083 Known limitations: only works for
2084 user-defined functions, not for PHP internal functions (reflection
2085 does not support retrieving number/type of params for those); the
2086 wrapped php function will not be able to programmatically return an
2087 xmlrpc error response.
2089 If the ++$$return_source$$++ optional parameter is
2090 set, the function will return the php source code to build the wrapper
2091 function, instead of evaluating it (useful to save the code and use it
2092 later in a stand-alone xmlrpc server). It will be in the stored in the
2093 ++source++ member of the returned array.
2095 If the ++$$suppress_warnings$$++ optional parameter
2096 is set, any runtime warning generated while processing the
2097 user-defined php function will be catched and not be printed in the
2098 generated xml response.
2100 If the extra_options array contains the
2101 ++$$encode_php_objs$$++ value, wrapped functions returning
2102 php objects will generate "special" xmlrpc responses: when the xmlrpc
2103 decoding of those responses is carried out by this same lib, using the
2104 appropriate param in php_xmlrpc_decode(), the objects will be
2107 In short: php objects can be serialized, too (except for their
2108 resource members), using this function. Other libs might choke on the
2109 very same xml that will be generated in this case (i.e. it has a
2110 nonstandard attribute on struct element tags)
2112 If the ++$$decode_php_objs$$++ optional parameter is
2113 set, instances of php objects that have been appropriately encoded by
2114 the client using a coordinate option will be deserialized and passed
2115 to the user function as php objects instead of simple arrays (the same
2116 class definition should be present server side and client
2119 __Note that this might pose a security risk__,
2120 since in order to rebuild the object instances their constructor
2121 method has to be invoked, and this means that the remote client can
2122 trigger execution of unforeseen php code on the server: not really a
2123 code injection, but almost. Please enable this option only when you
2124 trust the remote clients.
2132 * State name from state number decoder. NB: do NOT remove this comment block.
2133 * @param integer $stateno the state number
2134 * @return string the name of the state (or error description)
2136 function findstate($stateno)
2139 if (isset($stateNames[$stateno-1]))
2141 return $stateNames[$stateno-1];
2145 return "I don't have a state for the index '" . $stateno . "'";
2149 // wrap php function, build xmlrpc server
2151 $findstate_sig = wrap_php_function('findstate');
2153 $methods['examples.getStateName'] = $findstate_sig;
2154 $srv = new xmlrpc_server($methods);
2160 === Functions removed from the library
2162 The following two functions have been deprecated in version 1.1 of
2163 the library, and removed in version 2, in order to avoid conflicts with
2164 the EPI xml-rpc library, which also defines two functions with the same
2167 To ease the transition to the new naming scheme and avoid breaking
2168 existing implementations, the following scheme has been adopted:
2170 * If EPI-XMLRPC is not active in the current PHP installation,
2171 the constant ++$$XMLRPC_EPI_ENABLED$$++ will be set to
2175 * If EPI-XMLRPC is active in the current PHP installation, the
2176 constant ++$$XMLRPC_EPI_ENABLED$$++ will be set to
2181 The following documentation is kept for historical
2188 mixedx mlrpc_decode xmlrpcval $xmlrpc_val Alias for php_xmlrpc_decode.
2194 xmlrpcval xmlrpc_encode mixed $phpvalAlias for php_xmlrpc_encode.
2200 ==== xmlrpc_debugmsg
2202 void xmlrpc_debugmsgstring$debugstringSends the contents of $debugstring in XML
2203 comments in the server return payload. If a PHP client has debugging
2204 turned on, the user will be able to see server debug
2207 Use this function in your methods so you can pass back
2208 diagnostic information. It is only available from
2216 In order to extend the functionality offered by XML-RPC servers
2217 without impacting on the protocol, reserved methods are supported in this
2220 All methods starting with system. are
2221 considered reserved by the server. PHP for XML-RPC itself provides four
2222 special methods, detailed in this chapter.
2224 Note that all server objects will automatically respond to clients
2225 querying these methods, unless the property
2226 allow_system_funcs has been set to
2227 false before calling the
2228 service() method. This might pose a security risk
2229 if the server is exposed to public access, e.g. on the internet.
2232 === system.getCapabilities
2235 === system.listMethods
2237 This method may be used to enumerate the methods implemented by
2240 The system.listMethods method requires no
2241 parameters. It returns an array of strings, each of which is the name of
2242 a method implemented by the server.
2246 === system.methodSignature
2248 This method takes one parameter, the name of a method implemented
2249 by the XML-RPC server.
2251 It returns an array of possible signatures for this method. A
2252 signature is an array of types. The first of these types is the return
2253 type of the method, the rest are parameters.
2255 Multiple signatures (i.e. overloading) are permitted: this is the
2256 reason that an array of signatures are returned by this method.
2258 Signatures themselves are restricted to the top level parameters
2259 expected by a method. For instance if a method expects one array of
2260 structs as a parameter, and it returns a string, its signature is simply
2261 "string, array". If it expects three integers, its signature is "string,
2264 For parameters that can be of more than one type, the "undefined"
2265 string is supported.
2267 If no signature is defined for the method, a not-array value is
2268 returned. Therefore this is the way to test for a non-signature, if
2269 $resp below is the response object from a method
2270 call to system.methodSignature:
2275 $v = $resp->value();
2276 if ($v->kindOf() != "array") {
2277 // then the method did not have a signature defined
2282 See the __introspect.php__ demo included in this
2283 distribution for an example of using this method.
2287 === system.methodHelp
2289 This method takes one parameter, the name of a method implemented
2290 by the XML-RPC server.
2292 It returns a documentation string describing the use of that
2293 method. If no such string is available, an empty string is
2296 The documentation string may contain HTML markup.
2298 === system.multicall
2300 This method takes one parameter, an array of 'request' struct
2301 types. Each request struct must contain a
2302 methodName member of type string and a
2303 params member of type array, and corresponds to
2304 the invocation of the corresponding method.
2306 It returns a response of type array, with each value of the array
2307 being either an error struct (containing the faultCode and faultString
2308 members) or the successful response value of the corresponding single
2316 The best examples are to be found in the sample files included with
2317 the distribution. Some are included here.
2321 === XML-RPC client: state name query
2323 Code to get the corresponding state name from a number (1-50) from
2324 the demo server available on SourceForge
2329 $m = new xmlrpcmsg('examples.getStateName',
2330 array(new xmlrpcval($HTTP_POST_VARS["stateno"], "int")));
2331 $c = new xmlrpc_client("/server.php", "phpxmlrpc.sourceforge.net", 80);
2333 if (!$r->faultCode()) {
2335 print "State number " . htmlentities($HTTP_POST_VARS["stateno"]) . " is " .
2336 htmlentities($v->scalarval()) . "<BR>";
2337 print "<HR>I got this value back<BR><PRE>" .
2338 htmlentities($r->serialize()) . "</PRE><HR>\n";
2341 print "Code: " . htmlentities($r->faultCode()) . "<BR>" .
2342 "Reason: '" . htmlentities($r->faultString()) . "'<BR>";
2347 === Executing a multicall call
2355 == Frequently Asked Questions
2359 ==== How to send custom XML as payload of a method call::
2361 Unfortunately, at the time the XML-RPC spec was designed, support
2362 for namespaces in XML was not as ubiquitous as it is now. As a
2363 consequence, no support was provided in the protocol for embedding XML
2364 elements from other namespaces into an xmlrpc request.
2366 To send an XML "chunk" as payload of a method call or response,
2367 two options are available: either send the complete XML block as a
2368 string xmlrpc value, or as a base64 value. Since the '<' character in
2369 string values is encoded as '&lt;' in the xml payload of the method
2370 call, the XML string will not break the surrounding xmlrpc, unless
2371 characters outside of the assumed character set are used. The second
2372 method has the added benefits of working independently of the charset
2373 encoding used for the xml to be transmitted, and preserving exactly
2374 whitespace, whilst incurring in some extra message length and cpu load
2375 (for carrying out the base64 encoding/decoding).
2378 ==== Is there any limitation on the size of the requests / responses that can be successfully sent?::
2380 Yes. But I have no hard figure to give; it most likely will depend
2381 on the version of PHP in usage and its configuration.
2383 Keep in mind that this library is not optimized for speed nor for
2384 memory usage. Better alternatives exist when there are strict
2385 requirements on throughput or resource usage, such as the php native
2386 xmlrpc extension (see the PHP manual for more information).
2388 Keep in mind also that HTTP is probably not the best choice in
2389 such a situation, and XML is a deadly enemy. CSV formatted data over
2390 socket would be much more efficient.
2392 If you really need to move a massive amount of data around, and
2393 you are crazy enough to do it using phpxmlrpc, your best bet is to
2394 bypass usage of the xmlrpcval objects, at least in the decoding phase,
2395 and have the server (or client) object return to the calling function
2396 directly php values (see xmlrpc_client::return_type
2397 and xmlrpc_server::functions_parameters_type for more
2401 ==== My server (client) returns an error whenever the client (server) returns accented characters
2406 ==== How to enable long-lasting method calls
2411 ==== My client returns "XML-RPC Fault #2: Invalid return payload: enable debugging to examine incoming payload": what should I do?
2413 The response you are seeing is a default error response that the
2414 client object returns to the php application when the server did not
2415 respond to the call with a valid xmlrpc response.
2417 The most likely cause is that you are not using the correct URL
2418 when creating the client object, or you do not have appropriate access
2419 rights to the web page you are requesting, or some other common http
2422 To find out what the server is really returning to your client,
2423 you have to enable the debug mode of the client, using
2424 $client->setdebug(1);
2427 ==== How can I save to a file the xml of the xmlrpc responses received from servers?
2429 If what you need is to save the responses received from the server
2430 as xml, you have two options:
2432 1- use the serialize() method on the response object.
2438 $resp = $client->send($msg);
2439 if (!$resp->faultCode())
2440 $data_to_be_saved = $resp->serialize();
2444 Note that this will not be 100% accurate, since the xml generated
2445 by the response object can be different from the xml received,
2446 especially if there is some character set conversion involved, or such
2447 (eg. if you receive an empty string tag as <string/>, serialize()
2448 will output <string></string>), or if the server sent back
2449 as response something invalid (in which case the xml generated client
2450 side using serialize() will correspond to the error response generated
2451 internally by the lib).
2453 2 - set the client object to return the raw xml received instead
2454 of the decoded objects:
2460 $client = new xmlrpc_client($url);
2461 $client->return_type = 'xml';
2462 $resp = $client->send($msg);
2463 if (!$resp->faultCode())
2464 $data_to_be_saved = $resp->value();
2468 Note that using this method the xml response response will not be
2469 parsed at all by the library, only the http communication protocol will
2470 be checked. This means that xmlrpc responses sent by the server that
2471 would have generated an error response on the client (eg. malformed xml,
2472 responses that have faultcode set, etc...) now will not be flagged as
2473 invalid, and you might end up saving not valid xml but random
2477 ==== Can I use the ms windows character set?
2479 If the data your application is using comes from a Microsoft
2480 application, there are some chances that the character set used to
2481 encode it is CP1252 (the same might apply to data received from an
2482 external xmlrpc server/client, but it is quite rare to find xmlrpc
2483 toolkits that encode to CP1252 instead of UTF8). It is a character set
2484 which is "almost" compatible with ISO 8859-1, but for a few extra
2487 PHP-XMLRPC only supports the ISO 8859-1 and UTF8 character sets.
2488 The net result of this situation is that those extra characters will not
2489 be properly encoded, and will be received at the other end of the
2490 XML-RPC transmission as "garbled data". Unfortunately the library cannot
2491 provide real support for CP1252 because of limitations in the PHP 4 xml
2492 parser. Luckily, we tried our best to support this character set anyway,
2493 and, since version 2.2.1, there is some form of support, left commented
2496 To properly encode outgoing data that is natively in CP1252, you
2497 will have to uncomment all relative code in the file
2498 __xmlrpc.inc__ (you can search for the string "1252"),
2499 then set ++$$$GLOBALS['xmlrpc_internalencoding']='CP1252';$$++
2500 Please note that all incoming data will then be fed to your application
2501 as UTF-8 to avoid any potential data loss.
2504 ==== Does the library support using cookies / http sessions?
2506 In short: yes, but a little coding is needed to make it
2509 The code below uses sessions to e.g. let the client store a value
2510 on the server and retrieve it later.
2515 $resp = $client->send(new xmlrpcmsg('registervalue', array(new xmlrpcval('foo'), new xmlrpcval('bar'))));
2516 if (!$resp->faultCode())
2518 $cookies = $resp->cookies();
2519 if (array_key_exists('PHPSESSID', $cookies)) // nb: make sure to use the correct session cookie name
2521 $session_id = $cookies['PHPSESSID']['value'];
2523 // do some other stuff here...
2525 $client->setcookie('PHPSESSID', $session_id);
2526 $val = $client->send(new xmlrpcmsg('getvalue', array(new xmlrpcval('foo')));
2532 Server-side sessions are handled normally like in any other
2533 php application. Please see the php manual for more information about
2536 NB: unlike web browsers, not all xmlrpc clients support usage of
2537 http cookies. If you have troubles with sessions and control only the
2538 server side of the communication, please check with the makers of the
2539 xmlrpc client in use.
2545 == Integration with the PHP xmlrpc extension
2547 To be documented more...
2549 In short: for the fastest execution possible, you can enable the php
2550 native xmlrpc extension, and use it in conjunction with phpxmlrpc. The
2551 following code snippet gives an example of such integration
2557 /*** client side ***/
2558 $c = new xmlrpc_client('http://phpxmlrpc.sourceforge.net/server.php');
2560 // tell the client to return raw xml as response value
2561 $c->return_type = 'xml';
2563 // let the native xmlrpc extension take care of encoding request parameters
2564 $r = $c->send(xmlrpc_encode_request('examples.getStateName', $_POST['stateno']));
2566 if ($r->faultCode())
2567 // HTTP transport error
2568 echo 'Got error '.$r->faultCode();
2571 // HTTP request OK, but XML returned from server not parsed yet
2572 $v = xmlrpc_decode($r->value());
2573 // check if we got a valid xmlrpc response from server
2575 echo 'Got invalid response';
2577 // check if server sent a fault response
2578 if (xmlrpc_is_fault($v))
2579 echo 'Got xmlrpc fault '.$v['faultCode'];
2581 echo'Got response: '.htmlentities($v);
2590 == Substitution of the PHP xmlrpc extension
2592 Yet another interesting situation is when you are using a ready-made
2593 php application, that provides support for the XMLRPC protocol via the
2594 native php xmlrpc extension, but the extension is not available on your
2595 php install (e.g. because of shared hosting constraints).
2597 Since version 2.1, the PHP-XMLRPC library provides a compatibility
2598 layer that aims to be 100% compliant with the xmlrpc extension API. This
2599 means that any code written to run on the extension should obtain the
2600 exact same results, albeit using more resources and a longer processing
2601 time, using the PHP-XMLRPC library and the extension compatibility module.
2602 The module is part of the EXTRAS package, available as a separate download
2603 from the sourceforge.net website, since version 0.2
2609 == 'Enough of xmlrpcvals!': new style library usage
2613 In the meantime, see docs about xmlrpc_client::return_type and
2614 xmlrpc_server::functions_parameters_types, as well as php_xmlrpc_encode,
2615 php_xmlrpc_decode and php_xmlrpc_decode_xml
2621 == Usage of the debugger
2623 A webservice debugger is included in the library to help during
2624 development and testing.
2626 The interface should be self-explicative enough to need little
2629 image::debugger.gif[,,,,align="center"]
2631 The most useful feature of the debugger is without doubt the "Show
2632 debug info" option. It allows to have a screen dump of the complete http
2633 communication between client and server, including the http headers as
2634 well as the request and response payloads, and is invaluable when
2635 troubleshooting problems with charset encoding, authentication or http
2638 The debugger can take advantage of the JSONRPC library extension, to
2639 allow debugging of JSON-RPC webservices, and of the JS-XMLRPC library
2640 visual editor to allow easy mouse-driven construction of the payload for
2641 remote methods. Both components have to be downloaded separately from the
2642 sourceforge.net web pages and copied to the debugger directory to enable
2643 the extra functionality:
2646 * to enable jsonrpc functionality, download the PHP-XMLRPC
2647 EXTRAS package, and copy the file __jsonrpc.inc__
2648 either to the same directory as the debugger or somewhere in your
2652 * to enable the visual value editing dialog, download the
2653 JS-XMLRPC library, and copy somewhere in the web root files
2654 __visualeditor.php__,
2655 __visualeditor.css__ and the folders
2656 __yui__ and __img__. Then edit the
2657 debugger file __controller.php__ and set
2658 appropriately the variable $editorpath.
2666 __Note:__ not all items the following list have
2667 (yet) been fully documented, and some might not be present in any other
2668 chapter in the manual. To find a more detailed description of new
2669 functions and methods please take a look at the source code of the
2670 library, which is quite thoroughly commented in phpdoc form.
2674 ...to be documented...
2678 __Note:__ this is the last release of the library that will support PHP 5.1 and up.
2679 Future releases will target php 5.3 as minimum supported version.
2681 * when using curl and keepalive, reset curl handle if we did not get back an http 200 response (eg a 302)
2683 * omit port on http 'Host' header if it is 80
2685 * test suite allows interrogating https servers ignoring their certs
2687 * method setAcceptedCompression was failing to disable reception of compressed responses if the
2688 client supported them
2692 This is the first release of the library to only support PHP 5.
2693 Some legacy code has been removed, and support for features such as
2694 exceptions and dateTime objects introduced.
2696 The "beta" tag is meant to indicate the fact that the refactoring
2697 has been more widespread than in precedent releases and that more
2698 changes are likely to be introduced with time - the library is still
2699 considered to be production quality.
2701 * improved: removed all usage of php functions deprecated in
2702 php 5.3, usage of assign-by-ref when creating new objects
2705 * improved: add support for the <ex:nil/> tag used by
2706 the apache library, both in input and output
2708 * improved: add support for dateTime
2709 objects in both in php_xmlrpc_encode and as
2710 parameter for constructor of
2713 * improved: add support for timestamps as parameter for
2714 constructor of xmlrpcval
2716 * improved: add option 'dates_as_objects' to
2717 php_xmlrpc_decode to return
2718 dateTime objects for xmlrpc
2721 * improved: add new method
2723 xmrlpc_client to allow extra flexibility in
2724 tweaking http config, such as explicitly binding to an ip
2727 * improved: add new method
2729 xmrlpc_client to to allow having different
2730 user-agent http headers
2732 * improved: add a new member variable in server class to allow
2733 fine-tuning of the encoding of returned values when the server is
2736 * improved: allow servers in 'xmlrpcvals' mode to also
2737 register plain php functions by defining them in the dispatch map
2738 with an added option
2740 * improved: catch exceptions thrown during execution of php
2741 functions exposed as methods by the server
2743 * fixed: bad encoding if same object is encoded twice using
2748 __Note:__ this is the last release of the
2749 library that will support PHP 4. Future releases (if any) should target
2750 php 5.0 as minimum supported version.
2752 * fixed: encoding of utf-8 characters outside of the BMP
2755 * fixed: character set declarations surrounded by double
2756 quotes were not recognized in http headers
2758 * fixed: be more tolerant in detection of charset in http
2761 * fixed: fix detection of zlib.output_compression
2763 * fixed: use feof() to test if socket connections are to be
2764 closed instead of the number of bytes read (rare bug when
2765 communicating with some servers)
2767 * fixed: format floating point values using the correct
2768 decimal separator even when php locale is set to one that uses
2771 * fixed: improve robustness of the debugger when parsing weird
2772 results from non-compliant servers
2774 * php warning when receiving 'false' in a bool value
2776 * improved: allow the add_to_map server method to add docs for
2779 * improved: added the possibility to wrap for exposure as
2780 xmlrpc methods plain php class methods, object methods and even
2785 * fixed: work aroung bug in php 5.2.2 which broke support of
2788 * fixed: is_dir parameter of setCaCertificate() method is
2791 * fixed: a php warning in xmlrpc_client creator method
2793 * fixed: parsing of '1e+1' as valid float
2795 * fixed: allow errorlevel 3 to work when prev. error handler was
2798 * fixed: usage of client::setcookie() for multiple cookies in
2801 * improved: support for CP1252 charset is not part or the
2802 library but almost possible
2804 * improved: more info when curl is enabled and debug mode is
2808 * fixed: debugger errors on php installs with magic_quotes_gpc
2811 * fixed: support for https connections via proxy
2813 * fixed: wrap_xmlrpc_method() generated code failed to properly
2816 * improved: slightly faster encoding of data which is internally
2819 * improved: debugger always generates a 'null' id for jsonrpc if
2822 * new: debugger can take advantage of a graphical value builder
2823 (it has to be downloaded separately, as part of jsxmlrpc package.
2824 See Appendix D for more details)
2826 * new: support for the <NIL/> xmlrpc extension. see below
2829 * new: server support for the system.getCapabilities xmlrpc
2832 * new: <<wrap_xmlrpc_method,wrap_xmlrpc_method()>>
2833 accepts two new options: debug and return_on_fault
2837 * The wrap_php_function and
2838 wrap_xmlrpc_method functions have been moved
2839 out of the base library file __xmlrpc.inc__ into
2840 a file of their own: __$$xmlrpc_wrappers.php$$__. You
2841 will have to include() / require() it in your scripts if you have
2842 been using those functions. For increased security, the automatic
2843 rebuilding of php object instances out of received xmlrpc structs
2844 in wrap_xmlrpc_method() has been disabled
2845 (but it can be optionally re-enabled). Both
2846 wrap_php_function() and
2847 wrap_xmlrpc_method() functions accept many
2848 more options to fine tune their behaviour, including one to return
2849 the php code to be saved and later used as standalone php
2852 * The constructor of xmlrpcval() values has seen some internal
2853 changes, and it will not throw a php warning anymore when invoked
2854 using an unknown xmlrpc type: the error will only be written to
2855 php error log. Also ++$$new xmlrpcval('true', 'boolean')$$++
2856 is not supported anymore
2859 php_xmlrpc_decode_xml() will take the xml
2860 representation of either an xmlrpc request, response or single
2861 value and return the corresponding php-xmlrpc object
2864 * A new function wrap_xmlrpc_server()has
2865 been added, to wrap all (or some) of the methods exposed by a
2866 remote xmlrpc server into a php class
2868 * A new file has been added:
2869 __$$verify_compat.php$$__, to help users diagnose the
2870 level of compliance of their php installation with the
2873 * Restored compatibility with php 4.0.5 (for those poor souls
2876 * Method xmlrpc_server->service()
2877 now returns a value: either the response payload or xmlrpcresp
2881 xmlrpc_server->add_to_map() now
2882 accepts xmlrpc methods with no param definitions
2884 * Documentation for single parameters of exposed methods can
2885 be added to the dispatch map (and turned into html docs in
2886 conjunction with a future release of the 'extras' package)
2888 * Full response payload is saved into xmlrpcresp object for
2891 * The debugger can now generate code that wraps a remote
2892 method into a php function (works for jsonrpc, too); it also has
2893 better support for being activated via a single GET call (e.g. for
2894 integration into other tools)
2896 * Stricter parsing of incoming xmlrpc messages: two more
2897 invalid cases are now detected (double ++data++
2898 element inside ++array++ and
2899 ++struct++/++array++ after scalar
2900 inside ++value++ element)
2902 * More logging of errors in a lot of situations
2904 * Javadoc documentation of lib files (almost) complete
2906 * Many performance tweaks and code cleanups, plus the usual
2907 crop of bugs fixed (see NEWS file for complete list of
2910 * Lib internals have been modified to provide better support
2911 for grafting extra functionality on top of it. Stay tuned for
2912 future releases of the EXTRAS package (or go read Appendix
2917 * Added to the client class the possibility to use Digest and
2918 NTLM authentication methods (when using the CURL library) for
2919 connecting to servers and NTLM for connecting to proxies
2921 * Added to the client class the possibility to specify
2922 alternate certificate files/directories for authenticating the
2923 peer with when using HTTPS communication
2925 * Reviewed all examples and added a new demo file, containing
2926 a proxy to forward xmlrpc requests to other servers (useful e.g.
2929 * The debugger has been upgraded to reflect the new client
2932 * All known bugs have been squashed, and the lib is more
2933 tolerant than ever of commonly-found mistakes
2935 === 2.0 Release candidate 3
2937 * Added to server class the property
2938 functions_parameters_type, that allows the
2939 server to register plain php functions as xmlrpc methods (i.e.
2940 functions that do not take an xmlrpcmsg object as unique
2943 * let server and client objects serialize calls using a
2944 specified character set encoding for the produced xml instead of
2945 US-ASCII (ISO-8859-1 and UTF-8 supported)
2947 * let php_xmlrpc_decode accept xmlrpcmsg objects as valid
2950 * 'class::method' syntax is now accepted in the server
2953 * xmlrpc_clent::SetDebug() accepts
2954 integer values instead of a boolean value, with debugging level 2
2955 adding to the information printed to screen the complete client
2958 === 2.0 Release candidate 2
2960 * Added a new property of the client object:
2961 ++$$xmlrpc_client->return_type$$++, indicating whether
2962 calls to the send() method will return xmlrpcresp objects whose
2963 value() is an xmlrpcval object, a php value (automatically
2964 decoded) or the raw xml received from the server.
2966 * Added in the extras dir. two new library file:
2968 __jsonrpcs.inc__ containing new classes that
2969 implement support for the json-rpc protocol (alpha quality
2972 * Added a new client method: ++setKey($key,
2973 $keypass)++ to be used in HTTPS connections
2975 * Added a new file containing some benchmarks in the testsuite
2978 === 2.0 Release candidate 1
2980 * Support for HTTP proxies (new method:
2981 ++$$xmlrpc_client::setProxy()$$++)
2983 * Support HTTP compression of both requests and responses.
2984 Clients can specify what kind of compression they accept for
2985 responses between deflate/gzip/any, and whether to compress the
2986 requests. Servers by default compress responses to clients that
2987 explicitly declare support for compression (new methods:
2988 ++$$xmlrpc_client::setAcceptedCompression()$$++,
2989 ++$$xmlrpc_client::setRequestCompression()$$++). Note that the
2990 ZLIB php extension needs to be enabled in PHP to support
2993 * Implement HTTP 1.1 connections, but only if CURL is enabled
2994 (added an extra parameter to
2995 ++$$xmlrpc_client::xmlrpc_client$$++ to set the desired HTTP
2996 protocol at creation time and a new supported value for the last
2997 parameter of ++$$xmlrpc_client::send$$++, which now can be
2998 safely omitted if it has been specified at creation time)
3000 With PHP versions greater than 4.3.8 keep-alives are enabled
3001 by default for HTTP 1.1 connections. This should yield faster
3002 execution times when making multiple calls in sequence to the same
3003 xml-rpc server from a single client.
3005 * Introduce support for cookies. Cookies to be sent to the
3006 server with a request can be set using
3007 ++$$xmlrpc_client::setCookie()$$++, while cookies received from
3008 the server are found in ++xmlrpcresp::cookies()++. It is
3009 left to the user to check for validity of received cookies and
3010 decide whether they apply to successive calls or not.
3012 * Better support for detecting different character set encodings
3013 of xml-rpc requests and responses: both client and server objects
3014 will correctly detect the charset encoding of received xml, and use
3015 an appropriate xml parser.
3017 Supported encodings are US-ASCII, UTF-8 and ISO-8859-1.
3019 * Added one new xmlrpcmsg constructor syntax, allowing usage of
3020 a single string with the complete URL of the target server
3022 * Convert xml-rpc boolean values into native php values instead
3025 * Force the ++$$php_xmlrpc_encode$$++ function to properly
3026 encode numerically indexed php arrays into xml-rpc arrays
3027 (numerically indexed php arrays always start with a key of 0 and
3028 increment keys by values of 1)
3030 * Prevent the ++$$php_xmlrpc_encode$$++ function from
3031 further re-encoding any objects of class ++xmlrpcval++ that
3032 are passed to it. This allows to call the function with arguments
3033 consisting of mixed php values / xmlrpcval objects.
3035 * Allow a server to NOT respond to system.* method calls
3036 (setting the ++$$$server->allow_system_funcs$$++
3039 * Implement a new xmlrpcval method to determine if a value of
3040 type struct has a member of a given name without having to loop
3041 trough all members: ++xmlrpcval::structMemExists()++
3043 * Expand methods ++xmlrpcval::addArray++,
3044 ++addScalar++ and ++addStruct++ allowing extra php
3045 values to be added to xmlrpcval objects already formed.
3047 * Let the ++$$xmlrpc_client::send$$++ method accept an XML
3048 string for sending instead of an xmlrpcmsg object, to facilitate
3049 debugging and integration with the php native xmlrpc
3052 * Extend the ++$$php_xmlrpc_encode$$++ and
3053 ++$$php_xmlrpc_decode$$++ functions to allow serialization and
3054 rebuilding of PHP objects. To successfully rebuild a serialized
3055 object, the object class must be defined in the deserializing end of
3056 the transfer. Note that object members of type resource will be
3057 deserialized as NULL values.
3059 Note that his has been implemented adding a "php_class"
3060 attribute to xml representation of xmlrpcval of STRUCT type, which,
3061 strictly speaking, breaks the xml-rpc spec. Other xmlrpc
3062 implementations are supposed to ignore such an attribute (unless
3063 they implement a brain-dead custom xml parser...), so it should be
3064 safe enabling it in heterogeneous environments. The activation of
3065 this feature is done by usage of an option passed as second
3066 parameter to both ++$$php_xmlrpc_encode$$++ and
3067 ++$$php_xmlrpc_decode$$++.
3069 * Extend the ++$$php_xmlrpc_encode$$++ function to allow
3070 automatic serialization of iso8601-conforming php strings as
3071 datetime.iso8601 xmlrpcvals, by usage of an optional
3074 * Added an automatic stub code generator for converting xmlrpc
3075 methods to php functions and vice-versa.
3077 This is done via two new functions:
3078 ++$$wrap_php_function$$++ and ++$$wrap_xmlrpc_method$$++,
3079 and has many caveats, with php being a typeless language and
3082 * Allow object methods to be used in server dispatch map
3084 * Added a complete debugger solution, in the
3087 * Added configurable server-side debug messages, controlled by
3088 the new method ++$$xmlrpc_server::SetDebug()$$++. At level 0,
3089 no debug messages are sent to the client; level 1 is the same as the
3090 old behaviour; at level 2 a lot more info is echoed back to the
3091 client, regarding the received call; at level 3 all warnings raised
3092 during server processing are trapped (this prevents breaking the xml
3093 to be echoed back to the client) and added to the debug info sent
3096 * New XML parsing code, yields smaller memory footprint and
3097 faster execution times, not to mention complete elimination of the
3098 dreaded __eval()__ construct, so prone to code
3101 * Rewritten most of the error messages, making text more
3104 ++++++++++++++++++++++++++++++++++++++
3105 <!-- Keep this comment at the end of the file
3110 sgml-minimize-attributes:nil
3111 sgml-always-quote-attributes:t
3114 sgml-parent-document:nil
3115 sgml-exposed-tags:nil
3116 sgml-local-catalogs:nil
3117 sgml-local-ecat-files:nil
3118 sgml-namecase-general:t
3119 sgml-general-insert-case:lower
3122 ++++++++++++++++++++++++++++++++++++++
git://git.onelab.eu / plcapi.git / blob