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. You can find the API documentation at link:$$http://gggeek.github.io/phpxmlrpc/doc-4/api/index.html$$[http://gggeek.github.io/phpxmlrpc/doc-4/api/index.html]
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/test.pl, extras/test.py:: Perl and Python programs to exercise server.php to test that some of the methods work.
138 lib/*:: a compatibility layer for applications which still rely on version 3 of the API
140 src/*:: the XML-RPC library classes. You can autoload these via Composer, or via a dedicated Autoloader class
142 tests/*:: the test suite for the library, written using PhpUnit, and the configuration to run it on Travis
149 Known bugs are tracked using the link:$$https://github.com/gggeek/phpxmlrpc/issues$$[GitHub issue tracker]
153 This started out as a bare framework. Many "nice" bits have been put in over time, but backwards compatibility has
154 always taken precedence over API cleanups. As such, you might find some API choices questionable.
156 Specifically, very little type validation or coercion has been put in. PHP being a loosely-typed language, this is
157 going to have to be done explicitly (in other words: you can call a lot of library functions passing them arguments
158 of the wrong type and receive an error message only much further down the code, where it will be difficult to
161 dateTime.iso8601 is supported opaquely. It can't be done natively as the XML-RPC specification explicitly forbids
162 passing of timezone specifiers in ISO8601 format dates. You can, however, use the PhpXmlRpc\Helper\Date class to do
163 the encoding and decoding for you.
165 Very little HTTP response checking is performed (e.g. HTTP redirects are not followed and the Content-Length HTTP
166 header, mandated by the xml-rpc spec, is not validated); cookie support still involves quite a bit of coding on the
169 Support for receiving from servers version 1 cookies (i.e. conforming to RFC 2965) is quite incomplete, and might cause
180 XML-RPC for PHP is offered "as-is" without any warranty or commitment to support. However, informal advice and help is
181 available via the XML-RPC for PHP website and mailing list.
183 * The __XML-RPC for PHP__ development is hosted on
184 link:$$https://github.com/gggeek/phpxmlrpc$$[github.com/gggeek/phpxmlrpc]. Bugs, feature requests and patches can be
185 posted to the link:$$https://github.com/gggeek/phpxmlrpc/issues$$[project's website].
187 * The __PHP XML-RPC interest mailing list__ is run by the original author. More details
188 link:$$http://lists.gnomehack.com/mailman/listinfo/phpxmlrpc$$[can be found here].
193 === The Jellyfish Book
195 image::progxmlrpc.s.gif[The Jellyfish Book]
196 Together with Simon St.Laurent and Joe Johnston, Edd Dumbill wrote a book on XML-RPC for O'Reilly and Associates on
197 XML-RPC. It features a rather fetching jellyfish on the cover.
199 Complete details of the book are link:$$http://www.oreilly.com/catalog/progxmlrpc/$$[available from O'Reilly's web site.]
201 Edd is responsible for the chapter on PHP, which includes a worked example of creating a forum server, and hooking it up
202 the O'Reilly's link:$$http://meerkat.oreillynet.com/$$[Meerkat] service in order to allow commenting on news stories
205 If you've benefited from the effort that has been put into writing this software, then please consider buying the book!
210 == Class documentation
217 The type i4 is accepted as a synonym
218 for int when creating xmlrpcval objects. The
219 xml parsing code will always convert i4 to
221 by this implementation as the canonical name for this type.
223 The type i8 on the other hand is considered as a separate type.
224 Note that the library will never output integers as 'i8' on its own,
225 even when php is compiled in 64-bit mode.
229 Base 64 encoding is performed transparently to the caller when
230 using this type. Decoding is also transparent. Therefore you ought
231 to consider it as a "binary" data type, for use when you want to
232 pass data that is not 7-bit clean.
236 The php values ++true++ and
237 ++1++ map to ++true++. All other
238 values (including the empty string) are converted to
243 Characters <, >;, ', ", &, are encoded using their
244 entity reference as < > ' " and
245 & All other characters outside of the ASCII range are
246 encoded using their character reference representation (e.g.
247 È for é). The XML-RPC spec recommends only encoding
248 ++< >++ but this implementation goes further,
249 for reasons explained by link:$$http://www.w3.org/TR/REC-xml#syntax$$[the XML 1.0 recommendation]. In particular, using character reference
250 representation has the advantage of producing XML that is valid
251 independently of the charset encoding assumed.
255 There is no support for encoding ++null++
256 values in the XML-RPC spec, but at least a couple of extensions (and
257 many toolkits) do support it. Before using ++null++
258 values in your messages, make sure that the responding party accepts
259 them, and uses the same encoding convention (see ...).
261 [[xmlrpcval-creation]]
263 ==== Xmlrpcval creation
265 The constructor is the normal way to create an
266 xmlrpcval. The constructor can take these
270 xmlrpcval xmlrpcvalnew
271 xmlrpcval string $stringVal xmlrpcvalnew
272 xmlrpcval mixed $scalarVal string$scalartyp xmlrpcvalnew
273 xmlrpcval array $arrayVal string $arraytyp The first constructor creates an empty value, which must be
274 altered using the methods addScalar,
275 addArray or addStruct before
278 The second constructor creates a simple string value.
280 The third constructor is used to create a scalar value. The
281 second parameter must be a name of an XML-RPC type. Valid types are:
282 "++int++", "++boolean++",
283 "++string++", "++double++",
284 "++dateTime.iso8601++", "++base64++" or
292 $myInt = new xmlrpcval(1267, "int");
293 $myString = new xmlrpcval("Hello, World!", "string");
294 $myBool = new xmlrpcval(1, "boolean");
295 $myString2 = new xmlrpcval(1.24, "string"); // note: this will serialize a php float value as xmlrpc string
299 The fourth constructor form can be used to compose complex
300 XML-RPC values. The first argument is either a simple array in the
301 case of an XML-RPC array or an associative
302 array in the case of a struct. The elements of
303 the array __must be xmlrpcval objects themselves__.
305 The second parameter must be either "++array++"
313 $myArray = new xmlrpcval(
315 new xmlrpcval("Tom"),
316 new xmlrpcval("Dick"),
317 new xmlrpcval("Harry")
322 $myStruct = new xmlrpcval(
324 "name" => new xmlrpcval("Tom", "string"),
325 "age" => new xmlrpcval(34, "int"),
326 "address" => new xmlrpcval(
328 "street" => new xmlrpcval("Fifht Ave", "string"),
329 "city" => new xmlrpcval("NY", "string")
337 See the file ++vardemo.php++ in this distribution
342 ==== Xmlrpc-client creation
344 The constructor accepts one of two possible syntaxes:
347 xmlrpc_clientstring$server_urlxmlrpc_clientnew
348 xmlrpc_clientstring$server_pathstring$server_hostnameint$server_port80string$transport'http'Here are a couple of usage examples of the first form:
354 $client = new xmlrpc_client("http://phpxmlrpc.sourceforge.net/server.php");
355 $another_client = new xmlrpc_client("https://james:bond@secret.service.com:443/xmlrpcserver?agent=007");
359 The second syntax does not allow to express a username and
360 password to be used for basic HTTP authorization as in the second
361 example above, but instead it allows to choose whether xmlrpc calls
362 will be made using the HTTP 1.0 or 1.1 protocol.
364 Here's another example client set up to query Userland's XML-RPC
365 server at __betty.userland.com__:
370 $client = new xmlrpc_client("/RPC2", "betty.userland.com", 80);
374 The server_port parameter is optional,
375 and if omitted will default to 80 when using HTTP and 443 when using
376 HTTPS (see the <<xmlrpc-client-send>> method
379 The transport parameter is optional, and
380 if omitted will default to 'http'. Allowed values are either
382 'http11'. Its value can be overridden with every call
383 to the send method. See the
384 send method below for more details about the
385 meaning of the different values.
392 The implementation of this class has been kept as simple to use as
393 possible. The constructor for the server basically does all the work.
394 Here's a minimal example:
400 function foo ($xmlrpcmsg) {
402 return new xmlrpcresp($some_xmlrpc_val);
406 function foobar($xmlrpcmsg) {
408 return new xmlrpcresp($some_xmlrpc_val);
412 $s = new xmlrpc_server(
414 "examples.myFunc1" => array("function" => "foo"),
415 "examples.myFunc2" => array("function" => "bar::foobar"),
420 This performs everything you need to do with a server. The single
421 constructor argument is an associative array from xmlrpc method names to
422 php function names. The incoming request is parsed and dispatched to the
423 relevant php function, which is responsible for returning a
424 xmlrpcresp object, that will be serialized back
428 ==== Method handler functions
430 Both php functions and class methods can be registered as xmlrpc
433 The synopsis of a method handler function is:
435 xmlrpcresp $resp = function (xmlrpcmsg $msg)
437 No text should be echoed 'to screen' by the handler function, or
438 it will break the xml response sent back to the client. This applies
439 also to error and warning messages that PHP prints to screen unless
440 the appropriate parameters have been set in the php.in file. Another
441 way to prevent echoing of errors inside the response and facilitate
442 debugging is to use the server SetDebug method with debug level 3 (see
443 ...). Exceptions thrown duting execution of handler functions are
444 caught by default and a XML-RPC error reponse is generated instead.
445 This behaviour can be finetuned by usage of the
446 exception_handling member variable (see
449 Note that if you implement a method with a name prefixed by
450 ++system.++ the handler function will be invoked by the
451 server with two parameters, the first being the server itself and the
452 second being the xmlrpcmsg object.
454 The same php function can be registered as handler of multiple
457 Here is a more detailed example of what the handler function
464 function foo ($xmlrpcmsg) {
465 global $xmlrpcerruser; // import user errcode base value
467 $meth = $xmlrpcmsg->method(); // retrieve method name
468 $par = $xmlrpcmsg->getParam(0); // retrieve value of first parameter - assumes at least one param received
469 $val = $par->scalarval(); // decode value of first parameter - assumes it is a scalar value
474 // this is an error condition
475 return new xmlrpcresp(0, $xmlrpcerruser+1, // user error 1
476 "There's a problem, Captain");
478 // this is a successful value being returned
479 return new xmlrpcresp(new xmlrpcval("All's fine!", "string"));
485 See __server.php__ in this distribution for
486 more examples of how to do this.
488 Since release 2.0RC3 there is a new, even simpler way of
489 registering php functions with the server. See section 5.7
493 ==== The dispatch map
495 The first argument to the xmlrpc_server
496 constructor is an array, called the __dispatch map__.
497 In this array is the information the server needs to service the
498 XML-RPC methods you define.
500 The dispatch map takes the form of an associative array of
501 associative arrays: the outer array has one entry for each method, the
502 key being the method name. The corresponding value is another
503 associative array, which can have the following members:
506 * ++function++ - this
507 entry is mandatory. It must be either a name of a function in the
508 global scope which services the XML-RPC method, or an array
509 containing an instance of an object and a static method name (for
510 static class methods the 'class::method' syntax is also
514 * ++signature++ - this
515 entry is an array containing the possible signatures (see <<signatures>>) for the method. If this entry is present
516 then the server will check that the correct number and type of
517 parameters have been sent for this method before dispatching
521 * ++docstring++ - this
522 entry is a string containing documentation for the method. The
523 documentation may contain HTML markup.
526 * ++$$signature_docs$$++ - this entry can be used
527 to provide documentation for the single parameters. It must match
528 in structure the 'signature' member. By default, only the
529 documenting_xmlrpc_server class in the
530 extras package will take advantage of this, since the
531 "system.methodHelp" protocol does not support documenting method
532 parameters individually.
535 * ++$$parameters_type$$++ - this entry can be used
536 when the server is working in 'xmlrpcvals' mode (see ...) to
537 define one or more entries in the dispatch map as being functions
538 that follow the 'phpvals' calling convention. The only useful
539 value is currently the string ++phpvals++.
541 Look at the __server.php__ example in the
542 distribution to see what a dispatch map looks like.
546 ==== Method signatures
548 A signature is a description of a method's return type and its
549 parameter types. A method may have more than one signature.
551 Within a server's dispatch map, each method has an array of
552 possible signatures. Each signature is an array of types. The first
553 entry is the return type. For instance, the method
556 string examples.getStateName(int)
563 array($xmlrpcString, $xmlrpcInt)
567 and, assuming that it is the only possible signature for the
568 method, it might be used like this in server creation:
572 $findstate_sig = array(array($xmlrpcString, $xmlrpcInt));
574 $findstate_doc = 'When passed an integer between 1 and 51 returns the
575 name of a US state, where the integer is the index of that state name
576 in an alphabetic order.';
578 $s = new xmlrpc_server( array(
579 "examples.getStateName" => array(
580 "function" => "findstate",
581 "signature" => $findstate_sig,
582 "docstring" => $findstate_doc
589 Note that method signatures do not allow to check nested
590 parameters, e.g. the number, names and types of the members of a
591 struct param cannot be validated.
593 If a method that you want to expose has a definite number of
594 parameters, but each of those parameters could reasonably be of
595 multiple types, the array of acceptable signatures will easily grow
596 into a combinatorial explosion. To avoid such a situation, the lib
597 defines the global var $xmlrpcValue, which can be
598 used in method signatures as a placeholder for 'any xmlrpc
605 $echoback_sig = array(array($xmlrpcValue, $xmlrpcValue));
607 $findstate_doc = 'Echoes back to the client the received value, regardless of its type';
609 $s = new xmlrpc_server( array(
611 "function" => "echoback",
612 "signature" => $echoback_sig, // this sig guarantees that the method handler will be called with one and only one parameter
613 "docstring" => $echoback_doc
618 Methods system.listMethods,
620 system.methodSignature and
621 system.multicall are already defined by the
622 server, and should not be reimplemented (see Reserved Methods
626 ==== Delaying the server response
628 You may want to construct the server, but for some reason not
629 fulfill the request immediately (security verification, for instance).
630 If you omit to pass to the constructor the dispatch map or pass it a
631 second argument of ++0++ this will have the desired
632 effect. You can then use the service() method of
633 the server class to service the request. For example:
639 $s = new xmlrpc_server($myDispMap, 0); // second parameter = 0 prevents automatic servicing of request
641 // ... some code that does other stuff here
647 Note that the service method will print
648 the complete result payload to screen and send appropriate HTTP
649 headers back to the client, but also return the response object. This
650 permits further manipulation of the response, possibly in combination
651 with output buffering.
653 To prevent the server from sending HTTP headers back to the
654 client, you can pass a second parameter with a value of
655 ++TRUE++ to the service
656 method. In this case, the response payload will be returned instead of
659 Xmlrpc requests retrieved by other means than HTTP POST bodies
660 can also be processed. For example:
666 $s = new xmlrpc_server(); // not passing a dispatch map prevents automatic servicing of request
668 // ... some code that does other stuff here, including setting dispatch map into server object
670 $resp = $s->service($xmlrpc_request_body, true); // parse a variable instead of POST body, retrieve response payload
672 // ... some code that does other stuff with xml response $resp here
677 ==== Modifying the server behaviour
679 A couple of methods / class variables are available to modify
680 the behaviour of the server. The only way to take advantage of their
681 existence is by usage of a delayed server response (see above)
686 This function controls weather the server is going to echo
687 debugging messages back to the client as comments in response body.
688 Valid values: 0,1,2,3, with 1 being the default. At level 0, no
689 debug info is returned to the client. At level 2, the complete
690 client request is added to the response, as part of the xml
691 comments. At level 3, a new PHP error handler is set when executing
692 user functions exposed as server methods, and all non-fatal errors
693 are trapped and added as comments into the response.
696 ===== allow_system_funcs
698 Default_value: TRUE. When set to FALSE, disables support for
699 System.xxx functions in the server. It
700 might be useful e.g. if you do not wish the server to respond to
701 requests to System.ListMethods.
704 ===== compress_response
706 When set to TRUE, enables the server to take advantage of HTTP
707 compression, otherwise disables it. Responses will be transparently
708 compressed, but only when an xmlrpc-client declares its support for
709 compression in the HTTP headers of the request.
711 Note that the ZLIB php extension must be installed for this to
712 work. If it is, compress_response will default to
716 ===== exception_handling
718 This variable controls the behaviour of the server when an
719 exception is thrown by a method handler php function. Valid values:
720 0,1,2, with 0 being the default. At level 0, the server catches the
721 exception and return an 'internal error' xmlrpc response; at 1 it
722 catches the exceptions and return an xmlrpc response with the error
723 code and error message corresponding to the exception that was
724 thron; at 2 = the exception is floated to the upper layers in the
728 ===== response_charset_encoding
730 Charset encoding to be used for response (only affects string
733 If it can, the server will convert the generated response from
734 internal_encoding to the intended one.
736 Valid values are: a supported xml encoding (only UTF-8 and
737 ISO-8859-1 at present, unless mbstring is enabled), null (leave
738 charset unspecified in response and convert output stream to
739 US_ASCII), 'default' (use xmlrpc library default as specified in
740 xmlrpc.inc, convert output stream if needed), or 'auto' (use
741 client-specified charset encoding or same as request if request
742 headers do not specify it (unless request is US-ASCII: then use
743 library default anyway).
748 Fault codes for your servers should start at the value indicated
749 by the global ++$xmlrpcerruser++ + 1.
751 Standard errors returned by the server include:
753 ++1++ Unknown method:: Returned if the server was asked to dispatch a method it
756 ++2++ Invalid return payload:: This error is actually generated by the client, not
757 server, code, but signifies that a server returned something it
758 couldn't understand. A more detailed error report is sometimes
759 added onto the end of the phrase above.
761 ++3++ Incorrect parameters:: This error is generated when the server has signature(s)
762 defined for a method, and the parameters passed by the client do
763 not match any of signatures.
765 ++4++ Can't introspect: method unknown:: This error is generated by the builtin
766 system.* methods when any kind of
767 introspection is attempted on a method undefined by the
770 ++5++ Didn't receive 200 OK from remote server:: This error is generated by the client when a remote server
771 doesn't return HTTP/1.1 200 OK in response to a request. A more
772 detailed error report is added onto the end of the phrase
775 ++6++ No data received from server:: This error is generated by the client when a remote server
776 returns HTTP/1.1 200 OK in response to a request, but no
777 response body follows the HTTP headers.
779 ++7++ No SSL support compiled in:: This error is generated by the client when trying to send
780 a request with HTTPS and the CURL extension is not available to
783 ++8++ CURL error:: This error is generated by the client when trying to send
784 a request with HTTPS and the HTTPS communication fails.
786 ++9-14++ multicall errors:: These errors are generated by the server when something
787 fails inside a system.multicall request.
789 ++100-++ XML parse errors:: Returns 100 plus the XML parser error code for the fault
790 that occurred. The faultString returned
791 explains where the parse error was in the incoming XML
795 ==== 'New style' servers
797 In the same spirit of simplification that inspired the
798 xmlrpc_client::return_type class variable, a new
799 class variable has been added to the server class:
800 functions_parameters_type. When set to 'phpvals',
801 the functions registered in the server dispatch map will be called
802 with plain php values as parameters, instead of a single xmlrpcmsg
803 instance parameter. The return value of those functions is expected to
804 be a plain php value, too. An example is worth a thousand
809 function foo($usr_id, $out_lang='en') {
810 global $xmlrpcerruser;
814 if ($someErrorCondition)
815 return new xmlrpcresp(0, $xmlrpcerruser+1, 'DOH!');
820 'picture' => new xmlrpcval(file_get_contents($picOfTheGuy), 'base64')
824 $s = new xmlrpc_server(
826 "examples.myFunc" => array(
827 "function" => "bar::foobar",
828 "signature" => array(
829 array($xmlrpcString, $xmlrpcInt),
830 array($xmlrpcString, $xmlrpcInt, $xmlrpcString)
834 $s->functions_parameters_type = 'phpvals';
839 There are a few things to keep in mind when using this
842 to return an xmlrpc error, the method handler function must
843 return an instance of xmlrpcresp. The only
844 other way for the server to know when an error response should be
845 served to the client is to throw an exception and set the server's
846 exception_handling memeber var to 1;
848 to return a base64 value, the method handler function must
849 encode it on its own, creating an instance of an xmlrpcval
852 the method handler function cannot determine the name of the
853 xmlrpc method it is serving, unlike standard handler functions that
854 can retrieve it from the message object;
856 when receiving nested parameters, the method handler function
857 has no way to distinguish a php string that was sent as base64 value
858 from one that was sent as a string value;
860 this has a direct consequence on the support of
861 system.multicall: a method whose signature contains datetime or base64
862 values will not be available to multicall calls;
864 last but not least, the direct parsing of xml to php values is
865 much faster than using xmlrpcvals, and allows the library to handle
866 much bigger messages without allocating all available server memory or
867 smashing PHP recursive call stack.
874 Many global variables are defined in the xmlrpc.inc file. Some of
875 those are meant to be used as constants (and modifying their value might
876 cause unpredictable behaviour), while some others can be modified in your
877 php scripts to alter the behaviour of the xml-rpc client and
881 === "Constant" variables
886 $xmlrpcerruser800The minimum value for errors reported by user
887 implemented XML-RPC servers. Error numbers lower than that are
888 reserved for library usage.
891 ==== $xmlrpcI4, $xmlrpcI8 $xmlrpcInt, $xmlrpcBoolean, $xmlrpcDouble, $xmlrpcString, $xmlrpcDateTime, $xmlrpcBase64, $xmlrpcArray, $xmlrpcStruct, $xmlrpcValue, $xmlrpcNull
893 For convenience the strings representing the XML-RPC types have
894 been encoded as global variables:
901 $xmlrpcBoolean="boolean";
902 $xmlrpcDouble="double";
903 $xmlrpcString="string";
904 $xmlrpcDateTime="dateTime.iso8601";
905 $xmlrpcBase64="base64";
906 $xmlrpcArray="array";
907 $xmlrpcStruct="struct";
908 $xmlrpcValue="undefined";
913 ==== $xmlrpcTypes, $xmlrpc_valid_parents, $xmlrpcerr, $xmlrpcstr, $xmlrpcerrxml, $xmlrpc_backslash, $_xh, $xml_iso88591_Entities, $xmlEntities, $xmlrpcs_capabilities
915 Reserved for internal usage.
918 === Variables whose value can be modified
920 [[xmlrpc-defencoding]]
922 ==== xmlrpc_defencoding
924 $xmlrpc_defencoding"UTF8"This variable defines the character set encoding that will be
925 used by the xml-rpc client and server to decode the received messages,
926 when a specific charset declaration is not found (in the messages sent
927 non-ascii chars are always encoded using character references, so that
928 the produced xml is valid regardless of the charset encoding
931 Allowed values: ++"UTF8"++,
932 ++"ISO-8859-1"++, ++"ASCII".++
934 Note that the appropriate RFC actually mandates that XML
935 received over HTTP without indication of charset encoding be treated
936 as US-ASCII, but many servers and clients 'in the wild' violate the
937 standard, and assume the default encoding is UTF-8.
940 ==== xmlrpc_internalencoding
942 $xmlrpc_internalencoding"ISO-8859-1"This variable defines the character set encoding
943 that the library uses to transparently encode into valid XML the
944 xml-rpc values created by the user and to re-encode the received
945 xml-rpc values when it passes them to the PHP application. It only
946 affects xml-rpc values of string type. It is a separate value from
947 xmlrpc_defencoding, allowing e.g. to send/receive xml messages encoded
948 on-the-wire in US-ASCII and process them as UTF-8. It defaults to the
949 character set used internally by PHP (unless you are running an
950 MBString-enabled installation), so you should change it only in
951 special situations, if e.g. the string values exchanged in the xml-rpc
952 messages are directly inserted into / fetched from a database
953 configured to return UTF8 encoded strings to PHP. Example
961 include('xmlrpc.inc');
962 $xmlrpc_internalencoding = 'UTF-8'; // this has to be set after the inclusion above
963 $v = new xmlrpcval('κόÏ
\83με'); // This xmlrpc value will be correctly serialized as the greek word 'kosme'
969 $xmlrpcName"XML-RPC for PHP"The string representation of the name of the XML-RPC
970 for PHP library. It is used by the client for building the User-Agent
971 HTTP header that is sent with every request to the server. You can
972 change its value if you need to customize the User-Agent
978 $xmlrpcVersion"2.2"The string representation of the version number of
979 the XML-RPC for PHP library in use. It is used by the client for
980 building the User-Agent HTTP header that is sent with every request to
981 the server. You can change its value if you need to customize the
985 ==== xmlrpc_null_extension
987 When set to TRUE, the lib will enable
988 support for the <NIL/> (and <EX:NIL/>) xmlrpc value, as
989 per the extension to the standard proposed here. This means that
990 <NIL> and <EX:NIL/> tags received will be parsed as valid
991 xmlrpc, and the corresponding xmlrpcvals will return "null" for
995 ==== xmlrpc_null_apache_encoding
997 When set to ++TRUE++, php NULL values encoded
998 into xmlrpcval objects get serialized using the
999 ++<EX:NIL/>++ tag instead of
1000 ++<NIL/>++. Please note that both forms are
1001 always accepted as input regardless of the value of this
1009 XML-RPC for PHP contains some helper functions which you can use to
1010 make processing of XML-RPC requests easier.
1015 The XML-RPC specification has this to say on dates:
1019 [[wrap_xmlrpc_method]]
1020 Don't assume a timezone. It should be
1021 specified by the server in its documentation what assumptions it makes
1026 Unfortunately, this means that date processing isn't
1027 straightforward. Although XML-RPC uses ISO 8601 format dates, it doesn't
1028 use the timezone specifier.
1030 We strongly recommend that in every case where you pass dates in
1031 XML-RPC calls, you use UTC (GMT) as your timezone. Most computer
1032 languages include routines for handling GMT times natively, and you
1033 won't have to translate between timezones.
1035 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
1036 8601 specification. Note that XML-RPC uses exactly one of the available
1037 representations: CCYYMMDDTHH:MM:SS.
1043 stringiso8601_encodestring$time_tint$utc0Returns an ISO 8601 formatted date generated from the UNIX
1044 timestamp $time_t, as returned by the PHP
1047 The argument $utc can be omitted, in
1048 which case it defaults to ++0++. If it is set to
1049 ++1++, then the function corrects the time passed in
1050 for UTC. Example: if you're in the GMT-6:00 timezone and set
1051 $utc, you will receive a date representation
1052 six hours ahead of your local time.
1054 The included demo program __vardemo.php__
1055 includes a demonstration of this function.
1061 intiso8601_decodestring$isoStringint$utc0Returns a UNIX timestamp from an ISO 8601 encoded time and date
1062 string passed in. If $utc is
1063 ++1++ then $isoString is assumed
1064 to be in the UTC timezone, and thus the result is also UTC: otherwise,
1065 the timezone is assumed to be your local timezone and you receive a
1070 === Easy use with nested PHP values
1072 Dan Libby was kind enough to contribute two helper functions that
1073 make it easier to translate to and from PHP values. This makes it easier
1074 to deal with complex structures. At the moment support is limited to
1075 int, double, string,
1076 array, datetime and struct
1077 datatypes; note also that all PHP arrays are encoded as structs, except
1078 arrays whose keys are integer numbers starting with 0 and incremented by
1081 These functions reside in __xmlrpc.inc__.
1085 ==== php_xmlrpc_decode
1087 mixedphp_xmlrpc_decodexmlrpcval$xmlrpc_valarray$optionsarrayphp_xmlrpc_decodexmlrpcmsg$xmlrpcmsg_valstring$optionsReturns a native PHP value corresponding to the values found in
1088 the xmlrpcval $xmlrpc_val,
1089 translated into PHP types. Base-64 and datetime values are
1090 automatically decoded to strings.
1092 In the second form, returns an array containing the parameters
1094 xmlrpcmsg_val, decoded
1097 The options parameter is optional. If
1098 specified, it must consist of an array of options to be enabled in the
1099 decoding process. At the moment the only valid option are
1101 ++$$dates_as_objects$$++. When the first is set, php
1102 objects that have been converted to xml-rpc structs using the
1103 php_xmlrpc_encode function and a corresponding
1104 encoding option will be converted back into object values instead of
1105 arrays (provided that the class definition is available at
1106 reconstruction time). When the second is set, XML-RPC datetime values
1107 will be converted into native dateTime objects
1110 ____WARNING__:__ please take
1111 extreme care before enabling the decode_php_objs
1112 option: when php objects are rebuilt from the received xml, their
1113 constructor function will be silently invoked. This means that you are
1114 allowing the remote end to trigger execution of uncontrolled PHP code
1115 on your server, opening the door to code injection exploits. Only
1116 enable this option when you have complete trust of the remote
1123 // wrapper to expose an existing php function as xmlrpc method handler
1124 function foo_wrapper($m)
1126 $params = php_xmlrpc_decode($m);
1127 $retval = call_user_func_array('foo', $params);
1128 return new xmlrpcresp(new xmlrpcval($retval)); // foo return value will be serialized as string
1131 $s = new xmlrpc_server(array(
1132 "examples.myFunc1" => array(
1133 "function" => "foo_wrapper",
1141 ==== php_xmlrpc_encode
1143 xmlrpcvalphp_xmlrpc_encodemixed$phpvalarray$optionsReturns an xmlrpcval object populated with the PHP
1144 values in $phpval. Works recursively on arrays
1145 and objects, encoding numerically indexed php arrays into array-type
1146 xmlrpcval objects and non numerically indexed php arrays into
1147 struct-type xmlrpcval objects. Php objects are encoded into
1148 struct-type xmlrpcvals, excepted for php values that are already
1149 instances of the xmlrpcval class or descendants thereof, which will
1150 not be further encoded. Note that there's no support for encoding php
1151 values into base-64 values. Encoding of date-times is optionally
1152 carried on on php strings with the correct format.
1154 The options parameter is optional. If
1155 specified, it must consist of an array of options to be enabled in the
1156 encoding process. At the moment the only valid options are
1157 encode_php_objs, ++$$null_extension$$++
1160 The first will enable the creation of 'particular' xmlrpcval
1161 objects out of php objects, that add a "php_class" xml attribute to
1162 their serialized representation. This attribute allows the function
1163 php_xmlrpc_decode to rebuild the native php objects (provided that the
1164 same class definition exists on both sides of the communication). The
1165 second allows to encode php ++NULL++ values to the
1167 ++<EX:NIL>++, see ...) tag. The last encodes any
1168 string that matches the ISO8601 format into an XML-RPC
1175 // the easy way to build a complex xml-rpc struct, showing nested base64 value and datetime values
1176 $val = php_xmlrpc_encode(array(
1177 'first struct_element: an int' => 666,
1178 'second: an array' => array ('apple', 'orange', 'banana'),
1179 'third: a base64 element' => new xmlrpcval('hello world', 'base64'),
1180 'fourth: a datetime' => '20060107T01:53:00'
1181 ), array('auto_dates'));
1185 ==== php_xmlrpc_decode_xml
1187 xmlrpcval | xmlrpcresp |
1188 xmlrpcmsgphp_xmlrpc_decode_xmlstring$xmlarray$optionsDecodes the xml representation of either an xmlrpc request,
1189 response or single value, returning the corresponding php-xmlrpc
1190 object, or ++FALSE++ in case of an error.
1192 The options parameter is optional. If
1193 specified, it must consist of an array of options to be enabled in the
1194 decoding process. At the moment, no option is supported.
1200 $text = '<value><array><data><value>Hello world</value></data></array></value>';
1201 $val = php_xmlrpc_decode_xml($text);
1202 if ($val) echo 'Found a value of type '.$val->kindOf(); else echo 'Found invalid xml';
1206 === Automatic conversion of php functions into xmlrpc methods (and vice versa)
1208 For the extremely lazy coder, helper functions have been added
1209 that allow to convert a php function into an xmlrpc method, and a
1210 remotely exposed xmlrpc method into a local php function - or a set of
1211 methods into a php class. Note that these comes with many caveat.
1214 ==== wrap_xmlrpc_method
1216 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
1217 function that will call the remote method and return results using
1218 native php types for both params and results. The generated php
1219 function will return an xmlrpcresp object for failed xmlrpc
1222 The second syntax is deprecated, and is listed here only for
1223 backward compatibility.
1225 The server must support the
1226 system.methodSignature xmlrpc method call for
1227 this function to work.
1229 The client param must be a valid
1230 xmlrpc_client object, previously created with the address of the
1231 target xmlrpc server, and to which the preferred communication options
1234 The optional parameters can be passed as array key,value pairs
1235 in the extra_options param.
1237 The signum optional param has the purpose
1238 of indicating which method signature to use, if the given server
1239 method has multiple signatures (defaults to 0).
1242 protocol optional params are the same as in the
1243 xmlrpc_client::send() method.
1245 If set, the optional new_function_name
1246 parameter indicates which name should be used for the generated
1247 function. In case it is not set the function name will be
1250 If the ++$$return_source$$++ optional parameter is
1251 set, the function will return the php source code to build the wrapper
1252 function, instead of evaluating it (useful to save the code and use it
1253 later as stand-alone xmlrpc client).
1255 If the ++$$encode_php_objs$$++ optional parameter is
1256 set, instances of php objects later passed as parameters to the newly
1257 created function will receive a 'special' treatment that allows the
1258 server to rebuild them as php objects instead of simple arrays. Note
1259 that this entails using a "slightly augmented" version of the xmlrpc
1260 protocol (ie. using element attributes), which might not be understood
1261 by xmlrpc servers implemented using other libraries.
1263 If the ++$$decode_php_objs$$++ optional parameter is
1264 set, instances of php objects that have been appropriately encoded by
1265 the server using a coordinate option will be deserialized as php
1266 objects instead of simple arrays (the same class definition should be
1267 present server side and client side).
1269 __Note that this might pose a security risk__,
1270 since in order to rebuild the object instances their constructor
1271 method has to be invoked, and this means that the remote server can
1272 trigger execution of unforeseen php code on the client: not really a
1273 code injection, but almost. Please enable this option only when you
1274 trust the remote server.
1276 In case of an error during generation of the wrapper function,
1277 FALSE is returned, otherwise the name (or source code) of the new
1280 Known limitations: server must support
1281 system.methodsignature for the wanted xmlrpc
1282 method; for methods that expose multiple signatures, only one can be
1283 picked; for remote calls with nested xmlrpc params, the caller of the
1284 generated php function has to encode on its own the params passed to
1285 the php function if these are structs or arrays whose (sub)members
1286 include values of type base64.
1288 Note: calling the generated php function 'might' be slow: a new
1289 xmlrpc client is created on every invocation and an xmlrpc-connection
1290 opened+closed. An extra 'debug' param is appended to the parameter
1291 list of the generated php function, useful for debugging
1300 $c = new xmlrpc_client('http://phpxmlrpc.sourceforge.net/server.php');
1302 $function = wrap_xmlrpc_method($client, 'examples.getStateName');
1305 die('Cannot introspect remote method');
1308 $statename = $function($a);
1309 if (is_a($statename, 'xmlrpcresp')) // call failed
1311 echo 'Call failed: '.$statename->faultCode().'. Calling again with debug on';
1312 $function($a, true);
1315 echo "OK, state nr. $stateno is $statename";
1320 [[wrap_php_function]]
1322 ==== wrap_php_function
1324 arraywrap_php_functionstring$funcnamestring$wrapper_function_namearray$extra_optionsGiven a user-defined PHP function, create a PHP 'wrapper'
1325 function that can be exposed as xmlrpc method from an xmlrpc_server
1326 object and called from remote clients, and return the appropriate
1327 definition to be added to a server's dispatch map.
1329 The optional $wrapper_function_name
1330 specifies the name that will be used for the auto-generated
1333 Since php is a typeless language, to infer types of input and
1334 output parameters, it relies on parsing the javadoc-style comment
1335 block associated with the given function. Usage of xmlrpc native types
1336 (such as datetime.dateTime.iso8601 and base64) in the docblock @param
1337 tag is also allowed, if you need the php function to receive/send data
1338 in that particular format (note that base64 encoding/decoding is
1339 transparently carried out by the lib, while datetime vals are passed
1342 Known limitations: only works for
1343 user-defined functions, not for PHP internal functions (reflection
1344 does not support retrieving number/type of params for those); the
1345 wrapped php function will not be able to programmatically return an
1346 xmlrpc error response.
1348 If the ++$$return_source$$++ optional parameter is
1349 set, the function will return the php source code to build the wrapper
1350 function, instead of evaluating it (useful to save the code and use it
1351 later in a stand-alone xmlrpc server). It will be in the stored in the
1352 ++source++ member of the returned array.
1354 If the ++$$suppress_warnings$$++ optional parameter
1355 is set, any runtime warning generated while processing the
1356 user-defined php function will be catched and not be printed in the
1357 generated xml response.
1359 If the extra_options array contains the
1360 ++$$encode_php_objs$$++ value, wrapped functions returning
1361 php objects will generate "special" xmlrpc responses: when the xmlrpc
1362 decoding of those responses is carried out by this same lib, using the
1363 appropriate param in php_xmlrpc_decode(), the objects will be
1366 In short: php objects can be serialized, too (except for their
1367 resource members), using this function. Other libs might choke on the
1368 very same xml that will be generated in this case (i.e. it has a
1369 nonstandard attribute on struct element tags)
1371 If the ++$$decode_php_objs$$++ optional parameter is
1372 set, instances of php objects that have been appropriately encoded by
1373 the client using a coordinate option will be deserialized and passed
1374 to the user function as php objects instead of simple arrays (the same
1375 class definition should be present server side and client
1378 __Note that this might pose a security risk__,
1379 since in order to rebuild the object instances their constructor
1380 method has to be invoked, and this means that the remote client can
1381 trigger execution of unforeseen php code on the server: not really a
1382 code injection, but almost. Please enable this option only when you
1383 trust the remote clients.
1391 * State name from state number decoder. NB: do NOT remove this comment block.
1392 * @param integer $stateno the state number
1393 * @return string the name of the state (or error description)
1395 function findstate($stateno)
1398 if (isset($stateNames[$stateno-1]))
1400 return $stateNames[$stateno-1];
1404 return "I don't have a state for the index '" . $stateno . "'";
1408 // wrap php function, build xmlrpc server
1410 $findstate_sig = wrap_php_function('findstate');
1412 $methods['examples.getStateName'] = $findstate_sig;
1413 $srv = new xmlrpc_server($methods);
1419 === Functions removed from the library
1421 The following two functions have been deprecated in version 1.1 of
1422 the library, and removed in version 2, in order to avoid conflicts with
1423 the EPI xml-rpc library, which also defines two functions with the same
1426 To ease the transition to the new naming scheme and avoid breaking
1427 existing implementations, the following scheme has been adopted:
1429 * If EPI-XMLRPC is not active in the current PHP installation,
1430 the constant `XMLRPC_EPI_ENABLED` will be set to
1434 * If EPI-XMLRPC is active in the current PHP installation, the
1435 constant `XMLRPC_EPI_ENABLED` will be set to
1440 The following documentation is kept for historical
1447 mixedx mlrpc_decode xmlrpcval $xmlrpc_val Alias for php_xmlrpc_decode.
1453 xmlrpcval xmlrpc_encode mixed $phpvalAlias for php_xmlrpc_encode.
1459 ==== xmlrpc_debugmsg
1461 void xmlrpc_debugmsgstring$debugstringSends the contents of $debugstring in XML
1462 comments in the server return payload. If a PHP client has debugging
1463 turned on, the user will be able to see server debug
1466 Use this function in your methods so you can pass back
1467 diagnostic information. It is only available from
1475 In order to extend the functionality offered by XML-RPC servers
1476 without impacting on the protocol, reserved methods are supported in this
1479 All methods starting with system. are
1480 considered reserved by the server. PHP for XML-RPC itself provides four
1481 special methods, detailed in this chapter.
1483 Note that all server objects will automatically respond to clients
1484 querying these methods, unless the property
1485 allow_system_funcs has been set to
1486 false before calling the
1487 service() method. This might pose a security risk
1488 if the server is exposed to public access, e.g. on the internet.
1491 === system.getCapabilities
1494 === system.listMethods
1496 This method may be used to enumerate the methods implemented by
1499 The system.listMethods method requires no
1500 parameters. It returns an array of strings, each of which is the name of
1501 a method implemented by the server.
1505 === system.methodSignature
1507 This method takes one parameter, the name of a method implemented
1508 by the XML-RPC server.
1510 It returns an array of possible signatures for this method. A
1511 signature is an array of types. The first of these types is the return
1512 type of the method, the rest are parameters.
1514 Multiple signatures (i.e. overloading) are permitted: this is the
1515 reason that an array of signatures are returned by this method.
1517 Signatures themselves are restricted to the top level parameters
1518 expected by a method. For instance if a method expects one array of
1519 structs as a parameter, and it returns a string, its signature is simply
1520 "string, array". If it expects three integers, its signature is "string,
1523 For parameters that can be of more than one type, the "undefined"
1524 string is supported.
1526 If no signature is defined for the method, a not-array value is
1527 returned. Therefore this is the way to test for a non-signature, if
1528 $resp below is the response object from a method
1529 call to system.methodSignature:
1534 $v = $resp->value();
1535 if ($v->kindOf() != "array") {
1536 // then the method did not have a signature defined
1541 See the __introspect.php__ demo included in this
1542 distribution for an example of using this method.
1546 === system.methodHelp
1548 This method takes one parameter, the name of a method implemented
1549 by the XML-RPC server.
1551 It returns a documentation string describing the use of that
1552 method. If no such string is available, an empty string is
1555 The documentation string may contain HTML markup.
1557 === system.multicall
1559 This method takes one parameter, an array of 'request' struct
1560 types. Each request struct must contain a
1561 methodName member of type string and a
1562 params member of type array, and corresponds to
1563 the invocation of the corresponding method.
1565 It returns a response of type array, with each value of the array
1566 being either an error struct (containing the faultCode and faultString
1567 members) or the successful response value of the corresponding single
1575 The best examples are to be found in the sample files included with
1576 the distribution. Some are included here.
1580 === XML-RPC client: state name query
1582 Code to get the corresponding state name from a number (1-50) from
1583 the demo server available on SourceForge
1588 $m = new xmlrpcmsg('examples.getStateName',
1589 array(new xmlrpcval($HTTP_POST_VARS["stateno"], "int")));
1590 $c = new xmlrpc_client("/server.php", "phpxmlrpc.sourceforge.net", 80);
1592 if (!$r->faultCode()) {
1594 print "State number " . htmlentities($HTTP_POST_VARS["stateno"]) . " is " .
1595 htmlentities($v->scalarval()) . "<BR>";
1596 print "<HR>I got this value back<BR><PRE>" .
1597 htmlentities($r->serialize()) . "</PRE><HR>\n";
1600 print "Code: " . htmlentities($r->faultCode()) . "<BR>" .
1601 "Reason: '" . htmlentities($r->faultString()) . "'<BR>";
1606 === Executing a multicall call
1614 == Frequently Asked Questions
1616 ==== How to send custom XML as payload of a method call::
1618 Unfortunately, at the time the XML-RPC spec was designed, support
1619 for namespaces in XML was not as ubiquitous as it is now. As a
1620 consequence, no support was provided in the protocol for embedding XML
1621 elements from other namespaces into an xmlrpc request.
1623 To send an XML "chunk" as payload of a method call or response,
1624 two options are available: either send the complete XML block as a
1625 string xmlrpc value, or as a base64 value. Since the '<' character in
1626 string values is encoded as '<' in the xml payload of the method
1627 call, the XML string will not break the surrounding xmlrpc, unless
1628 characters outside of the assumed character set are used. The second
1629 method has the added benefits of working independently of the charset
1630 encoding used for the xml to be transmitted, and preserving exactly
1631 whitespace, whilst incurring in some extra message length and cpu load
1632 (for carrying out the base64 encoding/decoding).
1635 ==== Is there any limitation on the size of the requests / responses that can be successfully sent?::
1637 Yes. But I have no hard figure to give; it most likely will depend
1638 on the version of PHP in usage and its configuration.
1640 Keep in mind that this library is not optimized for speed nor for
1641 memory usage. Better alternatives exist when there are strict
1642 requirements on throughput or resource usage, such as the php native
1643 xmlrpc extension (see the PHP manual for more information).
1645 Keep in mind also that HTTP is probably not the best choice in
1646 such a situation, and XML is a deadly enemy. CSV formatted data over
1647 socket would be much more efficient.
1649 If you really need to move a massive amount of data around, and
1650 you are crazy enough to do it using phpxmlrpc, your best bet is to
1651 bypass usage of the xmlrpcval objects, at least in the decoding phase,
1652 and have the server (or client) object return to the calling function
1653 directly php values (see xmlrpc_client::return_type
1654 and xmlrpc_server::functions_parameters_type for more
1658 ==== My server (client) returns an error whenever the client (server) returns accented characters
1663 ==== How to enable long-lasting method calls
1668 ==== My client returns "XML-RPC Fault #2: Invalid return payload: enable debugging to examine incoming payload": what should I do?
1670 The response you are seeing is a default error response that the
1671 client object returns to the php application when the server did not
1672 respond to the call with a valid xmlrpc response.
1674 The most likely cause is that you are not using the correct URL
1675 when creating the client object, or you do not have appropriate access
1676 rights to the web page you are requesting, or some other common http
1679 To find out what the server is really returning to your client,
1680 you have to enable the debug mode of the client, using
1681 $client->setdebug(1);
1684 ==== How can I save to a file the xml of the xmlrpc responses received from servers?
1686 If what you need is to save the responses received from the server
1687 as xml, you have two options:
1689 1- use the serialize() method on the response object.
1695 $resp = $client->send($msg);
1696 if (!$resp->faultCode())
1697 $data_to_be_saved = $resp->serialize();
1701 Note that this will not be 100% accurate, since the xml generated
1702 by the response object can be different from the xml received,
1703 especially if there is some character set conversion involved, or such
1704 (eg. if you receive an empty string tag as <string/>, serialize()
1705 will output <string></string>), or if the server sent back
1706 as response something invalid (in which case the xml generated client
1707 side using serialize() will correspond to the error response generated
1708 internally by the lib).
1710 2 - set the client object to return the raw xml received instead
1711 of the decoded objects:
1717 $client = new xmlrpc_client($url);
1718 $client->return_type = 'xml';
1719 $resp = $client->send($msg);
1720 if (!$resp->faultCode())
1721 $data_to_be_saved = $resp->value();
1725 Note that using this method the xml response response will not be
1726 parsed at all by the library, only the http communication protocol will
1727 be checked. This means that xmlrpc responses sent by the server that
1728 would have generated an error response on the client (eg. malformed xml,
1729 responses that have faultcode set, etc...) now will not be flagged as
1730 invalid, and you might end up saving not valid xml but random
1734 ==== Can I use the ms windows character set?
1736 If the data your application is using comes from a Microsoft
1737 application, there are some chances that the character set used to
1738 encode it is CP1252 (the same might apply to data received from an
1739 external xmlrpc server/client, but it is quite rare to find xmlrpc
1740 toolkits that encode to CP1252 instead of UTF8). It is a character set
1741 which is "almost" compatible with ISO 8859-1, but for a few extra
1744 PHP-XMLRPC only supports the ISO 8859-1 and UTF8 character sets.
1745 The net result of this situation is that those extra characters will not
1746 be properly encoded, and will be received at the other end of the
1747 XML-RPC transmission as "garbled data". Unfortunately the library cannot
1748 provide real support for CP1252 because of limitations in the PHP 4 xml
1749 parser. Luckily, we tried our best to support this character set anyway,
1750 and, since version 2.2.1, there is some form of support, left commented
1753 To properly encode outgoing data that is natively in CP1252, you
1754 will have to uncomment all relative code in the file
1755 __xmlrpc.inc__ (you can search for the string "1252"),
1756 then set ++$$$GLOBALS['xmlrpc_internalencoding']='CP1252';$$++
1757 Please note that all incoming data will then be fed to your application
1758 as UTF-8 to avoid any potential data loss.
1761 ==== Does the library support using cookies / http sessions?
1763 In short: yes, but a little coding is needed to make it
1766 The code below uses sessions to e.g. let the client store a value
1767 on the server and retrieve it later.
1772 $resp = $client->send(new xmlrpcmsg('registervalue', array(new xmlrpcval('foo'), new xmlrpcval('bar'))));
1773 if (!$resp->faultCode())
1775 $cookies = $resp->cookies();
1776 if (array_key_exists('PHPSESSID', $cookies)) // nb: make sure to use the correct session cookie name
1778 $session_id = $cookies['PHPSESSID']['value'];
1780 // do some other stuff here...
1782 $client->setcookie('PHPSESSID', $session_id);
1783 $val = $client->send(new xmlrpcmsg('getvalue', array(new xmlrpcval('foo')));
1789 Server-side sessions are handled normally like in any other
1790 php application. Please see the php manual for more information about
1793 NB: unlike web browsers, not all xmlrpc clients support usage of
1794 http cookies. If you have troubles with sessions and control only the
1795 server side of the communication, please check with the makers of the
1796 xmlrpc client in use.
1802 == Integration with the PHP xmlrpc extension
1804 To be documented more...
1806 In short: for the fastest execution possible, you can enable the php
1807 native xmlrpc extension, and use it in conjunction with phpxmlrpc. The
1808 following code snippet gives an example of such integration
1814 /*** client side ***/
1815 $c = new xmlrpc_client('http://phpxmlrpc.sourceforge.net/server.php');
1817 // tell the client to return raw xml as response value
1818 $c->return_type = 'xml';
1820 // let the native xmlrpc extension take care of encoding request parameters
1821 $r = $c->send(xmlrpc_encode_request('examples.getStateName', $_POST['stateno']));
1823 if ($r->faultCode())
1824 // HTTP transport error
1825 echo 'Got error '.$r->faultCode();
1828 // HTTP request OK, but XML returned from server not parsed yet
1829 $v = xmlrpc_decode($r->value());
1830 // check if we got a valid xmlrpc response from server
1832 echo 'Got invalid response';
1834 // check if server sent a fault response
1835 if (xmlrpc_is_fault($v))
1836 echo 'Got xmlrpc fault '.$v['faultCode'];
1838 echo'Got response: '.htmlentities($v);
1847 == Substitution of the PHP xmlrpc extension
1849 Yet another interesting situation is when you are using a ready-made
1850 php application, that provides support for the XMLRPC protocol via the
1851 native php xmlrpc extension, but the extension is not available on your
1852 php install (e.g. because of shared hosting constraints).
1854 Since version 2.1, the PHP-XMLRPC library provides a compatibility
1855 layer that aims to be 100% compliant with the xmlrpc extension API. This
1856 means that any code written to run on the extension should obtain the
1857 exact same results, albeit using more resources and a longer processing
1858 time, using the PHP-XMLRPC library and the extension compatibility module.
1859 The module is part of the EXTRAS package, available as a separate download
1860 from the sourceforge.net website, since version 0.2
1866 == 'Enough of xmlrpcvals!': new style library usage
1870 In the meantime, see docs about xmlrpc_client::return_type and
1871 xmlrpc_server::functions_parameters_types, as well as php_xmlrpc_encode,
1872 php_xmlrpc_decode and php_xmlrpc_decode_xml
1878 == Usage of the debugger
1880 A webservice debugger is included in the library to help during
1881 development and testing.
1883 The interface should be self-explicative enough to need little
1886 image::debugger.gif[,,,,align="center"]
1888 The most useful feature of the debugger is without doubt the "Show
1889 debug info" option. It allows to have a screen dump of the complete http
1890 communication between client and server, including the http headers as
1891 well as the request and response payloads, and is invaluable when
1892 troubleshooting problems with charset encoding, authentication or http
1895 The debugger can take advantage of the JSONRPC library extension, to
1896 allow debugging of JSON-RPC webservices, and of the JS-XMLRPC library
1897 visual editor to allow easy mouse-driven construction of the payload for
1898 remote methods. Both components have to be downloaded separately from the
1899 sourceforge.net web pages and copied to the debugger directory to enable
1900 the extra functionality:
1903 * to enable jsonrpc functionality, download the PHP-XMLRPC
1904 EXTRAS package, and copy the file __jsonrpc.inc__
1905 either to the same directory as the debugger or somewhere in your
1909 * to enable the visual value editing dialog, download the
1910 JS-XMLRPC library, and copy somewhere in the web root files
1911 __visualeditor.php__,
1912 __visualeditor.css__ and the folders
1913 __yui__ and __img__. Then edit the
1914 debugger file __controller.php__ and set
1915 appropriately the variable $editorpath.
1924 CAUTION: not all items the following list have (yet) been fully documented, and some might not be present in any other
1925 chapter in the manual. To find a more detailed description of new functions and methods please take a look at the
1926 source code of the library, which is quite thoroughly commented in phpdoc form.
1930 * new: introduction of namespaces and full OOP.
1932 All php classes have been renamed and moved to separate files.
1934 Class autoloading can now be done in accord with the PSR-4 standard.
1936 All global variables and global functions have been removed.
1938 Iterating over xmlrpc value objects is now easier thank to support for ArrayAccess and Traversable interfaces.
1940 Backward compatibility is maintained via _lib/xmlrpc.inc_, _lib/xmlrpcs.inc_ and _lib/xmlrpc_wrappers.inc_.
1941 For more details, head on to doc/api_changes_v4.md
1943 * changed: the default character encoding delivered from the library to your code is now utf8.
1944 It can be changed at any time setting a value to `PhpXmlRpc\PhpXmlRpc::$xmlrpc_internalencoding`
1946 * improved: the library now accepts requests/responses sent using other character sets than UTF-8/ISO-8859-1/ASCII.
1947 This only works when the mbstring php extension is enabled.
1949 * improved: no need to call anymore `$client->setSSLVerifyHost(2)` to silence a curl warning when using https
1950 with recent curl builds
1952 * improved: the xmlrpcval class now supports the interfaces `Countable` and `IteratorAggregate`
1954 * improved: a specific option allows users to decide the version of SSL to use for https calls.
1955 This is useful f.e. for the testing suite, when the server target of calls has no proper ssl certificate,
1956 and the cURL extension has been compiled with GnuTLS (such as on Travis VMs)
1958 * improved: the function `wrap_php_function()` now can be used to wrap closures (it is now a method btw)
1960 * improved: all _wrap_something()_ functions now return a closure by default instead of a function name
1962 * improved: debug messages are not html-escaped any more when executing from the command line
1964 * improved: the library is now tested using Travis ( https://travis-ci.org/ ).
1965 Tests are executed using all php versions from 5.3 to 7.0 nightly, plus HHVM; code-coverage information
1966 is generated using php 5.6 and uploaded to both Code Coverage and Scrutinizer online services
1968 * improved: phpunit is now installed via composer, not bundled anymore
1970 * improved: when phpunit is used to generate code-coverage data, the code executed server-side is accounted for
1972 * improved: the test suite has basic checks for the debugger and demo files
1974 * improved: more tests in the test suite
1976 * fixed: the server would not reset the user-set debug messages between subsequent `service()` calls
1978 * fixed: the server would not reset previous php error handlers when an exception was thrown by user code and
1979 exception_handling set to 2
1981 * fixed: the server would fail to decode a request with ISO-8859-1 payload and character set declaration in the xml
1984 * fixed: the client would fail to decode a response with ISO-8859-1 payload and character set declaration in the xml
1987 * fixed: the function `decode_xml()` would not decode an xml with character set declaration in the xml prolog
1989 * fixed: the client can now successfully call methods using ISO-8859-1 or UTF-8 characters in their name
1991 * fixed: the debugger would fail sending a request with ISO-8859-1 payload (it missed the character set declaration).
1992 It would have a hard time coping with ISO-8859-1 in other fields, such as e.g. the remote method name
1994 * fixed: the debugger would generate a bad payload via the 'load method synopsis' button for signatures containing NULL
1995 or undefined parameters
1997 * fixed: the debugger would generate a bad payload via the 'load method synopsis' button for methods with multiple
2000 * improved: the debugger is displayed using UTF-8, making it more useful to debug any kind of service
2002 * improved: echo all debug messages even when there are characters in them which php deems to be in a wrong encoding;
2003 previously those messages would just disappear (this is visible e.g. in the debugger)
2005 * changed: debug info handling
2006 - at debug level 1, the rebuilt php objects are not dumped to screen (server-side already did that)
2007 - at debug level 1, curl communication info are not dumped to screen
2008 - at debug level 1, the tests echo payloads of failures; at debug level 2 all payloads
2010 * improved: makefiles have been replaced with a php_based pakefile
2012 * improved: the source for the manual is stored in asciidoc format, which can be displayed natively by GitHub
2013 with nice html formatting. Also the HTML version generated by hand and bundled in tarballs is much nicer
2014 to look at than previous versions
2016 * improved: all php code is now formatted according to the PSR-2 standard
2020 __Note:__ this is the last release of the library that will support PHP 5.1 and up. Future releases will target php 5.3
2021 as minimum supported version.
2023 * when using curl and keepalive, reset curl handle if we did not get back an http 200 response (eg a 302)
2025 * omit port on http 'Host' header if it is 80
2027 * test suite allows interrogating https servers ignoring their certs
2029 * method `setAcceptedCompression` was failing to disable reception of compressed responses if the client supported them
2033 This is the first release of the library to only support PHP 5. Some legacy code has been removed, and support for
2034 features such as exceptions and dateTime objects introduced.
2036 The "beta" tag is meant to indicate the fact that the refactoring has been more widespread than in precedent releases
2037 and that more changes are likely to be introduced with time - the library is still considered to be production
2040 * improved: removed all usage of php functions deprecated in php 5.3, usage of assign-by-ref when creating new objects
2043 * improved: add support for the `<ex:nil>` tag used by the apache library, both in input and output
2045 * improved: add support for dateTime objects in both in php_xmlrpc_encode and as parameter for constructor of xmlrpcval
2047 * improved: add support for timestamps as parameter for constructor of xmlrpcval
2049 * improved: add option `dates_as_objects` to `php_xmlrpc_decode` to return dateTime objects for xmlrpc datetimes
2051 * improved: add new method `SetCurlOptions` to xmrlpc_client to allow extra flexibility in tweaking http config, such as
2052 explicitly binding to an ip address
2054 * improved: add new method `SetUserAgent` to xmrlpc_client to to allow having different user-agent http headers
2056 * improved: add a new member variable in server class to allow fine-tuning of the encoding of returned values when the
2057 server is in 'phpvals' mode
2059 * improved: allow servers in 'xmlrpcvals' mode to also register plain php functions by defining them in the dispatch map
2060 with an added option
2062 * improved: catch exceptions thrown during execution of php functions exposed as methods by the server
2064 * fixed: bad encoding if same object is encoded twice using `php_xmlrpc_encode`
2068 __Note:__ this is the last release of the library that will support PHP 4. Future releases (if any) should target
2069 php 5.0 as minimum supported version.
2071 * fixed: encoding of utf-8 characters outside of the BMP plane
2073 * fixed: character set declarations surrounded by double quotes were not recognized in http headers
2075 * fixed: be more tolerant in detection of charset in http headers
2077 * fixed: fix detection of zlib.output_compression
2079 * fixed: use `feof()` to test if socket connections are to be closed instead of the number of bytes read (rare bug when
2080 communicating with some servers)
2082 * fixed: format floating point values using the correct decimal separator even when php locale is set to one that uses
2085 * fixed: improve robustness of the debugger when parsing weird results from non-compliant servers
2087 * php warning when receiving `false` in a bool value
2089 * improved: allow the add_to_map server method to add docs for single params too
2091 * improved: added the possibility to wrap for exposure as xmlrpc methods plain php class methods, object methods and even
2096 * fixed: work aroung bug in php 5.2.2 which broke support of `HTTP_RAW_POST_DATA`
2098 * fixed: is_dir parameter of `setCaCertificate()` method is reversed
2100 * fixed: a php warning in xmlrpc_client creator method
2102 * fixed: parsing of `1e+1` as valid float
2104 * fixed: allow errorlevel 3 to work when prev. error handler was a static method
2106 * fixed: usage of `client::setcookie()` for multiple cookies in non-ssl mode
2108 * improved: support for CP1252 charset is not part or the library but almost possible
2110 * improved: more info when curl is enabled and debug mode is on
2114 * fixed: debugger errors on php installs with `magic_quotes_gpc` on
2116 * fixed: support for https connections via proxy
2118 * fixed: `wrap_xmlrpc_method()` generated code failed to properly encode php objects
2120 * improved: slightly faster encoding of data which is internally UTF-8
2122 * improved: debugger always generates a `null` id for jsonrpc if user omits it
2124 * new: debugger can take advantage of a graphical value builder (it has to be downloaded separately, as part of jsxmlrpc
2125 package. See Appendix D for more details)
2127 * new: support for the `<NIL/>` xmlrpc extension. see below for more details
2129 * new: server support for the `system.getCapabilities` xmlrpc extension
2131 * new: `wrap_xmlrpc_method`, `wrap_xmlrpc_method()` accepts two new options: debug and return_on_fault
2135 * The wrap_php_function and wrap_xmlrpc_method functions have been moved out of the base library file _xmlrpc.inc_
2136 into a file of their own: _xmlrpc_wrappers.php_. You will have to include() / require() it in your scripts if
2137 you have been using those functions.
2138 For increased security, the automatic rebuilding of php object instances out ofreceived xmlrpc structs in
2139 `wrap_xmlrpc_method()` has been disabled (but it can be optionally re-enabled).
2140 Both `wrap_php_function()` and `wrap_xmlrpc_method()` functions accept many more options to fine tune their behaviour,
2141 including one to return the php code to be saved and later used as standalone php script
2143 * The constructor of xmlrpcval() values has seen some internal changes, and it will not throw a php warning anymore when
2144 invoked using an unknown xmlrpc type: the error will only be written to php error log. Also
2145 `new xmlrpcval('true', 'boolean')` is not supported anymore
2147 * The new function `php_xmlrpc_decode_xml()` will take the xml representation of either an xmlrpc request, response or
2148 single value and return the corresponding php-xmlrpc object instance
2150 * A new function `wrap_xmlrpc_server()` has been added, to wrap all (or some) of the methods exposed by a remote xmlrpc
2151 server into a php class
2153 * A new file has been added: _verify_compat.php_, to help users diagnose the level of compliance of their php
2154 installation with the library
2156 * Restored compatibility with php 4.0.5 (for those poor souls still stuck on it)
2158 * Method `xmlrpc_server->service()` now returns a value: either the response payload or xmlrpcresp object instance
2160 * Method `xmlrpc_server->add_to_map()` now accepts xmlrpc methods with no param definitions
2162 * Documentation for single parameters of exposed methods can be added to the dispatch map (and turned into html docs in
2163 conjunction with a future release of the 'extras' package)
2165 * Full response payload is saved into xmlrpcresp object for further debugging
2167 * The debugger can now generate code that wraps a remote method into a php function (works for jsonrpc, too); it also
2168 has better support for being activated via a single GET call (e.g. for integration into other tools)
2170 * Stricter parsing of incoming xmlrpc messages: two more invalid cases are now detected (double `data` element inside
2171 `array` and `struct`/`array` after scalar inside `value` element)
2173 * More logging of errors in a lot of situations
2175 * Javadoc documentation of lib files (almost) complete
2177 * Many performance tweaks and code cleanups, plus the usual crop of bugs fixed (see NEWS file for complete list of bugs)
2179 * Lib internals have been modified to provide better support for grafting extra functionality on top of it. Stay tuned
2180 for future releases of the EXTRAS package (or go read Appendix B)...
2184 * Added to the client class the possibility to use Digest and NTLM authentication methods (when using the CURL library)
2185 for connecting to servers and NTLM for connecting to proxies
2187 * Added to the client class the possibility to specify alternate certificate files/directories for authenticating the
2188 peer with when using HTTPS communication
2190 * Reviewed all examples and added a new demo file, containing a proxy to forward xmlrpc requests to other servers
2191 (useful e.g. for ajax coding)
2193 * The debugger has been upgraded to reflect the new client capabilities
2195 * All known bugs have been squashed, and the lib is more tolerant than ever of commonly-found mistakes
2197 === 2.0 Release candidate 3
2199 * Added to server class the property functions_parameters_type, that allows the server to register plain php functions
2200 as xmlrpc methods (i.e. functions that do not take an xmlrpcmsg object as unique param)
2202 * let server and client objects serialize calls using a specified character set encoding for the produced xml instead of
2203 US-ASCII (ISO-8859-1 and UTF-8 supported)
2205 * let `php_xmlrpc_decode` accept xmlrpcmsg objects as valid input
2207 * 'class::method' syntax is now accepted in the server dispatch map
2209 * `xmlrpc_clent::SetDebug()` accepts integer values instead of a boolean value, with debugging level 2 adding to the
2210 information printed to screen the complete client request
2212 === 2.0 Release candidate 2
2214 * Added a new property of the client object: `xmlrpc_client->return_type`, indicating whether calls to the
2215 send() method will return xmlrpcresp objects whose value() is an xmlrpcval object, a php value (automatically
2216 decoded) or the raw xml received from the server.
2218 * Added in the extras dir. two new library files: _jsonrpc.inc_ and _jsonrpcs.inc_ containing new classes that
2219 implement support for the json-rpc protocol (alpha quality code)
2221 * Added a new client method: `setKey($key, $keypass)` to be used in HTTPS connections
2223 * Added a new file containing some benchmarks in the testsuite directory
2225 === 2.0 Release candidate 1
2227 * Support for HTTP proxies (new method: `xmlrpc_client::setProxy()`)
2229 * Support HTTP compression of both requests and responses.
2230 Clients can specify what kind of compression they accept for responses between deflate/gzip/any, and whether to
2231 compress the requests.
2232 Servers by default compress responses to clients that explicitly declare support for compression (new methods:
2233 `xmlrpc_client::setAcceptedCompression()`, `xmlrpc_client::setRequestCompression()`).
2234 Note that the ZLIB php extension needs to be enabled in PHP to support compression.
2236 * Implement HTTP 1.1 connections, but only if CURL is enabled (added an extra parameter to
2237 `xmlrpc_client::xmlrpc_client` to set the desired HTTP protocol at creation time and a new supported value for
2238 the last parameter of `xmlrpc_client::send`, which now can be safely omitted if it has been specified at
2241 With PHP versions greater than 4.3.8 keep-alives are enabled by default for HTTP 1.1 connections. This should yield
2242 faster execution times when making multiple calls in sequence to the same xml-rpc server from a single client.
2244 * Introduce support for cookies.
2245 Cookies to be sent to the server with a request can be set using `xmlrpc_client::setCookie()`, while cookies
2246 received from the server are found in ++xmlrpcresp::cookies()++. It is left to the user to check for validity of
2247 received cookies and decide whether they apply to successive calls or not.
2249 * Better support for detecting different character set encodings of xml-rpc requests and responses: both client and
2250 server objects will correctly detect the charset encoding of received xml, and use an appropriate xml parser.
2252 Supported encodings are US-ASCII, UTF-8 and ISO-8859-1.
2254 * Added one new xmlrpcmsg constructor syntax, allowing usage of a single string with the complete URL of the target
2257 * Convert xml-rpc boolean values into native php values instead of 0 and 1
2259 * Force the `php_xmlrpc_encode` function to properly encode numerically indexed php arrays into xml-rpc arrays
2260 (numerically indexed php arrays always start with a key of 0 and increment keys by values of 1)
2262 * Prevent the `php_xmlrpc_encode` function from further re-encoding any objects of class ++xmlrpcval++ that
2263 are passed to it. This allows to call the function with arguments consisting of mixed php values / xmlrpcval objects
2265 * Allow a server to NOT respond to system.* method calls (setting the `$server->allow_system_funcs` property).
2267 * Implement a new xmlrpcval method to determine if a value of type struct has a member of a given name without having to
2268 loop trough all members: `xmlrpcval::structMemExists()`
2270 * Expand methods `xmlrpcval::addArray`, `addScalar` and `addStruct` allowing extra php values to be added to
2271 xmlrpcval objects already formed.
2273 * Let the `xmlrpc_client::send` method accept an XML string for sending instead of an xmlrpcmsg object, to
2274 facilitate debugging and integration with the php native xmlrpc extension
2276 * Extend the `php_xmlrpc_encode` and `php_xmlrpc_decode` functions to allow serialization and rebuilding of
2277 PHP objects. To successfully rebuild a serialized object, the object class must be defined in the deserializing end
2278 of the transfer. Note that object members of type resource will be deserialized as NULL values.
2280 Note that his has been implemented adding a "php_class" attribute to xml representation of xmlrpcval of STRUCT type,
2281 which, strictly speaking, breaks the xml-rpc spec. Other xmlrpc implementations are supposed to ignore such an
2282 attribute (unless they implement a brain-dead custom xml parser...), so it should be safe enabling it in
2283 heterogeneous environments. The activation of this feature is done by usage of an option passed as second parameter
2284 to both `php_xmlrpc_encode` and `php_xmlrpc_decode`.
2286 * Extend the `php_xmlrpc_encode` function to allow automatic serialization of iso8601-conforming php strings as
2287 datetime.iso8601 xmlrpcvals, by usage of an optional parameter
2289 * Added an automatic stub code generator for converting xmlrpc methods to php functions and vice-versa.
2291 This is done via two new functions: `wrap_php_function` and `wrap_xmlrpc_method`, and has many caveats,
2292 with php being a typeless language and all...
2294 * Allow object methods to be used in server dispatch map
2296 * Added a complete debugger solution, in the __debugger__ folder
2298 * Added configurable server-side debug messages, controlled by the new method `xmlrpc_server::SetDebug()`.
2299 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
2300 more info is echoed back to the client, regarding the received call; at level 3 all warnings raised during server
2301 processing are trapped (this prevents breaking the xml to be echoed back to the client) and added to the debug info
2302 sent back to the client
2304 * New XML parsing code, yields smaller memory footprint and faster execution times, not to mention complete elimination
2305 of the dreaded __eval()__ construct, so prone to code injection exploits
2307 * Rewritten most of the error messages, making text more explicative
2309 ++++++++++++++++++++++++++++++++++++++
2310 <!-- Keep this comment at the end of the file
2315 sgml-minimize-attributes:nil
2316 sgml-always-quote-attributes:t
2319 sgml-parent-document:nil
2320 sgml-exposed-tags:nil
2321 sgml-local-catalogs:nil
2322 sgml-local-ecat-files:nil
2323 sgml-namecase-general:t
2324 sgml-general-insert-case:lower
2327 ++++++++++++++++++++++++++++++++++++++