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.
229 The type i8 on the other hand is considered as a separate type.
230 Note that the library will never output integers as 'i8' on its own,
231 even when php is compiled in 64-bit mode.
235 Base 64 encoding is performed transparently to the caller when
236 using this type. Decoding is also transparent. Therefore you ought
237 to consider it as a "binary" data type, for use when you want to
238 pass data that is not 7-bit clean.
242 The php values ++true++ and
243 ++1++ map to ++true++. All other
244 values (including the empty string) are converted to
249 Characters <, >;, ', ", &, are encoded using their
250 entity reference as < > ' " and
251 & All other characters outside of the ASCII range are
252 encoded using their character reference representation (e.g.
253 È for é). The XML-RPC spec recommends only encoding
254 ++< >++ but this implementation goes further,
255 for reasons explained by link:$$http://www.w3.org/TR/REC-xml#syntax$$[the XML 1.0 recommendation]. In particular, using character reference
256 representation has the advantage of producing XML that is valid
257 independently of the charset encoding assumed.
261 There is no support for encoding ++null++
262 values in the XML-RPC spec, but at least a couple of extensions (and
263 many toolkits) do support it. Before using ++null++
264 values in your messages, make sure that the responding party accepts
265 them, and uses the same encoding convention (see ...).
267 [[xmlrpcval-creation]]
269 ==== Xmlrpcval creation
271 The constructor is the normal way to create an
272 xmlrpcval. The constructor can take these
276 xmlrpcval xmlrpcvalnew
277 xmlrpcval string $stringVal xmlrpcvalnew
278 xmlrpcval mixed $scalarVal string$scalartyp xmlrpcvalnew
279 xmlrpcval array $arrayVal string $arraytyp The first constructor creates an empty value, which must be
280 altered using the methods addScalar,
281 addArray or addStruct before
284 The second constructor creates a simple string value.
286 The third constructor is used to create a scalar value. The
287 second parameter must be a name of an XML-RPC type. Valid types are:
288 "++int++", "++boolean++",
289 "++string++", "++double++",
290 "++dateTime.iso8601++", "++base64++" or
298 $myInt = new xmlrpcval(1267, "int");
299 $myString = new xmlrpcval("Hello, World!", "string");
300 $myBool = new xmlrpcval(1, "boolean");
301 $myString2 = new xmlrpcval(1.24, "string"); // note: this will serialize a php float value as xmlrpc string
305 The fourth constructor form can be used to compose complex
306 XML-RPC values. The first argument is either a simple array in the
307 case of an XML-RPC array or an associative
308 array in the case of a struct. The elements of
309 the array __must be xmlrpcval objects themselves__.
311 The second parameter must be either "++array++"
319 $myArray = new xmlrpcval(
321 new xmlrpcval("Tom"),
322 new xmlrpcval("Dick"),
323 new xmlrpcval("Harry")
328 $myStruct = new xmlrpcval(
330 "name" => new xmlrpcval("Tom", "string"),
331 "age" => new xmlrpcval(34, "int"),
332 "address" => new xmlrpcval(
334 "street" => new xmlrpcval("Fifht Ave", "string"),
335 "city" => new xmlrpcval("NY", "string")
343 See the file ++vardemo.php++ in this distribution
348 ==== Xmlrpc-client creation
350 The constructor accepts one of two possible syntaxes:
353 xmlrpc_clientstring$server_urlxmlrpc_clientnew
354 xmlrpc_clientstring$server_pathstring$server_hostnameint$server_port80string$transport'http'Here are a couple of usage examples of the first form:
360 $client = new xmlrpc_client("http://phpxmlrpc.sourceforge.net/server.php");
361 $another_client = new xmlrpc_client("https://james:bond@secret.service.com:443/xmlrpcserver?agent=007");
365 The second syntax does not allow to express a username and
366 password to be used for basic HTTP authorization as in the second
367 example above, but instead it allows to choose whether xmlrpc calls
368 will be made using the HTTP 1.0 or 1.1 protocol.
370 Here's another example client set up to query Userland's XML-RPC
371 server at __betty.userland.com__:
376 $client = new xmlrpc_client("/RPC2", "betty.userland.com", 80);
380 The server_port parameter is optional,
381 and if omitted will default to 80 when using HTTP and 443 when using
382 HTTPS (see the <<xmlrpc-client-send>> method
385 The transport parameter is optional, and
386 if omitted will default to 'http'. Allowed values are either
388 'http11'. Its value can be overridden with every call
389 to the send method. See the
390 send method below for more details about the
391 meaning of the different values.
398 The implementation of this class has been kept as simple to use as
399 possible. The constructor for the server basically does all the work.
400 Here's a minimal example:
406 function foo ($xmlrpcmsg) {
408 return new xmlrpcresp($some_xmlrpc_val);
412 function foobar($xmlrpcmsg) {
414 return new xmlrpcresp($some_xmlrpc_val);
418 $s = new xmlrpc_server(
420 "examples.myFunc1" => array("function" => "foo"),
421 "examples.myFunc2" => array("function" => "bar::foobar"),
426 This performs everything you need to do with a server. The single
427 constructor argument is an associative array from xmlrpc method names to
428 php function names. The incoming request is parsed and dispatched to the
429 relevant php function, which is responsible for returning a
430 xmlrpcresp object, that will be serialized back
434 ==== Method handler functions
436 Both php functions and class methods can be registered as xmlrpc
439 The synopsis of a method handler function is:
441 xmlrpcresp $resp = function (xmlrpcmsg $msg)
443 No text should be echoed 'to screen' by the handler function, or
444 it will break the xml response sent back to the client. This applies
445 also to error and warning messages that PHP prints to screen unless
446 the appropriate parameters have been set in the php.in file. Another
447 way to prevent echoing of errors inside the response and facilitate
448 debugging is to use the server SetDebug method with debug level 3 (see
449 ...). Exceptions thrown duting execution of handler functions are
450 caught by default and a XML-RPC error reponse is generated instead.
451 This behaviour can be finetuned by usage of the
452 exception_handling member variable (see
455 Note that if you implement a method with a name prefixed by
456 ++system.++ the handler function will be invoked by the
457 server with two parameters, the first being the server itself and the
458 second being the xmlrpcmsg object.
460 The same php function can be registered as handler of multiple
463 Here is a more detailed example of what the handler function
470 function foo ($xmlrpcmsg) {
471 global $xmlrpcerruser; // import user errcode base value
473 $meth = $xmlrpcmsg->method(); // retrieve method name
474 $par = $xmlrpcmsg->getParam(0); // retrieve value of first parameter - assumes at least one param received
475 $val = $par->scalarval(); // decode value of first parameter - assumes it is a scalar value
480 // this is an error condition
481 return new xmlrpcresp(0, $xmlrpcerruser+1, // user error 1
482 "There's a problem, Captain");
484 // this is a successful value being returned
485 return new xmlrpcresp(new xmlrpcval("All's fine!", "string"));
491 See __server.php__ in this distribution for
492 more examples of how to do this.
494 Since release 2.0RC3 there is a new, even simpler way of
495 registering php functions with the server. See section 5.7
499 ==== The dispatch map
501 The first argument to the xmlrpc_server
502 constructor is an array, called the __dispatch map__.
503 In this array is the information the server needs to service the
504 XML-RPC methods you define.
506 The dispatch map takes the form of an associative array of
507 associative arrays: the outer array has one entry for each method, the
508 key being the method name. The corresponding value is another
509 associative array, which can have the following members:
512 * ++function++ - this
513 entry is mandatory. It must be either a name of a function in the
514 global scope which services the XML-RPC method, or an array
515 containing an instance of an object and a static method name (for
516 static class methods the 'class::method' syntax is also
520 * ++signature++ - this
521 entry is an array containing the possible signatures (see <<signatures>>) for the method. If this entry is present
522 then the server will check that the correct number and type of
523 parameters have been sent for this method before dispatching
527 * ++docstring++ - this
528 entry is a string containing documentation for the method. The
529 documentation may contain HTML markup.
532 * ++$$signature_docs$$++ - this entry can be used
533 to provide documentation for the single parameters. It must match
534 in structure the 'signature' member. By default, only the
535 documenting_xmlrpc_server class in the
536 extras package will take advantage of this, since the
537 "system.methodHelp" protocol does not support documenting method
538 parameters individually.
541 * ++$$parameters_type$$++ - this entry can be used
542 when the server is working in 'xmlrpcvals' mode (see ...) to
543 define one or more entries in the dispatch map as being functions
544 that follow the 'phpvals' calling convention. The only useful
545 value is currently the string ++phpvals++.
547 Look at the __server.php__ example in the
548 distribution to see what a dispatch map looks like.
552 ==== Method signatures
554 A signature is a description of a method's return type and its
555 parameter types. A method may have more than one signature.
557 Within a server's dispatch map, each method has an array of
558 possible signatures. Each signature is an array of types. The first
559 entry is the return type. For instance, the method
562 string examples.getStateName(int)
569 array($xmlrpcString, $xmlrpcInt)
573 and, assuming that it is the only possible signature for the
574 method, it might be used like this in server creation:
578 $findstate_sig = array(array($xmlrpcString, $xmlrpcInt));
580 $findstate_doc = 'When passed an integer between 1 and 51 returns the
581 name of a US state, where the integer is the index of that state name
582 in an alphabetic order.';
584 $s = new xmlrpc_server( array(
585 "examples.getStateName" => array(
586 "function" => "findstate",
587 "signature" => $findstate_sig,
588 "docstring" => $findstate_doc
595 Note that method signatures do not allow to check nested
596 parameters, e.g. the number, names and types of the members of a
597 struct param cannot be validated.
599 If a method that you want to expose has a definite number of
600 parameters, but each of those parameters could reasonably be of
601 multiple types, the array of acceptable signatures will easily grow
602 into a combinatorial explosion. To avoid such a situation, the lib
603 defines the global var $xmlrpcValue, which can be
604 used in method signatures as a placeholder for 'any xmlrpc
611 $echoback_sig = array(array($xmlrpcValue, $xmlrpcValue));
613 $findstate_doc = 'Echoes back to the client the received value, regardless of its type';
615 $s = new xmlrpc_server( array(
617 "function" => "echoback",
618 "signature" => $echoback_sig, // this sig guarantees that the method handler will be called with one and only one parameter
619 "docstring" => $echoback_doc
624 Methods system.listMethods,
626 system.methodSignature and
627 system.multicall are already defined by the
628 server, and should not be reimplemented (see Reserved Methods
632 ==== Delaying the server response
634 You may want to construct the server, but for some reason not
635 fulfill the request immediately (security verification, for instance).
636 If you omit to pass to the constructor the dispatch map or pass it a
637 second argument of ++0++ this will have the desired
638 effect. You can then use the service() method of
639 the server class to service the request. For example:
645 $s = new xmlrpc_server($myDispMap, 0); // second parameter = 0 prevents automatic servicing of request
647 // ... some code that does other stuff here
653 Note that the service method will print
654 the complete result payload to screen and send appropriate HTTP
655 headers back to the client, but also return the response object. This
656 permits further manipulation of the response, possibly in combination
657 with output buffering.
659 To prevent the server from sending HTTP headers back to the
660 client, you can pass a second parameter with a value of
661 ++TRUE++ to the service
662 method. In this case, the response payload will be returned instead of
665 Xmlrpc requests retrieved by other means than HTTP POST bodies
666 can also be processed. For example:
672 $s = new xmlrpc_server(); // not passing a dispatch map prevents automatic servicing of request
674 // ... some code that does other stuff here, including setting dispatch map into server object
676 $resp = $s->service($xmlrpc_request_body, true); // parse a variable instead of POST body, retrieve response payload
678 // ... some code that does other stuff with xml response $resp here
683 ==== Modifying the server behaviour
685 A couple of methods / class variables are available to modify
686 the behaviour of the server. The only way to take advantage of their
687 existence is by usage of a delayed server response (see above)
692 This function controls weather the server is going to echo
693 debugging messages back to the client as comments in response body.
694 Valid values: 0,1,2,3, with 1 being the default. At level 0, no
695 debug info is returned to the client. At level 2, the complete
696 client request is added to the response, as part of the xml
697 comments. At level 3, a new PHP error handler is set when executing
698 user functions exposed as server methods, and all non-fatal errors
699 are trapped and added as comments into the response.
702 ===== allow_system_funcs
704 Default_value: TRUE. When set to FALSE, disables support for
705 System.xxx functions in the server. It
706 might be useful e.g. if you do not wish the server to respond to
707 requests to System.ListMethods.
710 ===== compress_response
712 When set to TRUE, enables the server to take advantage of HTTP
713 compression, otherwise disables it. Responses will be transparently
714 compressed, but only when an xmlrpc-client declares its support for
715 compression in the HTTP headers of the request.
717 Note that the ZLIB php extension must be installed for this to
718 work. If it is, compress_response will default to
722 ===== exception_handling
724 This variable controls the behaviour of the server when an
725 exception is thrown by a method handler php function. Valid values:
726 0,1,2, with 0 being the default. At level 0, the server catches the
727 exception and return an 'internal error' xmlrpc response; at 1 it
728 catches the exceptions and return an xmlrpc response with the error
729 code and error message corresponding to the exception that was
730 thron; at 2 = the exception is floated to the upper layers in the
734 ===== response_charset_encoding
736 Charset encoding to be used for response (only affects string
739 If it can, the server will convert the generated response from
740 internal_encoding to the intended one.
742 Valid values are: a supported xml encoding (only UTF-8 and
743 ISO-8859-1 at present, unless mbstring is enabled), null (leave
744 charset unspecified in response and convert output stream to
745 US_ASCII), 'default' (use xmlrpc library default as specified in
746 xmlrpc.inc, convert output stream if needed), or 'auto' (use
747 client-specified charset encoding or same as request if request
748 headers do not specify it (unless request is US-ASCII: then use
749 library default anyway).
754 Fault codes for your servers should start at the value indicated
755 by the global ++$xmlrpcerruser++ + 1.
757 Standard errors returned by the server include:
759 ++1++ Unknown method:: Returned if the server was asked to dispatch a method it
762 ++2++ Invalid return payload:: This error is actually generated by the client, not
763 server, code, but signifies that a server returned something it
764 couldn't understand. A more detailed error report is sometimes
765 added onto the end of the phrase above.
767 ++3++ Incorrect parameters:: This error is generated when the server has signature(s)
768 defined for a method, and the parameters passed by the client do
769 not match any of signatures.
771 ++4++ Can't introspect: method unknown:: This error is generated by the builtin
772 system.* methods when any kind of
773 introspection is attempted on a method undefined by the
776 ++5++ Didn't receive 200 OK from remote server:: This error is generated by the client when a remote server
777 doesn't return HTTP/1.1 200 OK in response to a request. A more
778 detailed error report is added onto the end of the phrase
781 ++6++ No data received from server:: This error is generated by the client when a remote server
782 returns HTTP/1.1 200 OK in response to a request, but no
783 response body follows the HTTP headers.
785 ++7++ No SSL support compiled in:: This error is generated by the client when trying to send
786 a request with HTTPS and the CURL extension is not available to
789 ++8++ CURL error:: This error is generated by the client when trying to send
790 a request with HTTPS and the HTTPS communication fails.
792 ++9-14++ multicall errors:: These errors are generated by the server when something
793 fails inside a system.multicall request.
795 ++100-++ XML parse errors:: Returns 100 plus the XML parser error code for the fault
796 that occurred. The faultString returned
797 explains where the parse error was in the incoming XML
801 ==== 'New style' servers
803 In the same spirit of simplification that inspired the
804 xmlrpc_client::return_type class variable, a new
805 class variable has been added to the server class:
806 functions_parameters_type. When set to 'phpvals',
807 the functions registered in the server dispatch map will be called
808 with plain php values as parameters, instead of a single xmlrpcmsg
809 instance parameter. The return value of those functions is expected to
810 be a plain php value, too. An example is worth a thousand
815 function foo($usr_id, $out_lang='en') {
816 global $xmlrpcerruser;
820 if ($someErrorCondition)
821 return new xmlrpcresp(0, $xmlrpcerruser+1, 'DOH!');
826 'picture' => new xmlrpcval(file_get_contents($picOfTheGuy), 'base64')
830 $s = new xmlrpc_server(
832 "examples.myFunc" => array(
833 "function" => "bar::foobar",
834 "signature" => array(
835 array($xmlrpcString, $xmlrpcInt),
836 array($xmlrpcString, $xmlrpcInt, $xmlrpcString)
840 $s->functions_parameters_type = 'phpvals';
845 There are a few things to keep in mind when using this
848 to return an xmlrpc error, the method handler function must
849 return an instance of xmlrpcresp. The only
850 other way for the server to know when an error response should be
851 served to the client is to throw an exception and set the server's
852 exception_handling memeber var to 1;
854 to return a base64 value, the method handler function must
855 encode it on its own, creating an instance of an xmlrpcval
858 the method handler function cannot determine the name of the
859 xmlrpc method it is serving, unlike standard handler functions that
860 can retrieve it from the message object;
862 when receiving nested parameters, the method handler function
863 has no way to distinguish a php string that was sent as base64 value
864 from one that was sent as a string value;
866 this has a direct consequence on the support of
867 system.multicall: a method whose signature contains datetime or base64
868 values will not be available to multicall calls;
870 last but not least, the direct parsing of xml to php values is
871 much faster than using xmlrpcvals, and allows the library to handle
872 much bigger messages without allocating all available server memory or
873 smashing PHP recursive call stack.
880 Many global variables are defined in the xmlrpc.inc file. Some of
881 those are meant to be used as constants (and modifying their value might
882 cause unpredictable behaviour), while some others can be modified in your
883 php scripts to alter the behaviour of the xml-rpc client and
887 === "Constant" variables
892 $xmlrpcerruser800The minimum value for errors reported by user
893 implemented XML-RPC servers. Error numbers lower than that are
894 reserved for library usage.
897 ==== $xmlrpcI4, $xmlrpcI8 $xmlrpcInt, $xmlrpcBoolean, $xmlrpcDouble, $xmlrpcString, $xmlrpcDateTime, $xmlrpcBase64, $xmlrpcArray, $xmlrpcStruct, $xmlrpcValue, $xmlrpcNull
899 For convenience the strings representing the XML-RPC types have
900 been encoded as global variables:
907 $xmlrpcBoolean="boolean";
908 $xmlrpcDouble="double";
909 $xmlrpcString="string";
910 $xmlrpcDateTime="dateTime.iso8601";
911 $xmlrpcBase64="base64";
912 $xmlrpcArray="array";
913 $xmlrpcStruct="struct";
914 $xmlrpcValue="undefined";
919 ==== $xmlrpcTypes, $xmlrpc_valid_parents, $xmlrpcerr, $xmlrpcstr, $xmlrpcerrxml, $xmlrpc_backslash, $_xh, $xml_iso88591_Entities, $xmlEntities, $xmlrpcs_capabilities
921 Reserved for internal usage.
924 === Variables whose value can be modified
926 [[xmlrpc-defencoding]]
928 ==== xmlrpc_defencoding
930 $xmlrpc_defencoding"UTF8"This variable defines the character set encoding that will be
931 used by the xml-rpc client and server to decode the received messages,
932 when a specific charset declaration is not found (in the messages sent
933 non-ascii chars are always encoded using character references, so that
934 the produced xml is valid regardless of the charset encoding
937 Allowed values: ++"UTF8"++,
938 ++"ISO-8859-1"++, ++"ASCII".++
940 Note that the appropriate RFC actually mandates that XML
941 received over HTTP without indication of charset encoding be treated
942 as US-ASCII, but many servers and clients 'in the wild' violate the
943 standard, and assume the default encoding is UTF-8.
946 ==== xmlrpc_internalencoding
948 $xmlrpc_internalencoding"ISO-8859-1"This variable defines the character set encoding
949 that the library uses to transparently encode into valid XML the
950 xml-rpc values created by the user and to re-encode the received
951 xml-rpc values when it passes them to the PHP application. It only
952 affects xml-rpc values of string type. It is a separate value from
953 xmlrpc_defencoding, allowing e.g. to send/receive xml messages encoded
954 on-the-wire in US-ASCII and process them as UTF-8. It defaults to the
955 character set used internally by PHP (unless you are running an
956 MBString-enabled installation), so you should change it only in
957 special situations, if e.g. the string values exchanged in the xml-rpc
958 messages are directly inserted into / fetched from a database
959 configured to return UTF8 encoded strings to PHP. Example
967 include('xmlrpc.inc');
968 $xmlrpc_internalencoding = 'UTF-8'; // this has to be set after the inclusion above
969 $v = new xmlrpcval('κόÏ
\83με'); // This xmlrpc value will be correctly serialized as the greek word 'kosme'
975 $xmlrpcName"XML-RPC for PHP"The string representation of the name of the XML-RPC
976 for PHP library. It is used by the client for building the User-Agent
977 HTTP header that is sent with every request to the server. You can
978 change its value if you need to customize the User-Agent
984 $xmlrpcVersion"2.2"The string representation of the version number of
985 the XML-RPC for PHP library in use. It is used by the client for
986 building the User-Agent HTTP header that is sent with every request to
987 the server. You can change its value if you need to customize the
991 ==== xmlrpc_null_extension
993 When set to TRUE, the lib will enable
994 support for the <NIL/> (and <EX:NIL/>) xmlrpc value, as
995 per the extension to the standard proposed here. This means that
996 <NIL> and <EX:NIL/> tags received will be parsed as valid
997 xmlrpc, and the corresponding xmlrpcvals will return "null" for
1001 ==== xmlrpc_null_apache_encoding
1003 When set to ++TRUE++, php NULL values encoded
1004 into xmlrpcval objects get serialized using the
1005 ++<EX:NIL/>++ tag instead of
1006 ++<NIL/>++. Please note that both forms are
1007 always accepted as input regardless of the value of this
1015 XML-RPC for PHP contains some helper functions which you can use to
1016 make processing of XML-RPC requests easier.
1021 The XML-RPC specification has this to say on dates:
1025 [[wrap_xmlrpc_method]]
1026 Don't assume a timezone. It should be
1027 specified by the server in its documentation what assumptions it makes
1032 Unfortunately, this means that date processing isn't
1033 straightforward. Although XML-RPC uses ISO 8601 format dates, it doesn't
1034 use the timezone specifier.
1036 We strongly recommend that in every case where you pass dates in
1037 XML-RPC calls, you use UTC (GMT) as your timezone. Most computer
1038 languages include routines for handling GMT times natively, and you
1039 won't have to translate between timezones.
1041 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
1042 8601 specification. Note that XML-RPC uses exactly one of the available
1043 representations: CCYYMMDDTHH:MM:SS.
1049 stringiso8601_encodestring$time_tint$utc0Returns an ISO 8601 formatted date generated from the UNIX
1050 timestamp $time_t, as returned by the PHP
1053 The argument $utc can be omitted, in
1054 which case it defaults to ++0++. If it is set to
1055 ++1++, then the function corrects the time passed in
1056 for UTC. Example: if you're in the GMT-6:00 timezone and set
1057 $utc, you will receive a date representation
1058 six hours ahead of your local time.
1060 The included demo program __vardemo.php__
1061 includes a demonstration of this function.
1067 intiso8601_decodestring$isoStringint$utc0Returns a UNIX timestamp from an ISO 8601 encoded time and date
1068 string passed in. If $utc is
1069 ++1++ then $isoString is assumed
1070 to be in the UTC timezone, and thus the result is also UTC: otherwise,
1071 the timezone is assumed to be your local timezone and you receive a
1076 === Easy use with nested PHP values
1078 Dan Libby was kind enough to contribute two helper functions that
1079 make it easier to translate to and from PHP values. This makes it easier
1080 to deal with complex structures. At the moment support is limited to
1081 int, double, string,
1082 array, datetime and struct
1083 datatypes; note also that all PHP arrays are encoded as structs, except
1084 arrays whose keys are integer numbers starting with 0 and incremented by
1087 These functions reside in __xmlrpc.inc__.
1091 ==== php_xmlrpc_decode
1093 mixedphp_xmlrpc_decodexmlrpcval$xmlrpc_valarray$optionsarrayphp_xmlrpc_decodexmlrpcmsg$xmlrpcmsg_valstring$optionsReturns a native PHP value corresponding to the values found in
1094 the xmlrpcval $xmlrpc_val,
1095 translated into PHP types. Base-64 and datetime values are
1096 automatically decoded to strings.
1098 In the second form, returns an array containing the parameters
1100 xmlrpcmsg_val, decoded
1103 The options parameter is optional. If
1104 specified, it must consist of an array of options to be enabled in the
1105 decoding process. At the moment the only valid option are
1107 ++$$dates_as_objects$$++. When the first is set, php
1108 objects that have been converted to xml-rpc structs using the
1109 php_xmlrpc_encode function and a corresponding
1110 encoding option will be converted back into object values instead of
1111 arrays (provided that the class definition is available at
1112 reconstruction time). When the second is set, XML-RPC datetime values
1113 will be converted into native dateTime objects
1116 ____WARNING__:__ please take
1117 extreme care before enabling the decode_php_objs
1118 option: when php objects are rebuilt from the received xml, their
1119 constructor function will be silently invoked. This means that you are
1120 allowing the remote end to trigger execution of uncontrolled PHP code
1121 on your server, opening the door to code injection exploits. Only
1122 enable this option when you have complete trust of the remote
1129 // wrapper to expose an existing php function as xmlrpc method handler
1130 function foo_wrapper($m)
1132 $params = php_xmlrpc_decode($m);
1133 $retval = call_user_func_array('foo', $params);
1134 return new xmlrpcresp(new xmlrpcval($retval)); // foo return value will be serialized as string
1137 $s = new xmlrpc_server(array(
1138 "examples.myFunc1" => array(
1139 "function" => "foo_wrapper",
1147 ==== php_xmlrpc_encode
1149 xmlrpcvalphp_xmlrpc_encodemixed$phpvalarray$optionsReturns an xmlrpcval object populated with the PHP
1150 values in $phpval. Works recursively on arrays
1151 and objects, encoding numerically indexed php arrays into array-type
1152 xmlrpcval objects and non numerically indexed php arrays into
1153 struct-type xmlrpcval objects. Php objects are encoded into
1154 struct-type xmlrpcvals, excepted for php values that are already
1155 instances of the xmlrpcval class or descendants thereof, which will
1156 not be further encoded. Note that there's no support for encoding php
1157 values into base-64 values. Encoding of date-times is optionally
1158 carried on on php strings with the correct format.
1160 The options parameter is optional. If
1161 specified, it must consist of an array of options to be enabled in the
1162 encoding process. At the moment the only valid options are
1163 encode_php_objs, ++$$null_extension$$++
1166 The first will enable the creation of 'particular' xmlrpcval
1167 objects out of php objects, that add a "php_class" xml attribute to
1168 their serialized representation. This attribute allows the function
1169 php_xmlrpc_decode to rebuild the native php objects (provided that the
1170 same class definition exists on both sides of the communication). The
1171 second allows to encode php ++NULL++ values to the
1173 ++<EX:NIL>++, see ...) tag. The last encodes any
1174 string that matches the ISO8601 format into an XML-RPC
1181 // the easy way to build a complex xml-rpc struct, showing nested base64 value and datetime values
1182 $val = php_xmlrpc_encode(array(
1183 'first struct_element: an int' => 666,
1184 'second: an array' => array ('apple', 'orange', 'banana'),
1185 'third: a base64 element' => new xmlrpcval('hello world', 'base64'),
1186 'fourth: a datetime' => '20060107T01:53:00'
1187 ), array('auto_dates'));
1191 ==== php_xmlrpc_decode_xml
1193 xmlrpcval | xmlrpcresp |
1194 xmlrpcmsgphp_xmlrpc_decode_xmlstring$xmlarray$optionsDecodes the xml representation of either an xmlrpc request,
1195 response or single value, returning the corresponding php-xmlrpc
1196 object, or ++FALSE++ in case of an error.
1198 The options parameter is optional. If
1199 specified, it must consist of an array of options to be enabled in the
1200 decoding process. At the moment, no option is supported.
1206 $text = '<value><array><data><value>Hello world</value></data></array></value>';
1207 $val = php_xmlrpc_decode_xml($text);
1208 if ($val) echo 'Found a value of type '.$val->kindOf(); else echo 'Found invalid xml';
1212 === Automatic conversion of php functions into xmlrpc methods (and vice versa)
1214 For the extremely lazy coder, helper functions have been added
1215 that allow to convert a php function into an xmlrpc method, and a
1216 remotely exposed xmlrpc method into a local php function - or a set of
1217 methods into a php class. Note that these comes with many caveat.
1220 ==== wrap_xmlrpc_method
1222 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
1223 function that will call the remote method and return results using
1224 native php types for both params and results. The generated php
1225 function will return an xmlrpcresp object for failed xmlrpc
1228 The second syntax is deprecated, and is listed here only for
1229 backward compatibility.
1231 The server must support the
1232 system.methodSignature xmlrpc method call for
1233 this function to work.
1235 The client param must be a valid
1236 xmlrpc_client object, previously created with the address of the
1237 target xmlrpc server, and to which the preferred communication options
1240 The optional parameters can be passed as array key,value pairs
1241 in the extra_options param.
1243 The signum optional param has the purpose
1244 of indicating which method signature to use, if the given server
1245 method has multiple signatures (defaults to 0).
1248 protocol optional params are the same as in the
1249 xmlrpc_client::send() method.
1251 If set, the optional new_function_name
1252 parameter indicates which name should be used for the generated
1253 function. In case it is not set the function name will be
1256 If the ++$$return_source$$++ optional parameter is
1257 set, the function will return the php source code to build the wrapper
1258 function, instead of evaluating it (useful to save the code and use it
1259 later as stand-alone xmlrpc client).
1261 If the ++$$encode_php_objs$$++ optional parameter is
1262 set, instances of php objects later passed as parameters to the newly
1263 created function will receive a 'special' treatment that allows the
1264 server to rebuild them as php objects instead of simple arrays. Note
1265 that this entails using a "slightly augmented" version of the xmlrpc
1266 protocol (ie. using element attributes), which might not be understood
1267 by xmlrpc servers implemented using other libraries.
1269 If the ++$$decode_php_objs$$++ optional parameter is
1270 set, instances of php objects that have been appropriately encoded by
1271 the server using a coordinate option will be deserialized as php
1272 objects instead of simple arrays (the same class definition should be
1273 present server side and client side).
1275 __Note that this might pose a security risk__,
1276 since in order to rebuild the object instances their constructor
1277 method has to be invoked, and this means that the remote server can
1278 trigger execution of unforeseen php code on the client: not really a
1279 code injection, but almost. Please enable this option only when you
1280 trust the remote server.
1282 In case of an error during generation of the wrapper function,
1283 FALSE is returned, otherwise the name (or source code) of the new
1286 Known limitations: server must support
1287 system.methodsignature for the wanted xmlrpc
1288 method; for methods that expose multiple signatures, only one can be
1289 picked; for remote calls with nested xmlrpc params, the caller of the
1290 generated php function has to encode on its own the params passed to
1291 the php function if these are structs or arrays whose (sub)members
1292 include values of type base64.
1294 Note: calling the generated php function 'might' be slow: a new
1295 xmlrpc client is created on every invocation and an xmlrpc-connection
1296 opened+closed. An extra 'debug' param is appended to the parameter
1297 list of the generated php function, useful for debugging
1306 $c = new xmlrpc_client('http://phpxmlrpc.sourceforge.net/server.php');
1308 $function = wrap_xmlrpc_method($client, 'examples.getStateName');
1311 die('Cannot introspect remote method');
1314 $statename = $function($a);
1315 if (is_a($statename, 'xmlrpcresp')) // call failed
1317 echo 'Call failed: '.$statename->faultCode().'. Calling again with debug on';
1318 $function($a, true);
1321 echo "OK, state nr. $stateno is $statename";
1326 [[wrap_php_function]]
1328 ==== wrap_php_function
1330 arraywrap_php_functionstring$funcnamestring$wrapper_function_namearray$extra_optionsGiven a user-defined PHP function, create a PHP 'wrapper'
1331 function that can be exposed as xmlrpc method from an xmlrpc_server
1332 object and called from remote clients, and return the appropriate
1333 definition to be added to a server's dispatch map.
1335 The optional $wrapper_function_name
1336 specifies the name that will be used for the auto-generated
1339 Since php is a typeless language, to infer types of input and
1340 output parameters, it relies on parsing the javadoc-style comment
1341 block associated with the given function. Usage of xmlrpc native types
1342 (such as datetime.dateTime.iso8601 and base64) in the docblock @param
1343 tag is also allowed, if you need the php function to receive/send data
1344 in that particular format (note that base64 encoding/decoding is
1345 transparently carried out by the lib, while datetime vals are passed
1348 Known limitations: only works for
1349 user-defined functions, not for PHP internal functions (reflection
1350 does not support retrieving number/type of params for those); the
1351 wrapped php function will not be able to programmatically return an
1352 xmlrpc error response.
1354 If the ++$$return_source$$++ optional parameter is
1355 set, the function will return the php source code to build the wrapper
1356 function, instead of evaluating it (useful to save the code and use it
1357 later in a stand-alone xmlrpc server). It will be in the stored in the
1358 ++source++ member of the returned array.
1360 If the ++$$suppress_warnings$$++ optional parameter
1361 is set, any runtime warning generated while processing the
1362 user-defined php function will be catched and not be printed in the
1363 generated xml response.
1365 If the extra_options array contains the
1366 ++$$encode_php_objs$$++ value, wrapped functions returning
1367 php objects will generate "special" xmlrpc responses: when the xmlrpc
1368 decoding of those responses is carried out by this same lib, using the
1369 appropriate param in php_xmlrpc_decode(), the objects will be
1372 In short: php objects can be serialized, too (except for their
1373 resource members), using this function. Other libs might choke on the
1374 very same xml that will be generated in this case (i.e. it has a
1375 nonstandard attribute on struct element tags)
1377 If the ++$$decode_php_objs$$++ optional parameter is
1378 set, instances of php objects that have been appropriately encoded by
1379 the client using a coordinate option will be deserialized and passed
1380 to the user function as php objects instead of simple arrays (the same
1381 class definition should be present server side and client
1384 __Note that this might pose a security risk__,
1385 since in order to rebuild the object instances their constructor
1386 method has to be invoked, and this means that the remote client can
1387 trigger execution of unforeseen php code on the server: not really a
1388 code injection, but almost. Please enable this option only when you
1389 trust the remote clients.
1397 * State name from state number decoder. NB: do NOT remove this comment block.
1398 * @param integer $stateno the state number
1399 * @return string the name of the state (or error description)
1401 function findstate($stateno)
1404 if (isset($stateNames[$stateno-1]))
1406 return $stateNames[$stateno-1];
1410 return "I don't have a state for the index '" . $stateno . "'";
1414 // wrap php function, build xmlrpc server
1416 $findstate_sig = wrap_php_function('findstate');
1418 $methods['examples.getStateName'] = $findstate_sig;
1419 $srv = new xmlrpc_server($methods);
1425 === Functions removed from the library
1427 The following two functions have been deprecated in version 1.1 of
1428 the library, and removed in version 2, in order to avoid conflicts with
1429 the EPI xml-rpc library, which also defines two functions with the same
1432 To ease the transition to the new naming scheme and avoid breaking
1433 existing implementations, the following scheme has been adopted:
1435 * If EPI-XMLRPC is not active in the current PHP installation,
1436 the constant `XMLRPC_EPI_ENABLED` will be set to
1440 * If EPI-XMLRPC is active in the current PHP installation, the
1441 constant `XMLRPC_EPI_ENABLED` will be set to
1446 The following documentation is kept for historical
1453 mixedx mlrpc_decode xmlrpcval $xmlrpc_val Alias for php_xmlrpc_decode.
1459 xmlrpcval xmlrpc_encode mixed $phpvalAlias for php_xmlrpc_encode.
1465 ==== xmlrpc_debugmsg
1467 void xmlrpc_debugmsgstring$debugstringSends the contents of $debugstring in XML
1468 comments in the server return payload. If a PHP client has debugging
1469 turned on, the user will be able to see server debug
1472 Use this function in your methods so you can pass back
1473 diagnostic information. It is only available from
1481 In order to extend the functionality offered by XML-RPC servers
1482 without impacting on the protocol, reserved methods are supported in this
1485 All methods starting with system. are
1486 considered reserved by the server. PHP for XML-RPC itself provides four
1487 special methods, detailed in this chapter.
1489 Note that all server objects will automatically respond to clients
1490 querying these methods, unless the property
1491 allow_system_funcs has been set to
1492 false before calling the
1493 service() method. This might pose a security risk
1494 if the server is exposed to public access, e.g. on the internet.
1497 === system.getCapabilities
1500 === system.listMethods
1502 This method may be used to enumerate the methods implemented by
1505 The system.listMethods method requires no
1506 parameters. It returns an array of strings, each of which is the name of
1507 a method implemented by the server.
1511 === system.methodSignature
1513 This method takes one parameter, the name of a method implemented
1514 by the XML-RPC server.
1516 It returns an array of possible signatures for this method. A
1517 signature is an array of types. The first of these types is the return
1518 type of the method, the rest are parameters.
1520 Multiple signatures (i.e. overloading) are permitted: this is the
1521 reason that an array of signatures are returned by this method.
1523 Signatures themselves are restricted to the top level parameters
1524 expected by a method. For instance if a method expects one array of
1525 structs as a parameter, and it returns a string, its signature is simply
1526 "string, array". If it expects three integers, its signature is "string,
1529 For parameters that can be of more than one type, the "undefined"
1530 string is supported.
1532 If no signature is defined for the method, a not-array value is
1533 returned. Therefore this is the way to test for a non-signature, if
1534 $resp below is the response object from a method
1535 call to system.methodSignature:
1540 $v = $resp->value();
1541 if ($v->kindOf() != "array") {
1542 // then the method did not have a signature defined
1547 See the __introspect.php__ demo included in this
1548 distribution for an example of using this method.
1552 === system.methodHelp
1554 This method takes one parameter, the name of a method implemented
1555 by the XML-RPC server.
1557 It returns a documentation string describing the use of that
1558 method. If no such string is available, an empty string is
1561 The documentation string may contain HTML markup.
1563 === system.multicall
1565 This method takes one parameter, an array of 'request' struct
1566 types. Each request struct must contain a
1567 methodName member of type string and a
1568 params member of type array, and corresponds to
1569 the invocation of the corresponding method.
1571 It returns a response of type array, with each value of the array
1572 being either an error struct (containing the faultCode and faultString
1573 members) or the successful response value of the corresponding single
1581 The best examples are to be found in the sample files included with
1582 the distribution. Some are included here.
1586 === XML-RPC client: state name query
1588 Code to get the corresponding state name from a number (1-50) from
1589 the demo server available on SourceForge
1594 $m = new xmlrpcmsg('examples.getStateName',
1595 array(new xmlrpcval($HTTP_POST_VARS["stateno"], "int")));
1596 $c = new xmlrpc_client("/server.php", "phpxmlrpc.sourceforge.net", 80);
1598 if (!$r->faultCode()) {
1600 print "State number " . htmlentities($HTTP_POST_VARS["stateno"]) . " is " .
1601 htmlentities($v->scalarval()) . "<BR>";
1602 print "<HR>I got this value back<BR><PRE>" .
1603 htmlentities($r->serialize()) . "</PRE><HR>\n";
1606 print "Code: " . htmlentities($r->faultCode()) . "<BR>" .
1607 "Reason: '" . htmlentities($r->faultString()) . "'<BR>";
1612 === Executing a multicall call
1620 == Frequently Asked Questions
1622 ==== How to send custom XML as payload of a method call::
1624 Unfortunately, at the time the XML-RPC spec was designed, support
1625 for namespaces in XML was not as ubiquitous as it is now. As a
1626 consequence, no support was provided in the protocol for embedding XML
1627 elements from other namespaces into an xmlrpc request.
1629 To send an XML "chunk" as payload of a method call or response,
1630 two options are available: either send the complete XML block as a
1631 string xmlrpc value, or as a base64 value. Since the '<' character in
1632 string values is encoded as '<' in the xml payload of the method
1633 call, the XML string will not break the surrounding xmlrpc, unless
1634 characters outside of the assumed character set are used. The second
1635 method has the added benefits of working independently of the charset
1636 encoding used for the xml to be transmitted, and preserving exactly
1637 whitespace, whilst incurring in some extra message length and cpu load
1638 (for carrying out the base64 encoding/decoding).
1641 ==== Is there any limitation on the size of the requests / responses that can be successfully sent?::
1643 Yes. But I have no hard figure to give; it most likely will depend
1644 on the version of PHP in usage and its configuration.
1646 Keep in mind that this library is not optimized for speed nor for
1647 memory usage. Better alternatives exist when there are strict
1648 requirements on throughput or resource usage, such as the php native
1649 xmlrpc extension (see the PHP manual for more information).
1651 Keep in mind also that HTTP is probably not the best choice in
1652 such a situation, and XML is a deadly enemy. CSV formatted data over
1653 socket would be much more efficient.
1655 If you really need to move a massive amount of data around, and
1656 you are crazy enough to do it using phpxmlrpc, your best bet is to
1657 bypass usage of the xmlrpcval objects, at least in the decoding phase,
1658 and have the server (or client) object return to the calling function
1659 directly php values (see xmlrpc_client::return_type
1660 and xmlrpc_server::functions_parameters_type for more
1664 ==== My server (client) returns an error whenever the client (server) returns accented characters
1669 ==== How to enable long-lasting method calls
1674 ==== My client returns "XML-RPC Fault #2: Invalid return payload: enable debugging to examine incoming payload": what should I do?
1676 The response you are seeing is a default error response that the
1677 client object returns to the php application when the server did not
1678 respond to the call with a valid xmlrpc response.
1680 The most likely cause is that you are not using the correct URL
1681 when creating the client object, or you do not have appropriate access
1682 rights to the web page you are requesting, or some other common http
1685 To find out what the server is really returning to your client,
1686 you have to enable the debug mode of the client, using
1687 $client->setdebug(1);
1690 ==== How can I save to a file the xml of the xmlrpc responses received from servers?
1692 If what you need is to save the responses received from the server
1693 as xml, you have two options:
1695 1- use the serialize() method on the response object.
1701 $resp = $client->send($msg);
1702 if (!$resp->faultCode())
1703 $data_to_be_saved = $resp->serialize();
1707 Note that this will not be 100% accurate, since the xml generated
1708 by the response object can be different from the xml received,
1709 especially if there is some character set conversion involved, or such
1710 (eg. if you receive an empty string tag as <string/>, serialize()
1711 will output <string></string>), or if the server sent back
1712 as response something invalid (in which case the xml generated client
1713 side using serialize() will correspond to the error response generated
1714 internally by the lib).
1716 2 - set the client object to return the raw xml received instead
1717 of the decoded objects:
1723 $client = new xmlrpc_client($url);
1724 $client->return_type = 'xml';
1725 $resp = $client->send($msg);
1726 if (!$resp->faultCode())
1727 $data_to_be_saved = $resp->value();
1731 Note that using this method the xml response response will not be
1732 parsed at all by the library, only the http communication protocol will
1733 be checked. This means that xmlrpc responses sent by the server that
1734 would have generated an error response on the client (eg. malformed xml,
1735 responses that have faultcode set, etc...) now will not be flagged as
1736 invalid, and you might end up saving not valid xml but random
1740 ==== Can I use the ms windows character set?
1742 If the data your application is using comes from a Microsoft
1743 application, there are some chances that the character set used to
1744 encode it is CP1252 (the same might apply to data received from an
1745 external xmlrpc server/client, but it is quite rare to find xmlrpc
1746 toolkits that encode to CP1252 instead of UTF8). It is a character set
1747 which is "almost" compatible with ISO 8859-1, but for a few extra
1750 PHP-XMLRPC only supports the ISO 8859-1 and UTF8 character sets.
1751 The net result of this situation is that those extra characters will not
1752 be properly encoded, and will be received at the other end of the
1753 XML-RPC transmission as "garbled data". Unfortunately the library cannot
1754 provide real support for CP1252 because of limitations in the PHP 4 xml
1755 parser. Luckily, we tried our best to support this character set anyway,
1756 and, since version 2.2.1, there is some form of support, left commented
1759 To properly encode outgoing data that is natively in CP1252, you
1760 will have to uncomment all relative code in the file
1761 __xmlrpc.inc__ (you can search for the string "1252"),
1762 then set ++$$$GLOBALS['xmlrpc_internalencoding']='CP1252';$$++
1763 Please note that all incoming data will then be fed to your application
1764 as UTF-8 to avoid any potential data loss.
1767 ==== Does the library support using cookies / http sessions?
1769 In short: yes, but a little coding is needed to make it
1772 The code below uses sessions to e.g. let the client store a value
1773 on the server and retrieve it later.
1778 $resp = $client->send(new xmlrpcmsg('registervalue', array(new xmlrpcval('foo'), new xmlrpcval('bar'))));
1779 if (!$resp->faultCode())
1781 $cookies = $resp->cookies();
1782 if (array_key_exists('PHPSESSID', $cookies)) // nb: make sure to use the correct session cookie name
1784 $session_id = $cookies['PHPSESSID']['value'];
1786 // do some other stuff here...
1788 $client->setcookie('PHPSESSID', $session_id);
1789 $val = $client->send(new xmlrpcmsg('getvalue', array(new xmlrpcval('foo')));
1795 Server-side sessions are handled normally like in any other
1796 php application. Please see the php manual for more information about
1799 NB: unlike web browsers, not all xmlrpc clients support usage of
1800 http cookies. If you have troubles with sessions and control only the
1801 server side of the communication, please check with the makers of the
1802 xmlrpc client in use.
1808 == Integration with the PHP xmlrpc extension
1810 To be documented more...
1812 In short: for the fastest execution possible, you can enable the php
1813 native xmlrpc extension, and use it in conjunction with phpxmlrpc. The
1814 following code snippet gives an example of such integration
1820 /*** client side ***/
1821 $c = new xmlrpc_client('http://phpxmlrpc.sourceforge.net/server.php');
1823 // tell the client to return raw xml as response value
1824 $c->return_type = 'xml';
1826 // let the native xmlrpc extension take care of encoding request parameters
1827 $r = $c->send(xmlrpc_encode_request('examples.getStateName', $_POST['stateno']));
1829 if ($r->faultCode())
1830 // HTTP transport error
1831 echo 'Got error '.$r->faultCode();
1834 // HTTP request OK, but XML returned from server not parsed yet
1835 $v = xmlrpc_decode($r->value());
1836 // check if we got a valid xmlrpc response from server
1838 echo 'Got invalid response';
1840 // check if server sent a fault response
1841 if (xmlrpc_is_fault($v))
1842 echo 'Got xmlrpc fault '.$v['faultCode'];
1844 echo'Got response: '.htmlentities($v);
1853 == Substitution of the PHP xmlrpc extension
1855 Yet another interesting situation is when you are using a ready-made
1856 php application, that provides support for the XMLRPC protocol via the
1857 native php xmlrpc extension, but the extension is not available on your
1858 php install (e.g. because of shared hosting constraints).
1860 Since version 2.1, the PHP-XMLRPC library provides a compatibility
1861 layer that aims to be 100% compliant with the xmlrpc extension API. This
1862 means that any code written to run on the extension should obtain the
1863 exact same results, albeit using more resources and a longer processing
1864 time, using the PHP-XMLRPC library and the extension compatibility module.
1865 The module is part of the EXTRAS package, available as a separate download
1866 from the sourceforge.net website, since version 0.2
1872 == 'Enough of xmlrpcvals!': new style library usage
1876 In the meantime, see docs about xmlrpc_client::return_type and
1877 xmlrpc_server::functions_parameters_types, as well as php_xmlrpc_encode,
1878 php_xmlrpc_decode and php_xmlrpc_decode_xml
1884 == Usage of the debugger
1886 A webservice debugger is included in the library to help during
1887 development and testing.
1889 The interface should be self-explicative enough to need little
1892 image::debugger.gif[,,,,align="center"]
1894 The most useful feature of the debugger is without doubt the "Show
1895 debug info" option. It allows to have a screen dump of the complete http
1896 communication between client and server, including the http headers as
1897 well as the request and response payloads, and is invaluable when
1898 troubleshooting problems with charset encoding, authentication or http
1901 The debugger can take advantage of the JSONRPC library extension, to
1902 allow debugging of JSON-RPC webservices, and of the JS-XMLRPC library
1903 visual editor to allow easy mouse-driven construction of the payload for
1904 remote methods. Both components have to be downloaded separately from the
1905 sourceforge.net web pages and copied to the debugger directory to enable
1906 the extra functionality:
1909 * to enable jsonrpc functionality, download the PHP-XMLRPC
1910 EXTRAS package, and copy the file __jsonrpc.inc__
1911 either to the same directory as the debugger or somewhere in your
1915 * to enable the visual value editing dialog, download the
1916 JS-XMLRPC library, and copy somewhere in the web root files
1917 __visualeditor.php__,
1918 __visualeditor.css__ and the folders
1919 __yui__ and __img__. Then edit the
1920 debugger file __controller.php__ and set
1921 appropriately the variable $editorpath.
1930 CAUTION: not all items the following list have (yet) been fully documented, and some might not be present in any other
1931 chapter in the manual. To find a more detailed description of new functions and methods please take a look at the
1932 source code of the library, which is quite thoroughly commented in phpdoc form.
1936 * new: introduction of namespaces and full OOP.
1938 All php classes have been renamed and moved to separate files.
1940 Class autoloading can now be done in accord with the PSR-4 standard.
1942 All global variables and global functions have been removed.
1944 Iterating over xmlrpc value objects is now easier thank to support for ArrayAccess and Traversable interfaces.
1946 Backward compatibility is maintained via _lib/xmlrpc.inc_, _lib/xmlrpcs.inc_ and _lib/xmlrpc_wrappers.inc_.
1947 For more details, head on to doc/api_changes_v4.md
1949 * changed: the default character encoding delivered from the library to your code is now utf8.
1950 It can be changed at any time setting a value to `PhpXmlRpc\PhpXmlRpc::$xmlrpc_internalencoding`
1952 * improved: the library now accepts requests/responses sent using other character sets than UTF-8/ISO-8859-1/ASCII.
1953 This only works when the mbstring php extension is enabled.
1955 * improved: no need to call anymore `$client->setSSLVerifyHost(2)` to silence a curl warning when using https
1956 with recent curl builds
1958 * improved: the xmlrpcval class now supports the interfaces `Countable` and `IteratorAggregate`
1960 * improved: a specific option allows users to decide the version of SSL to use for https calls.
1961 This is useful f.e. for the testing suite, when the server target of calls has no proper ssl certificate,
1962 and the cURL extension has been compiled with GnuTLS (such as on Travis VMs)
1964 * improved: the function `wrap_php_function()` now can be used to wrap closures (it is now a method btw)
1966 * improved: all _wrap_something()_ functions now return a closure by default instead of a function name
1968 * improved: debug messages are not html-escaped any more when executing from the command line
1970 * improved: the library is now tested using Travis ( https://travis-ci.org/ ).
1971 Tests are executed using all php versions from 5.3 to 7.0 nightly, plus HHVM; code-coverage information
1972 is generated using php 5.6 and uploaded to both Code Coverage and Scrutinizer online services
1974 * improved: phpunit is now installed via composer, not bundled anymore
1976 * improved: when phpunit is used to generate code-coverage data, the code executed server-side is accounted for
1978 * improved: the test suite has basic checks for the debugger and demo files
1980 * improved: more tests in the test suite
1982 * fixed: the server would not reset the user-set debug messages between subsequent `service()` calls
1984 * fixed: the server would not reset previous php error handlers when an exception was thrown by user code and
1985 exception_handling set to 2
1987 * fixed: the server would fail to decode a request with ISO-8859-1 payload and character set declaration in the xml
1990 * fixed: the client would fail to decode a response with ISO-8859-1 payload and character set declaration in the xml
1993 * fixed: the function `decode_xml()` would not decode an xml with character set declaration in the xml prolog
1995 * fixed: the client can now successfully call methods using ISO-8859-1 or UTF-8 characters in their name
1997 * fixed: the debugger would fail sending a request with ISO-8859-1 payload (it missed the character set declaration).
1998 It would have a hard time coping with ISO-8859-1 in other fields, such as e.g. the remote method name
2000 * fixed: the debugger would generate a bad payload via the 'load method synopsis' button for signatures containing NULL
2001 or undefined parameters
2003 * fixed: the debugger would generate a bad payload via the 'load method synopsis' button for methods with multiple
2006 * improved: the debugger is displayed using UTF-8, making it more useful to debug any kind of service
2008 * improved: echo all debug messages even when there are characters in them which php deems to be in a wrong encoding;
2009 previously those messages would just disappear (this is visible e.g. in the debugger)
2011 * changed: debug info handling
2012 - at debug level 1, the rebuilt php objects are not dumped to screen (server-side already did that)
2013 - at debug level 1, curl communication info are not dumped to screen
2014 - at debug level 1, the tests echo payloads of failures; at debug level 2 all payloads
2016 * improved: makefiles have been replaced with a php_based pakefile
2018 * improved: the source for the manual is stored in asciidoc format, which can be displayed natively by GitHub
2019 with nice html formatting. Also the HTML version generated by hand and bundled in tarballs is much nicer
2020 to look at than previous versions
2022 * improved: all php code is now formatted according to the PSR-2 standard
2026 __Note:__ this is the last release of the library that will support PHP 5.1 and up. Future releases will target php 5.3
2027 as minimum supported version.
2029 * when using curl and keepalive, reset curl handle if we did not get back an http 200 response (eg a 302)
2031 * omit port on http 'Host' header if it is 80
2033 * test suite allows interrogating https servers ignoring their certs
2035 * method `setAcceptedCompression` was failing to disable reception of compressed responses if the client supported them
2039 This is the first release of the library to only support PHP 5. Some legacy code has been removed, and support for
2040 features such as exceptions and dateTime objects introduced.
2042 The "beta" tag is meant to indicate the fact that the refactoring has been more widespread than in precedent releases
2043 and that more changes are likely to be introduced with time - the library is still considered to be production
2046 * improved: removed all usage of php functions deprecated in php 5.3, usage of assign-by-ref when creating new objects
2049 * improved: add support for the `<ex:nil>` tag used by the apache library, both in input and output
2051 * improved: add support for dateTime objects in both in php_xmlrpc_encode and as parameter for constructor of xmlrpcval
2053 * improved: add support for timestamps as parameter for constructor of xmlrpcval
2055 * improved: add option `dates_as_objects` to `php_xmlrpc_decode` to return dateTime objects for xmlrpc datetimes
2057 * improved: add new method `SetCurlOptions` to xmrlpc_client to allow extra flexibility in tweaking http config, such as
2058 explicitly binding to an ip address
2060 * improved: add new method `SetUserAgent` to xmrlpc_client to to allow having different user-agent http headers
2062 * improved: add a new member variable in server class to allow fine-tuning of the encoding of returned values when the
2063 server is in 'phpvals' mode
2065 * improved: allow servers in 'xmlrpcvals' mode to also register plain php functions by defining them in the dispatch map
2066 with an added option
2068 * improved: catch exceptions thrown during execution of php functions exposed as methods by the server
2070 * fixed: bad encoding if same object is encoded twice using `php_xmlrpc_encode`
2074 __Note:__ this is the last release of the library that will support PHP 4. Future releases (if any) should target
2075 php 5.0 as minimum supported version.
2077 * fixed: encoding of utf-8 characters outside of the BMP plane
2079 * fixed: character set declarations surrounded by double quotes were not recognized in http headers
2081 * fixed: be more tolerant in detection of charset in http headers
2083 * fixed: fix detection of zlib.output_compression
2085 * fixed: use `feof()` to test if socket connections are to be closed instead of the number of bytes read (rare bug when
2086 communicating with some servers)
2088 * fixed: format floating point values using the correct decimal separator even when php locale is set to one that uses
2091 * fixed: improve robustness of the debugger when parsing weird results from non-compliant servers
2093 * php warning when receiving `false` in a bool value
2095 * improved: allow the add_to_map server method to add docs for single params too
2097 * improved: added the possibility to wrap for exposure as xmlrpc methods plain php class methods, object methods and even
2102 * fixed: work aroung bug in php 5.2.2 which broke support of `HTTP_RAW_POST_DATA`
2104 * fixed: is_dir parameter of `setCaCertificate()` method is reversed
2106 * fixed: a php warning in xmlrpc_client creator method
2108 * fixed: parsing of `1e+1` as valid float
2110 * fixed: allow errorlevel 3 to work when prev. error handler was a static method
2112 * fixed: usage of `client::setcookie()` for multiple cookies in non-ssl mode
2114 * improved: support for CP1252 charset is not part or the library but almost possible
2116 * improved: more info when curl is enabled and debug mode is on
2120 * fixed: debugger errors on php installs with `magic_quotes_gpc` on
2122 * fixed: support for https connections via proxy
2124 * fixed: `wrap_xmlrpc_method()` generated code failed to properly encode php objects
2126 * improved: slightly faster encoding of data which is internally UTF-8
2128 * improved: debugger always generates a `null` id for jsonrpc if user omits it
2130 * new: debugger can take advantage of a graphical value builder (it has to be downloaded separately, as part of jsxmlrpc
2131 package. See Appendix D for more details)
2133 * new: support for the `<NIL/>` xmlrpc extension. see below for more details
2135 * new: server support for the `system.getCapabilities` xmlrpc extension
2137 * new: `wrap_xmlrpc_method`, `wrap_xmlrpc_method()` accepts two new options: debug and return_on_fault
2141 * The wrap_php_function and wrap_xmlrpc_method functions have been moved out of the base library file _xmlrpc.inc_
2142 into a file of their own: _xmlrpc_wrappers.php_. You will have to include() / require() it in your scripts if
2143 you have been using those functions.
2144 For increased security, the automatic rebuilding of php object instances out ofreceived xmlrpc structs in
2145 `wrap_xmlrpc_method()` has been disabled (but it can be optionally re-enabled).
2146 Both `wrap_php_function()` and `wrap_xmlrpc_method()` functions accept many more options to fine tune their behaviour,
2147 including one to return the php code to be saved and later used as standalone php script
2149 * The constructor of xmlrpcval() values has seen some internal changes, and it will not throw a php warning anymore when
2150 invoked using an unknown xmlrpc type: the error will only be written to php error log. Also
2151 `new xmlrpcval('true', 'boolean')` is not supported anymore
2153 * The new function `php_xmlrpc_decode_xml()` will take the xml representation of either an xmlrpc request, response or
2154 single value and return the corresponding php-xmlrpc object instance
2156 * A new function `wrap_xmlrpc_server()` has been added, to wrap all (or some) of the methods exposed by a remote xmlrpc
2157 server into a php class
2159 * A new file has been added: _verify_compat.php_, to help users diagnose the level of compliance of their php
2160 installation with the library
2162 * Restored compatibility with php 4.0.5 (for those poor souls still stuck on it)
2164 * Method `xmlrpc_server->service()` now returns a value: either the response payload or xmlrpcresp object instance
2166 * Method `xmlrpc_server->add_to_map()` now accepts xmlrpc methods with no param definitions
2168 * Documentation for single parameters of exposed methods can be added to the dispatch map (and turned into html docs in
2169 conjunction with a future release of the 'extras' package)
2171 * Full response payload is saved into xmlrpcresp object for further debugging
2173 * The debugger can now generate code that wraps a remote method into a php function (works for jsonrpc, too); it also
2174 has better support for being activated via a single GET call (e.g. for integration into other tools)
2176 * Stricter parsing of incoming xmlrpc messages: two more invalid cases are now detected (double `data` element inside
2177 `array` and `struct`/`array` after scalar inside `value` element)
2179 * More logging of errors in a lot of situations
2181 * Javadoc documentation of lib files (almost) complete
2183 * Many performance tweaks and code cleanups, plus the usual crop of bugs fixed (see NEWS file for complete list of bugs)
2185 * Lib internals have been modified to provide better support for grafting extra functionality on top of it. Stay tuned
2186 for future releases of the EXTRAS package (or go read Appendix B)...
2190 * Added to the client class the possibility to use Digest and NTLM authentication methods (when using the CURL library)
2191 for connecting to servers and NTLM for connecting to proxies
2193 * Added to the client class the possibility to specify alternate certificate files/directories for authenticating the
2194 peer with when using HTTPS communication
2196 * Reviewed all examples and added a new demo file, containing a proxy to forward xmlrpc requests to other servers
2197 (useful e.g. for ajax coding)
2199 * The debugger has been upgraded to reflect the new client capabilities
2201 * All known bugs have been squashed, and the lib is more tolerant than ever of commonly-found mistakes
2203 === 2.0 Release candidate 3
2205 * Added to server class the property functions_parameters_type, that allows the server to register plain php functions
2206 as xmlrpc methods (i.e. functions that do not take an xmlrpcmsg object as unique param)
2208 * let server and client objects serialize calls using a specified character set encoding for the produced xml instead of
2209 US-ASCII (ISO-8859-1 and UTF-8 supported)
2211 * let `php_xmlrpc_decode` accept xmlrpcmsg objects as valid input
2213 * 'class::method' syntax is now accepted in the server dispatch map
2215 * `xmlrpc_clent::SetDebug()` accepts integer values instead of a boolean value, with debugging level 2 adding to the
2216 information printed to screen the complete client request
2218 === 2.0 Release candidate 2
2220 * Added a new property of the client object: `xmlrpc_client->return_type`, indicating whether calls to the
2221 send() method will return xmlrpcresp objects whose value() is an xmlrpcval object, a php value (automatically
2222 decoded) or the raw xml received from the server.
2224 * Added in the extras dir. two new library files: _jsonrpc.inc_ and _jsonrpcs.inc_ containing new classes that
2225 implement support for the json-rpc protocol (alpha quality code)
2227 * Added a new client method: `setKey($key, $keypass)` to be used in HTTPS connections
2229 * Added a new file containing some benchmarks in the testsuite directory
2231 === 2.0 Release candidate 1
2233 * Support for HTTP proxies (new method: `xmlrpc_client::setProxy()`)
2235 * Support HTTP compression of both requests and responses.
2236 Clients can specify what kind of compression they accept for responses between deflate/gzip/any, and whether to
2237 compress the requests.
2238 Servers by default compress responses to clients that explicitly declare support for compression (new methods:
2239 `xmlrpc_client::setAcceptedCompression()`, `xmlrpc_client::setRequestCompression()`).
2240 Note that the ZLIB php extension needs to be enabled in PHP to support compression.
2242 * Implement HTTP 1.1 connections, but only if CURL is enabled (added an extra parameter to
2243 `xmlrpc_client::xmlrpc_client` to set the desired HTTP protocol at creation time and a new supported value for
2244 the last parameter of `xmlrpc_client::send`, which now can be safely omitted if it has been specified at
2247 With PHP versions greater than 4.3.8 keep-alives are enabled by default for HTTP 1.1 connections. This should yield
2248 faster execution times when making multiple calls in sequence to the same xml-rpc server from a single client.
2250 * Introduce support for cookies.
2251 Cookies to be sent to the server with a request can be set using `xmlrpc_client::setCookie()`, while cookies
2252 received from the server are found in ++xmlrpcresp::cookies()++. It is left to the user to check for validity of
2253 received cookies and decide whether they apply to successive calls or not.
2255 * Better support for detecting different character set encodings of xml-rpc requests and responses: both client and
2256 server objects will correctly detect the charset encoding of received xml, and use an appropriate xml parser.
2258 Supported encodings are US-ASCII, UTF-8 and ISO-8859-1.
2260 * Added one new xmlrpcmsg constructor syntax, allowing usage of a single string with the complete URL of the target
2263 * Convert xml-rpc boolean values into native php values instead of 0 and 1
2265 * Force the `php_xmlrpc_encode` function to properly encode numerically indexed php arrays into xml-rpc arrays
2266 (numerically indexed php arrays always start with a key of 0 and increment keys by values of 1)
2268 * Prevent the `php_xmlrpc_encode` function from further re-encoding any objects of class ++xmlrpcval++ that
2269 are passed to it. This allows to call the function with arguments consisting of mixed php values / xmlrpcval objects
2271 * Allow a server to NOT respond to system.* method calls (setting the `$server->allow_system_funcs` property).
2273 * Implement a new xmlrpcval method to determine if a value of type struct has a member of a given name without having to
2274 loop trough all members: `xmlrpcval::structMemExists()`
2276 * Expand methods `xmlrpcval::addArray`, `addScalar` and `addStruct` allowing extra php values to be added to
2277 xmlrpcval objects already formed.
2279 * Let the `xmlrpc_client::send` method accept an XML string for sending instead of an xmlrpcmsg object, to
2280 facilitate debugging and integration with the php native xmlrpc extension
2282 * Extend the `php_xmlrpc_encode` and `php_xmlrpc_decode` functions to allow serialization and rebuilding of
2283 PHP objects. To successfully rebuild a serialized object, the object class must be defined in the deserializing end
2284 of the transfer. Note that object members of type resource will be deserialized as NULL values.
2286 Note that his has been implemented adding a "php_class" attribute to xml representation of xmlrpcval of STRUCT type,
2287 which, strictly speaking, breaks the xml-rpc spec. Other xmlrpc implementations are supposed to ignore such an
2288 attribute (unless they implement a brain-dead custom xml parser...), so it should be safe enabling it in
2289 heterogeneous environments. The activation of this feature is done by usage of an option passed as second parameter
2290 to both `php_xmlrpc_encode` and `php_xmlrpc_decode`.
2292 * Extend the `php_xmlrpc_encode` function to allow automatic serialization of iso8601-conforming php strings as
2293 datetime.iso8601 xmlrpcvals, by usage of an optional parameter
2295 * Added an automatic stub code generator for converting xmlrpc methods to php functions and vice-versa.
2297 This is done via two new functions: `wrap_php_function` and `wrap_xmlrpc_method`, and has many caveats,
2298 with php being a typeless language and all...
2300 * Allow object methods to be used in server dispatch map
2302 * Added a complete debugger solution, in the __debugger__ folder
2304 * Added configurable server-side debug messages, controlled by the new method `xmlrpc_server::SetDebug()`.
2305 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
2306 more info is echoed back to the client, regarding the received call; at level 3 all warnings raised during server
2307 processing are trapped (this prevents breaking the xml to be echoed back to the client) and added to the debug info
2308 sent back to the client
2310 * New XML parsing code, yields smaller memory footprint and faster execution times, not to mention complete elimination
2311 of the dreaded __eval()__ construct, so prone to code injection exploits
2313 * Rewritten most of the error messages, making text more explicative
2315 ++++++++++++++++++++++++++++++++++++++
2316 <!-- Keep this comment at the end of the file
2321 sgml-minimize-attributes:nil
2322 sgml-always-quote-attributes:t
2325 sgml-parent-document:nil
2326 sgml-exposed-tags:nil
2327 sgml-local-catalogs:nil
2328 sgml-local-ecat-files:nil
2329 sgml-namecase-general:t
2330 sgml-general-insert-case:lower
2333 ++++++++++++++++++++++++++++++++++++++