3 :keywords: xmlrpc, xml, rpc, webservices, http
6 :source-highlighter: highlightjs
12 WARNING: THIS MANUAL HAS NOT YET BEEN UPDATED TO REFLECT ALL THE CHANGES WHICH HAVE MADE IN VERSION 4. DO NOT USE FOR NOW.
14 This collection of PHP classes provides a framework for writing XML-RPC clients and servers in PHP.
16 Main goals of the project are ease of use, flexibility and completeness.
18 The original author is Edd Dumbill of link:$$http://usefulinc.com/$$[Useful Information Company]. As of the 1.0 stable
19 release, the project was opened to wider involvement and moved to
20 link:$$http://phpxmlrpc.sourceforge.net/$$[SourceForge]; later, to link:$$https://github.com/gggeek/phpxmlrpc$$[Github]
22 XML-RPC is a format devised by link:$$http://www.userland.com/$$[Userland Software] for achieving remote procedure call
23 via XML using HTTP as the transport. XML-RPC has its own web site, link:$$http://www.xmlrpc.com/$$[www.xmlrpc.com]
25 A list of XML-RPC implementations for other languages such as Perl and Python can be found on the
26 link:$$http://www.xmlrpc.com/$$[www.xmlrpc.com] site.
66 Ernest MacDougal Campbell III
104 Przemyslaw Wroblewski
106 Bruno Zanetti Melotti
110 == System Requirements
112 The library has been designed with goals of flexibility and backward compatibility. As such, it supports a wide range of
113 PHP installs. Note that not all features of the lib are available in every configuration.
115 The __minimum supported__ PHP version is 5.3.
117 If you wish to use HTTPS or HTTP 1.1 to communicate with remote servers, or to use NTLM authentication, you need the
118 *curl* extension compiled into your PHP installation.
120 If you wish to receive XML-RPC requests or responses in any other character set than US-ASCII, ISO-8859-1 or UTF-8, you
121 will need the *mbstring* extension compiled into your PHP installation.
123 The *xmlrpc* native extension is not required to be compiled into your PHP installation, but if it is, there will be no
124 interference with the operation of this library.
128 == Files in the distribution
130 debugger/*:: a graphical debugger which can be used to test calls to xmlrpc servers
132 demo/*:: example code for implementing both xmlrpc client and server functionality
134 doc/*:: the documentation/ this manual, and the list of API changes between versions 3 and 4
136 extras/rsakey.pem:: A test certificate key for the SSL support, which can be used to generate dummy certificates. It has
137 the passphrase "test."
139 extras/test.pl, extras/test.py:: Perl and Python programs to exercise server.php to test that some of the methods work.
141 extras/workspace.testPhpServer.fttb:: Frontier scripts to exercise the demo server. Thanks to Dave Winer for permission
142 to include these. See link:$$http://www.xmlrpc.com/discuss/msgReader$853$$[Dave's announcement of these.]
144 lib/*:: a compatibility layer for applications which still rely on version 3 of the API
146 src/*:: the XML-RPC library classes. You can autoload these via Composer, or via a dedicated Autoloader class
148 tests/*:: the test suite for the library, written using PhpUnit, and the configuration to run it on Travis
155 Known bugs are tracked using the link:$$https://github.com/gggeek/phpxmlrpc/issues$$[GitHub issue tracker]
159 This started out as a bare framework. Many "nice" bits have been put in over time, but backwards compatibility has
160 always taken precedence over API cleanups. As such, you might find some API choices questionable.
162 Specifically, very little type validation or coercion has been put in. PHP being a loosely-typed language, this is
163 going to have to be done explicitly (in other words: you can call a lot of library functions passing them arguments
164 of the wrong type and receive an error message only much further down the code, where it will be difficult to
167 dateTime.iso8601 is supported opaquely. It can't be done natively as the XML-RPC specification explicitly forbids
168 passing of timezone specifiers in ISO8601 format dates. You can, however, use the PhpXmlRpc\Helper\Date class to do
169 the encoding and decoding for you.
171 Very little HTTP response checking is performed (e.g. HTTP redirects are not followed and the Content-Length HTTP
172 header, mandated by the xml-rpc spec, is not validated); cookie support still involves quite a bit of coding on the
175 Support for receiving from servers version 1 cookies (i.e. conforming to RFC 2965) is quite incomplete, and might cause
186 XML-RPC for PHP is offered "as-is" without any warranty or commitment to support. However, informal advice and help is
187 available via the XML-RPC for PHP website and mailing list.
189 * The __XML-RPC for PHP__ development is hosted on
190 link:$$https://github.com/gggeek/phpxmlrpc$$[github.com/gggeek/phpxmlrpc]. Bugs, feature requests and patches can be
191 posted to the link:$$https://github.com/gggeek/phpxmlrpc/issues$$[project's website].
193 * The __PHP XML-RPC interest mailing list__ is run by the original author. More details
194 link:$$http://lists.gnomehack.com/mailman/listinfo/phpxmlrpc$$[can be found here].
199 === The Jellyfish Book
201 image::progxmlrpc.s.gif[The Jellyfish Book]
202 Together with Simon St.Laurent and Joe Johnston, Edd Dumbill wrote a book on XML-RPC for O'Reilly and Associates on
203 XML-RPC. It features a rather fetching jellyfish on the cover.
205 Complete details of the book are link:$$http://www.oreilly.com/catalog/progxmlrpc/$$[available from O'Reilly's web site.]
207 Edd is responsible for the chapter on PHP, which includes a worked example of creating a forum server, and hooking it up
208 the O'Reilly's link:$$http://meerkat.oreillynet.com/$$[Meerkat] service in order to allow commenting on news stories
211 If you've benefited from the effort that has been put into writing this software, then please consider buying the book!
216 == Class documentation
222 This is where a lot of the hard work gets done. This class enables
223 the creation and encapsulation of values for XML-RPC.
225 Ensure you've read the XML-RPC spec at link:$$http://www.xmlrpc.com/stories/storyReader$7$$[http://www.xmlrpc.com/stories/storyReader$7]
226 before reading on as it will make things clearer.
228 The xmlrpcval class can store arbitrarily
229 complicated values using the following types: ++i4 int boolean string double dateTime.iso8601 base64 array struct++
230 ++null++. You should refer to the link:$$http://www.xmlrpc.com/spec$$[spec] for more information on
231 what each of these types mean.
237 The type i4 is accepted as a synonym
238 for int when creating xmlrpcval objects. The
239 xml parsing code will always convert i4 to
241 by this implementation as the canonical name for this type.
245 Base 64 encoding is performed transparently to the caller when
246 using this type. Decoding is also transparent. Therefore you ought
247 to consider it as a "binary" data type, for use when you want to
248 pass data that is not 7-bit clean.
252 The php values ++true++ and
253 ++1++ map to ++true++. All other
254 values (including the empty string) are converted to
259 Characters <, >;, ', ", &, are encoded using their
260 entity reference as < > ' " and
261 & All other characters outside of the ASCII range are
262 encoded using their character reference representation (e.g.
263 È for é). The XML-RPC spec recommends only encoding
264 ++< >++ but this implementation goes further,
265 for reasons explained by link:$$http://www.w3.org/TR/REC-xml#syntax$$[the XML 1.0 recommendation]. In particular, using character reference
266 representation has the advantage of producing XML that is valid
267 independently of the charset encoding assumed.
271 There is no support for encoding ++null++
272 values in the XML-RPC spec, but at least a couple of extensions (and
273 many toolkits) do support it. Before using ++null++
274 values in your messages, make sure that the responding party accepts
275 them, and uses the same encoding convention (see ...).
277 [[xmlrpcval-creation]]
281 The constructor is the normal way to create an
282 xmlrpcval. The constructor can take these
286 xmlrpcval xmlrpcvalnew
287 xmlrpcval string $stringVal xmlrpcvalnew
288 xmlrpcval mixed $scalarVal string$scalartyp xmlrpcvalnew
289 xmlrpcval array $arrayVal string $arraytyp The first constructor creates an empty value, which must be
290 altered using the methods addScalar,
291 addArray or addStruct before
294 The second constructor creates a simple string value.
296 The third constructor is used to create a scalar value. The
297 second parameter must be a name of an XML-RPC type. Valid types are:
298 "++int++", "++boolean++",
299 "++string++", "++double++",
300 "++dateTime.iso8601++", "++base64++" or
308 $myInt = new xmlrpcval(1267, "int");
309 $myString = new xmlrpcval("Hello, World!", "string");
310 $myBool = new xmlrpcval(1, "boolean");
311 $myString2 = new xmlrpcval(1.24, "string"); // note: this will serialize a php float value as xmlrpc string
315 The fourth constructor form can be used to compose complex
316 XML-RPC values. The first argument is either a simple array in the
317 case of an XML-RPC array or an associative
318 array in the case of a struct. The elements of
319 the array __must be xmlrpcval objects themselves__.
321 The second parameter must be either "++array++"
329 $myArray = new xmlrpcval(
331 new xmlrpcval("Tom"),
332 new xmlrpcval("Dick"),
333 new xmlrpcval("Harry")
338 $myStruct = new xmlrpcval(
340 "name" => new xmlrpcval("Tom", "string"),
341 "age" => new xmlrpcval(34, "int"),
342 "address" => new xmlrpcval(
344 "street" => new xmlrpcval("Fifht Ave", "string"),
345 "city" => new xmlrpcval("NY", "string")
353 See the file ++vardemo.php++ in this distribution
356 [[xmlrpcval-methods]]
362 int addScalarstring$stringValintaddScalarmixed$scalarValstring$scalartypIf $val is an empty
363 xmlrpcval this method makes it a scalar
364 value, and sets that value.
366 If $val is already a scalar value, then
367 no more scalars can be added and ++0++ is
370 If $val is an xmlrpcval of type array,
371 the php value $scalarval is added as its last
374 If all went OK, ++1++ is returned, otherwise
379 intaddArrayarray$arrayValThe argument is a simple (numerically indexed) array. The
380 elements of the array __must be xmlrpcval objects themselves__.
382 Turns an empty xmlrpcval into an
383 array with contents as specified by
386 If $val is an xmlrpcval of type array,
387 the elements of $arrayVal are appended to the
390 See the fourth constructor form for more information.
392 If all went OK, ++1++ is returned, otherwise
397 int addStructarray$assocArrayValThe argument is an associative array. The elements of the
398 array __must be xmlrpcval objects themselves__.
400 Turns an empty xmlrpcval into a
401 struct with contents as specified by
404 If $val is an xmlrpcval of type struct,
405 the elements of $arrayVal are merged with the
408 See the fourth constructor form for more information.
410 If all went OK, ++1++ is returned, otherwise
415 string kindOf Returns a string containing "struct", "array" or "scalar"
416 describing the base type of the value. If it returns "undef" it
417 means that the value hasn't been initialised.
421 string serialize Returns a string containing the XML-RPC representation of this
427 mixed scalarVal If $val->kindOf() == "scalar", this
428 method returns the actual PHP-language value of the scalar (base 64
429 decoding is automatically handled here).
433 string scalarTyp If $val->kindOf() == "scalar", this
434 method returns a string denoting the type of the scalar. As
435 mentioned before, ++i4++ is always coerced to
440 xmlrpcval arrayMem int $n If $val->kindOf() == "array", returns
441 the $nth element in the array represented by
442 the value $val. The value returned is an
448 // iterating over values of an array object
449 for ($i = 0; $i < $val->arraySize(); $i++)
451 $v = $val->arrayMem($i);
452 echo "Element $i of the array is of type ".$v->kindOf();
459 int arraySize If $val is an
460 array, returns the number of elements in that
465 xmlrpcval structMem string $memberName If $val->kindOf() == "struct", returns
466 the element called $memberName from the
467 struct represented by the value $val. The
468 value returned is an xmlrpcval object.
472 array structEach Returns the next (key, value) pair from the struct, when
474 $value is an xmlrpcval itself. See also <<structreset>>.
479 // iterating over all values of a struct object
481 while (list($key, $v) = $val->structEach())
483 echo "Element $key of the struct is of type ".$v->kindOf();
492 void structReset Resets the internal pointer for
493 structEach() to the beginning of the struct,
494 where $val is a struct.
498 ===== structMemExists
500 bool structMemExsists string $memberName Returns TRUE or
501 FALSE depending on whether a member of the
502 given name exists in the struct.
508 This class provides a representation for a request to an XML-RPC
509 server. A client sends an xmlrpcmsg to a server,
510 and receives back an xmlrpcresp (see <<xmlrpc-client-send>>).
514 The constructor takes the following forms:
517 xmlrpcmsgstring$methodNamearray$parameterArraynullWhere methodName is a string indicating
518 the name of the method you wish to invoke, and
519 parameterArray is a simple php
521 objects. Here's an example message to the __US state name__ server:
526 $msg = new xmlrpcmsg("examples.getStateName", array(new xmlrpcval(23, "int")));
530 This example requests the name of state number 23. For more
531 information on xmlrpcval objects, see <<xmlrpcval>>.
533 Note that the parameterArray parameter is
534 optional and can be omitted for methods that take no input parameters
535 or if you plan to add parameters one by one.
542 bool addParam xmlrpcval $xmlrpcVal Adds the xmlrpcval
543 xmlrpcVal to the parameter list for this
544 method call. Returns TRUE or FALSE on error.
548 int getNumParams Returns the number of parameters attached to this
553 xmlrpcval getParam int $n Gets the nth parameter in the message
554 (with the index zero-based). Use this method in server
555 implementations to retrieve the values sent by the client.
559 string method string method string $methNameGets or sets the method contained in the XML-RPC
564 xmlrpcresp parseResponsestring $xmlString Given an incoming XML-RPC server response contained in the
565 string $xmlString, this method constructs an
566 xmlrpcresp response object and returns it,
567 setting error codes as appropriate (see <<xmlrpc-client-send>>).
569 This method processes any HTTP/MIME headers it finds.
571 ===== parseResponseFile
573 xmlrpcresp parseResponseFile file handle
574 resource$fileHandleGiven an incoming XML-RPC server response on the open file
575 handle fileHandle, this method reads all the
576 data it finds and passes it to
579 This method is useful to construct responses from pre-prepared
580 files (see files ++demo1.xml, demo2.xml, demo3.xml++
581 in this distribution). It processes any HTTP headers it finds, and
582 does not close the file handle.
587 serializeReturns the an XML string representing the XML-RPC
594 This is the basic class used to represent a client of an XML-RPC
599 The constructor accepts one of two possible syntaxes:
602 xmlrpc_clientstring$server_urlxmlrpc_clientnew
603 xmlrpc_clientstring$server_pathstring$server_hostnameint$server_port80string$transport'http'Here are a couple of usage examples of the first form:
609 $client = new xmlrpc_client("http://phpxmlrpc.sourceforge.net/server.php");
610 $another_client = new xmlrpc_client("https://james:bond@secret.service.com:443/xmlrpcserver?agent=007");
614 The second syntax does not allow to express a username and
615 password to be used for basic HTTP authorization as in the second
616 example above, but instead it allows to choose whether xmlrpc calls
617 will be made using the HTTP 1.0 or 1.1 protocol.
619 Here's another example client set up to query Userland's XML-RPC
620 server at __betty.userland.com__:
625 $client = new xmlrpc_client("/RPC2", "betty.userland.com", 80);
629 The server_port parameter is optional,
630 and if omitted will default to 80 when using HTTP and 443 when using
631 HTTPS (see the <<xmlrpc-client-send>> method
634 The transport parameter is optional, and
635 if omitted will default to 'http'. Allowed values are either
637 'http11'. Its value can be overridden with every call
638 to the send method. See the
639 send method below for more details about the
640 meaning of the different values.
645 This class supports the following methods.
647 [[xmlrpc-client-send]]
651 This method takes the forms:
653 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
654 xmlrpcmsg (see <<xmlrpcmsg>>),
655 and response is an instance of
656 xmlrpcresp (see <<xmlrpcresp>>).
658 If xmlrpc_messages is an array of
659 message instances, ++responses++ will be an array of
660 response instances. The client will try to make use of a single
661 ++system.multicall++ xml-rpc method call to forward to the
662 server all the messages in a single HTTP round trip, unless
663 ++$$$client->no_multicall$$++ has been previously set to
664 ++TRUE++ (see the multicall method below), in which case
665 many consecutive xmlrpc requests will be sent.
667 The third syntax allows to build by hand (or any other means)
668 a complete xmlrpc request message, and send it to the server.
669 xml_payload should be a string containing the
670 complete xml representation of the request. It is e.g. useful when,
671 for maximal speed of execution, the request is serialized into a
672 string using the native php xmlrpc functions (see link:$$http://www.php.net/xmlrpc$$[the php manual on xmlrpc]).
674 The timeout is optional, and will be
675 set to ++0++ (wait for platform-specific predefined
676 timeout) if omitted. This timeout value is passed to
677 fsockopen(). It is also used for detecting
678 server timeouts during communication (i.e. if the server does not
679 send anything to the client for timeout
680 seconds, the connection will be closed).
682 The transport parameter is optional,
683 and if omitted will default to the transport set using instance
684 creator or 'http' if omitted. The only other valid values are
685 'https', which will use an SSL HTTP connection to connect to the
686 remote server, and 'http11'. Note that your PHP must have the "curl"
687 extension compiled in order to use both these features. Note that
688 when using SSL you should normally set your port number to 443,
689 unless the SSL server you are contacting runs at any other
692 In addition to low-level errors, the XML-RPC server you were
693 querying may return an error in the
694 xmlrpcresp object. See <<xmlrpcresp>> for details of how to handle these
701 This method takes the form:
703 array multiCall array $messages int $timeout string $transport bool $fallback This method is used to boxcar many method calls in a single
704 xml-rpc request. It will try first to make use of the
705 ++system.multicall++ xml-rpc method call, and fall back to
706 executing many separate requests if the server returns any
710 xmlrpcmsg objects (see <<xmlrpcmsg>>), and response is an
711 array of xmlrpcresp objects (see <<xmlrpcresp>>).
714 transport parameters are optional, and behave
715 as in the send method above.
717 The fallback parameter is optional, and
718 defaults to TRUE. When set to
719 FALSE it will prevent the client to try using
720 many single method calls in case of failure of the first multicall
721 request. It should be set only when the server is known to support
722 the multicall extension.
724 ===== setAcceptedCompression
726 void setAcceptedCompression string $compressionmethod This method defines whether the client will accept compressed
727 xml payload forming the bodies of the xmlrpc responses received from
728 servers. Note that enabling reception of compressed responses merely
729 adds some standard http headers to xmlrpc requests. It is up to the
730 xmlrpc server to return compressed responses when receiving such
731 requests. Allowed values for
732 compressionmethod are: 'gzip', 'deflate',
733 'any' or null (with any meaning either gzip or deflate).
735 This requires the "zlib" extension to be enabled in your php
736 install. If it is, by default xmlrpc_client
737 instances will enable reception of compressed content.
739 ===== setCaCertificate
741 voidsetCaCertificatestring$certificatebool$is_dirThis method sets an optional certificate to be used in
742 SSL-enabled communication to validate a remote server with (when the
743 server_method is set to 'https' in the
744 client's construction or in the send method and
745 SetSSLVerifypeer has been set to
748 The certificate parameter must be the
749 filename of a PEM formatted certificate, or a directory containing
750 multiple certificate files. The is_dir
751 parameter defaults to FALSE, set it to
753 certificate indicates a directory instead of
756 This requires the "curl" extension to be compiled into your
757 installation of PHP. For more details see the man page for the
758 curl_setopt function.
763 voidsetCertificatestring$certificatestring$passphraseThis method sets the optional certificate and passphrase used
764 in SSL-enabled communication with a remote server (when the
765 server_method is set to 'https' in the
766 client's construction or in the send method).
768 The certificate parameter must be the
769 filename of a PEM formatted certificate. The
770 passphrase parameter must contain the
771 password required to use the certificate.
773 This requires the "curl" extension to be compiled into your
774 installation of PHP. For more details see the man page for the
775 curl_setopt function.
777 Note: to retrieve information about the client certificate on
778 the server side, you will need to look into the environment
779 variables which are set up by the webserver. Different webservers
780 will typically set up different variables.
784 void setCookiestring $name string $value string $path string $domain int $portThis method sets a cookie that will be sent to the xmlrpc
785 server along with every further request (useful e.g. for keeping
786 session info outside of the xml-rpc payload).
788 $value is optional, and defaults to
791 $path, $domain and $port are optional,
792 and will be omitted from the cookie header if unspecified. Note that
793 setting any of these values will turn the cookie into a 'version 1'
794 cookie, that might not be fully supported by the server (see RFC2965
799 voidsetCredentialsstring$usernamestring$passwordint$authtypeThis method sets the username and password for authorizing the
800 client to a server. With the default (HTTP) transport, this
801 information is used for HTTP Basic authorization. Note that username
802 and password can also be set using the class constructor. With HTTP
803 1.1 and HTTPS transport, NTLM and Digest authentication protocols
804 are also supported. To enable them use the constants
806 CURLAUTH_NTLM as values for the authtype
812 voidsetCurlOptionsarray$optionsThis method allows to directly set any desired
813 option to manipulate the usage of the cURL client (when in cURL
814 mode). It can be used eg. to explicitly bind to an outgoing ip
815 address when the server is multihomed
820 void setDebugint$debugLvldebugLvl is either ++0, 1++ or 2 depending on whether you require the client to
821 print debugging information to the browser. The default is not to
822 output this information (0).
824 The debugging information at level 1includes the raw data
825 returned from the XML-RPC server it was querying (including bot HTTP
826 headers and the full XML payload), and the PHP value the client
827 attempts to create to represent the value returned by the server. At
828 level2, the complete payload of the xmlrpc request is also printed,
829 before being sent t the server.
831 This option can be very useful when debugging servers as it
832 allows you to see exactly what the client sends and the server
838 voidsetKeyint$keyint$keypassThis method sets the optional certificate key and passphrase
839 used in SSL-enabled communication with a remote server (when the
840 transport is set to 'https' in the client's
841 construction or in the send method).
843 This requires the "curl" extension to be compiled into your
844 installation of PHP. For more details see the man page for the
845 curl_setopt function.
850 voidsetProxystring$proxyhostint$proxyportstring$proxyusernamestring$proxypasswordint$authtypeThis method enables calling servers via an HTTP proxy. The
852 proxypassword and authtype
853 parameters are optional. Authtype defaults to
854 CURLAUTH_BASIC (Basic authentication protocol);
855 the only other valid value is the constant
856 CURLAUTH_NTLM, and has effect only when the
857 client uses the HTTP 1.1 protocol.
859 NB: CURL versions before 7.11.10 cannot use a proxy to
860 communicate with https servers.
863 ===== setRequestCompression
865 voidsetRequestCompressionstring$compressionmethodThis method defines whether the xml payload forming the
866 request body will be sent to the server in compressed format, as per
867 the HTTP specification. This is particularly useful for large
868 request parameters and over slow network connections. Allowed values
869 for compressionmethod are: 'gzip', 'deflate',
870 'any' or null (with any meaning either gzip or deflate). Note that
871 there is no automatic fallback mechanism in place for errors due to
872 servers not supporting receiving compressed request bodies, so make
873 sure that the particular server you are querying does accept
874 compressed requests before turning it on.
876 This requires the "zlib" extension to be enabled in your php
880 ===== setSSLVerifyHost
882 voidsetSSLVerifyHostint$iThis method defines whether connections made to XML-RPC
883 backends via HTTPS should verify the remote host's SSL certificate's
884 common name (CN). By default, only the existence of a CN is checked.
886 integer value; 0 to not check the CN at all, 1 to merely check for
887 its existence, and 2 to check that the CN on the certificate matches
888 the hostname that is being connected to.
891 ===== setSSLVerifyPeer
893 voidsetSSLVerifyPeerbool$iThis method defines whether connections made to XML-RPC
894 backends via HTTPS should verify the remote host's SSL certificate,
895 and cause the connection to fail if the cert verification fails.
896 $i should be a boolean
897 value. Default value: TRUE. To specify custom
898 SSL certificates to validate the server with, use the
899 setCaCertificate method.
904 voidUseragentstring$useragentThis method sets a custom user-agent that will be
905 used by the client in the http headers sent with the request. The
906 default value is built using the library name and version
912 NB: direct manipulation of these variables is only recommended
918 This member variable determines whether the multicall() method
919 will try to take advantage of the system.multicall xmlrpc method to
920 dispatch to the server an array of requests in a single http
921 roundtrip or simply execute many consecutive http calls. Defaults to
922 FALSE, but it will be enabled automatically on the first failure of
923 execution of system.multicall.
926 ===== request_charset_encoding
928 This is the charset encoding that will be used for serializing
929 request sent by the client.
931 If defaults to NULL, which means using US-ASCII and encoding
932 all characters outside of the ASCII range using their xml character
933 entity representation (this has the benefit that line end characters
934 will not be mangled in the transfer, a CR-LF will be preserved as
937 Valid values are 'US-ASCII', 'UTF-8' and 'ISO-8859-1'
943 This member variable determines whether the value returned
944 inside an xmlrpcresp object as results of calls to the send() and
945 multicall() methods will be an xmlrpcval object, a plain php value
946 or a raw xml string. Allowed values are 'xmlrpcvals' (the default),
947 'phpvals' and 'xml'. To allow the user to differentiate between a
948 correct and a faulty response, fault responses will be returned as
949 xmlrpcresp objects in any case. Note that the 'phpvals' setting will
950 yield faster execution times, but some of the information from the
951 original response will be lost. It will be e.g. impossible to tell
952 whether a particular php string value was sent by the server as an
953 xmlrpc string or base64 value.
961 $client = new xmlrpc_client("phpxmlrpc.sourceforge.net/server.php");
962 $client->return_type = 'phpvals';
963 $message = new xmlrpcmsg("examples.getStateName", array(new xmlrpcval(23, "int")));
964 $resp = $client->send($message);
965 if ($resp->faultCode()) echo 'KO. Error: '.$resp->faultString(); else echo 'OK: got '.$resp->value();
969 For more details about usage of the 'xml' value, see Appendix
976 This class is used to contain responses to XML-RPC requests. A
977 server method handler will construct an
978 xmlrpcresp and pass it as a return value. This
979 same value will be returned by the result of an invocation of the
987 xmlrpcrespxmlrpcval$xmlrpcvalxmlrpcrespnew
988 xmlrpcresp0int$errcodestring$err_stringThe first syntax is used when execution has happened without
989 difficulty: $xmlrpcval is an
990 xmlrpcval value with the result of the method
991 execution contained in it. Alternatively it can be a string containing
992 the xml serialization of the single xml-rpc value result of method
995 The second type of constructor is used in case of failure.
996 errcode and err_string
997 are used to provide indication of what has gone wrong. See <<xmlrpc-server>> for more information on passing error
1006 intfaultCodeReturns the integer fault code return from the XML-RPC
1007 response. A zero value indicates success, any other value indicates
1013 stringfaultStringReturns the human readable explanation of the fault indicated
1014 by $resp->faultCode().
1019 xmlrpcvalvalueReturns an xmlrpcval object containing
1020 the return value sent by the server. If the response's
1021 faultCode is non-zero then the value returned
1022 by this method should not be used (it may not even be an
1025 Note: if the xmlrpcresp instance in question has been created
1026 by an xmlrpc_client object whose
1027 return_type was set to 'phpvals', then a plain
1028 php value will be returned instead of an
1029 xmlrpcval object. If the
1030 return_type was set to 'xml', an xml string will
1031 be returned (see the return_type member var above for more
1037 stringserializeReturns an XML string representation of the response (xml
1038 prologue not included).
1044 The implementation of this class has been kept as simple to use as
1045 possible. The constructor for the server basically does all the work.
1046 Here's a minimal example:
1052 function foo ($xmlrpcmsg) {
1054 return new xmlrpcresp($some_xmlrpc_val);
1058 function foobar($xmlrpcmsg) {
1060 return new xmlrpcresp($some_xmlrpc_val);
1064 $s = new xmlrpc_server(
1066 "examples.myFunc1" => array("function" => "foo"),
1067 "examples.myFunc2" => array("function" => "bar::foobar"),
1072 This performs everything you need to do with a server. The single
1073 constructor argument is an associative array from xmlrpc method names to
1074 php function names. The incoming request is parsed and dispatched to the
1075 relevant php function, which is responsible for returning a
1076 xmlrpcresp object, that will be serialized back
1080 ==== Method handler functions
1082 Both php functions and class methods can be registered as xmlrpc
1085 The synopsis of a method handler function is:
1087 xmlrpcresp $resp = function (xmlrpcmsg $msg)
1089 No text should be echoed 'to screen' by the handler function, or
1090 it will break the xml response sent back to the client. This applies
1091 also to error and warning messages that PHP prints to screen unless
1092 the appropriate parameters have been set in the php.in file. Another
1093 way to prevent echoing of errors inside the response and facilitate
1094 debugging is to use the server SetDebug method with debug level 3 (see
1095 ...). Exceptions thrown duting execution of handler functions are
1096 caught by default and a XML-RPC error reponse is generated instead.
1097 This behaviour can be finetuned by usage of the
1098 exception_handling member variable (see
1101 Note that if you implement a method with a name prefixed by
1102 ++system.++ the handler function will be invoked by the
1103 server with two parameters, the first being the server itself and the
1104 second being the xmlrpcmsg object.
1106 The same php function can be registered as handler of multiple
1109 Here is a more detailed example of what the handler function
1116 function foo ($xmlrpcmsg) {
1117 global $xmlrpcerruser; // import user errcode base value
1119 $meth = $xmlrpcmsg->method(); // retrieve method name
1120 $par = $xmlrpcmsg->getParam(0); // retrieve value of first parameter - assumes at least one param received
1121 $val = $par->scalarval(); // decode value of first parameter - assumes it is a scalar value
1126 // this is an error condition
1127 return new xmlrpcresp(0, $xmlrpcerruser+1, // user error 1
1128 "There's a problem, Captain");
1130 // this is a successful value being returned
1131 return new xmlrpcresp(new xmlrpcval("All's fine!", "string"));
1137 See __server.php__ in this distribution for
1138 more examples of how to do this.
1140 Since release 2.0RC3 there is a new, even simpler way of
1141 registering php functions with the server. See section 5.7
1145 ==== The dispatch map
1147 The first argument to the xmlrpc_server
1148 constructor is an array, called the __dispatch map__.
1149 In this array is the information the server needs to service the
1150 XML-RPC methods you define.
1152 The dispatch map takes the form of an associative array of
1153 associative arrays: the outer array has one entry for each method, the
1154 key being the method name. The corresponding value is another
1155 associative array, which can have the following members:
1158 * ++function++ - this
1159 entry is mandatory. It must be either a name of a function in the
1160 global scope which services the XML-RPC method, or an array
1161 containing an instance of an object and a static method name (for
1162 static class methods the 'class::method' syntax is also
1166 * ++signature++ - this
1167 entry is an array containing the possible signatures (see <<signatures>>) for the method. If this entry is present
1168 then the server will check that the correct number and type of
1169 parameters have been sent for this method before dispatching
1173 * ++docstring++ - this
1174 entry is a string containing documentation for the method. The
1175 documentation may contain HTML markup.
1178 * ++$$signature_docs$$++ - this entry can be used
1179 to provide documentation for the single parameters. It must match
1180 in structure the 'signature' member. By default, only the
1181 documenting_xmlrpc_server class in the
1182 extras package will take advantage of this, since the
1183 "system.methodHelp" protocol does not support documenting method
1184 parameters individually.
1187 * ++$$parameters_type$$++ - this entry can be used
1188 when the server is working in 'xmlrpcvals' mode (see ...) to
1189 define one or more entries in the dispatch map as being functions
1190 that follow the 'phpvals' calling convention. The only useful
1191 value is currently the string ++phpvals++.
1193 Look at the __server.php__ example in the
1194 distribution to see what a dispatch map looks like.
1198 ==== Method signatures
1200 A signature is a description of a method's return type and its
1201 parameter types. A method may have more than one signature.
1203 Within a server's dispatch map, each method has an array of
1204 possible signatures. Each signature is an array of types. The first
1205 entry is the return type. For instance, the method
1208 string examples.getStateName(int)
1215 array($xmlrpcString, $xmlrpcInt)
1219 and, assuming that it is the only possible signature for the
1220 method, it might be used like this in server creation:
1224 $findstate_sig = array(array($xmlrpcString, $xmlrpcInt));
1226 $findstate_doc = 'When passed an integer between 1 and 51 returns the
1227 name of a US state, where the integer is the index of that state name
1228 in an alphabetic order.';
1230 $s = new xmlrpc_server( array(
1231 "examples.getStateName" => array(
1232 "function" => "findstate",
1233 "signature" => $findstate_sig,
1234 "docstring" => $findstate_doc
1241 Note that method signatures do not allow to check nested
1242 parameters, e.g. the number, names and types of the members of a
1243 struct param cannot be validated.
1245 If a method that you want to expose has a definite number of
1246 parameters, but each of those parameters could reasonably be of
1247 multiple types, the array of acceptable signatures will easily grow
1248 into a combinatorial explosion. To avoid such a situation, the lib
1249 defines the global var $xmlrpcValue, which can be
1250 used in method signatures as a placeholder for 'any xmlrpc
1257 $echoback_sig = array(array($xmlrpcValue, $xmlrpcValue));
1259 $findstate_doc = 'Echoes back to the client the received value, regardless of its type';
1261 $s = new xmlrpc_server( array(
1262 "echoBack" => array(
1263 "function" => "echoback",
1264 "signature" => $echoback_sig, // this sig guarantees that the method handler will be called with one and only one parameter
1265 "docstring" => $echoback_doc
1270 Methods system.listMethods,
1272 system.methodSignature and
1273 system.multicall are already defined by the
1274 server, and should not be reimplemented (see Reserved Methods
1278 ==== Delaying the server response
1280 You may want to construct the server, but for some reason not
1281 fulfill the request immediately (security verification, for instance).
1282 If you omit to pass to the constructor the dispatch map or pass it a
1283 second argument of ++0++ this will have the desired
1284 effect. You can then use the service() method of
1285 the server class to service the request. For example:
1291 $s = new xmlrpc_server($myDispMap, 0); // second parameter = 0 prevents automatic servicing of request
1293 // ... some code that does other stuff here
1299 Note that the service method will print
1300 the complete result payload to screen and send appropriate HTTP
1301 headers back to the client, but also return the response object. This
1302 permits further manipulation of the response, possibly in combination
1303 with output buffering.
1305 To prevent the server from sending HTTP headers back to the
1306 client, you can pass a second parameter with a value of
1307 ++TRUE++ to the service
1308 method. In this case, the response payload will be returned instead of
1309 the response object.
1311 Xmlrpc requests retrieved by other means than HTTP POST bodies
1312 can also be processed. For example:
1318 $s = new xmlrpc_server(); // not passing a dispatch map prevents automatic servicing of request
1320 // ... some code that does other stuff here, including setting dispatch map into server object
1322 $resp = $s->service($xmlrpc_request_body, true); // parse a variable instead of POST body, retrieve response payload
1324 // ... some code that does other stuff with xml response $resp here
1329 ==== Modifying the server behaviour
1331 A couple of methods / class variables are available to modify
1332 the behaviour of the server. The only way to take advantage of their
1333 existence is by usage of a delayed server response (see above)
1338 This function controls weather the server is going to echo
1339 debugging messages back to the client as comments in response body.
1340 Valid values: 0,1,2,3, with 1 being the default. At level 0, no
1341 debug info is returned to the client. At level 2, the complete
1342 client request is added to the response, as part of the xml
1343 comments. At level 3, a new PHP error handler is set when executing
1344 user functions exposed as server methods, and all non-fatal errors
1345 are trapped and added as comments into the response.
1348 ===== allow_system_funcs
1350 Default_value: TRUE. When set to FALSE, disables support for
1351 System.xxx functions in the server. It
1352 might be useful e.g. if you do not wish the server to respond to
1353 requests to System.ListMethods.
1356 ===== compress_response
1358 When set to TRUE, enables the server to take advantage of HTTP
1359 compression, otherwise disables it. Responses will be transparently
1360 compressed, but only when an xmlrpc-client declares its support for
1361 compression in the HTTP headers of the request.
1363 Note that the ZLIB php extension must be installed for this to
1364 work. If it is, compress_response will default to
1368 ===== exception_handling
1370 This variable controls the behaviour of the server when an
1371 exception is thrown by a method handler php function. Valid values:
1372 0,1,2, with 0 being the default. At level 0, the server catches the
1373 exception and return an 'internal error' xmlrpc response; at 1 it
1374 catches the exceptions and return an xmlrpc response with the error
1375 code and error message corresponding to the exception that was
1376 thron; at 2 = the exception is floated to the upper layers in the
1380 ===== response_charset_encoding
1382 Charset encoding to be used for response (only affects string
1385 If it can, the server will convert the generated response from
1386 internal_encoding to the intended one.
1388 Valid values are: a supported xml encoding (only UTF-8 and
1389 ISO-8859-1 at present, unless mbstring is enabled), null (leave
1390 charset unspecified in response and convert output stream to
1391 US_ASCII), 'default' (use xmlrpc library default as specified in
1392 xmlrpc.inc, convert output stream if needed), or 'auto' (use
1393 client-specified charset encoding or same as request if request
1394 headers do not specify it (unless request is US-ASCII: then use
1395 library default anyway).
1398 ==== Fault reporting
1400 Fault codes for your servers should start at the value indicated
1401 by the global ++$xmlrpcerruser++ + 1.
1403 Standard errors returned by the server include:
1405 ++1++ Unknown method:: Returned if the server was asked to dispatch a method it
1408 ++2++ Invalid return payload:: This error is actually generated by the client, not
1409 server, code, but signifies that a server returned something it
1410 couldn't understand. A more detailed error report is sometimes
1411 added onto the end of the phrase above.
1413 ++3++ Incorrect parameters:: This error is generated when the server has signature(s)
1414 defined for a method, and the parameters passed by the client do
1415 not match any of signatures.
1417 ++4++ Can't introspect: method unknown:: This error is generated by the builtin
1418 system.* methods when any kind of
1419 introspection is attempted on a method undefined by the
1422 ++5++ Didn't receive 200 OK from remote server:: This error is generated by the client when a remote server
1423 doesn't return HTTP/1.1 200 OK in response to a request. A more
1424 detailed error report is added onto the end of the phrase
1427 ++6++ No data received from server:: This error is generated by the client when a remote server
1428 returns HTTP/1.1 200 OK in response to a request, but no
1429 response body follows the HTTP headers.
1431 ++7++ No SSL support compiled in:: This error is generated by the client when trying to send
1432 a request with HTTPS and the CURL extension is not available to
1435 ++8++ CURL error:: This error is generated by the client when trying to send
1436 a request with HTTPS and the HTTPS communication fails.
1438 ++9-14++ multicall errors:: These errors are generated by the server when something
1439 fails inside a system.multicall request.
1441 ++100-++ XML parse errors:: Returns 100 plus the XML parser error code for the fault
1442 that occurred. The faultString returned
1443 explains where the parse error was in the incoming XML
1447 ==== 'New style' servers
1449 In the same spirit of simplification that inspired the
1450 xmlrpc_client::return_type class variable, a new
1451 class variable has been added to the server class:
1452 functions_parameters_type. When set to 'phpvals',
1453 the functions registered in the server dispatch map will be called
1454 with plain php values as parameters, instead of a single xmlrpcmsg
1455 instance parameter. The return value of those functions is expected to
1456 be a plain php value, too. An example is worth a thousand
1461 function foo($usr_id, $out_lang='en') {
1462 global $xmlrpcerruser;
1466 if ($someErrorCondition)
1467 return new xmlrpcresp(0, $xmlrpcerruser+1, 'DOH!');
1472 'picture' => new xmlrpcval(file_get_contents($picOfTheGuy), 'base64')
1476 $s = new xmlrpc_server(
1478 "examples.myFunc" => array(
1479 "function" => "bar::foobar",
1480 "signature" => array(
1481 array($xmlrpcString, $xmlrpcInt),
1482 array($xmlrpcString, $xmlrpcInt, $xmlrpcString)
1486 $s->functions_parameters_type = 'phpvals';
1491 There are a few things to keep in mind when using this
1494 to return an xmlrpc error, the method handler function must
1495 return an instance of xmlrpcresp. The only
1496 other way for the server to know when an error response should be
1497 served to the client is to throw an exception and set the server's
1498 exception_handling memeber var to 1;
1500 to return a base64 value, the method handler function must
1501 encode it on its own, creating an instance of an xmlrpcval
1504 the method handler function cannot determine the name of the
1505 xmlrpc method it is serving, unlike standard handler functions that
1506 can retrieve it from the message object;
1508 when receiving nested parameters, the method handler function
1509 has no way to distinguish a php string that was sent as base64 value
1510 from one that was sent as a string value;
1512 this has a direct consequence on the support of
1513 system.multicall: a method whose signature contains datetime or base64
1514 values will not be available to multicall calls;
1516 last but not least, the direct parsing of xml to php values is
1517 much faster than using xmlrpcvals, and allows the library to handle
1518 much bigger messages without allocating all available server memory or
1519 smashing PHP recursive call stack.
1526 Many global variables are defined in the xmlrpc.inc file. Some of
1527 those are meant to be used as constants (and modifying their value might
1528 cause unpredictable behaviour), while some others can be modified in your
1529 php scripts to alter the behaviour of the xml-rpc client and
1533 === "Constant" variables
1538 $xmlrpcerruser800The minimum value for errors reported by user
1539 implemented XML-RPC servers. Error numbers lower than that are
1540 reserved for library usage.
1543 ==== $xmlrpcI4, $xmlrpcInt, $xmlrpcBoolean, $xmlrpcDouble, $xmlrpcString, $xmlrpcDateTime, $xmlrpcBase64, $xmlrpcArray, $xmlrpcStruct, $xmlrpcValue, $xmlrpcNull
1545 For convenience the strings representing the XML-RPC types have
1546 been encoded as global variables:
1552 $xmlrpcBoolean="boolean";
1553 $xmlrpcDouble="double";
1554 $xmlrpcString="string";
1555 $xmlrpcDateTime="dateTime.iso8601";
1556 $xmlrpcBase64="base64";
1557 $xmlrpcArray="array";
1558 $xmlrpcStruct="struct";
1559 $xmlrpcValue="undefined";
1564 ==== $xmlrpcTypes, $xmlrpc_valid_parents, $xmlrpcerr, $xmlrpcstr, $xmlrpcerrxml, $xmlrpc_backslash, $_xh, $xml_iso88591_Entities, $xmlEntities, $xmlrpcs_capabilities
1566 Reserved for internal usage.
1569 === Variables whose value can be modified
1571 [[xmlrpc-defencoding]]
1573 ==== xmlrpc_defencoding
1575 $xmlrpc_defencoding"UTF8"This variable defines the character set encoding that will be
1576 used by the xml-rpc client and server to decode the received messages,
1577 when a specific charset declaration is not found (in the messages sent
1578 non-ascii chars are always encoded using character references, so that
1579 the produced xml is valid regardless of the charset encoding
1582 Allowed values: ++"UTF8"++,
1583 ++"ISO-8859-1"++, ++"ASCII".++
1585 Note that the appropriate RFC actually mandates that XML
1586 received over HTTP without indication of charset encoding be treated
1587 as US-ASCII, but many servers and clients 'in the wild' violate the
1588 standard, and assume the default encoding is UTF-8.
1591 ==== xmlrpc_internalencoding
1593 $xmlrpc_internalencoding"ISO-8859-1"This variable defines the character set encoding
1594 that the library uses to transparently encode into valid XML the
1595 xml-rpc values created by the user and to re-encode the received
1596 xml-rpc values when it passes them to the PHP application. It only
1597 affects xml-rpc values of string type. It is a separate value from
1598 xmlrpc_defencoding, allowing e.g. to send/receive xml messages encoded
1599 on-the-wire in US-ASCII and process them as UTF-8. It defaults to the
1600 character set used internally by PHP (unless you are running an
1601 MBString-enabled installation), so you should change it only in
1602 special situations, if e.g. the string values exchanged in the xml-rpc
1603 messages are directly inserted into / fetched from a database
1604 configured to return UTF8 encoded strings to PHP. Example
1612 include('xmlrpc.inc');
1613 $xmlrpc_internalencoding = 'UTF-8'; // this has to be set after the inclusion above
1614 $v = new xmlrpcval('κόÏ
\83με'); // This xmlrpc value will be correctly serialized as the greek word 'kosme'
1620 $xmlrpcName"XML-RPC for PHP"The string representation of the name of the XML-RPC
1621 for PHP library. It is used by the client for building the User-Agent
1622 HTTP header that is sent with every request to the server. You can
1623 change its value if you need to customize the User-Agent
1629 $xmlrpcVersion"2.2"The string representation of the version number of
1630 the XML-RPC for PHP library in use. It is used by the client for
1631 building the User-Agent HTTP header that is sent with every request to
1632 the server. You can change its value if you need to customize the
1636 ==== xmlrpc_null_extension
1638 When set to TRUE, the lib will enable
1639 support for the <NIL/> (and <EX:NIL/>) xmlrpc value, as
1640 per the extension to the standard proposed here. This means that
1641 <NIL> and <EX:NIL/> tags received will be parsed as valid
1642 xmlrpc, and the corresponding xmlrpcvals will return "null" for
1646 ==== xmlrpc_null_apache_encoding
1648 When set to ++TRUE++, php NULL values encoded
1649 into xmlrpcval objects get serialized using the
1650 ++<EX:NIL/>++ tag instead of
1651 ++<NIL/>++. Please note that both forms are
1652 always accepted as input regardless of the value of this
1660 XML-RPC for PHP contains some helper functions which you can use to
1661 make processing of XML-RPC requests easier.
1666 The XML-RPC specification has this to say on dates:
1670 [[wrap_xmlrpc_method]]
1671 Don't assume a timezone. It should be
1672 specified by the server in its documentation what assumptions it makes
1677 Unfortunately, this means that date processing isn't
1678 straightforward. Although XML-RPC uses ISO 8601 format dates, it doesn't
1679 use the timezone specifier.
1681 We strongly recommend that in every case where you pass dates in
1682 XML-RPC calls, you use UTC (GMT) as your timezone. Most computer
1683 languages include routines for handling GMT times natively, and you
1684 won't have to translate between timezones.
1686 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
1687 8601 specification. Note that XML-RPC uses exactly one of the available
1688 representations: CCYYMMDDTHH:MM:SS.
1694 stringiso8601_encodestring$time_tint$utc0Returns an ISO 8601 formatted date generated from the UNIX
1695 timestamp $time_t, as returned by the PHP
1698 The argument $utc can be omitted, in
1699 which case it defaults to ++0++. If it is set to
1700 ++1++, then the function corrects the time passed in
1701 for UTC. Example: if you're in the GMT-6:00 timezone and set
1702 $utc, you will receive a date representation
1703 six hours ahead of your local time.
1705 The included demo program __vardemo.php__
1706 includes a demonstration of this function.
1712 intiso8601_decodestring$isoStringint$utc0Returns a UNIX timestamp from an ISO 8601 encoded time and date
1713 string passed in. If $utc is
1714 ++1++ then $isoString is assumed
1715 to be in the UTC timezone, and thus the result is also UTC: otherwise,
1716 the timezone is assumed to be your local timezone and you receive a
1721 === Easy use with nested PHP values
1723 Dan Libby was kind enough to contribute two helper functions that
1724 make it easier to translate to and from PHP values. This makes it easier
1725 to deal with complex structures. At the moment support is limited to
1726 int, double, string,
1727 array, datetime and struct
1728 datatypes; note also that all PHP arrays are encoded as structs, except
1729 arrays whose keys are integer numbers starting with 0 and incremented by
1732 These functions reside in __xmlrpc.inc__.
1736 ==== php_xmlrpc_decode
1738 mixedphp_xmlrpc_decodexmlrpcval$xmlrpc_valarray$optionsarrayphp_xmlrpc_decodexmlrpcmsg$xmlrpcmsg_valstring$optionsReturns a native PHP value corresponding to the values found in
1739 the xmlrpcval $xmlrpc_val,
1740 translated into PHP types. Base-64 and datetime values are
1741 automatically decoded to strings.
1743 In the second form, returns an array containing the parameters
1745 xmlrpcmsg_val, decoded
1748 The options parameter is optional. If
1749 specified, it must consist of an array of options to be enabled in the
1750 decoding process. At the moment the only valid option are
1752 ++$$dates_as_objects$$++. When the first is set, php
1753 objects that have been converted to xml-rpc structs using the
1754 php_xmlrpc_encode function and a corresponding
1755 encoding option will be converted back into object values instead of
1756 arrays (provided that the class definition is available at
1757 reconstruction time). When the second is set, XML-RPC datetime values
1758 will be converted into native dateTime objects
1761 ____WARNING__:__ please take
1762 extreme care before enabling the decode_php_objs
1763 option: when php objects are rebuilt from the received xml, their
1764 constructor function will be silently invoked. This means that you are
1765 allowing the remote end to trigger execution of uncontrolled PHP code
1766 on your server, opening the door to code injection exploits. Only
1767 enable this option when you have complete trust of the remote
1774 // wrapper to expose an existing php function as xmlrpc method handler
1775 function foo_wrapper($m)
1777 $params = php_xmlrpc_decode($m);
1778 $retval = call_user_func_array('foo', $params);
1779 return new xmlrpcresp(new xmlrpcval($retval)); // foo return value will be serialized as string
1782 $s = new xmlrpc_server(array(
1783 "examples.myFunc1" => array(
1784 "function" => "foo_wrapper",
1792 ==== php_xmlrpc_encode
1794 xmlrpcvalphp_xmlrpc_encodemixed$phpvalarray$optionsReturns an xmlrpcval object populated with the PHP
1795 values in $phpval. Works recursively on arrays
1796 and objects, encoding numerically indexed php arrays into array-type
1797 xmlrpcval objects and non numerically indexed php arrays into
1798 struct-type xmlrpcval objects. Php objects are encoded into
1799 struct-type xmlrpcvals, excepted for php values that are already
1800 instances of the xmlrpcval class or descendants thereof, which will
1801 not be further encoded. Note that there's no support for encoding php
1802 values into base-64 values. Encoding of date-times is optionally
1803 carried on on php strings with the correct format.
1805 The options parameter is optional. If
1806 specified, it must consist of an array of options to be enabled in the
1807 encoding process. At the moment the only valid options are
1808 encode_php_objs, ++$$null_extension$$++
1811 The first will enable the creation of 'particular' xmlrpcval
1812 objects out of php objects, that add a "php_class" xml attribute to
1813 their serialized representation. This attribute allows the function
1814 php_xmlrpc_decode to rebuild the native php objects (provided that the
1815 same class definition exists on both sides of the communication). The
1816 second allows to encode php ++NULL++ values to the
1818 ++<EX:NIL>++, see ...) tag. The last encodes any
1819 string that matches the ISO8601 format into an XML-RPC
1826 // the easy way to build a complex xml-rpc struct, showing nested base64 value and datetime values
1827 $val = php_xmlrpc_encode(array(
1828 'first struct_element: an int' => 666,
1829 'second: an array' => array ('apple', 'orange', 'banana'),
1830 'third: a base64 element' => new xmlrpcval('hello world', 'base64'),
1831 'fourth: a datetime' => '20060107T01:53:00'
1832 ), array('auto_dates'));
1836 ==== php_xmlrpc_decode_xml
1838 xmlrpcval | xmlrpcresp |
1839 xmlrpcmsgphp_xmlrpc_decode_xmlstring$xmlarray$optionsDecodes the xml representation of either an xmlrpc request,
1840 response or single value, returning the corresponding php-xmlrpc
1841 object, or ++FALSE++ in case of an error.
1843 The options parameter is optional. If
1844 specified, it must consist of an array of options to be enabled in the
1845 decoding process. At the moment, no option is supported.
1851 $text = '<value><array><data><value>Hello world</value></data></array></value>';
1852 $val = php_xmlrpc_decode_xml($text);
1853 if ($val) echo 'Found a value of type '.$val->kindOf(); else echo 'Found invalid xml';
1857 === Automatic conversion of php functions into xmlrpc methods (and vice versa)
1859 For the extremely lazy coder, helper functions have been added
1860 that allow to convert a php function into an xmlrpc method, and a
1861 remotely exposed xmlrpc method into a local php function - or a set of
1862 methods into a php class. Note that these comes with many caveat.
1865 ==== wrap_xmlrpc_method
1867 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
1868 function that will call the remote method and return results using
1869 native php types for both params and results. The generated php
1870 function will return an xmlrpcresp object for failed xmlrpc
1873 The second syntax is deprecated, and is listed here only for
1874 backward compatibility.
1876 The server must support the
1877 system.methodSignature xmlrpc method call for
1878 this function to work.
1880 The client param must be a valid
1881 xmlrpc_client object, previously created with the address of the
1882 target xmlrpc server, and to which the preferred communication options
1885 The optional parameters can be passed as array key,value pairs
1886 in the extra_options param.
1888 The signum optional param has the purpose
1889 of indicating which method signature to use, if the given server
1890 method has multiple signatures (defaults to 0).
1893 protocol optional params are the same as in the
1894 xmlrpc_client::send() method.
1896 If set, the optional new_function_name
1897 parameter indicates which name should be used for the generated
1898 function. In case it is not set the function name will be
1901 If the ++$$return_source$$++ optional parameter is
1902 set, the function will return the php source code to build the wrapper
1903 function, instead of evaluating it (useful to save the code and use it
1904 later as stand-alone xmlrpc client).
1906 If the ++$$encode_php_objs$$++ optional parameter is
1907 set, instances of php objects later passed as parameters to the newly
1908 created function will receive a 'special' treatment that allows the
1909 server to rebuild them as php objects instead of simple arrays. Note
1910 that this entails using a "slightly augmented" version of the xmlrpc
1911 protocol (ie. using element attributes), which might not be understood
1912 by xmlrpc servers implemented using other libraries.
1914 If the ++$$decode_php_objs$$++ optional parameter is
1915 set, instances of php objects that have been appropriately encoded by
1916 the server using a coordinate option will be deserialized as php
1917 objects instead of simple arrays (the same class definition should be
1918 present server side and client side).
1920 __Note that this might pose a security risk__,
1921 since in order to rebuild the object instances their constructor
1922 method has to be invoked, and this means that the remote server can
1923 trigger execution of unforeseen php code on the client: not really a
1924 code injection, but almost. Please enable this option only when you
1925 trust the remote server.
1927 In case of an error during generation of the wrapper function,
1928 FALSE is returned, otherwise the name (or source code) of the new
1931 Known limitations: server must support
1932 system.methodsignature for the wanted xmlrpc
1933 method; for methods that expose multiple signatures, only one can be
1934 picked; for remote calls with nested xmlrpc params, the caller of the
1935 generated php function has to encode on its own the params passed to
1936 the php function if these are structs or arrays whose (sub)members
1937 include values of type base64.
1939 Note: calling the generated php function 'might' be slow: a new
1940 xmlrpc client is created on every invocation and an xmlrpc-connection
1941 opened+closed. An extra 'debug' param is appended to the parameter
1942 list of the generated php function, useful for debugging
1951 $c = new xmlrpc_client('http://phpxmlrpc.sourceforge.net/server.php');
1953 $function = wrap_xmlrpc_method($client, 'examples.getStateName');
1956 die('Cannot introspect remote method');
1959 $statename = $function($a);
1960 if (is_a($statename, 'xmlrpcresp')) // call failed
1962 echo 'Call failed: '.$statename->faultCode().'. Calling again with debug on';
1963 $function($a, true);
1966 echo "OK, state nr. $stateno is $statename";
1971 [[wrap_php_function]]
1973 ==== wrap_php_function
1975 arraywrap_php_functionstring$funcnamestring$wrapper_function_namearray$extra_optionsGiven a user-defined PHP function, create a PHP 'wrapper'
1976 function that can be exposed as xmlrpc method from an xmlrpc_server
1977 object and called from remote clients, and return the appropriate
1978 definition to be added to a server's dispatch map.
1980 The optional $wrapper_function_name
1981 specifies the name that will be used for the auto-generated
1984 Since php is a typeless language, to infer types of input and
1985 output parameters, it relies on parsing the javadoc-style comment
1986 block associated with the given function. Usage of xmlrpc native types
1987 (such as datetime.dateTime.iso8601 and base64) in the docblock @param
1988 tag is also allowed, if you need the php function to receive/send data
1989 in that particular format (note that base64 encoding/decoding is
1990 transparently carried out by the lib, while datetime vals are passed
1993 Known limitations: only works for
1994 user-defined functions, not for PHP internal functions (reflection
1995 does not support retrieving number/type of params for those); the
1996 wrapped php function will not be able to programmatically return an
1997 xmlrpc error response.
1999 If the ++$$return_source$$++ optional parameter is
2000 set, the function will return the php source code to build the wrapper
2001 function, instead of evaluating it (useful to save the code and use it
2002 later in a stand-alone xmlrpc server). It will be in the stored in the
2003 ++source++ member of the returned array.
2005 If the ++$$suppress_warnings$$++ optional parameter
2006 is set, any runtime warning generated while processing the
2007 user-defined php function will be catched and not be printed in the
2008 generated xml response.
2010 If the extra_options array contains the
2011 ++$$encode_php_objs$$++ value, wrapped functions returning
2012 php objects will generate "special" xmlrpc responses: when the xmlrpc
2013 decoding of those responses is carried out by this same lib, using the
2014 appropriate param in php_xmlrpc_decode(), the objects will be
2017 In short: php objects can be serialized, too (except for their
2018 resource members), using this function. Other libs might choke on the
2019 very same xml that will be generated in this case (i.e. it has a
2020 nonstandard attribute on struct element tags)
2022 If the ++$$decode_php_objs$$++ optional parameter is
2023 set, instances of php objects that have been appropriately encoded by
2024 the client using a coordinate option will be deserialized and passed
2025 to the user function as php objects instead of simple arrays (the same
2026 class definition should be present server side and client
2029 __Note that this might pose a security risk__,
2030 since in order to rebuild the object instances their constructor
2031 method has to be invoked, and this means that the remote client can
2032 trigger execution of unforeseen php code on the server: not really a
2033 code injection, but almost. Please enable this option only when you
2034 trust the remote clients.
2042 * State name from state number decoder. NB: do NOT remove this comment block.
2043 * @param integer $stateno the state number
2044 * @return string the name of the state (or error description)
2046 function findstate($stateno)
2049 if (isset($stateNames[$stateno-1]))
2051 return $stateNames[$stateno-1];
2055 return "I don't have a state for the index '" . $stateno . "'";
2059 // wrap php function, build xmlrpc server
2061 $findstate_sig = wrap_php_function('findstate');
2063 $methods['examples.getStateName'] = $findstate_sig;
2064 $srv = new xmlrpc_server($methods);
2070 === Functions removed from the library
2072 The following two functions have been deprecated in version 1.1 of
2073 the library, and removed in version 2, in order to avoid conflicts with
2074 the EPI xml-rpc library, which also defines two functions with the same
2077 To ease the transition to the new naming scheme and avoid breaking
2078 existing implementations, the following scheme has been adopted:
2080 * If EPI-XMLRPC is not active in the current PHP installation,
2081 the constant ++$$XMLRPC_EPI_ENABLED$$++ will be set to
2085 * If EPI-XMLRPC is active in the current PHP installation, the
2086 constant ++$$XMLRPC_EPI_ENABLED$$++ will be set to
2091 The following documentation is kept for historical
2098 mixedx mlrpc_decode xmlrpcval $xmlrpc_val Alias for php_xmlrpc_decode.
2104 xmlrpcval xmlrpc_encode mixed $phpvalAlias for php_xmlrpc_encode.
2110 ==== xmlrpc_debugmsg
2112 void xmlrpc_debugmsgstring$debugstringSends the contents of $debugstring in XML
2113 comments in the server return payload. If a PHP client has debugging
2114 turned on, the user will be able to see server debug
2117 Use this function in your methods so you can pass back
2118 diagnostic information. It is only available from
2126 In order to extend the functionality offered by XML-RPC servers
2127 without impacting on the protocol, reserved methods are supported in this
2130 All methods starting with system. are
2131 considered reserved by the server. PHP for XML-RPC itself provides four
2132 special methods, detailed in this chapter.
2134 Note that all server objects will automatically respond to clients
2135 querying these methods, unless the property
2136 allow_system_funcs has been set to
2137 false before calling the
2138 service() method. This might pose a security risk
2139 if the server is exposed to public access, e.g. on the internet.
2142 === system.getCapabilities
2145 === system.listMethods
2147 This method may be used to enumerate the methods implemented by
2150 The system.listMethods method requires no
2151 parameters. It returns an array of strings, each of which is the name of
2152 a method implemented by the server.
2156 === system.methodSignature
2158 This method takes one parameter, the name of a method implemented
2159 by the XML-RPC server.
2161 It returns an array of possible signatures for this method. A
2162 signature is an array of types. The first of these types is the return
2163 type of the method, the rest are parameters.
2165 Multiple signatures (i.e. overloading) are permitted: this is the
2166 reason that an array of signatures are returned by this method.
2168 Signatures themselves are restricted to the top level parameters
2169 expected by a method. For instance if a method expects one array of
2170 structs as a parameter, and it returns a string, its signature is simply
2171 "string, array". If it expects three integers, its signature is "string,
2174 For parameters that can be of more than one type, the "undefined"
2175 string is supported.
2177 If no signature is defined for the method, a not-array value is
2178 returned. Therefore this is the way to test for a non-signature, if
2179 $resp below is the response object from a method
2180 call to system.methodSignature:
2185 $v = $resp->value();
2186 if ($v->kindOf() != "array") {
2187 // then the method did not have a signature defined
2192 See the __introspect.php__ demo included in this
2193 distribution for an example of using this method.
2197 === system.methodHelp
2199 This method takes one parameter, the name of a method implemented
2200 by the XML-RPC server.
2202 It returns a documentation string describing the use of that
2203 method. If no such string is available, an empty string is
2206 The documentation string may contain HTML markup.
2208 === system.multicall
2210 This method takes one parameter, an array of 'request' struct
2211 types. Each request struct must contain a
2212 methodName member of type string and a
2213 params member of type array, and corresponds to
2214 the invocation of the corresponding method.
2216 It returns a response of type array, with each value of the array
2217 being either an error struct (containing the faultCode and faultString
2218 members) or the successful response value of the corresponding single
2226 The best examples are to be found in the sample files included with
2227 the distribution. Some are included here.
2231 === XML-RPC client: state name query
2233 Code to get the corresponding state name from a number (1-50) from
2234 the demo server available on SourceForge
2239 $m = new xmlrpcmsg('examples.getStateName',
2240 array(new xmlrpcval($HTTP_POST_VARS["stateno"], "int")));
2241 $c = new xmlrpc_client("/server.php", "phpxmlrpc.sourceforge.net", 80);
2243 if (!$r->faultCode()) {
2245 print "State number " . htmlentities($HTTP_POST_VARS["stateno"]) . " is " .
2246 htmlentities($v->scalarval()) . "<BR>";
2247 print "<HR>I got this value back<BR><PRE>" .
2248 htmlentities($r->serialize()) . "</PRE><HR>\n";
2251 print "Code: " . htmlentities($r->faultCode()) . "<BR>" .
2252 "Reason: '" . htmlentities($r->faultString()) . "'<BR>";
2257 === Executing a multicall call
2265 == Frequently Asked Questions
2267 ==== How to send custom XML as payload of a method call::
2269 Unfortunately, at the time the XML-RPC spec was designed, support
2270 for namespaces in XML was not as ubiquitous as it is now. As a
2271 consequence, no support was provided in the protocol for embedding XML
2272 elements from other namespaces into an xmlrpc request.
2274 To send an XML "chunk" as payload of a method call or response,
2275 two options are available: either send the complete XML block as a
2276 string xmlrpc value, or as a base64 value. Since the '<' character in
2277 string values is encoded as '<' in the xml payload of the method
2278 call, the XML string will not break the surrounding xmlrpc, unless
2279 characters outside of the assumed character set are used. The second
2280 method has the added benefits of working independently of the charset
2281 encoding used for the xml to be transmitted, and preserving exactly
2282 whitespace, whilst incurring in some extra message length and cpu load
2283 (for carrying out the base64 encoding/decoding).
2286 ==== Is there any limitation on the size of the requests / responses that can be successfully sent?::
2288 Yes. But I have no hard figure to give; it most likely will depend
2289 on the version of PHP in usage and its configuration.
2291 Keep in mind that this library is not optimized for speed nor for
2292 memory usage. Better alternatives exist when there are strict
2293 requirements on throughput or resource usage, such as the php native
2294 xmlrpc extension (see the PHP manual for more information).
2296 Keep in mind also that HTTP is probably not the best choice in
2297 such a situation, and XML is a deadly enemy. CSV formatted data over
2298 socket would be much more efficient.
2300 If you really need to move a massive amount of data around, and
2301 you are crazy enough to do it using phpxmlrpc, your best bet is to
2302 bypass usage of the xmlrpcval objects, at least in the decoding phase,
2303 and have the server (or client) object return to the calling function
2304 directly php values (see xmlrpc_client::return_type
2305 and xmlrpc_server::functions_parameters_type for more
2309 ==== My server (client) returns an error whenever the client (server) returns accented characters
2314 ==== How to enable long-lasting method calls
2319 ==== My client returns "XML-RPC Fault #2: Invalid return payload: enable debugging to examine incoming payload": what should I do?
2321 The response you are seeing is a default error response that the
2322 client object returns to the php application when the server did not
2323 respond to the call with a valid xmlrpc response.
2325 The most likely cause is that you are not using the correct URL
2326 when creating the client object, or you do not have appropriate access
2327 rights to the web page you are requesting, or some other common http
2330 To find out what the server is really returning to your client,
2331 you have to enable the debug mode of the client, using
2332 $client->setdebug(1);
2335 ==== How can I save to a file the xml of the xmlrpc responses received from servers?
2337 If what you need is to save the responses received from the server
2338 as xml, you have two options:
2340 1- use the serialize() method on the response object.
2346 $resp = $client->send($msg);
2347 if (!$resp->faultCode())
2348 $data_to_be_saved = $resp->serialize();
2352 Note that this will not be 100% accurate, since the xml generated
2353 by the response object can be different from the xml received,
2354 especially if there is some character set conversion involved, or such
2355 (eg. if you receive an empty string tag as <string/>, serialize()
2356 will output <string></string>), or if the server sent back
2357 as response something invalid (in which case the xml generated client
2358 side using serialize() will correspond to the error response generated
2359 internally by the lib).
2361 2 - set the client object to return the raw xml received instead
2362 of the decoded objects:
2368 $client = new xmlrpc_client($url);
2369 $client->return_type = 'xml';
2370 $resp = $client->send($msg);
2371 if (!$resp->faultCode())
2372 $data_to_be_saved = $resp->value();
2376 Note that using this method the xml response response will not be
2377 parsed at all by the library, only the http communication protocol will
2378 be checked. This means that xmlrpc responses sent by the server that
2379 would have generated an error response on the client (eg. malformed xml,
2380 responses that have faultcode set, etc...) now will not be flagged as
2381 invalid, and you might end up saving not valid xml but random
2385 ==== Can I use the ms windows character set?
2387 If the data your application is using comes from a Microsoft
2388 application, there are some chances that the character set used to
2389 encode it is CP1252 (the same might apply to data received from an
2390 external xmlrpc server/client, but it is quite rare to find xmlrpc
2391 toolkits that encode to CP1252 instead of UTF8). It is a character set
2392 which is "almost" compatible with ISO 8859-1, but for a few extra
2395 PHP-XMLRPC only supports the ISO 8859-1 and UTF8 character sets.
2396 The net result of this situation is that those extra characters will not
2397 be properly encoded, and will be received at the other end of the
2398 XML-RPC transmission as "garbled data". Unfortunately the library cannot
2399 provide real support for CP1252 because of limitations in the PHP 4 xml
2400 parser. Luckily, we tried our best to support this character set anyway,
2401 and, since version 2.2.1, there is some form of support, left commented
2404 To properly encode outgoing data that is natively in CP1252, you
2405 will have to uncomment all relative code in the file
2406 __xmlrpc.inc__ (you can search for the string "1252"),
2407 then set ++$$$GLOBALS['xmlrpc_internalencoding']='CP1252';$$++
2408 Please note that all incoming data will then be fed to your application
2409 as UTF-8 to avoid any potential data loss.
2412 ==== Does the library support using cookies / http sessions?
2414 In short: yes, but a little coding is needed to make it
2417 The code below uses sessions to e.g. let the client store a value
2418 on the server and retrieve it later.
2423 $resp = $client->send(new xmlrpcmsg('registervalue', array(new xmlrpcval('foo'), new xmlrpcval('bar'))));
2424 if (!$resp->faultCode())
2426 $cookies = $resp->cookies();
2427 if (array_key_exists('PHPSESSID', $cookies)) // nb: make sure to use the correct session cookie name
2429 $session_id = $cookies['PHPSESSID']['value'];
2431 // do some other stuff here...
2433 $client->setcookie('PHPSESSID', $session_id);
2434 $val = $client->send(new xmlrpcmsg('getvalue', array(new xmlrpcval('foo')));
2440 Server-side sessions are handled normally like in any other
2441 php application. Please see the php manual for more information about
2444 NB: unlike web browsers, not all xmlrpc clients support usage of
2445 http cookies. If you have troubles with sessions and control only the
2446 server side of the communication, please check with the makers of the
2447 xmlrpc client in use.
2453 == Integration with the PHP xmlrpc extension
2455 To be documented more...
2457 In short: for the fastest execution possible, you can enable the php
2458 native xmlrpc extension, and use it in conjunction with phpxmlrpc. The
2459 following code snippet gives an example of such integration
2465 /*** client side ***/
2466 $c = new xmlrpc_client('http://phpxmlrpc.sourceforge.net/server.php');
2468 // tell the client to return raw xml as response value
2469 $c->return_type = 'xml';
2471 // let the native xmlrpc extension take care of encoding request parameters
2472 $r = $c->send(xmlrpc_encode_request('examples.getStateName', $_POST['stateno']));
2474 if ($r->faultCode())
2475 // HTTP transport error
2476 echo 'Got error '.$r->faultCode();
2479 // HTTP request OK, but XML returned from server not parsed yet
2480 $v = xmlrpc_decode($r->value());
2481 // check if we got a valid xmlrpc response from server
2483 echo 'Got invalid response';
2485 // check if server sent a fault response
2486 if (xmlrpc_is_fault($v))
2487 echo 'Got xmlrpc fault '.$v['faultCode'];
2489 echo'Got response: '.htmlentities($v);
2498 == Substitution of the PHP xmlrpc extension
2500 Yet another interesting situation is when you are using a ready-made
2501 php application, that provides support for the XMLRPC protocol via the
2502 native php xmlrpc extension, but the extension is not available on your
2503 php install (e.g. because of shared hosting constraints).
2505 Since version 2.1, the PHP-XMLRPC library provides a compatibility
2506 layer that aims to be 100% compliant with the xmlrpc extension API. This
2507 means that any code written to run on the extension should obtain the
2508 exact same results, albeit using more resources and a longer processing
2509 time, using the PHP-XMLRPC library and the extension compatibility module.
2510 The module is part of the EXTRAS package, available as a separate download
2511 from the sourceforge.net website, since version 0.2
2517 == 'Enough of xmlrpcvals!': new style library usage
2521 In the meantime, see docs about xmlrpc_client::return_type and
2522 xmlrpc_server::functions_parameters_types, as well as php_xmlrpc_encode,
2523 php_xmlrpc_decode and php_xmlrpc_decode_xml
2529 == Usage of the debugger
2531 A webservice debugger is included in the library to help during
2532 development and testing.
2534 The interface should be self-explicative enough to need little
2537 image::debugger.gif[,,,,align="center"]
2539 The most useful feature of the debugger is without doubt the "Show
2540 debug info" option. It allows to have a screen dump of the complete http
2541 communication between client and server, including the http headers as
2542 well as the request and response payloads, and is invaluable when
2543 troubleshooting problems with charset encoding, authentication or http
2546 The debugger can take advantage of the JSONRPC library extension, to
2547 allow debugging of JSON-RPC webservices, and of the JS-XMLRPC library
2548 visual editor to allow easy mouse-driven construction of the payload for
2549 remote methods. Both components have to be downloaded separately from the
2550 sourceforge.net web pages and copied to the debugger directory to enable
2551 the extra functionality:
2554 * to enable jsonrpc functionality, download the PHP-XMLRPC
2555 EXTRAS package, and copy the file __jsonrpc.inc__
2556 either to the same directory as the debugger or somewhere in your
2560 * to enable the visual value editing dialog, download the
2561 JS-XMLRPC library, and copy somewhere in the web root files
2562 __visualeditor.php__,
2563 __visualeditor.css__ and the folders
2564 __yui__ and __img__. Then edit the
2565 debugger file __controller.php__ and set
2566 appropriately the variable $editorpath.
2575 CAUTION: not all items the following list have (yet) been fully documented, and some might not be present in any other
2576 chapter in the manual. To find a more detailed description of new functions and methods please take a look at the
2577 source code of the library, which is quite thoroughly commented in phpdoc form.
2581 * new: introduction of namespaces and full OOP.
2583 All php classes have been renamed and moved to separate files.
2585 Class autoloading can now be done in accord with the PSR-4 standard.
2587 All global variables and global functions have been removed.
2589 Iterating over xmlrpc value objects is now easier thank to support for ArrayAccess and Traversable interfaces.
2591 Backward compatibility is maintained via _lib/xmlrpc.inc_, _lib/xmlrpcs.inc_ and _lib/xmlrpc_wrappers.inc_.
2592 For more details, head on to doc/api_changes_v4.md
2594 * changed: the default character encoding delivered from the library to your code is now utf8.
2595 It can be changed at any time setting a value to `PhpXmlRpc\PhpXmlRpc::$xmlrpc_internalencoding`
2597 * improved: the library now accepts requests/responses sent using other character sets than UTF-8/ISO-8859-1/ASCII.
2598 This only works when the mbstring php extension is enabled.
2600 * improved: no need to call anymore `$client->setSSLVerifyHost(2)` to silence a curl warning when using https
2601 with recent curl builds
2603 * improved: the xmlrpcval class now supports the interfaces `Countable` and `IteratorAggregate`
2605 * improved: a specific option allows users to decide the version of SSL to use for https calls.
2606 This is useful f.e. for the testing suite, when the server target of calls has no proper ssl certificate,
2607 and the cURL extension has been compiled with GnuTLS (such as on Travis VMs)
2609 * improved: the function `wrap_php_function()` now can be used to wrap closures (it is now a method btw)
2611 * improved: all _wrap_something()_ functions now return a closure by default instead of a function name
2613 * improved: debug messages are not html-escaped any more when executing from the command line
2615 * improved: the library is now tested using Travis ( https://travis-ci.org/ ).
2616 Tests are executed using all php versions from 5.3 to 7.0 nightly, plus HHVM; code-coverage information
2617 is generated using php 5.6 and uploaded to both Code Coverage and Scrutinizer online services
2619 * improved: phpunit is now installed via composer, not bundled anymore
2621 * improved: when phpunit is used to generate code-coverage data, the code executed server-side is accounted for
2623 * improved: the test suite has basic checks for the debugger and demo files
2625 * improved: more tests in the test suite
2627 * fixed: the server would not reset the user-set debug messages between subsequent `service()` calls
2629 * fixed: the server would not reset previous php error handlers when an exception was thrown by user code and
2630 exception_handling set to 2
2632 * fixed: the server would fail to decode a request with ISO-8859-1 payload and character set declaration in the xml
2635 * fixed: the client would fail to decode a response with ISO-8859-1 payload and character set declaration in the xml
2638 * fixed: the function `decode_xml()` would not decode an xml with character set declaration in the xml prolog
2640 * fixed: the client can now successfully call methods using ISO-8859-1 or UTF-8 characters in their name
2642 * fixed: the debugger would fail sending a request with ISO-8859-1 payload (it missed the character set declaration).
2643 It would have a hard time coping with ISO-8859-1 in other fields, such as e.g. the remote method name
2645 * fixed: the debugger would generate a bad payload via the 'load method synopsis' button for signatures containing NULL
2646 or undefined parameters
2648 * fixed: the debugger would generate a bad payload via the 'load method synopsis' button for methods with multiple
2651 * improved: the debugger is displayed using UTF-8, making it more useful to debug any kind of service
2653 * improved: echo all debug messages even when there are characters in them which php deems to be in a wrong encoding;
2654 previously those messages would just disappear (this is visible e.g. in the debugger)
2656 * changed: debug info handling
2657 - at debug level 1, the rebuilt php objects are not dumped to screen (server-side already did that)
2658 - at debug level 1, curl communication info are not dumped to screen
2659 - at debug level 1, the tests echo payloads of failures; at debug level 2 all payloads
2661 * improved: makefiles have been replaced with a php_based pakefile
2663 * improved: the source for the manual is stored in asciidoc format, which can be displayed natively by GitHub
2664 with nice html formatting. Also the HTML version generated by hand and bundled in tarballs is much nicer
2665 to look at than previous versions
2667 * improved: all php code is now formatted according to the PSR-2 standard
2671 __Note:__ this is the last release of the library that will support PHP 5.1 and up. Future releases will target php 5.3
2672 as minimum supported version.
2674 * when using curl and keepalive, reset curl handle if we did not get back an http 200 response (eg a 302)
2676 * omit port on http 'Host' header if it is 80
2678 * test suite allows interrogating https servers ignoring their certs
2680 * method `setAcceptedCompression` was failing to disable reception of compressed responses if the client supported them
2684 This is the first release of the library to only support PHP 5. Some legacy code has been removed, and support for
2685 features such as exceptions and dateTime objects introduced.
2687 The "beta" tag is meant to indicate the fact that the refactoring has been more widespread than in precedent releases
2688 and that more changes are likely to be introduced with time - the library is still considered to be production
2691 * improved: removed all usage of php functions deprecated in php 5.3, usage of assign-by-ref when creating new objects
2694 * improved: add support for the `<ex:nil>` tag used by the apache library, both in input and output
2696 * improved: add support for dateTime objects in both in php_xmlrpc_encode and as parameter for constructor of xmlrpcval
2698 * improved: add support for timestamps as parameter for constructor of xmlrpcval
2700 * improved: add option `dates_as_objects` to `php_xmlrpc_decode` to return dateTime objects for xmlrpc datetimes
2702 * improved: add new method `SetCurlOptions` to xmrlpc_client to allow extra flexibility in tweaking http config, such as
2703 explicitly binding to an ip address
2705 * improved: add new method `SetUserAgent` to xmrlpc_client to to allow having different user-agent http headers
2707 * improved: add a new member variable in server class to allow fine-tuning of the encoding of returned values when the
2708 server is in 'phpvals' mode
2710 * improved: allow servers in 'xmlrpcvals' mode to also register plain php functions by defining them in the dispatch map
2711 with an added option
2713 * improved: catch exceptions thrown during execution of php functions exposed as methods by the server
2715 * fixed: bad encoding if same object is encoded twice using `php_xmlrpc_encode`
2719 __Note:__ this is the last release of the library that will support PHP 4. Future releases (if any) should target
2720 php 5.0 as minimum supported version.
2722 * fixed: encoding of utf-8 characters outside of the BMP plane
2724 * fixed: character set declarations surrounded by double quotes were not recognized in http headers
2726 * fixed: be more tolerant in detection of charset in http headers
2728 * fixed: fix detection of zlib.output_compression
2730 * fixed: use `feof()` to test if socket connections are to be closed instead of the number of bytes read (rare bug when
2731 communicating with some servers)
2733 * fixed: format floating point values using the correct decimal separator even when php locale is set to one that uses
2736 * fixed: improve robustness of the debugger when parsing weird results from non-compliant servers
2738 * php warning when receiving `false` in a bool value
2740 * improved: allow the add_to_map server method to add docs for single params too
2742 * improved: added the possibility to wrap for exposure as xmlrpc methods plain php class methods, object methods and even
2747 * fixed: work aroung bug in php 5.2.2 which broke support of `HTTP_RAW_POST_DATA`
2749 * fixed: is_dir parameter of `setCaCertificate()` method is reversed
2751 * fixed: a php warning in xmlrpc_client creator method
2753 * fixed: parsing of `1e+1` as valid float
2755 * fixed: allow errorlevel 3 to work when prev. error handler was a static method
2757 * fixed: usage of `client::setcookie()` for multiple cookies in non-ssl mode
2759 * improved: support for CP1252 charset is not part or the library but almost possible
2761 * improved: more info when curl is enabled and debug mode is on
2765 * fixed: debugger errors on php installs with `magic_quotes_gpc` on
2767 * fixed: support for https connections via proxy
2769 * fixed: `wrap_xmlrpc_method()` generated code failed to properly encode php objects
2771 * improved: slightly faster encoding of data which is internally UTF-8
2773 * improved: debugger always generates a `null` id for jsonrpc if user omits it
2775 * new: debugger can take advantage of a graphical value builder (it has to be downloaded separately, as part of jsxmlrpc
2776 package. See Appendix D for more details)
2778 * new: support for the `<NIL/>` xmlrpc extension. see below for more details
2780 * new: server support for the `system.getCapabilities` xmlrpc extension
2782 * new: `wrap_xmlrpc_method`, `wrap_xmlrpc_method()` accepts two new options: debug and return_on_fault
2786 * The wrap_php_function and wrap_xmlrpc_method functions have been moved out of the base library file _xmlrpc.inc_
2787 into a file of their own: _xmlrpc_wrappers.php_. You will have to include() / require() it in your scripts if
2788 you have been using those functions.
2789 For increased security, the automatic rebuilding of php object instances out ofreceived xmlrpc structs in
2790 `wrap_xmlrpc_method()` has been disabled (but it can be optionally re-enabled).
2791 Both `wrap_php_function()` and `wrap_xmlrpc_method()` functions accept many more options to fine tune their behaviour,
2792 including one to return the php code to be saved and later used as standalone php script
2794 * The constructor of xmlrpcval() values has seen some internal changes, and it will not throw a php warning anymore when
2795 invoked using an unknown xmlrpc type: the error will only be written to php error log. Also
2796 `new xmlrpcval('true', 'boolean')` is not supported anymore
2798 * The new function php_xmlrpc_decode_xml() will take the xml representation of either an xmlrpc request, response or
2799 single value and return the corresponding php-xmlrpc object instance
2801 * A new function wrap_xmlrpc_server()has been added, to wrap all (or some) of the methods exposed by a remote xmlrpc
2802 server into a php class
2804 * A new file has been added: _verify_compat.php_, to help users diagnose the level of compliance of their php
2805 installation with the library
2807 * Restored compatibility with php 4.0.5 (for those poor souls still stuck on it)
2809 * Method `xmlrpc_server->service()` now returns a value: either the response payload or xmlrpcresp object instance
2811 * Method `xmlrpc_server->add_to_map()` now accepts xmlrpc methods with no param definitions
2813 * Documentation for single parameters of exposed methods can be added to the dispatch map (and turned into html docs in
2814 conjunction with a future release of the 'extras' package)
2816 * Full response payload is saved into xmlrpcresp object for further debugging
2818 * The debugger can now generate code that wraps a remote method into a php function (works for jsonrpc, too); it also
2819 has better support for being activated via a single GET call (e.g. for integration into other tools)
2821 * Stricter parsing of incoming xmlrpc messages: two more invalid cases are now detected (double `data` element inside
2822 `array` and `struct`/`array` after scalar inside `value` element)
2824 * More logging of errors in a lot of situations
2826 * Javadoc documentation of lib files (almost) complete
2828 * Many performance tweaks and code cleanups, plus the usual crop of bugs fixed (see NEWS file for complete list of bugs)
2830 * Lib internals have been modified to provide better support for grafting extra functionality on top of it. Stay tuned
2831 for future releases of the EXTRAS package (or go read Appendix B)...
2835 * Added to the client class the possibility to use Digest and NTLM authentication methods (when using the CURL library)
2836 for connecting to servers and NTLM for connecting to proxies
2838 * Added to the client class the possibility to specify alternate certificate files/directories for authenticating the
2839 peer with when using HTTPS communication
2841 * Reviewed all examples and added a new demo file, containing a proxy to forward xmlrpc requests to other servers
2842 (useful e.g. for ajax coding)
2844 * The debugger has been upgraded to reflect the new client capabilities
2846 * All known bugs have been squashed, and the lib is more tolerant than ever of commonly-found mistakes
2848 === 2.0 Release candidate 3
2850 * Added to server class the property functions_parameters_type, that allows the server to register plain php functions
2851 as xmlrpc methods (i.e. functions that do not take an xmlrpcmsg object as unique param)
2853 * let server and client objects serialize calls using a specified character set encoding for the produced xml instead of
2854 US-ASCII (ISO-8859-1 and UTF-8 supported)
2856 * let `php_xmlrpc_decode` accept xmlrpcmsg objects as valid input
2858 * 'class::method' syntax is now accepted in the server dispatch map
2860 * `xmlrpc_clent::SetDebug()` accepts integer values instead of a boolean value, with debugging level 2 adding to the
2861 information printed to screen the complete client request
2863 === 2.0 Release candidate 2
2865 * Added a new property of the client object: `xmlrpc_client->return_type`, indicating whether calls to the
2866 send() method will return xmlrpcresp objects whose value() is an xmlrpcval object, a php value (automatically
2867 decoded) or the raw xml received from the server.
2869 * Added in the extras dir. two new library files: _jsonrpc.inc_ and _jsonrpcs.inc_ containing new classes that
2870 implement support for the json-rpc protocol (alpha quality code)
2872 * Added a new client method: `setKey($key, $keypass)` to be used in HTTPS connections
2874 * Added a new file containing some benchmarks in the testsuite directory
2876 === 2.0 Release candidate 1
2878 * Support for HTTP proxies (new method: `xmlrpc_client::setProxy()`)
2880 * Support HTTP compression of both requests and responses.
2881 Clients can specify what kind of compression they accept for responses between deflate/gzip/any, and whether to
2882 compress the requests.
2883 Servers by default compress responses to clients that explicitly declare support for compression (new methods:
2884 `xmlrpc_client::setAcceptedCompression()`, `xmlrpc_client::setRequestCompression()`).
2885 Note that the ZLIB php extension needs to be enabled in PHP to support compression.
2887 * Implement HTTP 1.1 connections, but only if CURL is enabled (added an extra parameter to
2888 `xmlrpc_client::xmlrpc_client` to set the desired HTTP protocol at creation time and a new supported value for
2889 the last parameter of `xmlrpc_client::send`, which now can be safely omitted if it has been specified at
2892 With PHP versions greater than 4.3.8 keep-alives are enabled by default for HTTP 1.1 connections. This should yield
2893 faster execution times when making multiple calls in sequence to the same xml-rpc server from a single client.
2895 * Introduce support for cookies.
2896 Cookies to be sent to the server with a request can be set using `xmlrpc_client::setCookie()`, while cookies
2897 received from the server are found in ++xmlrpcresp::cookies()++. It is left to the user to check for validity of
2898 received cookies and decide whether they apply to successive calls or not.
2900 * Better support for detecting different character set encodings of xml-rpc requests and responses: both client and
2901 server objects will correctly detect the charset encoding of received xml, and use an appropriate xml parser.
2903 Supported encodings are US-ASCII, UTF-8 and ISO-8859-1.
2905 * Added one new xmlrpcmsg constructor syntax, allowing usage of a single string with the complete URL of the target
2908 * Convert xml-rpc boolean values into native php values instead of 0 and 1
2910 * Force the `php_xmlrpc_encode` function to properly encode numerically indexed php arrays into xml-rpc arrays
2911 (numerically indexed php arrays always start with a key of 0 and increment keys by values of 1)
2913 * Prevent the `php_xmlrpc_encode` function from further re-encoding any objects of class ++xmlrpcval++ that
2914 are passed to it. This allows to call the function with arguments consisting of mixed php values / xmlrpcval objects
2916 * Allow a server to NOT respond to system.* method calls (setting the `$server->allow_system_funcs` property).
2918 * Implement a new xmlrpcval method to determine if a value of type struct has a member of a given name without having to
2919 loop trough all members: `xmlrpcval::structMemExists()`
2921 * Expand methods `xmlrpcval::addArray`, `addScalar` and `addStruct` allowing extra php values to be added to
2922 xmlrpcval objects already formed.
2924 * Let the `xmlrpc_client::send` method accept an XML string for sending instead of an xmlrpcmsg object, to
2925 facilitate debugging and integration with the php native xmlrpc extension
2927 * Extend the `php_xmlrpc_encode` and `php_xmlrpc_decode` functions to allow serialization and rebuilding of
2928 PHP objects. To successfully rebuild a serialized object, the object class must be defined in the deserializing end
2929 of the transfer. Note that object members of type resource will be deserialized as NULL values.
2931 Note that his has been implemented adding a "php_class" attribute to xml representation of xmlrpcval of STRUCT type,
2932 which, strictly speaking, breaks the xml-rpc spec. Other xmlrpc implementations are supposed to ignore such an
2933 attribute (unless they implement a brain-dead custom xml parser...), so it should be safe enabling it in
2934 heterogeneous environments. The activation of this feature is done by usage of an option passed as second parameter
2935 to both `php_xmlrpc_encode` and `php_xmlrpc_decode`.
2937 * Extend the `php_xmlrpc_encode` function to allow automatic serialization of iso8601-conforming php strings as
2938 datetime.iso8601 xmlrpcvals, by usage of an optional parameter
2940 * Added an automatic stub code generator for converting xmlrpc methods to php functions and vice-versa.
2942 This is done via two new functions: `wrap_php_function` and `wrap_xmlrpc_method`, and has many caveats,
2943 with php being a typeless language and all...
2945 * Allow object methods to be used in server dispatch map
2947 * Added a complete debugger solution, in the __debugger__ folder
2949 * Added configurable server-side debug messages, controlled by the new method `xmlrpc_server::SetDebug()`.
2950 At level 0, no debug messages are sent to the client; level 1 is the same as the old behaviour; at level 2 a lot
2951 more info is echoed back to the client, regarding the received call; at level 3 all warnings raised during server
2952 processing are trapped (this prevents breaking the xml to be echoed back to the client) and added to the debug info
2953 sent back to the client
2955 * New XML parsing code, yields smaller memory footprint and faster execution times, not to mention complete elimination
2956 of the dreaded __eval()__ construct, so prone to code injection exploits
2958 * Rewritten most of the error messages, making text more explicative
2960 ++++++++++++++++++++++++++++++++++++++
2961 <!-- Keep this comment at the end of the file
2966 sgml-minimize-attributes:nil
2967 sgml-always-quote-attributes:t
2970 sgml-parent-document:nil
2971 sgml-exposed-tags:nil
2972 sgml-local-catalogs:nil
2973 sgml-local-ecat-files:nil
2974 sgml-namecase-general:t
2975 sgml-general-insert-case:lower
2978 ++++++++++++++++++++++++++++++++++++++
git://git.onelab.eu / plcapi.git / blob