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/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
223 The type i4 is accepted as a synonym
224 for int when creating xmlrpcval objects. The
225 xml parsing code will always convert i4 to
227 by this implementation as the canonical name for this type.
231 Base 64 encoding is performed transparently to the caller when
232 using this type. Decoding is also transparent. Therefore you ought
233 to consider it as a "binary" data type, for use when you want to
234 pass data that is not 7-bit clean.
238 The php values ++true++ and
239 ++1++ map to ++true++. All other
240 values (including the empty string) are converted to
245 Characters <, >;, ', ", &, are encoded using their
246 entity reference as < > ' " and
247 & All other characters outside of the ASCII range are
248 encoded using their character reference representation (e.g.
249 È for é). The XML-RPC spec recommends only encoding
250 ++< >++ but this implementation goes further,
251 for reasons explained by link:$$http://www.w3.org/TR/REC-xml#syntax$$[the XML 1.0 recommendation]. In particular, using character reference
252 representation has the advantage of producing XML that is valid
253 independently of the charset encoding assumed.
257 There is no support for encoding ++null++
258 values in the XML-RPC spec, but at least a couple of extensions (and
259 many toolkits) do support it. Before using ++null++
260 values in your messages, make sure that the responding party accepts
261 them, and uses the same encoding convention (see ...).
263 [[xmlrpcval-creation]]
265 ==== Xmlrpcval creation
267 The constructor is the normal way to create an
268 xmlrpcval. The constructor can take these
272 xmlrpcval xmlrpcvalnew
273 xmlrpcval string $stringVal xmlrpcvalnew
274 xmlrpcval mixed $scalarVal string$scalartyp xmlrpcvalnew
275 xmlrpcval array $arrayVal string $arraytyp The first constructor creates an empty value, which must be
276 altered using the methods addScalar,
277 addArray or addStruct before
280 The second constructor creates a simple string value.
282 The third constructor is used to create a scalar value. The
283 second parameter must be a name of an XML-RPC type. Valid types are:
284 "++int++", "++boolean++",
285 "++string++", "++double++",
286 "++dateTime.iso8601++", "++base64++" or
294 $myInt = new xmlrpcval(1267, "int");
295 $myString = new xmlrpcval("Hello, World!", "string");
296 $myBool = new xmlrpcval(1, "boolean");
297 $myString2 = new xmlrpcval(1.24, "string"); // note: this will serialize a php float value as xmlrpc string
301 The fourth constructor form can be used to compose complex
302 XML-RPC values. The first argument is either a simple array in the
303 case of an XML-RPC array or an associative
304 array in the case of a struct. The elements of
305 the array __must be xmlrpcval objects themselves__.
307 The second parameter must be either "++array++"
315 $myArray = new xmlrpcval(
317 new xmlrpcval("Tom"),
318 new xmlrpcval("Dick"),
319 new xmlrpcval("Harry")
324 $myStruct = new xmlrpcval(
326 "name" => new xmlrpcval("Tom", "string"),
327 "age" => new xmlrpcval(34, "int"),
328 "address" => new xmlrpcval(
330 "street" => new xmlrpcval("Fifht Ave", "string"),
331 "city" => new xmlrpcval("NY", "string")
339 See the file ++vardemo.php++ in this distribution
344 ==== Xmlrpc-client creation
346 The constructor accepts one of two possible syntaxes:
349 xmlrpc_clientstring$server_urlxmlrpc_clientnew
350 xmlrpc_clientstring$server_pathstring$server_hostnameint$server_port80string$transport'http'Here are a couple of usage examples of the first form:
356 $client = new xmlrpc_client("http://phpxmlrpc.sourceforge.net/server.php");
357 $another_client = new xmlrpc_client("https://james:bond@secret.service.com:443/xmlrpcserver?agent=007");
361 The second syntax does not allow to express a username and
362 password to be used for basic HTTP authorization as in the second
363 example above, but instead it allows to choose whether xmlrpc calls
364 will be made using the HTTP 1.0 or 1.1 protocol.
366 Here's another example client set up to query Userland's XML-RPC
367 server at __betty.userland.com__:
372 $client = new xmlrpc_client("/RPC2", "betty.userland.com", 80);
376 The server_port parameter is optional,
377 and if omitted will default to 80 when using HTTP and 443 when using
378 HTTPS (see the <<xmlrpc-client-send>> method
381 The transport parameter is optional, and
382 if omitted will default to 'http'. Allowed values are either
384 'http11'. Its value can be overridden with every call
385 to the send method. See the
386 send method below for more details about the
387 meaning of the different values.
394 The implementation of this class has been kept as simple to use as
395 possible. The constructor for the server basically does all the work.
396 Here's a minimal example:
402 function foo ($xmlrpcmsg) {
404 return new xmlrpcresp($some_xmlrpc_val);
408 function foobar($xmlrpcmsg) {
410 return new xmlrpcresp($some_xmlrpc_val);
414 $s = new xmlrpc_server(
416 "examples.myFunc1" => array("function" => "foo"),
417 "examples.myFunc2" => array("function" => "bar::foobar"),
422 This performs everything you need to do with a server. The single
423 constructor argument is an associative array from xmlrpc method names to
424 php function names. The incoming request is parsed and dispatched to the
425 relevant php function, which is responsible for returning a
426 xmlrpcresp object, that will be serialized back
430 ==== Method handler functions
432 Both php functions and class methods can be registered as xmlrpc
435 The synopsis of a method handler function is:
437 xmlrpcresp $resp = function (xmlrpcmsg $msg)
439 No text should be echoed 'to screen' by the handler function, or
440 it will break the xml response sent back to the client. This applies
441 also to error and warning messages that PHP prints to screen unless
442 the appropriate parameters have been set in the php.in file. Another
443 way to prevent echoing of errors inside the response and facilitate
444 debugging is to use the server SetDebug method with debug level 3 (see
445 ...). Exceptions thrown duting execution of handler functions are
446 caught by default and a XML-RPC error reponse is generated instead.
447 This behaviour can be finetuned by usage of the
448 exception_handling member variable (see
451 Note that if you implement a method with a name prefixed by
452 ++system.++ the handler function will be invoked by the
453 server with two parameters, the first being the server itself and the
454 second being the xmlrpcmsg object.
456 The same php function can be registered as handler of multiple
459 Here is a more detailed example of what the handler function
466 function foo ($xmlrpcmsg) {
467 global $xmlrpcerruser; // import user errcode base value
469 $meth = $xmlrpcmsg->method(); // retrieve method name
470 $par = $xmlrpcmsg->getParam(0); // retrieve value of first parameter - assumes at least one param received
471 $val = $par->scalarval(); // decode value of first parameter - assumes it is a scalar value
476 // this is an error condition
477 return new xmlrpcresp(0, $xmlrpcerruser+1, // user error 1
478 "There's a problem, Captain");
480 // this is a successful value being returned
481 return new xmlrpcresp(new xmlrpcval("All's fine!", "string"));
487 See __server.php__ in this distribution for
488 more examples of how to do this.
490 Since release 2.0RC3 there is a new, even simpler way of
491 registering php functions with the server. See section 5.7
495 ==== The dispatch map
497 The first argument to the xmlrpc_server
498 constructor is an array, called the __dispatch map__.
499 In this array is the information the server needs to service the
500 XML-RPC methods you define.
502 The dispatch map takes the form of an associative array of
503 associative arrays: the outer array has one entry for each method, the
504 key being the method name. The corresponding value is another
505 associative array, which can have the following members:
508 * ++function++ - this
509 entry is mandatory. It must be either a name of a function in the
510 global scope which services the XML-RPC method, or an array
511 containing an instance of an object and a static method name (for
512 static class methods the 'class::method' syntax is also
516 * ++signature++ - this
517 entry is an array containing the possible signatures (see <<signatures>>) for the method. If this entry is present
518 then the server will check that the correct number and type of
519 parameters have been sent for this method before dispatching
523 * ++docstring++ - this
524 entry is a string containing documentation for the method. The
525 documentation may contain HTML markup.
528 * ++$$signature_docs$$++ - this entry can be used
529 to provide documentation for the single parameters. It must match
530 in structure the 'signature' member. By default, only the
531 documenting_xmlrpc_server class in the
532 extras package will take advantage of this, since the
533 "system.methodHelp" protocol does not support documenting method
534 parameters individually.
537 * ++$$parameters_type$$++ - this entry can be used
538 when the server is working in 'xmlrpcvals' mode (see ...) to
539 define one or more entries in the dispatch map as being functions
540 that follow the 'phpvals' calling convention. The only useful
541 value is currently the string ++phpvals++.
543 Look at the __server.php__ example in the
544 distribution to see what a dispatch map looks like.
548 ==== Method signatures
550 A signature is a description of a method's return type and its
551 parameter types. A method may have more than one signature.
553 Within a server's dispatch map, each method has an array of
554 possible signatures. Each signature is an array of types. The first
555 entry is the return type. For instance, the method
558 string examples.getStateName(int)
565 array($xmlrpcString, $xmlrpcInt)
569 and, assuming that it is the only possible signature for the
570 method, it might be used like this in server creation:
574 $findstate_sig = array(array($xmlrpcString, $xmlrpcInt));
576 $findstate_doc = 'When passed an integer between 1 and 51 returns the
577 name of a US state, where the integer is the index of that state name
578 in an alphabetic order.';
580 $s = new xmlrpc_server( array(
581 "examples.getStateName" => array(
582 "function" => "findstate",
583 "signature" => $findstate_sig,
584 "docstring" => $findstate_doc
591 Note that method signatures do not allow to check nested
592 parameters, e.g. the number, names and types of the members of a
593 struct param cannot be validated.
595 If a method that you want to expose has a definite number of
596 parameters, but each of those parameters could reasonably be of
597 multiple types, the array of acceptable signatures will easily grow
598 into a combinatorial explosion. To avoid such a situation, the lib
599 defines the global var $xmlrpcValue, which can be
600 used in method signatures as a placeholder for 'any xmlrpc
607 $echoback_sig = array(array($xmlrpcValue, $xmlrpcValue));
609 $findstate_doc = 'Echoes back to the client the received value, regardless of its type';
611 $s = new xmlrpc_server( array(
613 "function" => "echoback",
614 "signature" => $echoback_sig, // this sig guarantees that the method handler will be called with one and only one parameter
615 "docstring" => $echoback_doc
620 Methods system.listMethods,
622 system.methodSignature and
623 system.multicall are already defined by the
624 server, and should not be reimplemented (see Reserved Methods
628 ==== Delaying the server response
630 You may want to construct the server, but for some reason not
631 fulfill the request immediately (security verification, for instance).
632 If you omit to pass to the constructor the dispatch map or pass it a
633 second argument of ++0++ this will have the desired
634 effect. You can then use the service() method of
635 the server class to service the request. For example:
641 $s = new xmlrpc_server($myDispMap, 0); // second parameter = 0 prevents automatic servicing of request
643 // ... some code that does other stuff here
649 Note that the service method will print
650 the complete result payload to screen and send appropriate HTTP
651 headers back to the client, but also return the response object. This
652 permits further manipulation of the response, possibly in combination
653 with output buffering.
655 To prevent the server from sending HTTP headers back to the
656 client, you can pass a second parameter with a value of
657 ++TRUE++ to the service
658 method. In this case, the response payload will be returned instead of
661 Xmlrpc requests retrieved by other means than HTTP POST bodies
662 can also be processed. For example:
668 $s = new xmlrpc_server(); // not passing a dispatch map prevents automatic servicing of request
670 // ... some code that does other stuff here, including setting dispatch map into server object
672 $resp = $s->service($xmlrpc_request_body, true); // parse a variable instead of POST body, retrieve response payload
674 // ... some code that does other stuff with xml response $resp here
679 ==== Modifying the server behaviour
681 A couple of methods / class variables are available to modify
682 the behaviour of the server. The only way to take advantage of their
683 existence is by usage of a delayed server response (see above)
688 This function controls weather the server is going to echo
689 debugging messages back to the client as comments in response body.
690 Valid values: 0,1,2,3, with 1 being the default. At level 0, no
691 debug info is returned to the client. At level 2, the complete
692 client request is added to the response, as part of the xml
693 comments. At level 3, a new PHP error handler is set when executing
694 user functions exposed as server methods, and all non-fatal errors
695 are trapped and added as comments into the response.
698 ===== allow_system_funcs
700 Default_value: TRUE. When set to FALSE, disables support for
701 System.xxx functions in the server. It
702 might be useful e.g. if you do not wish the server to respond to
703 requests to System.ListMethods.
706 ===== compress_response
708 When set to TRUE, enables the server to take advantage of HTTP
709 compression, otherwise disables it. Responses will be transparently
710 compressed, but only when an xmlrpc-client declares its support for
711 compression in the HTTP headers of the request.
713 Note that the ZLIB php extension must be installed for this to
714 work. If it is, compress_response will default to
718 ===== exception_handling
720 This variable controls the behaviour of the server when an
721 exception is thrown by a method handler php function. Valid values:
722 0,1,2, with 0 being the default. At level 0, the server catches the
723 exception and return an 'internal error' xmlrpc response; at 1 it
724 catches the exceptions and return an xmlrpc response with the error
725 code and error message corresponding to the exception that was
726 thron; at 2 = the exception is floated to the upper layers in the
730 ===== response_charset_encoding
732 Charset encoding to be used for response (only affects string
735 If it can, the server will convert the generated response from
736 internal_encoding to the intended one.
738 Valid values are: a supported xml encoding (only UTF-8 and
739 ISO-8859-1 at present, unless mbstring is enabled), null (leave
740 charset unspecified in response and convert output stream to
741 US_ASCII), 'default' (use xmlrpc library default as specified in
742 xmlrpc.inc, convert output stream if needed), or 'auto' (use
743 client-specified charset encoding or same as request if request
744 headers do not specify it (unless request is US-ASCII: then use
745 library default anyway).
750 Fault codes for your servers should start at the value indicated
751 by the global ++$xmlrpcerruser++ + 1.
753 Standard errors returned by the server include:
755 ++1++ Unknown method:: Returned if the server was asked to dispatch a method it
758 ++2++ Invalid return payload:: This error is actually generated by the client, not
759 server, code, but signifies that a server returned something it
760 couldn't understand. A more detailed error report is sometimes
761 added onto the end of the phrase above.
763 ++3++ Incorrect parameters:: This error is generated when the server has signature(s)
764 defined for a method, and the parameters passed by the client do
765 not match any of signatures.
767 ++4++ Can't introspect: method unknown:: This error is generated by the builtin
768 system.* methods when any kind of
769 introspection is attempted on a method undefined by the
772 ++5++ Didn't receive 200 OK from remote server:: This error is generated by the client when a remote server
773 doesn't return HTTP/1.1 200 OK in response to a request. A more
774 detailed error report is added onto the end of the phrase
777 ++6++ No data received from server:: This error is generated by the client when a remote server
778 returns HTTP/1.1 200 OK in response to a request, but no
779 response body follows the HTTP headers.
781 ++7++ No SSL support compiled in:: This error is generated by the client when trying to send
782 a request with HTTPS and the CURL extension is not available to
785 ++8++ CURL error:: This error is generated by the client when trying to send
786 a request with HTTPS and the HTTPS communication fails.
788 ++9-14++ multicall errors:: These errors are generated by the server when something
789 fails inside a system.multicall request.
791 ++100-++ XML parse errors:: Returns 100 plus the XML parser error code for the fault
792 that occurred. The faultString returned
793 explains where the parse error was in the incoming XML
797 ==== 'New style' servers
799 In the same spirit of simplification that inspired the
800 xmlrpc_client::return_type class variable, a new
801 class variable has been added to the server class:
802 functions_parameters_type. When set to 'phpvals',
803 the functions registered in the server dispatch map will be called
804 with plain php values as parameters, instead of a single xmlrpcmsg
805 instance parameter. The return value of those functions is expected to
806 be a plain php value, too. An example is worth a thousand
811 function foo($usr_id, $out_lang='en') {
812 global $xmlrpcerruser;
816 if ($someErrorCondition)
817 return new xmlrpcresp(0, $xmlrpcerruser+1, 'DOH!');
822 'picture' => new xmlrpcval(file_get_contents($picOfTheGuy), 'base64')
826 $s = new xmlrpc_server(
828 "examples.myFunc" => array(
829 "function" => "bar::foobar",
830 "signature" => array(
831 array($xmlrpcString, $xmlrpcInt),
832 array($xmlrpcString, $xmlrpcInt, $xmlrpcString)
836 $s->functions_parameters_type = 'phpvals';
841 There are a few things to keep in mind when using this
844 to return an xmlrpc error, the method handler function must
845 return an instance of xmlrpcresp. The only
846 other way for the server to know when an error response should be
847 served to the client is to throw an exception and set the server's
848 exception_handling memeber var to 1;
850 to return a base64 value, the method handler function must
851 encode it on its own, creating an instance of an xmlrpcval
854 the method handler function cannot determine the name of the
855 xmlrpc method it is serving, unlike standard handler functions that
856 can retrieve it from the message object;
858 when receiving nested parameters, the method handler function
859 has no way to distinguish a php string that was sent as base64 value
860 from one that was sent as a string value;
862 this has a direct consequence on the support of
863 system.multicall: a method whose signature contains datetime or base64
864 values will not be available to multicall calls;
866 last but not least, the direct parsing of xml to php values is
867 much faster than using xmlrpcvals, and allows the library to handle
868 much bigger messages without allocating all available server memory or
869 smashing PHP recursive call stack.
876 Many global variables are defined in the xmlrpc.inc file. Some of
877 those are meant to be used as constants (and modifying their value might
878 cause unpredictable behaviour), while some others can be modified in your
879 php scripts to alter the behaviour of the xml-rpc client and
883 === "Constant" variables
888 $xmlrpcerruser800The minimum value for errors reported by user
889 implemented XML-RPC servers. Error numbers lower than that are
890 reserved for library usage.
893 ==== $xmlrpcI4, $xmlrpcInt, $xmlrpcBoolean, $xmlrpcDouble, $xmlrpcString, $xmlrpcDateTime, $xmlrpcBase64, $xmlrpcArray, $xmlrpcStruct, $xmlrpcValue, $xmlrpcNull
895 For convenience the strings representing the XML-RPC types have
896 been encoded as global variables:
902 $xmlrpcBoolean="boolean";
903 $xmlrpcDouble="double";
904 $xmlrpcString="string";
905 $xmlrpcDateTime="dateTime.iso8601";
906 $xmlrpcBase64="base64";
907 $xmlrpcArray="array";
908 $xmlrpcStruct="struct";
909 $xmlrpcValue="undefined";
914 ==== $xmlrpcTypes, $xmlrpc_valid_parents, $xmlrpcerr, $xmlrpcstr, $xmlrpcerrxml, $xmlrpc_backslash, $_xh, $xml_iso88591_Entities, $xmlEntities, $xmlrpcs_capabilities
916 Reserved for internal usage.
919 === Variables whose value can be modified
921 [[xmlrpc-defencoding]]
923 ==== xmlrpc_defencoding
925 $xmlrpc_defencoding"UTF8"This variable defines the character set encoding that will be
926 used by the xml-rpc client and server to decode the received messages,
927 when a specific charset declaration is not found (in the messages sent
928 non-ascii chars are always encoded using character references, so that
929 the produced xml is valid regardless of the charset encoding
932 Allowed values: ++"UTF8"++,
933 ++"ISO-8859-1"++, ++"ASCII".++
935 Note that the appropriate RFC actually mandates that XML
936 received over HTTP without indication of charset encoding be treated
937 as US-ASCII, but many servers and clients 'in the wild' violate the
938 standard, and assume the default encoding is UTF-8.
941 ==== xmlrpc_internalencoding
943 $xmlrpc_internalencoding"ISO-8859-1"This variable defines the character set encoding
944 that the library uses to transparently encode into valid XML the
945 xml-rpc values created by the user and to re-encode the received
946 xml-rpc values when it passes them to the PHP application. It only
947 affects xml-rpc values of string type. It is a separate value from
948 xmlrpc_defencoding, allowing e.g. to send/receive xml messages encoded
949 on-the-wire in US-ASCII and process them as UTF-8. It defaults to the
950 character set used internally by PHP (unless you are running an
951 MBString-enabled installation), so you should change it only in
952 special situations, if e.g. the string values exchanged in the xml-rpc
953 messages are directly inserted into / fetched from a database
954 configured to return UTF8 encoded strings to PHP. Example
962 include('xmlrpc.inc');
963 $xmlrpc_internalencoding = 'UTF-8'; // this has to be set after the inclusion above
964 $v = new xmlrpcval('κόÏ
\83με'); // This xmlrpc value will be correctly serialized as the greek word 'kosme'
970 $xmlrpcName"XML-RPC for PHP"The string representation of the name of the XML-RPC
971 for PHP library. It is used by the client for building the User-Agent
972 HTTP header that is sent with every request to the server. You can
973 change its value if you need to customize the User-Agent
979 $xmlrpcVersion"2.2"The string representation of the version number of
980 the XML-RPC for PHP library in use. It is used by the client for
981 building the User-Agent HTTP header that is sent with every request to
982 the server. You can change its value if you need to customize the
986 ==== xmlrpc_null_extension
988 When set to TRUE, the lib will enable
989 support for the <NIL/> (and <EX:NIL/>) xmlrpc value, as
990 per the extension to the standard proposed here. This means that
991 <NIL> and <EX:NIL/> tags received will be parsed as valid
992 xmlrpc, and the corresponding xmlrpcvals will return "null" for
996 ==== xmlrpc_null_apache_encoding
998 When set to ++TRUE++, php NULL values encoded
999 into xmlrpcval objects get serialized using the
1000 ++<EX:NIL/>++ tag instead of
1001 ++<NIL/>++. Please note that both forms are
1002 always accepted as input regardless of the value of this
1010 XML-RPC for PHP contains some helper functions which you can use to
1011 make processing of XML-RPC requests easier.
1016 The XML-RPC specification has this to say on dates:
1020 [[wrap_xmlrpc_method]]
1021 Don't assume a timezone. It should be
1022 specified by the server in its documentation what assumptions it makes
1027 Unfortunately, this means that date processing isn't
1028 straightforward. Although XML-RPC uses ISO 8601 format dates, it doesn't
1029 use the timezone specifier.
1031 We strongly recommend that in every case where you pass dates in
1032 XML-RPC calls, you use UTC (GMT) as your timezone. Most computer
1033 languages include routines for handling GMT times natively, and you
1034 won't have to translate between timezones.
1036 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
1037 8601 specification. Note that XML-RPC uses exactly one of the available
1038 representations: CCYYMMDDTHH:MM:SS.
1044 stringiso8601_encodestring$time_tint$utc0Returns an ISO 8601 formatted date generated from the UNIX
1045 timestamp $time_t, as returned by the PHP
1048 The argument $utc can be omitted, in
1049 which case it defaults to ++0++. If it is set to
1050 ++1++, then the function corrects the time passed in
1051 for UTC. Example: if you're in the GMT-6:00 timezone and set
1052 $utc, you will receive a date representation
1053 six hours ahead of your local time.
1055 The included demo program __vardemo.php__
1056 includes a demonstration of this function.
1062 intiso8601_decodestring$isoStringint$utc0Returns a UNIX timestamp from an ISO 8601 encoded time and date
1063 string passed in. If $utc is
1064 ++1++ then $isoString is assumed
1065 to be in the UTC timezone, and thus the result is also UTC: otherwise,
1066 the timezone is assumed to be your local timezone and you receive a
1071 === Easy use with nested PHP values
1073 Dan Libby was kind enough to contribute two helper functions that
1074 make it easier to translate to and from PHP values. This makes it easier
1075 to deal with complex structures. At the moment support is limited to
1076 int, double, string,
1077 array, datetime and struct
1078 datatypes; note also that all PHP arrays are encoded as structs, except
1079 arrays whose keys are integer numbers starting with 0 and incremented by
1082 These functions reside in __xmlrpc.inc__.
1086 ==== php_xmlrpc_decode
1088 mixedphp_xmlrpc_decodexmlrpcval$xmlrpc_valarray$optionsarrayphp_xmlrpc_decodexmlrpcmsg$xmlrpcmsg_valstring$optionsReturns a native PHP value corresponding to the values found in
1089 the xmlrpcval $xmlrpc_val,
1090 translated into PHP types. Base-64 and datetime values are
1091 automatically decoded to strings.
1093 In the second form, returns an array containing the parameters
1095 xmlrpcmsg_val, decoded
1098 The options parameter is optional. If
1099 specified, it must consist of an array of options to be enabled in the
1100 decoding process. At the moment the only valid option are
1102 ++$$dates_as_objects$$++. When the first is set, php
1103 objects that have been converted to xml-rpc structs using the
1104 php_xmlrpc_encode function and a corresponding
1105 encoding option will be converted back into object values instead of
1106 arrays (provided that the class definition is available at
1107 reconstruction time). When the second is set, XML-RPC datetime values
1108 will be converted into native dateTime objects
1111 ____WARNING__:__ please take
1112 extreme care before enabling the decode_php_objs
1113 option: when php objects are rebuilt from the received xml, their
1114 constructor function will be silently invoked. This means that you are
1115 allowing the remote end to trigger execution of uncontrolled PHP code
1116 on your server, opening the door to code injection exploits. Only
1117 enable this option when you have complete trust of the remote
1124 // wrapper to expose an existing php function as xmlrpc method handler
1125 function foo_wrapper($m)
1127 $params = php_xmlrpc_decode($m);
1128 $retval = call_user_func_array('foo', $params);
1129 return new xmlrpcresp(new xmlrpcval($retval)); // foo return value will be serialized as string
1132 $s = new xmlrpc_server(array(
1133 "examples.myFunc1" => array(
1134 "function" => "foo_wrapper",
1142 ==== php_xmlrpc_encode
1144 xmlrpcvalphp_xmlrpc_encodemixed$phpvalarray$optionsReturns an xmlrpcval object populated with the PHP
1145 values in $phpval. Works recursively on arrays
1146 and objects, encoding numerically indexed php arrays into array-type
1147 xmlrpcval objects and non numerically indexed php arrays into
1148 struct-type xmlrpcval objects. Php objects are encoded into
1149 struct-type xmlrpcvals, excepted for php values that are already
1150 instances of the xmlrpcval class or descendants thereof, which will
1151 not be further encoded. Note that there's no support for encoding php
1152 values into base-64 values. Encoding of date-times is optionally
1153 carried on on php strings with the correct format.
1155 The options parameter is optional. If
1156 specified, it must consist of an array of options to be enabled in the
1157 encoding process. At the moment the only valid options are
1158 encode_php_objs, ++$$null_extension$$++
1161 The first will enable the creation of 'particular' xmlrpcval
1162 objects out of php objects, that add a "php_class" xml attribute to
1163 their serialized representation. This attribute allows the function
1164 php_xmlrpc_decode to rebuild the native php objects (provided that the
1165 same class definition exists on both sides of the communication). The
1166 second allows to encode php ++NULL++ values to the
1168 ++<EX:NIL>++, see ...) tag. The last encodes any
1169 string that matches the ISO8601 format into an XML-RPC
1176 // the easy way to build a complex xml-rpc struct, showing nested base64 value and datetime values
1177 $val = php_xmlrpc_encode(array(
1178 'first struct_element: an int' => 666,
1179 'second: an array' => array ('apple', 'orange', 'banana'),
1180 'third: a base64 element' => new xmlrpcval('hello world', 'base64'),
1181 'fourth: a datetime' => '20060107T01:53:00'
1182 ), array('auto_dates'));
1186 ==== php_xmlrpc_decode_xml
1188 xmlrpcval | xmlrpcresp |
1189 xmlrpcmsgphp_xmlrpc_decode_xmlstring$xmlarray$optionsDecodes the xml representation of either an xmlrpc request,
1190 response or single value, returning the corresponding php-xmlrpc
1191 object, or ++FALSE++ in case of an error.
1193 The options parameter is optional. If
1194 specified, it must consist of an array of options to be enabled in the
1195 decoding process. At the moment, no option is supported.
1201 $text = '<value><array><data><value>Hello world</value></data></array></value>';
1202 $val = php_xmlrpc_decode_xml($text);
1203 if ($val) echo 'Found a value of type '.$val->kindOf(); else echo 'Found invalid xml';
1207 === Automatic conversion of php functions into xmlrpc methods (and vice versa)
1209 For the extremely lazy coder, helper functions have been added
1210 that allow to convert a php function into an xmlrpc method, and a
1211 remotely exposed xmlrpc method into a local php function - or a set of
1212 methods into a php class. Note that these comes with many caveat.
1215 ==== wrap_xmlrpc_method
1217 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
1218 function that will call the remote method and return results using
1219 native php types for both params and results. The generated php
1220 function will return an xmlrpcresp object for failed xmlrpc
1223 The second syntax is deprecated, and is listed here only for
1224 backward compatibility.
1226 The server must support the
1227 system.methodSignature xmlrpc method call for
1228 this function to work.
1230 The client param must be a valid
1231 xmlrpc_client object, previously created with the address of the
1232 target xmlrpc server, and to which the preferred communication options
1235 The optional parameters can be passed as array key,value pairs
1236 in the extra_options param.
1238 The signum optional param has the purpose
1239 of indicating which method signature to use, if the given server
1240 method has multiple signatures (defaults to 0).
1243 protocol optional params are the same as in the
1244 xmlrpc_client::send() method.
1246 If set, the optional new_function_name
1247 parameter indicates which name should be used for the generated
1248 function. In case it is not set the function name will be
1251 If the ++$$return_source$$++ optional parameter is
1252 set, the function will return the php source code to build the wrapper
1253 function, instead of evaluating it (useful to save the code and use it
1254 later as stand-alone xmlrpc client).
1256 If the ++$$encode_php_objs$$++ optional parameter is
1257 set, instances of php objects later passed as parameters to the newly
1258 created function will receive a 'special' treatment that allows the
1259 server to rebuild them as php objects instead of simple arrays. Note
1260 that this entails using a "slightly augmented" version of the xmlrpc
1261 protocol (ie. using element attributes), which might not be understood
1262 by xmlrpc servers implemented using other libraries.
1264 If the ++$$decode_php_objs$$++ optional parameter is
1265 set, instances of php objects that have been appropriately encoded by
1266 the server using a coordinate option will be deserialized as php
1267 objects instead of simple arrays (the same class definition should be
1268 present server side and client side).
1270 __Note that this might pose a security risk__,
1271 since in order to rebuild the object instances their constructor
1272 method has to be invoked, and this means that the remote server can
1273 trigger execution of unforeseen php code on the client: not really a
1274 code injection, but almost. Please enable this option only when you
1275 trust the remote server.
1277 In case of an error during generation of the wrapper function,
1278 FALSE is returned, otherwise the name (or source code) of the new
1281 Known limitations: server must support
1282 system.methodsignature for the wanted xmlrpc
1283 method; for methods that expose multiple signatures, only one can be
1284 picked; for remote calls with nested xmlrpc params, the caller of the
1285 generated php function has to encode on its own the params passed to
1286 the php function if these are structs or arrays whose (sub)members
1287 include values of type base64.
1289 Note: calling the generated php function 'might' be slow: a new
1290 xmlrpc client is created on every invocation and an xmlrpc-connection
1291 opened+closed. An extra 'debug' param is appended to the parameter
1292 list of the generated php function, useful for debugging
1301 $c = new xmlrpc_client('http://phpxmlrpc.sourceforge.net/server.php');
1303 $function = wrap_xmlrpc_method($client, 'examples.getStateName');
1306 die('Cannot introspect remote method');
1309 $statename = $function($a);
1310 if (is_a($statename, 'xmlrpcresp')) // call failed
1312 echo 'Call failed: '.$statename->faultCode().'. Calling again with debug on';
1313 $function($a, true);
1316 echo "OK, state nr. $stateno is $statename";
1321 [[wrap_php_function]]
1323 ==== wrap_php_function
1325 arraywrap_php_functionstring$funcnamestring$wrapper_function_namearray$extra_optionsGiven a user-defined PHP function, create a PHP 'wrapper'
1326 function that can be exposed as xmlrpc method from an xmlrpc_server
1327 object and called from remote clients, and return the appropriate
1328 definition to be added to a server's dispatch map.
1330 The optional $wrapper_function_name
1331 specifies the name that will be used for the auto-generated
1334 Since php is a typeless language, to infer types of input and
1335 output parameters, it relies on parsing the javadoc-style comment
1336 block associated with the given function. Usage of xmlrpc native types
1337 (such as datetime.dateTime.iso8601 and base64) in the docblock @param
1338 tag is also allowed, if you need the php function to receive/send data
1339 in that particular format (note that base64 encoding/decoding is
1340 transparently carried out by the lib, while datetime vals are passed
1343 Known limitations: only works for
1344 user-defined functions, not for PHP internal functions (reflection
1345 does not support retrieving number/type of params for those); the
1346 wrapped php function will not be able to programmatically return an
1347 xmlrpc error response.
1349 If the ++$$return_source$$++ optional parameter is
1350 set, the function will return the php source code to build the wrapper
1351 function, instead of evaluating it (useful to save the code and use it
1352 later in a stand-alone xmlrpc server). It will be in the stored in the
1353 ++source++ member of the returned array.
1355 If the ++$$suppress_warnings$$++ optional parameter
1356 is set, any runtime warning generated while processing the
1357 user-defined php function will be catched and not be printed in the
1358 generated xml response.
1360 If the extra_options array contains the
1361 ++$$encode_php_objs$$++ value, wrapped functions returning
1362 php objects will generate "special" xmlrpc responses: when the xmlrpc
1363 decoding of those responses is carried out by this same lib, using the
1364 appropriate param in php_xmlrpc_decode(), the objects will be
1367 In short: php objects can be serialized, too (except for their
1368 resource members), using this function. Other libs might choke on the
1369 very same xml that will be generated in this case (i.e. it has a
1370 nonstandard attribute on struct element tags)
1372 If the ++$$decode_php_objs$$++ optional parameter is
1373 set, instances of php objects that have been appropriately encoded by
1374 the client using a coordinate option will be deserialized and passed
1375 to the user function as php objects instead of simple arrays (the same
1376 class definition should be present server side and client
1379 __Note that this might pose a security risk__,
1380 since in order to rebuild the object instances their constructor
1381 method has to be invoked, and this means that the remote client can
1382 trigger execution of unforeseen php code on the server: not really a
1383 code injection, but almost. Please enable this option only when you
1384 trust the remote clients.
1392 * State name from state number decoder. NB: do NOT remove this comment block.
1393 * @param integer $stateno the state number
1394 * @return string the name of the state (or error description)
1396 function findstate($stateno)
1399 if (isset($stateNames[$stateno-1]))
1401 return $stateNames[$stateno-1];
1405 return "I don't have a state for the index '" . $stateno . "'";
1409 // wrap php function, build xmlrpc server
1411 $findstate_sig = wrap_php_function('findstate');
1413 $methods['examples.getStateName'] = $findstate_sig;
1414 $srv = new xmlrpc_server($methods);
1420 === Functions removed from the library
1422 The following two functions have been deprecated in version 1.1 of
1423 the library, and removed in version 2, in order to avoid conflicts with
1424 the EPI xml-rpc library, which also defines two functions with the same
1427 To ease the transition to the new naming scheme and avoid breaking
1428 existing implementations, the following scheme has been adopted:
1430 * If EPI-XMLRPC is not active in the current PHP installation,
1431 the constant `XMLRPC_EPI_ENABLED` will be set to
1435 * If EPI-XMLRPC is active in the current PHP installation, the
1436 constant `XMLRPC_EPI_ENABLED` will be set to
1441 The following documentation is kept for historical
1448 mixedx mlrpc_decode xmlrpcval $xmlrpc_val Alias for php_xmlrpc_decode.
1454 xmlrpcval xmlrpc_encode mixed $phpvalAlias for php_xmlrpc_encode.
1460 ==== xmlrpc_debugmsg
1462 void xmlrpc_debugmsgstring$debugstringSends the contents of $debugstring in XML
1463 comments in the server return payload. If a PHP client has debugging
1464 turned on, the user will be able to see server debug
1467 Use this function in your methods so you can pass back
1468 diagnostic information. It is only available from
1476 In order to extend the functionality offered by XML-RPC servers
1477 without impacting on the protocol, reserved methods are supported in this
1480 All methods starting with system. are
1481 considered reserved by the server. PHP for XML-RPC itself provides four
1482 special methods, detailed in this chapter.
1484 Note that all server objects will automatically respond to clients
1485 querying these methods, unless the property
1486 allow_system_funcs has been set to
1487 false before calling the
1488 service() method. This might pose a security risk
1489 if the server is exposed to public access, e.g. on the internet.
1492 === system.getCapabilities
1495 === system.listMethods
1497 This method may be used to enumerate the methods implemented by
1500 The system.listMethods method requires no
1501 parameters. It returns an array of strings, each of which is the name of
1502 a method implemented by the server.
1506 === system.methodSignature
1508 This method takes one parameter, the name of a method implemented
1509 by the XML-RPC server.
1511 It returns an array of possible signatures for this method. A
1512 signature is an array of types. The first of these types is the return
1513 type of the method, the rest are parameters.
1515 Multiple signatures (i.e. overloading) are permitted: this is the
1516 reason that an array of signatures are returned by this method.
1518 Signatures themselves are restricted to the top level parameters
1519 expected by a method. For instance if a method expects one array of
1520 structs as a parameter, and it returns a string, its signature is simply
1521 "string, array". If it expects three integers, its signature is "string,
1524 For parameters that can be of more than one type, the "undefined"
1525 string is supported.
1527 If no signature is defined for the method, a not-array value is
1528 returned. Therefore this is the way to test for a non-signature, if
1529 $resp below is the response object from a method
1530 call to system.methodSignature:
1535 $v = $resp->value();
1536 if ($v->kindOf() != "array") {
1537 // then the method did not have a signature defined
1542 See the __introspect.php__ demo included in this
1543 distribution for an example of using this method.
1547 === system.methodHelp
1549 This method takes one parameter, the name of a method implemented
1550 by the XML-RPC server.
1552 It returns a documentation string describing the use of that
1553 method. If no such string is available, an empty string is
1556 The documentation string may contain HTML markup.
1558 === system.multicall
1560 This method takes one parameter, an array of 'request' struct
1561 types. Each request struct must contain a
1562 methodName member of type string and a
1563 params member of type array, and corresponds to
1564 the invocation of the corresponding method.
1566 It returns a response of type array, with each value of the array
1567 being either an error struct (containing the faultCode and faultString
1568 members) or the successful response value of the corresponding single
1576 The best examples are to be found in the sample files included with
1577 the distribution. Some are included here.
1581 === XML-RPC client: state name query
1583 Code to get the corresponding state name from a number (1-50) from
1584 the demo server available on SourceForge
1589 $m = new xmlrpcmsg('examples.getStateName',
1590 array(new xmlrpcval($HTTP_POST_VARS["stateno"], "int")));
1591 $c = new xmlrpc_client("/server.php", "phpxmlrpc.sourceforge.net", 80);
1593 if (!$r->faultCode()) {
1595 print "State number " . htmlentities($HTTP_POST_VARS["stateno"]) . " is " .
1596 htmlentities($v->scalarval()) . "<BR>";
1597 print "<HR>I got this value back<BR><PRE>" .
1598 htmlentities($r->serialize()) . "</PRE><HR>\n";
1601 print "Code: " . htmlentities($r->faultCode()) . "<BR>" .
1602 "Reason: '" . htmlentities($r->faultString()) . "'<BR>";
1607 === Executing a multicall call
1615 == Frequently Asked Questions
1617 ==== How to send custom XML as payload of a method call::
1619 Unfortunately, at the time the XML-RPC spec was designed, support
1620 for namespaces in XML was not as ubiquitous as it is now. As a
1621 consequence, no support was provided in the protocol for embedding XML
1622 elements from other namespaces into an xmlrpc request.
1624 To send an XML "chunk" as payload of a method call or response,
1625 two options are available: either send the complete XML block as a
1626 string xmlrpc value, or as a base64 value. Since the '<' character in
1627 string values is encoded as '<' in the xml payload of the method
1628 call, the XML string will not break the surrounding xmlrpc, unless
1629 characters outside of the assumed character set are used. The second
1630 method has the added benefits of working independently of the charset
1631 encoding used for the xml to be transmitted, and preserving exactly
1632 whitespace, whilst incurring in some extra message length and cpu load
1633 (for carrying out the base64 encoding/decoding).
1636 ==== Is there any limitation on the size of the requests / responses that can be successfully sent?::
1638 Yes. But I have no hard figure to give; it most likely will depend
1639 on the version of PHP in usage and its configuration.
1641 Keep in mind that this library is not optimized for speed nor for
1642 memory usage. Better alternatives exist when there are strict
1643 requirements on throughput or resource usage, such as the php native
1644 xmlrpc extension (see the PHP manual for more information).
1646 Keep in mind also that HTTP is probably not the best choice in
1647 such a situation, and XML is a deadly enemy. CSV formatted data over
1648 socket would be much more efficient.
1650 If you really need to move a massive amount of data around, and
1651 you are crazy enough to do it using phpxmlrpc, your best bet is to
1652 bypass usage of the xmlrpcval objects, at least in the decoding phase,
1653 and have the server (or client) object return to the calling function
1654 directly php values (see xmlrpc_client::return_type
1655 and xmlrpc_server::functions_parameters_type for more
1659 ==== My server (client) returns an error whenever the client (server) returns accented characters
1664 ==== How to enable long-lasting method calls
1669 ==== My client returns "XML-RPC Fault #2: Invalid return payload: enable debugging to examine incoming payload": what should I do?
1671 The response you are seeing is a default error response that the
1672 client object returns to the php application when the server did not
1673 respond to the call with a valid xmlrpc response.
1675 The most likely cause is that you are not using the correct URL
1676 when creating the client object, or you do not have appropriate access
1677 rights to the web page you are requesting, or some other common http
1680 To find out what the server is really returning to your client,
1681 you have to enable the debug mode of the client, using
1682 $client->setdebug(1);
1685 ==== How can I save to a file the xml of the xmlrpc responses received from servers?
1687 If what you need is to save the responses received from the server
1688 as xml, you have two options:
1690 1- use the serialize() method on the response object.
1696 $resp = $client->send($msg);
1697 if (!$resp->faultCode())
1698 $data_to_be_saved = $resp->serialize();
1702 Note that this will not be 100% accurate, since the xml generated
1703 by the response object can be different from the xml received,
1704 especially if there is some character set conversion involved, or such
1705 (eg. if you receive an empty string tag as <string/>, serialize()
1706 will output <string></string>), or if the server sent back
1707 as response something invalid (in which case the xml generated client
1708 side using serialize() will correspond to the error response generated
1709 internally by the lib).
1711 2 - set the client object to return the raw xml received instead
1712 of the decoded objects:
1718 $client = new xmlrpc_client($url);
1719 $client->return_type = 'xml';
1720 $resp = $client->send($msg);
1721 if (!$resp->faultCode())
1722 $data_to_be_saved = $resp->value();
1726 Note that using this method the xml response response will not be
1727 parsed at all by the library, only the http communication protocol will
1728 be checked. This means that xmlrpc responses sent by the server that
1729 would have generated an error response on the client (eg. malformed xml,
1730 responses that have faultcode set, etc...) now will not be flagged as
1731 invalid, and you might end up saving not valid xml but random
1735 ==== Can I use the ms windows character set?
1737 If the data your application is using comes from a Microsoft
1738 application, there are some chances that the character set used to
1739 encode it is CP1252 (the same might apply to data received from an
1740 external xmlrpc server/client, but it is quite rare to find xmlrpc
1741 toolkits that encode to CP1252 instead of UTF8). It is a character set
1742 which is "almost" compatible with ISO 8859-1, but for a few extra
1745 PHP-XMLRPC only supports the ISO 8859-1 and UTF8 character sets.
1746 The net result of this situation is that those extra characters will not
1747 be properly encoded, and will be received at the other end of the
1748 XML-RPC transmission as "garbled data". Unfortunately the library cannot
1749 provide real support for CP1252 because of limitations in the PHP 4 xml
1750 parser. Luckily, we tried our best to support this character set anyway,
1751 and, since version 2.2.1, there is some form of support, left commented
1754 To properly encode outgoing data that is natively in CP1252, you
1755 will have to uncomment all relative code in the file
1756 __xmlrpc.inc__ (you can search for the string "1252"),
1757 then set ++$$$GLOBALS['xmlrpc_internalencoding']='CP1252';$$++
1758 Please note that all incoming data will then be fed to your application
1759 as UTF-8 to avoid any potential data loss.
1762 ==== Does the library support using cookies / http sessions?
1764 In short: yes, but a little coding is needed to make it
1767 The code below uses sessions to e.g. let the client store a value
1768 on the server and retrieve it later.
1773 $resp = $client->send(new xmlrpcmsg('registervalue', array(new xmlrpcval('foo'), new xmlrpcval('bar'))));
1774 if (!$resp->faultCode())
1776 $cookies = $resp->cookies();
1777 if (array_key_exists('PHPSESSID', $cookies)) // nb: make sure to use the correct session cookie name
1779 $session_id = $cookies['PHPSESSID']['value'];
1781 // do some other stuff here...
1783 $client->setcookie('PHPSESSID', $session_id);
1784 $val = $client->send(new xmlrpcmsg('getvalue', array(new xmlrpcval('foo')));
1790 Server-side sessions are handled normally like in any other
1791 php application. Please see the php manual for more information about
1794 NB: unlike web browsers, not all xmlrpc clients support usage of
1795 http cookies. If you have troubles with sessions and control only the
1796 server side of the communication, please check with the makers of the
1797 xmlrpc client in use.
1803 == Integration with the PHP xmlrpc extension
1805 To be documented more...
1807 In short: for the fastest execution possible, you can enable the php
1808 native xmlrpc extension, and use it in conjunction with phpxmlrpc. The
1809 following code snippet gives an example of such integration
1815 /*** client side ***/
1816 $c = new xmlrpc_client('http://phpxmlrpc.sourceforge.net/server.php');
1818 // tell the client to return raw xml as response value
1819 $c->return_type = 'xml';
1821 // let the native xmlrpc extension take care of encoding request parameters
1822 $r = $c->send(xmlrpc_encode_request('examples.getStateName', $_POST['stateno']));
1824 if ($r->faultCode())
1825 // HTTP transport error
1826 echo 'Got error '.$r->faultCode();
1829 // HTTP request OK, but XML returned from server not parsed yet
1830 $v = xmlrpc_decode($r->value());
1831 // check if we got a valid xmlrpc response from server
1833 echo 'Got invalid response';
1835 // check if server sent a fault response
1836 if (xmlrpc_is_fault($v))
1837 echo 'Got xmlrpc fault '.$v['faultCode'];
1839 echo'Got response: '.htmlentities($v);
1848 == Substitution of the PHP xmlrpc extension
1850 Yet another interesting situation is when you are using a ready-made
1851 php application, that provides support for the XMLRPC protocol via the
1852 native php xmlrpc extension, but the extension is not available on your
1853 php install (e.g. because of shared hosting constraints).
1855 Since version 2.1, the PHP-XMLRPC library provides a compatibility
1856 layer that aims to be 100% compliant with the xmlrpc extension API. This
1857 means that any code written to run on the extension should obtain the
1858 exact same results, albeit using more resources and a longer processing
1859 time, using the PHP-XMLRPC library and the extension compatibility module.
1860 The module is part of the EXTRAS package, available as a separate download
1861 from the sourceforge.net website, since version 0.2
1867 == 'Enough of xmlrpcvals!': new style library usage
1871 In the meantime, see docs about xmlrpc_client::return_type and
1872 xmlrpc_server::functions_parameters_types, as well as php_xmlrpc_encode,
1873 php_xmlrpc_decode and php_xmlrpc_decode_xml
1879 == Usage of the debugger
1881 A webservice debugger is included in the library to help during
1882 development and testing.
1884 The interface should be self-explicative enough to need little
1887 image::debugger.gif[,,,,align="center"]
1889 The most useful feature of the debugger is without doubt the "Show
1890 debug info" option. It allows to have a screen dump of the complete http
1891 communication between client and server, including the http headers as
1892 well as the request and response payloads, and is invaluable when
1893 troubleshooting problems with charset encoding, authentication or http
1896 The debugger can take advantage of the JSONRPC library extension, to
1897 allow debugging of JSON-RPC webservices, and of the JS-XMLRPC library
1898 visual editor to allow easy mouse-driven construction of the payload for
1899 remote methods. Both components have to be downloaded separately from the
1900 sourceforge.net web pages and copied to the debugger directory to enable
1901 the extra functionality:
1904 * to enable jsonrpc functionality, download the PHP-XMLRPC
1905 EXTRAS package, and copy the file __jsonrpc.inc__
1906 either to the same directory as the debugger or somewhere in your
1910 * to enable the visual value editing dialog, download the
1911 JS-XMLRPC library, and copy somewhere in the web root files
1912 __visualeditor.php__,
1913 __visualeditor.css__ and the folders
1914 __yui__ and __img__. Then edit the
1915 debugger file __controller.php__ and set
1916 appropriately the variable $editorpath.
1925 CAUTION: not all items the following list have (yet) been fully documented, and some might not be present in any other
1926 chapter in the manual. To find a more detailed description of new functions and methods please take a look at the
1927 source code of the library, which is quite thoroughly commented in phpdoc form.
1931 * new: introduction of namespaces and full OOP.
1933 All php classes have been renamed and moved to separate files.
1935 Class autoloading can now be done in accord with the PSR-4 standard.
1937 All global variables and global functions have been removed.
1939 Iterating over xmlrpc value objects is now easier thank to support for ArrayAccess and Traversable interfaces.
1941 Backward compatibility is maintained via _lib/xmlrpc.inc_, _lib/xmlrpcs.inc_ and _lib/xmlrpc_wrappers.inc_.
1942 For more details, head on to doc/api_changes_v4.md
1944 * changed: the default character encoding delivered from the library to your code is now utf8.
1945 It can be changed at any time setting a value to `PhpXmlRpc\PhpXmlRpc::$xmlrpc_internalencoding`
1947 * improved: the library now accepts requests/responses sent using other character sets than UTF-8/ISO-8859-1/ASCII.
1948 This only works when the mbstring php extension is enabled.
1950 * improved: no need to call anymore `$client->setSSLVerifyHost(2)` to silence a curl warning when using https
1951 with recent curl builds
1953 * improved: the xmlrpcval class now supports the interfaces `Countable` and `IteratorAggregate`
1955 * improved: a specific option allows users to decide the version of SSL to use for https calls.
1956 This is useful f.e. for the testing suite, when the server target of calls has no proper ssl certificate,
1957 and the cURL extension has been compiled with GnuTLS (such as on Travis VMs)
1959 * improved: the function `wrap_php_function()` now can be used to wrap closures (it is now a method btw)
1961 * improved: all _wrap_something()_ functions now return a closure by default instead of a function name
1963 * improved: debug messages are not html-escaped any more when executing from the command line
1965 * improved: the library is now tested using Travis ( https://travis-ci.org/ ).
1966 Tests are executed using all php versions from 5.3 to 7.0 nightly, plus HHVM; code-coverage information
1967 is generated using php 5.6 and uploaded to both Code Coverage and Scrutinizer online services
1969 * improved: phpunit is now installed via composer, not bundled anymore
1971 * improved: when phpunit is used to generate code-coverage data, the code executed server-side is accounted for
1973 * improved: the test suite has basic checks for the debugger and demo files
1975 * improved: more tests in the test suite
1977 * fixed: the server would not reset the user-set debug messages between subsequent `service()` calls
1979 * fixed: the server would not reset previous php error handlers when an exception was thrown by user code and
1980 exception_handling set to 2
1982 * fixed: the server would fail to decode a request with ISO-8859-1 payload and character set declaration in the xml
1985 * fixed: the client would fail to decode a response with ISO-8859-1 payload and character set declaration in the xml
1988 * fixed: the function `decode_xml()` would not decode an xml with character set declaration in the xml prolog
1990 * fixed: the client can now successfully call methods using ISO-8859-1 or UTF-8 characters in their name
1992 * fixed: the debugger would fail sending a request with ISO-8859-1 payload (it missed the character set declaration).
1993 It would have a hard time coping with ISO-8859-1 in other fields, such as e.g. the remote method name
1995 * fixed: the debugger would generate a bad payload via the 'load method synopsis' button for signatures containing NULL
1996 or undefined parameters
1998 * fixed: the debugger would generate a bad payload via the 'load method synopsis' button for methods with multiple
2001 * improved: the debugger is displayed using UTF-8, making it more useful to debug any kind of service
2003 * improved: echo all debug messages even when there are characters in them which php deems to be in a wrong encoding;
2004 previously those messages would just disappear (this is visible e.g. in the debugger)
2006 * changed: debug info handling
2007 - at debug level 1, the rebuilt php objects are not dumped to screen (server-side already did that)
2008 - at debug level 1, curl communication info are not dumped to screen
2009 - at debug level 1, the tests echo payloads of failures; at debug level 2 all payloads
2011 * improved: makefiles have been replaced with a php_based pakefile
2013 * improved: the source for the manual is stored in asciidoc format, which can be displayed natively by GitHub
2014 with nice html formatting. Also the HTML version generated by hand and bundled in tarballs is much nicer
2015 to look at than previous versions
2017 * improved: all php code is now formatted according to the PSR-2 standard
2021 __Note:__ this is the last release of the library that will support PHP 5.1 and up. Future releases will target php 5.3
2022 as minimum supported version.
2024 * when using curl and keepalive, reset curl handle if we did not get back an http 200 response (eg a 302)
2026 * omit port on http 'Host' header if it is 80
2028 * test suite allows interrogating https servers ignoring their certs
2030 * method `setAcceptedCompression` was failing to disable reception of compressed responses if the client supported them
2034 This is the first release of the library to only support PHP 5. Some legacy code has been removed, and support for
2035 features such as exceptions and dateTime objects introduced.
2037 The "beta" tag is meant to indicate the fact that the refactoring has been more widespread than in precedent releases
2038 and that more changes are likely to be introduced with time - the library is still considered to be production
2041 * improved: removed all usage of php functions deprecated in php 5.3, usage of assign-by-ref when creating new objects
2044 * improved: add support for the `<ex:nil>` tag used by the apache library, both in input and output
2046 * improved: add support for dateTime objects in both in php_xmlrpc_encode and as parameter for constructor of xmlrpcval
2048 * improved: add support for timestamps as parameter for constructor of xmlrpcval
2050 * improved: add option `dates_as_objects` to `php_xmlrpc_decode` to return dateTime objects for xmlrpc datetimes
2052 * improved: add new method `SetCurlOptions` to xmrlpc_client to allow extra flexibility in tweaking http config, such as
2053 explicitly binding to an ip address
2055 * improved: add new method `SetUserAgent` to xmrlpc_client to to allow having different user-agent http headers
2057 * improved: add a new member variable in server class to allow fine-tuning of the encoding of returned values when the
2058 server is in 'phpvals' mode
2060 * improved: allow servers in 'xmlrpcvals' mode to also register plain php functions by defining them in the dispatch map
2061 with an added option
2063 * improved: catch exceptions thrown during execution of php functions exposed as methods by the server
2065 * fixed: bad encoding if same object is encoded twice using `php_xmlrpc_encode`
2069 __Note:__ this is the last release of the library that will support PHP 4. Future releases (if any) should target
2070 php 5.0 as minimum supported version.
2072 * fixed: encoding of utf-8 characters outside of the BMP plane
2074 * fixed: character set declarations surrounded by double quotes were not recognized in http headers
2076 * fixed: be more tolerant in detection of charset in http headers
2078 * fixed: fix detection of zlib.output_compression
2080 * fixed: use `feof()` to test if socket connections are to be closed instead of the number of bytes read (rare bug when
2081 communicating with some servers)
2083 * fixed: format floating point values using the correct decimal separator even when php locale is set to one that uses
2086 * fixed: improve robustness of the debugger when parsing weird results from non-compliant servers
2088 * php warning when receiving `false` in a bool value
2090 * improved: allow the add_to_map server method to add docs for single params too
2092 * improved: added the possibility to wrap for exposure as xmlrpc methods plain php class methods, object methods and even
2097 * fixed: work aroung bug in php 5.2.2 which broke support of `HTTP_RAW_POST_DATA`
2099 * fixed: is_dir parameter of `setCaCertificate()` method is reversed
2101 * fixed: a php warning in xmlrpc_client creator method
2103 * fixed: parsing of `1e+1` as valid float
2105 * fixed: allow errorlevel 3 to work when prev. error handler was a static method
2107 * fixed: usage of `client::setcookie()` for multiple cookies in non-ssl mode
2109 * improved: support for CP1252 charset is not part or the library but almost possible
2111 * improved: more info when curl is enabled and debug mode is on
2115 * fixed: debugger errors on php installs with `magic_quotes_gpc` on
2117 * fixed: support for https connections via proxy
2119 * fixed: `wrap_xmlrpc_method()` generated code failed to properly encode php objects
2121 * improved: slightly faster encoding of data which is internally UTF-8
2123 * improved: debugger always generates a `null` id for jsonrpc if user omits it
2125 * new: debugger can take advantage of a graphical value builder (it has to be downloaded separately, as part of jsxmlrpc
2126 package. See Appendix D for more details)
2128 * new: support for the `<NIL/>` xmlrpc extension. see below for more details
2130 * new: server support for the `system.getCapabilities` xmlrpc extension
2132 * new: `wrap_xmlrpc_method`, `wrap_xmlrpc_method()` accepts two new options: debug and return_on_fault
2136 * The wrap_php_function and wrap_xmlrpc_method functions have been moved out of the base library file _xmlrpc.inc_
2137 into a file of their own: _xmlrpc_wrappers.php_. You will have to include() / require() it in your scripts if
2138 you have been using those functions.
2139 For increased security, the automatic rebuilding of php object instances out ofreceived xmlrpc structs in
2140 `wrap_xmlrpc_method()` has been disabled (but it can be optionally re-enabled).
2141 Both `wrap_php_function()` and `wrap_xmlrpc_method()` functions accept many more options to fine tune their behaviour,
2142 including one to return the php code to be saved and later used as standalone php script
2144 * The constructor of xmlrpcval() values has seen some internal changes, and it will not throw a php warning anymore when
2145 invoked using an unknown xmlrpc type: the error will only be written to php error log. Also
2146 `new xmlrpcval('true', 'boolean')` is not supported anymore
2148 * The new function `php_xmlrpc_decode_xml()` will take the xml representation of either an xmlrpc request, response or
2149 single value and return the corresponding php-xmlrpc object instance
2151 * A new function `wrap_xmlrpc_server()` has been added, to wrap all (or some) of the methods exposed by a remote xmlrpc
2152 server into a php class
2154 * A new file has been added: _verify_compat.php_, to help users diagnose the level of compliance of their php
2155 installation with the library
2157 * Restored compatibility with php 4.0.5 (for those poor souls still stuck on it)
2159 * Method `xmlrpc_server->service()` now returns a value: either the response payload or xmlrpcresp object instance
2161 * Method `xmlrpc_server->add_to_map()` now accepts xmlrpc methods with no param definitions
2163 * Documentation for single parameters of exposed methods can be added to the dispatch map (and turned into html docs in
2164 conjunction with a future release of the 'extras' package)
2166 * Full response payload is saved into xmlrpcresp object for further debugging
2168 * The debugger can now generate code that wraps a remote method into a php function (works for jsonrpc, too); it also
2169 has better support for being activated via a single GET call (e.g. for integration into other tools)
2171 * Stricter parsing of incoming xmlrpc messages: two more invalid cases are now detected (double `data` element inside
2172 `array` and `struct`/`array` after scalar inside `value` element)
2174 * More logging of errors in a lot of situations
2176 * Javadoc documentation of lib files (almost) complete
2178 * Many performance tweaks and code cleanups, plus the usual crop of bugs fixed (see NEWS file for complete list of bugs)
2180 * Lib internals have been modified to provide better support for grafting extra functionality on top of it. Stay tuned
2181 for future releases of the EXTRAS package (or go read Appendix B)...
2185 * Added to the client class the possibility to use Digest and NTLM authentication methods (when using the CURL library)
2186 for connecting to servers and NTLM for connecting to proxies
2188 * Added to the client class the possibility to specify alternate certificate files/directories for authenticating the
2189 peer with when using HTTPS communication
2191 * Reviewed all examples and added a new demo file, containing a proxy to forward xmlrpc requests to other servers
2192 (useful e.g. for ajax coding)
2194 * The debugger has been upgraded to reflect the new client capabilities
2196 * All known bugs have been squashed, and the lib is more tolerant than ever of commonly-found mistakes
2198 === 2.0 Release candidate 3
2200 * Added to server class the property functions_parameters_type, that allows the server to register plain php functions
2201 as xmlrpc methods (i.e. functions that do not take an xmlrpcmsg object as unique param)
2203 * let server and client objects serialize calls using a specified character set encoding for the produced xml instead of
2204 US-ASCII (ISO-8859-1 and UTF-8 supported)
2206 * let `php_xmlrpc_decode` accept xmlrpcmsg objects as valid input
2208 * 'class::method' syntax is now accepted in the server dispatch map
2210 * `xmlrpc_clent::SetDebug()` accepts integer values instead of a boolean value, with debugging level 2 adding to the
2211 information printed to screen the complete client request
2213 === 2.0 Release candidate 2
2215 * Added a new property of the client object: `xmlrpc_client->return_type`, indicating whether calls to the
2216 send() method will return xmlrpcresp objects whose value() is an xmlrpcval object, a php value (automatically
2217 decoded) or the raw xml received from the server.
2219 * Added in the extras dir. two new library files: _jsonrpc.inc_ and _jsonrpcs.inc_ containing new classes that
2220 implement support for the json-rpc protocol (alpha quality code)
2222 * Added a new client method: `setKey($key, $keypass)` to be used in HTTPS connections
2224 * Added a new file containing some benchmarks in the testsuite directory
2226 === 2.0 Release candidate 1
2228 * Support for HTTP proxies (new method: `xmlrpc_client::setProxy()`)
2230 * Support HTTP compression of both requests and responses.
2231 Clients can specify what kind of compression they accept for responses between deflate/gzip/any, and whether to
2232 compress the requests.
2233 Servers by default compress responses to clients that explicitly declare support for compression (new methods:
2234 `xmlrpc_client::setAcceptedCompression()`, `xmlrpc_client::setRequestCompression()`).
2235 Note that the ZLIB php extension needs to be enabled in PHP to support compression.
2237 * Implement HTTP 1.1 connections, but only if CURL is enabled (added an extra parameter to
2238 `xmlrpc_client::xmlrpc_client` to set the desired HTTP protocol at creation time and a new supported value for
2239 the last parameter of `xmlrpc_client::send`, which now can be safely omitted if it has been specified at
2242 With PHP versions greater than 4.3.8 keep-alives are enabled by default for HTTP 1.1 connections. This should yield
2243 faster execution times when making multiple calls in sequence to the same xml-rpc server from a single client.
2245 * Introduce support for cookies.
2246 Cookies to be sent to the server with a request can be set using `xmlrpc_client::setCookie()`, while cookies
2247 received from the server are found in ++xmlrpcresp::cookies()++. It is left to the user to check for validity of
2248 received cookies and decide whether they apply to successive calls or not.
2250 * Better support for detecting different character set encodings of xml-rpc requests and responses: both client and
2251 server objects will correctly detect the charset encoding of received xml, and use an appropriate xml parser.
2253 Supported encodings are US-ASCII, UTF-8 and ISO-8859-1.
2255 * Added one new xmlrpcmsg constructor syntax, allowing usage of a single string with the complete URL of the target
2258 * Convert xml-rpc boolean values into native php values instead of 0 and 1
2260 * Force the `php_xmlrpc_encode` function to properly encode numerically indexed php arrays into xml-rpc arrays
2261 (numerically indexed php arrays always start with a key of 0 and increment keys by values of 1)
2263 * Prevent the `php_xmlrpc_encode` function from further re-encoding any objects of class ++xmlrpcval++ that
2264 are passed to it. This allows to call the function with arguments consisting of mixed php values / xmlrpcval objects
2266 * Allow a server to NOT respond to system.* method calls (setting the `$server->allow_system_funcs` property).
2268 * Implement a new xmlrpcval method to determine if a value of type struct has a member of a given name without having to
2269 loop trough all members: `xmlrpcval::structMemExists()`
2271 * Expand methods `xmlrpcval::addArray`, `addScalar` and `addStruct` allowing extra php values to be added to
2272 xmlrpcval objects already formed.
2274 * Let the `xmlrpc_client::send` method accept an XML string for sending instead of an xmlrpcmsg object, to
2275 facilitate debugging and integration with the php native xmlrpc extension
2277 * Extend the `php_xmlrpc_encode` and `php_xmlrpc_decode` functions to allow serialization and rebuilding of
2278 PHP objects. To successfully rebuild a serialized object, the object class must be defined in the deserializing end
2279 of the transfer. Note that object members of type resource will be deserialized as NULL values.
2281 Note that his has been implemented adding a "php_class" attribute to xml representation of xmlrpcval of STRUCT type,
2282 which, strictly speaking, breaks the xml-rpc spec. Other xmlrpc implementations are supposed to ignore such an
2283 attribute (unless they implement a brain-dead custom xml parser...), so it should be safe enabling it in
2284 heterogeneous environments. The activation of this feature is done by usage of an option passed as second parameter
2285 to both `php_xmlrpc_encode` and `php_xmlrpc_decode`.
2287 * Extend the `php_xmlrpc_encode` function to allow automatic serialization of iso8601-conforming php strings as
2288 datetime.iso8601 xmlrpcvals, by usage of an optional parameter
2290 * Added an automatic stub code generator for converting xmlrpc methods to php functions and vice-versa.
2292 This is done via two new functions: `wrap_php_function` and `wrap_xmlrpc_method`, and has many caveats,
2293 with php being a typeless language and all...
2295 * Allow object methods to be used in server dispatch map
2297 * Added a complete debugger solution, in the __debugger__ folder
2299 * Added configurable server-side debug messages, controlled by the new method `xmlrpc_server::SetDebug()`.
2300 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
2301 more info is echoed back to the client, regarding the received call; at level 3 all warnings raised during server
2302 processing are trapped (this prevents breaking the xml to be echoed back to the client) and added to the debug info
2303 sent back to the client
2305 * New XML parsing code, yields smaller memory footprint and faster execution times, not to mention complete elimination
2306 of the dreaded __eval()__ construct, so prone to code injection exploits
2308 * Rewritten most of the error messages, making text more explicative
2310 ++++++++++++++++++++++++++++++++++++++
2311 <!-- Keep this comment at the end of the file
2316 sgml-minimize-attributes:nil
2317 sgml-always-quote-attributes:t
2320 sgml-parent-document:nil
2321 sgml-exposed-tags:nil
2322 sgml-local-catalogs:nil
2323 sgml-local-ecat-files:nil
2324 sgml-namecase-general:t
2325 sgml-general-insert-case:lower
2328 ++++++++++++++++++++++++++++++++++++++