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:$$https://sourceforge.net/projects/phpxmlrpc/$$[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]
63 Ernest MacDougal Campbell III
101 Przemyslaw Wroblewski
103 Bruno Zanetti Melotti
107 == System Requirements
109 The library has been designed with goals of flexibility and backward compatibility. As such, it supports a wide range of
110 PHP installs. Note that not all features of the lib are available in every configuration.
112 The __minimum supported__ PHP version is 5.3.
114 If you wish to use HTTPS or HTTP 1.1 to communicate with remote servers, or to use NTLM authentication, you need the
115 *curl* extension compiled into your PHP installation.
117 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
118 will need the *mbstring* extension compiled into your PHP installation.
120 The *xmlrpc* native extension is not required to be compiled into your PHP installation, but if it is, there will be no
121 interference with the operation of this library.
125 == Files in the distribution
127 debugger/*:: a graphical debugger which can be used to test calls to xmlrpc servers
129 demo/*:: example code for implementing both xmlrpc client and server functionality
131 doc/*:: the documentation, including this manual, and the list of API changes between versions 3 and 4
133 extras/*:: php utility scripts, such as a benchmark suite and an evironment compatibility checker
135 lib/*:: a compatibility layer for applications which still rely on version 3 of the API
137 src/*:: the XML-RPC library classes. You can autoload these via Composer, or via a dedicated Autoloader class
139 tests/*:: the test suite for the library, written using PhpUnit, and the configuration to run it either on GitHub Actions or in a local Docker container
145 Known bugs are tracked using the link:$$https://github.com/gggeek/phpxmlrpc/issues$$[GitHub issue tracker]
149 This started out as a bare framework. Many "nice" bits have been put in over time, but backwards compatibility has
150 always taken precedence over API cleanups. As such, you might find some API choices questionable.
152 Specifically, very little type validation or coercion has been put in. PHP being a loosely-typed language, this is
153 going to have to be done explicitly (in other words: you can call a lot of library functions passing them arguments
154 of the wrong type and receive an error message only much further down the code, where it will be difficult to
157 dateTime.iso8601 is supported opaquely. It can't be done natively as the XML-RPC specification explicitly forbids
158 passing of timezone specifiers in ISO8601 format dates. You can, however, use the PhpXmlRpc\Helper\Date class to do
159 the encoding and decoding for you.
161 Very little HTTP response checking is performed (e.g. HTTP redirects are not followed and the Content-Length HTTP
162 header, mandated by the xml-rpc spec, is not validated); cookie support still involves quite a bit of coding on the
171 XML-RPC for PHP is offered "as-is" without any warranty or commitment to support. However, informal advice and help is
172 available via the XML-RPC for PHP website and mailing list.
174 * The __XML-RPC for PHP__ development is hosted on
175 link:$$https://github.com/gggeek/phpxmlrpc$$[github.com/gggeek/phpxmlrpc]. Bugs, feature requests and patches can be
176 posted to the link:$$https://github.com/gggeek/phpxmlrpc/issues$$[project's website].
178 * The __PHP XML-RPC interest mailing list__ is run by the original author. More details
179 link:$$https://lists.usefulinc.com/cgi-bin/mailman/listinfo/phpxmlrpc$$[can be found here].
183 === The Jellyfish Book
185 image::progxmlrpc.s.gif[The Jellyfish Book]
186 Together with Simon St.Laurent and Joe Johnston, Edd Dumbill wrote a book on XML-RPC for O'Reilly and Associates on
187 XML-RPC. It features a rather fetching jellyfish on the cover.
189 Complete details of the book are link:$$https://www.oreilly.com/library/view/programming-web-services/0596001193/$$[available from O'Reilly's web site.]
191 Edd is responsible for the chapter on PHP, which includes a worked example of creating a forum server, and hooking it up
192 the (now discontinued) O'Reilly's Meerkat service in order to allow commenting on news stories
195 If you've benefited from the effort that has been put into writing this software, then please consider buying the book!
199 == Class documentation
205 The type i4 is accepted as a synonym
206 for int when creating xmlrpcval objects. The
207 xml parsing code will always convert i4 to
209 by this implementation as the canonical name for this type.
211 The type i8 on the other hand is considered as a separate type.
212 Note that the library will never output integers as 'i8' on its own,
213 even when php is compiled in 64-bit mode.
217 Base 64 encoding is performed transparently to the caller when
218 using this type. Decoding is also transparent. Therefore you ought
219 to consider it as a "binary" data type, for use when you want to
220 pass data that is not 7-bit clean.
224 The php values ++true++ and
225 ++1++ map to ++true++. All other
226 values (including the empty string) are converted to
231 Characters <, >;, ', ", &, are encoded using their
232 entity reference as < > ' " and
233 & All other characters outside of the ASCII range are
234 encoded using their character reference representation (e.g.
235 È for é). The XML-RPC spec recommends only encoding
236 ++< >++ but this implementation goes further,
237 for reasons explained by link:$$http://www.w3.org/TR/REC-xml#syntax$$[the XML 1.0 recommendation]. In particular, using character reference
238 representation has the advantage of producing XML that is valid
239 independently of the charset encoding assumed.
243 There is no support for encoding ++null++
244 values in the XML-RPC spec, but at least a couple of extensions (and
245 many toolkits) do support it. Before using ++null++
246 values in your messages, make sure that the responding party accepts
247 them, and uses the same encoding convention (see ...).
249 [[xmlrpcval-creation]]
250 ==== Xmlrpcval creation
252 The constructor is the normal way to create an
253 xmlrpcval. The constructor can take these
257 xmlrpcval xmlrpcvalnew
258 xmlrpcval string $stringVal xmlrpcvalnew
259 xmlrpcval mixed $scalarVal string$scalartyp xmlrpcvalnew
260 xmlrpcval array $arrayVal string $arraytyp The first constructor creates an empty value, which must be
261 altered using the methods addScalar,
262 addArray or addStruct before
265 The second constructor creates a simple string value.
267 The third constructor is used to create a scalar value. The
268 second parameter must be a name of an XML-RPC type. Valid types are:
269 "++int++", "++boolean++",
270 "++string++", "++double++",
271 "++dateTime.iso8601++", "++base64++" or
278 $myInt = new xmlrpcval(1267, "int");
279 $myString = new xmlrpcval("Hello, World!", "string");
280 $myBool = new xmlrpcval(1, "boolean");
281 $myString2 = new xmlrpcval(1.24, "string"); // note: this will serialize a php float value as xmlrpc string
284 The fourth constructor form can be used to compose complex
285 XML-RPC values. The first argument is either a simple array in the
286 case of an XML-RPC array or an associative
287 array in the case of a struct. The elements of
288 the array __must be xmlrpcval objects themselves__.
290 The second parameter must be either "++array++"
297 $myArray = new xmlrpcval(
299 new xmlrpcval("Tom"),
300 new xmlrpcval("Dick"),
301 new xmlrpcval("Harry")
306 $myStruct = new xmlrpcval(
308 "name" => new xmlrpcval("Tom", "string"),
309 "age" => new xmlrpcval(34, "int"),
310 "address" => new xmlrpcval(
312 "street" => new xmlrpcval("Fifht Ave", "string"),
313 "city" => new xmlrpcval("NY", "string")
320 See the file ++vardemo.php++ in this distribution
324 ==== Xmlrpc-client creation
326 The constructor accepts one of two possible syntaxes:
329 xmlrpc_clientstring$server_urlxmlrpc_clientnew
330 xmlrpc_clientstring$server_pathstring$server_hostnameint$server_port80string$transport'http'Here are a couple of usage examples of the first form:
335 $client = new xmlrpc_client("http://phpxmlrpc.sourceforge.net/server.php");
336 $another_client = new xmlrpc_client("https://james:bond@secret.service.com:443/xmlrpcserver?agent=007");
339 The second syntax does not allow to express a username and
340 password to be used for basic HTTP authorization as in the second
341 example above, but instead it allows to choose whether xmlrpc calls
342 will be made using the HTTP 1.0 or 1.1 protocol.
344 Here's another example client set up to query Userland's XML-RPC
345 server at __betty.userland.com__:
349 $client = new xmlrpc_client("/RPC2", "betty.userland.com", 80);
352 The server_port parameter is optional,
353 and if omitted will default to 80 when using HTTP and 443 when using
356 The transport parameter is optional, and
357 if omitted will default to 'http'. Allowed values are either
359 'http11'. Its value can be overridden with every call
360 to the send method. See the
361 send method below for more details about the
362 meaning of the different values.
369 The implementation of this class has been kept as simple to use as
370 possible. The constructor for the server basically does all the work.
371 Here's a minimal example:
376 function foo ($xmlrpcmsg) {
378 return new xmlrpcresp($some_xmlrpc_val);
382 function foobar($xmlrpcmsg) {
384 return new xmlrpcresp($some_xmlrpc_val);
388 $s = new xmlrpc_server(
390 "examples.myFunc1" => array("function" => "foo"),
391 "examples.myFunc2" => array("function" => "bar::foobar"),
395 This performs everything you need to do with a server. The single
396 constructor argument is an associative array from xmlrpc method names to
397 php function names. The incoming request is parsed and dispatched to the
398 relevant php function, which is responsible for returning a
399 xmlrpcresp object, that will be serialized back
403 ==== Method handler functions
405 Both php functions and class methods can be registered as xmlrpc
408 The synopsis of a method handler function is:
410 xmlrpcresp $resp = function (xmlrpcmsg $msg)
412 No text should be echoed 'to screen' by the handler function, or
413 it will break the xml response sent back to the client. This applies
414 also to error and warning messages that PHP prints to screen unless
415 the appropriate parameters have been set in the php.in file. Another
416 way to prevent echoing of errors inside the response and facilitate
417 debugging is to use the server SetDebug method with debug level 3 (see
418 ...). Exceptions thrown duting execution of handler functions are
419 caught by default and a XML-RPC error reponse is generated instead.
420 This behaviour can be finetuned by usage of the
421 exception_handling member variable (see
424 Note that if you implement a method with a name prefixed by
425 ++system.++ the handler function will be invoked by the
426 server with two parameters, the first being the server itself and the
427 second being the xmlrpcmsg object.
429 The same php function can be registered as handler of multiple
432 Here is a more detailed example of what the handler function
438 function foo ($xmlrpcmsg) {
439 global $xmlrpcerruser; // import user errcode base value
441 $meth = $xmlrpcmsg->method(); // retrieve method name
442 $par = $xmlrpcmsg->getParam(0); // retrieve value of first parameter - assumes at least one param received
443 $val = $par->scalarval(); // decode value of first parameter - assumes it is a scalar value
448 // this is an error condition
449 return new xmlrpcresp(0, $xmlrpcerruser+1, // user error 1
450 "There's a problem, Captain");
452 // this is a successful value being returned
453 return new xmlrpcresp(new xmlrpcval("All's fine!", "string"));
458 See __server.php__ in this distribution for
459 more examples of how to do this.
461 Since release 2.0RC3 there is a new, even simpler way of
462 registering php functions with the server. See section 5.7
466 ==== The dispatch map
468 The first argument to the xmlrpc_server
469 constructor is an array, called the __dispatch map__.
470 In this array is the information the server needs to service the
471 XML-RPC methods you define.
473 The dispatch map takes the form of an associative array of
474 associative arrays: the outer array has one entry for each method, the
475 key being the method name. The corresponding value is another
476 associative array, which can have the following members:
479 * ++function++ - this
480 entry is mandatory. It must be either a name of a function in the
481 global scope which services the XML-RPC method, or an array
482 containing an instance of an object and a static method name (for
483 static class methods the 'class::method' syntax is also
487 * ++signature++ - this
488 entry is an array containing the possible signatures (see <<signatures>>) for the method. If this entry is present
489 then the server will check that the correct number and type of
490 parameters have been sent for this method before dispatching
494 * ++docstring++ - this
495 entry is a string containing documentation for the method. The
496 documentation may contain HTML markup.
499 * ++$$signature_docs$$++ - this entry can be used
500 to provide documentation for the single parameters. It must match
501 in structure the 'signature' member. By default, only the
502 documenting_xmlrpc_server class in the
503 extras package will take advantage of this, since the
504 "system.methodHelp" protocol does not support documenting method
505 parameters individually.
508 * ++$$parameters_type$$++ - this entry can be used
509 when the server is working in 'xmlrpcvals' mode (see ...) to
510 define one or more entries in the dispatch map as being functions
511 that follow the 'phpvals' calling convention. The only useful
512 value is currently the string ++phpvals++.
514 Look at the __server.php__ example in the
515 distribution to see what a dispatch map looks like.
518 ==== Method signatures
520 A signature is a description of a method's return type and its
521 parameter types. A method may have more than one signature.
523 Within a server's dispatch map, each method has an array of
524 possible signatures. Each signature is an array of types. The first
525 entry is the return type. For instance, the method
529 string examples.getStateName(int)
536 array($xmlrpcString, $xmlrpcInt)
539 and, assuming that it is the only possible signature for the
540 method, it might be used like this in server creation:
544 $findstate_sig = array(array($xmlrpcString, $xmlrpcInt));
546 $findstate_doc = 'When passed an integer between 1 and 51 returns the
547 name of a US state, where the integer is the index of that state name
548 in an alphabetic order.';
550 $s = new xmlrpc_server( array(
551 "examples.getStateName" => array(
552 "function" => "findstate",
553 "signature" => $findstate_sig,
554 "docstring" => $findstate_doc
558 Note that method signatures do not allow to check nested
559 parameters, e.g. the number, names and types of the members of a
560 struct param cannot be validated.
562 If a method that you want to expose has a definite number of
563 parameters, but each of those parameters could reasonably be of
564 multiple types, the array of acceptable signatures will easily grow
565 into a combinatorial explosion. To avoid such a situation, the lib
566 defines the global var $xmlrpcValue, which can be
567 used in method signatures as a placeholder for 'any xmlrpc
572 $echoback_sig = array(array($xmlrpcValue, $xmlrpcValue));
574 $findstate_doc = 'Echoes back to the client the received value, regardless of its type';
576 $s = new xmlrpc_server( array(
578 "function" => "echoback",
579 "signature" => $echoback_sig, // this sig guarantees that the method handler will be called with one and only one parameter
580 "docstring" => $echoback_doc
584 Methods system.listMethods,
586 system.methodSignature and
587 system.multicall are already defined by the
588 server, and should not be reimplemented (see Reserved Methods
591 ==== Delaying the server response
593 You may want to construct the server, but for some reason not
594 fulfill the request immediately (security verification, for instance).
595 If you omit to pass to the constructor the dispatch map or pass it a
596 second argument of ++0++ this will have the desired
597 effect. You can then use the service() method of
598 the server class to service the request. For example:
603 $s = new xmlrpc_server($myDispMap, 0); // second parameter = 0 prevents automatic servicing of request
605 // ... some code that does other stuff here
610 Note that the service method will print
611 the complete result payload to screen and send appropriate HTTP
612 headers back to the client, but also return the response object. This
613 permits further manipulation of the response, possibly in combination
614 with output buffering.
616 To prevent the server from sending HTTP headers back to the
617 client, you can pass a second parameter with a value of
618 ++TRUE++ to the service
619 method. In this case, the response payload will be returned instead of
622 Xmlrpc requests retrieved by other means than HTTP POST bodies
623 can also be processed. For example:
627 $s = new xmlrpc_server(); // not passing a dispatch map prevents automatic servicing of request
629 // ... some code that does other stuff here, including setting dispatch map into server object
631 $resp = $s->service($xmlrpc_request_body, true); // parse a variable instead of POST body, retrieve response payload
633 // ... some code that does other stuff with xml response $resp here
636 ==== Modifying the server behaviour
638 A couple of methods / class variables are available to modify
639 the behaviour of the server. The only way to take advantage of their
640 existence is by usage of a delayed server response (see above)
645 This function controls weather the server is going to echo
646 debugging messages back to the client as comments in response body.
647 Valid values: 0,1,2,3, with 1 being the default. At level 0, no
648 debug info is returned to the client. At level 2, the complete
649 client request is added to the response, as part of the xml
650 comments. At level 3, a new PHP error handler is set when executing
651 user functions exposed as server methods, and all non-fatal errors
652 are trapped and added as comments into the response.
655 ===== allow_system_funcs
657 Default_value: TRUE. When set to FALSE, disables support for
658 System.xxx functions in the server. It
659 might be useful e.g. if you do not wish the server to respond to
660 requests to System.ListMethods.
663 ===== compress_response
665 When set to TRUE, enables the server to take advantage of HTTP
666 compression, otherwise disables it. Responses will be transparently
667 compressed, but only when an xmlrpc-client declares its support for
668 compression in the HTTP headers of the request.
670 Note that the ZLIB php extension must be installed for this to
671 work. If it is, compress_response will default to
675 ===== exception_handling
677 This variable controls the behaviour of the server when an
678 exception is thrown by a method handler php function. Valid values:
679 0,1,2, with 0 being the default. At level 0, the server catches the
680 exception and return an 'internal error' xmlrpc response; at 1 it
681 catches the exceptions and return an xmlrpc response with the error
682 code and error message corresponding to the exception that was
683 thron; at 2 = the exception is floated to the upper layers in the
687 ===== response_charset_encoding
689 Charset encoding to be used for response (only affects string
692 If it can, the server will convert the generated response from
693 internal_encoding to the intended one.
695 Valid values are: a supported xml encoding (only UTF-8 and
696 ISO-8859-1 at present, unless mbstring is enabled), null (leave
697 charset unspecified in response and convert output stream to
698 US_ASCII), 'default' (use xmlrpc library default as specified in
699 xmlrpc.inc, convert output stream if needed), or 'auto' (use
700 client-specified charset encoding or same as request if request
701 headers do not specify it (unless request is US-ASCII: then use
702 library default anyway).
707 Fault codes for your servers should start at the value indicated
708 by the global ++$xmlrpcerruser++ + 1.
710 Standard errors returned by the server include:
712 ++1++ Unknown method:: Returned if the server was asked to dispatch a method it
715 ++2++ Invalid return payload:: This error is actually generated by the client, not
716 server, code, but signifies that a server returned something it
717 couldn't understand. A more detailed error report is sometimes
718 added onto the end of the phrase above.
720 ++3++ Incorrect parameters:: This error is generated when the server has signature(s)
721 defined for a method, and the parameters passed by the client do
722 not match any of signatures.
724 ++4++ Can't introspect: method unknown:: This error is generated by the builtin
725 system.* methods when any kind of
726 introspection is attempted on a method undefined by the
729 ++5++ Didn't receive 200 OK from remote server:: This error is generated by the client when a remote server
730 doesn't return HTTP/1.1 200 OK in response to a request. A more
731 detailed error report is added onto the end of the phrase
734 ++6++ No data received from server:: This error is generated by the client when a remote server
735 returns HTTP/1.1 200 OK in response to a request, but no
736 response body follows the HTTP headers.
738 ++7++ No SSL support compiled in:: This error is generated by the client when trying to send
739 a request with HTTPS and the CURL extension is not available to
742 ++8++ CURL error:: This error is generated by the client when trying to send
743 a request with HTTPS and the HTTPS communication fails.
745 ++9-14++ multicall errors:: These errors are generated by the server when something
746 fails inside a system.multicall request.
748 ++100-++ XML parse errors:: Returns 100 plus the XML parser error code for the fault
749 that occurred. The faultString returned
750 explains where the parse error was in the incoming XML
754 ==== 'New style' servers
756 In the same spirit of simplification that inspired the
757 xmlrpc_client::return_type class variable, a new
758 class variable has been added to the server class:
759 functions_parameters_type. When set to 'phpvals',
760 the functions registered in the server dispatch map will be called
761 with plain php values as parameters, instead of a single xmlrpcmsg
762 instance parameter. The return value of those functions is expected to
763 be a plain php value, too. An example is worth a thousand
767 function foo($usr_id, $out_lang='en') {
768 global $xmlrpcerruser;
772 if ($someErrorCondition)
773 return new xmlrpcresp(0, $xmlrpcerruser+1, 'DOH!');
778 'picture' => new xmlrpcval(file_get_contents($picOfTheGuy), 'base64')
782 $s = new xmlrpc_server(
784 "examples.myFunc" => array(
785 "function" => "bar::foobar",
786 "signature" => array(
787 array($xmlrpcString, $xmlrpcInt),
788 array($xmlrpcString, $xmlrpcInt, $xmlrpcString)
792 $s->functions_parameters_type = 'phpvals';
796 There are a few things to keep in mind when using this
799 to return an xmlrpc error, the method handler function must
800 return an instance of xmlrpcresp. The only
801 other way for the server to know when an error response should be
802 served to the client is to throw an exception and set the server's
803 exception_handling memeber var to 1;
805 to return a base64 value, the method handler function must
806 encode it on its own, creating an instance of an xmlrpcval
809 the method handler function cannot determine the name of the
810 xmlrpc method it is serving, unlike standard handler functions that
811 can retrieve it from the message object;
813 when receiving nested parameters, the method handler function
814 has no way to distinguish a php string that was sent as base64 value
815 from one that was sent as a string value;
817 this has a direct consequence on the support of
818 system.multicall: a method whose signature contains datetime or base64
819 values will not be available to multicall calls;
821 last but not least, the direct parsing of xml to php values is
822 much faster than using xmlrpcvals, and allows the library to handle
823 much bigger messages without allocating all available server memory or
824 smashing PHP recursive call stack.
830 Many global variables are defined in the xmlrpc.inc file. Some of
831 those are meant to be used as constants (and modifying their value might
832 cause unpredictable behaviour), while some others can be modified in your
833 php scripts to alter the behaviour of the xml-rpc client and
837 === "Constant" variables
842 $xmlrpcerruser800The minimum value for errors reported by user
843 implemented XML-RPC servers. Error numbers lower than that are
844 reserved for library usage.
847 ==== $xmlrpcI4, $xmlrpcI8 $xmlrpcInt, $xmlrpcBoolean, $xmlrpcDouble, $xmlrpcString, $xmlrpcDateTime, $xmlrpcBase64, $xmlrpcArray, $xmlrpcStruct, $xmlrpcValue, $xmlrpcNull
849 For convenience the strings representing the XML-RPC types have
850 been encoded as global variables:
856 $xmlrpcBoolean="boolean";
857 $xmlrpcDouble="double";
858 $xmlrpcString="string";
859 $xmlrpcDateTime="dateTime.iso8601";
860 $xmlrpcBase64="base64";
861 $xmlrpcArray="array";
862 $xmlrpcStruct="struct";
863 $xmlrpcValue="undefined";
867 ==== $xmlrpcTypes, $xmlrpc_valid_parents, $xmlrpcerr, $xmlrpcstr, $xmlrpcerrxml, $xmlrpc_backslash, $_xh, $xml_iso88591_Entities, $xmlEntities, $xmlrpcs_capabilities
869 Reserved for internal usage.
872 === Variables whose value can be modified
874 [[xmlrpc-defencoding]]
875 ==== xmlrpc_defencoding
877 $xmlrpc_defencoding"UTF8"This variable defines the character set encoding that will be
878 used by the xml-rpc client and server to decode the received messages,
879 when a specific charset declaration is not found (in the messages sent
880 non-ascii chars are always encoded using character references, so that
881 the produced xml is valid regardless of the charset encoding
884 Allowed values: ++"UTF8"++,
885 ++"ISO-8859-1"++, ++"ASCII".++
887 Note that the appropriate RFC actually mandates that XML
888 received over HTTP without indication of charset encoding be treated
889 as US-ASCII, but many servers and clients 'in the wild' violate the
890 standard, and assume the default encoding is UTF-8.
893 ==== xmlrpc_internalencoding
895 $xmlrpc_internalencoding"ISO-8859-1"This variable defines the character set encoding
896 that the library uses to transparently encode into valid XML the
897 xml-rpc values created by the user and to re-encode the received
898 xml-rpc values when it passes them to the PHP application. It only
899 affects xml-rpc values of string type. It is a separate value from
900 xmlrpc_defencoding, allowing e.g. to send/receive xml messages encoded
901 on-the-wire in US-ASCII and process them as UTF-8. It defaults to the
902 character set used internally by PHP (unless you are running an
903 MBString-enabled installation), so you should change it only in
904 special situations, if e.g. the string values exchanged in the xml-rpc
905 messages are directly inserted into / fetched from a database
906 configured to return UTF8 encoded strings to PHP. Example
913 include('xmlrpc.inc');
914 $xmlrpc_internalencoding = 'UTF-8'; // this has to be set after the inclusion above
915 $v = new xmlrpcval('κόÏ
\83με'); // This xmlrpc value will be correctly serialized as the greek word 'kosme'
920 $xmlrpcName"XML-RPC for PHP"The string representation of the name of the XML-RPC
921 for PHP library. It is used by the client for building the User-Agent
922 HTTP header that is sent with every request to the server. You can
923 change its value if you need to customize the User-Agent
929 $xmlrpcVersion"2.2"The string representation of the version number of
930 the XML-RPC for PHP library in use. It is used by the client for
931 building the User-Agent HTTP header that is sent with every request to
932 the server. You can change its value if you need to customize the
936 ==== xmlrpc_null_extension
938 When set to TRUE, the lib will enable
939 support for the <NIL/> (and <EX:NIL/>) xmlrpc value, as
940 per the extension to the standard proposed here. This means that
941 <NIL> and <EX:NIL/> tags received will be parsed as valid
942 xmlrpc, and the corresponding xmlrpcvals will return "null" for
946 ==== xmlrpc_null_apache_encoding
948 When set to ++TRUE++, php NULL values encoded
949 into xmlrpcval objects get serialized using the
950 ++<EX:NIL/>++ tag instead of
951 ++<NIL/>++. Please note that both forms are
952 always accepted as input regardless of the value of this
959 XML-RPC for PHP contains some helper functions which you can use to
960 make processing of XML-RPC requests easier.
965 The XML-RPC specification has this to say on dates:
969 [[wrap_xmlrpc_method]]
970 Don't assume a timezone. It should be
971 specified by the server in its documentation what assumptions it makes
976 Unfortunately, this means that date processing isn't
977 straightforward. Although XML-RPC uses ISO 8601 format dates, it doesn't
978 use the timezone specifier.
980 We strongly recommend that in every case where you pass dates in
981 XML-RPC calls, you use UTC (GMT) as your timezone. Most computer
982 languages include routines for handling GMT times natively, and you
983 won't have to translate between timezones.
985 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
986 8601 specification. Note that XML-RPC uses exactly one of the available
987 representations: CCYYMMDDTHH:MM:SS.
992 stringiso8601_encodestring$time_tint$utc0Returns an ISO 8601 formatted date generated from the UNIX
993 timestamp $time_t, as returned by the PHP
996 The argument $utc can be omitted, in
997 which case it defaults to ++0++. If it is set to
998 ++1++, then the function corrects the time passed in
999 for UTC. Example: if you're in the GMT-6:00 timezone and set
1000 $utc, you will receive a date representation
1001 six hours ahead of your local time.
1003 The included demo program __vardemo.php__
1004 includes a demonstration of this function.
1009 intiso8601_decodestring$isoStringint$utc0Returns a UNIX timestamp from an ISO 8601 encoded time and date
1010 string passed in. If $utc is
1011 ++1++ then $isoString is assumed
1012 to be in the UTC timezone, and thus the result is also UTC: otherwise,
1013 the timezone is assumed to be your local timezone and you receive a
1017 === Easy use with nested PHP values
1019 Dan Libby was kind enough to contribute two helper functions that
1020 make it easier to translate to and from PHP values. This makes it easier
1021 to deal with complex structures. At the moment support is limited to
1022 int, double, string,
1023 array, datetime and struct
1024 datatypes; note also that all PHP arrays are encoded as structs, except
1025 arrays whose keys are integer numbers starting with 0 and incremented by
1028 These functions reside in __xmlrpc.inc__.
1031 ==== php_xmlrpc_decode
1033 mixedphp_xmlrpc_decodexmlrpcval$xmlrpc_valarray$optionsarrayphp_xmlrpc_decodexmlrpcmsg$xmlrpcmsg_valstring$optionsReturns a native PHP value corresponding to the values found in
1034 the xmlrpcval $xmlrpc_val,
1035 translated into PHP types. Base-64 and datetime values are
1036 automatically decoded to strings.
1038 In the second form, returns an array containing the parameters
1040 xmlrpcmsg_val, decoded
1043 The options parameter is optional. If
1044 specified, it must consist of an array of options to be enabled in the
1045 decoding process. At the moment the only valid option are
1047 ++$$dates_as_objects$$++. When the first is set, php
1048 objects that have been converted to xml-rpc structs using the
1049 php_xmlrpc_encode function and a corresponding
1050 encoding option will be converted back into object values instead of
1051 arrays (provided that the class definition is available at
1052 reconstruction time). When the second is set, XML-RPC datetime values
1053 will be converted into native dateTime objects
1056 ____WARNING__:__ please take
1057 extreme care before enabling the decode_php_objs
1058 option: when php objects are rebuilt from the received xml, their
1059 constructor function will be silently invoked. This means that you are
1060 allowing the remote end to trigger execution of uncontrolled PHP code
1061 on your server, opening the door to code injection exploits. Only
1062 enable this option when you have complete trust of the remote
1068 // wrapper to expose an existing php function as xmlrpc method handler
1069 function foo_wrapper($m)
1071 $params = php_xmlrpc_decode($m);
1072 $retval = call_user_func_array('foo', $params);
1073 return new xmlrpcresp(new xmlrpcval($retval)); // foo return value will be serialized as string
1076 $s = new xmlrpc_server(array(
1077 "examples.myFunc1" => array(
1078 "function" => "foo_wrapper",
1084 ==== php_xmlrpc_encode
1086 xmlrpcvalphp_xmlrpc_encodemixed$phpvalarray$optionsReturns an xmlrpcval object populated with the PHP
1087 values in $phpval. Works recursively on arrays
1088 and objects, encoding numerically indexed php arrays into array-type
1089 xmlrpcval objects and non numerically indexed php arrays into
1090 struct-type xmlrpcval objects. Php objects are encoded into
1091 struct-type xmlrpcvals, excepted for php values that are already
1092 instances of the xmlrpcval class or descendants thereof, which will
1093 not be further encoded. Note that there's no support for encoding php
1094 values into base-64 values. Encoding of date-times is optionally
1095 carried on on php strings with the correct format.
1097 The options parameter is optional. If
1098 specified, it must consist of an array of options to be enabled in the
1099 encoding process. At the moment the only valid options are
1100 encode_php_objs, ++$$null_extension$$++
1103 The first will enable the creation of 'particular' xmlrpcval
1104 objects out of php objects, that add a "php_class" xml attribute to
1105 their serialized representation. This attribute allows the function
1106 php_xmlrpc_decode to rebuild the native php objects (provided that the
1107 same class definition exists on both sides of the communication). The
1108 second allows to encode php ++NULL++ values to the
1110 ++<EX:NIL>++, see ...) tag. The last encodes any
1111 string that matches the ISO8601 format into an XML-RPC
1117 // the easy way to build a complex xml-rpc struct, showing nested base64 value and datetime values
1118 $val = php_xmlrpc_encode(array(
1119 'first struct_element: an int' => 666,
1120 'second: an array' => array ('apple', 'orange', 'banana'),
1121 'third: a base64 element' => new xmlrpcval('hello world', 'base64'),
1122 'fourth: a datetime' => '20060107T01:53:00'
1123 ), array('auto_dates'));
1126 ==== php_xmlrpc_decode_xml
1128 xmlrpcval | xmlrpcresp |
1129 xmlrpcmsgphp_xmlrpc_decode_xmlstring$xmlarray$optionsDecodes the xml representation of either an xmlrpc request,
1130 response or single value, returning the corresponding php-xmlrpc
1131 object, or ++FALSE++ in case of an error.
1133 The options parameter is optional. If
1134 specified, it must consist of an array of options to be enabled in the
1135 decoding process. At the moment, no option is supported.
1140 $text = '<value><array><data><value>Hello world</value></data></array></value>';
1141 $val = php_xmlrpc_decode_xml($text);
1142 if ($val) echo 'Found a value of type '.$val->kindOf(); else echo 'Found invalid xml';
1145 === Automatic conversion of php functions into xmlrpc methods (and vice versa)
1147 For the extremely lazy coder, helper functions have been added
1148 that allow to convert a php function into an xmlrpc method, and a
1149 remotely exposed xmlrpc method into a local php function - or a set of
1150 methods into a php class. Note that these comes with many caveat.
1153 ==== wrap_xmlrpc_method
1155 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
1156 function that will call the remote method and return results using
1157 native php types for both params and results. The generated php
1158 function will return an xmlrpcresp object for failed xmlrpc
1161 The second syntax is deprecated, and is listed here only for
1162 backward compatibility.
1164 The server must support the
1165 system.methodSignature xmlrpc method call for
1166 this function to work.
1168 The client param must be a valid
1169 xmlrpc_client object, previously created with the address of the
1170 target xmlrpc server, and to which the preferred communication options
1173 The optional parameters can be passed as array key,value pairs
1174 in the extra_options param.
1176 The signum optional param has the purpose
1177 of indicating which method signature to use, if the given server
1178 method has multiple signatures (defaults to 0).
1181 protocol optional params are the same as in the
1182 xmlrpc_client::send() method.
1184 If set, the optional new_function_name
1185 parameter indicates which name should be used for the generated
1186 function. In case it is not set the function name will be
1189 If the ++$$return_source$$++ optional parameter is
1190 set, the function will return the php source code to build the wrapper
1191 function, instead of evaluating it (useful to save the code and use it
1192 later as stand-alone xmlrpc client).
1194 If the ++$$encode_php_objs$$++ optional parameter is
1195 set, instances of php objects later passed as parameters to the newly
1196 created function will receive a 'special' treatment that allows the
1197 server to rebuild them as php objects instead of simple arrays. Note
1198 that this entails using a "slightly augmented" version of the xmlrpc
1199 protocol (ie. using element attributes), which might not be understood
1200 by xmlrpc servers implemented using other libraries.
1202 If the ++$$decode_php_objs$$++ optional parameter is
1203 set, instances of php objects that have been appropriately encoded by
1204 the server using a coordinate option will be deserialized as php
1205 objects instead of simple arrays (the same class definition should be
1206 present server side and client side).
1208 __Note that this might pose a security risk__,
1209 since in order to rebuild the object instances their constructor
1210 method has to be invoked, and this means that the remote server can
1211 trigger execution of unforeseen php code on the client: not really a
1212 code injection, but almost. Please enable this option only when you
1213 trust the remote server.
1215 In case of an error during generation of the wrapper function,
1216 FALSE is returned, otherwise the name (or source code) of the new
1219 Known limitations: server must support
1220 system.methodsignature for the wanted xmlrpc
1221 method; for methods that expose multiple signatures, only one can be
1222 picked; for remote calls with nested xmlrpc params, the caller of the
1223 generated php function has to encode on its own the params passed to
1224 the php function if these are structs or arrays whose (sub)members
1225 include values of type base64.
1227 Note: calling the generated php function 'might' be slow: a new
1228 xmlrpc client is created on every invocation and an xmlrpc-connection
1229 opened+closed. An extra 'debug' param is appended to the parameter
1230 list of the generated php function, useful for debugging
1238 $c = new xmlrpc_client('http://phpxmlrpc.sourceforge.net/server.php');
1240 $function = wrap_xmlrpc_method($client, 'examples.getStateName');
1243 die('Cannot introspect remote method');
1246 $statename = $function($a);
1247 if (is_a($statename, 'xmlrpcresp')) // call failed
1249 echo 'Call failed: '.$statename->faultCode().'. Calling again with debug on';
1250 $function($a, true);
1253 echo "OK, state nr. $stateno is $statename";
1257 [[wrap_php_function]]
1258 ==== wrap_php_function
1260 arraywrap_php_functionstring$funcnamestring$wrapper_function_namearray$extra_optionsGiven a user-defined PHP function, create a PHP 'wrapper'
1261 function that can be exposed as xmlrpc method from an xmlrpc_server
1262 object and called from remote clients, and return the appropriate
1263 definition to be added to a server's dispatch map.
1265 The optional $wrapper_function_name
1266 specifies the name that will be used for the auto-generated
1269 Since php is a typeless language, to infer types of input and
1270 output parameters, it relies on parsing the javadoc-style comment
1271 block associated with the given function. Usage of xmlrpc native types
1272 (such as datetime.dateTime.iso8601 and base64) in the docblock @param
1273 tag is also allowed, if you need the php function to receive/send data
1274 in that particular format (note that base64 encoding/decoding is
1275 transparently carried out by the lib, while datetime vals are passed
1278 Known limitations: only works for
1279 user-defined functions, not for PHP internal functions (reflection
1280 does not support retrieving number/type of params for those); the
1281 wrapped php function will not be able to programmatically return an
1282 xmlrpc error response.
1284 If the ++$$return_source$$++ optional parameter is
1285 set, the function will return the php source code to build the wrapper
1286 function, instead of evaluating it (useful to save the code and use it
1287 later in a stand-alone xmlrpc server). It will be in the stored in the
1288 ++source++ member of the returned array.
1290 If the ++$$suppress_warnings$$++ optional parameter
1291 is set, any runtime warning generated while processing the
1292 user-defined php function will be catched and not be printed in the
1293 generated xml response.
1295 If the extra_options array contains the
1296 ++$$encode_php_objs$$++ value, wrapped functions returning
1297 php objects will generate "special" xmlrpc responses: when the xmlrpc
1298 decoding of those responses is carried out by this same lib, using the
1299 appropriate param in php_xmlrpc_decode(), the objects will be
1302 In short: php objects can be serialized, too (except for their
1303 resource members), using this function. Other libs might choke on the
1304 very same xml that will be generated in this case (i.e. it has a
1305 nonstandard attribute on struct element tags)
1307 If the ++$$decode_php_objs$$++ optional parameter is
1308 set, instances of php objects that have been appropriately encoded by
1309 the client using a coordinate option will be deserialized and passed
1310 to the user function as php objects instead of simple arrays (the same
1311 class definition should be present server side and client
1314 __Note that this might pose a security risk__,
1315 since in order to rebuild the object instances their constructor
1316 method has to be invoked, and this means that the remote client can
1317 trigger execution of unforeseen php code on the server: not really a
1318 code injection, but almost. Please enable this option only when you
1319 trust the remote clients.
1327 * State name from state number decoder. NB: do NOT remove this comment block.
1328 * @param integer $stateno the state number
1329 * @return string the name of the state (or error description)
1331 function findstate($stateno)
1334 if (isset($stateNames[$stateno-1]))
1336 return $stateNames[$stateno-1];
1340 return "I don't have a state for the index '" . $stateno . "'";
1344 // wrap php function, build xmlrpc server
1346 $findstate_sig = wrap_php_function('findstate');
1348 $methods['examples.getStateName'] = $findstate_sig;
1349 $srv = new xmlrpc_server($methods);
1353 === Functions removed from the library
1355 The following two functions have been deprecated in version 1.1 of
1356 the library, and removed in version 2, in order to avoid conflicts with
1357 the EPI xml-rpc library, which also defines two functions with the same
1360 To ease the transition to the new naming scheme and avoid breaking
1361 existing implementations, the following scheme has been adopted:
1363 * If EPI-XMLRPC is not active in the current PHP installation,
1364 the constant `XMLRPC_EPI_ENABLED` will be set to
1368 * If EPI-XMLRPC is active in the current PHP installation, the
1369 constant `XMLRPC_EPI_ENABLED` will be set to
1372 The following documentation is kept for historical
1378 mixedx mlrpc_decode xmlrpcval $xmlrpc_val Alias for php_xmlrpc_decode.
1383 xmlrpcval xmlrpc_encode mixed $phpvalAlias for php_xmlrpc_encode.
1388 ==== xmlrpc_debugmsg
1390 void xmlrpc_debugmsgstring$debugstringSends the contents of $debugstring in XML
1391 comments in the server return payload. If a PHP client has debugging
1392 turned on, the user will be able to see server debug
1395 Use this function in your methods so you can pass back
1396 diagnostic information. It is only available from
1403 In order to extend the functionality offered by XML-RPC servers
1404 without impacting on the protocol, reserved methods are supported in this
1407 All methods starting with system. are
1408 considered reserved by the server. PHP for XML-RPC itself provides four
1409 special methods, detailed in this chapter.
1411 Note that all server objects will automatically respond to clients
1412 querying these methods, unless the property
1413 allow_system_funcs has been set to
1414 false before calling the
1415 service() method. This might pose a security risk
1416 if the server is exposed to public access, e.g. on the internet.
1419 === system.getCapabilities
1422 === system.listMethods
1424 This method may be used to enumerate the methods implemented by
1427 The system.listMethods method requires no
1428 parameters. It returns an array of strings, each of which is the name of
1429 a method implemented by the server.
1432 === system.methodSignature
1434 This method takes one parameter, the name of a method implemented
1435 by the XML-RPC server.
1437 It returns an array of possible signatures for this method. A
1438 signature is an array of types. The first of these types is the return
1439 type of the method, the rest are parameters.
1441 Multiple signatures (i.e. overloading) are permitted: this is the
1442 reason that an array of signatures are returned by this method.
1444 Signatures themselves are restricted to the top level parameters
1445 expected by a method. For instance if a method expects one array of
1446 structs as a parameter, and it returns a string, its signature is simply
1447 "string, array". If it expects three integers, its signature is "string,
1450 For parameters that can be of more than one type, the "undefined"
1451 string is supported.
1453 If no signature is defined for the method, a not-array value is
1454 returned. Therefore this is the way to test for a non-signature, if
1455 $resp below is the response object from a method
1456 call to system.methodSignature:
1460 $v = $resp->value();
1461 if ($v->kindOf() != "array") {
1462 // then the method did not have a signature defined
1466 See the __introspect.php__ demo included in this
1467 distribution for an example of using this method.
1470 === system.methodHelp
1472 This method takes one parameter, the name of a method implemented
1473 by the XML-RPC server.
1475 It returns a documentation string describing the use of that
1476 method. If no such string is available, an empty string is
1479 The documentation string may contain HTML markup.
1481 === system.multicall
1483 This method takes one parameter, an array of 'request' struct
1484 types. Each request struct must contain a
1485 methodName member of type string and a
1486 params member of type array, and corresponds to
1487 the invocation of the corresponding method.
1489 It returns a response of type array, with each value of the array
1490 being either an error struct (containing the faultCode and faultString
1491 members) or the successful response value of the corresponding single
1498 The best examples are to be found in the sample files included with
1499 the distribution. Some are included here.
1502 === XML-RPC client: state name query
1504 Code to get the corresponding state name from a number (1-50) from
1505 the demo server available on SourceForge
1509 $m = new xmlrpcmsg('examples.getStateName',
1510 array(new xmlrpcval($HTTP_POST_VARS["stateno"], "int")));
1511 $c = new xmlrpc_client("/server.php", "phpxmlrpc.sourceforge.net", 80);
1513 if (!$r->faultCode()) {
1515 print "State number " . htmlentities($HTTP_POST_VARS["stateno"]) . " is " .
1516 htmlentities($v->scalarval()) . "<BR>";
1517 print "<HR>I got this value back<BR><PRE>" .
1518 htmlentities($r->serialize()) . "</PRE><HR>\n";
1521 print "Code: " . htmlentities($r->faultCode()) . "<BR>" .
1522 "Reason: '" . htmlentities($r->faultString()) . "'<BR>";
1526 === Executing a multicall call
1534 == Frequently Asked Questions
1536 ==== How to send custom XML as payload of a method call::
1538 Unfortunately, at the time the XML-RPC spec was designed, support
1539 for namespaces in XML was not as ubiquitous as it is now. As a
1540 consequence, no support was provided in the protocol for embedding XML
1541 elements from other namespaces into an xmlrpc request.
1543 To send an XML "chunk" as payload of a method call or response,
1544 two options are available: either send the complete XML block as a
1545 string xmlrpc value, or as a base64 value. Since the '<' character in
1546 string values is encoded as '<' in the xml payload of the method
1547 call, the XML string will not break the surrounding xmlrpc, unless
1548 characters outside of the assumed character set are used. The second
1549 method has the added benefits of working independently of the charset
1550 encoding used for the xml to be transmitted, and preserving exactly
1551 whitespace, whilst incurring in some extra message length and cpu load
1552 (for carrying out the base64 encoding/decoding).
1555 ==== Is there any limitation on the size of the requests / responses that can be successfully sent?::
1557 Yes. But I have no hard figure to give; it most likely will depend
1558 on the version of PHP in usage and its configuration.
1560 Keep in mind that this library is not optimized for speed nor for
1561 memory usage. Better alternatives exist when there are strict
1562 requirements on throughput or resource usage, such as the php native
1563 xmlrpc extension (see the PHP manual for more information).
1565 Keep in mind also that HTTP is probably not the best choice in
1566 such a situation, and XML is a deadly enemy. CSV formatted data over
1567 socket would be much more efficient.
1569 If you really need to move a massive amount of data around, and
1570 you are crazy enough to do it using phpxmlrpc, your best bet is to
1571 bypass usage of the xmlrpcval objects, at least in the decoding phase,
1572 and have the server (or client) object return to the calling function
1573 directly php values (see xmlrpc_client::return_type
1574 and xmlrpc_server::functions_parameters_type for more
1578 ==== My server (client) returns an error whenever the client (server) returns accented characters
1583 ==== How to enable long-lasting method calls
1588 ==== My client returns "XML-RPC Fault #2: Invalid return payload: enable debugging to examine incoming payload": what should I do?
1590 The response you are seeing is a default error response that the
1591 client object returns to the php application when the server did not
1592 respond to the call with a valid xmlrpc response.
1594 The most likely cause is that you are not using the correct URL
1595 when creating the client object, or you do not have appropriate access
1596 rights to the web page you are requesting, or some other common http
1599 To find out what the server is really returning to your client,
1600 you have to enable the debug mode of the client, using
1601 $client->setDebug(1);
1604 ==== How can I save to a file the xml of the xmlrpc responses received from servers?
1606 If what you need is to save the responses received from the server
1607 as xml, you have two options:
1609 1- use the serialize() method on the response object.
1614 $resp = $client->send($msg);
1615 if (!$resp->faultCode())
1616 $data_to_be_saved = $resp->serialize();
1619 Note that this will not be 100% accurate, since the xml generated
1620 by the response object can be different from the xml received,
1621 especially if there is some character set conversion involved, or such
1622 (eg. if you receive an empty string tag as <string/>, serialize()
1623 will output <string></string>), or if the server sent back
1624 as response something invalid (in which case the xml generated client
1625 side using serialize() will correspond to the error response generated
1626 internally by the lib).
1628 2 - set the client object to return the raw xml received instead
1629 of the decoded objects:
1634 $client = new xmlrpc_client($url);
1635 $client->return_type = 'xml';
1636 $resp = $client->send($msg);
1637 if (!$resp->faultCode())
1638 $data_to_be_saved = $resp->value();
1641 Note that using this method the xml response response will not be
1642 parsed at all by the library, only the http communication protocol will
1643 be checked. This means that xmlrpc responses sent by the server that
1644 would have generated an error response on the client (eg. malformed xml,
1645 responses that have faultcode set, etc...) now will not be flagged as
1646 invalid, and you might end up saving not valid xml but random
1650 ==== Can I use the ms windows character set?
1652 If the data your application is using comes from a Microsoft
1653 application, there are some chances that the character set used to
1654 encode it is CP1252 (the same might apply to data received from an
1655 external xmlrpc server/client, but it is quite rare to find xmlrpc
1656 toolkits that encode to CP1252 instead of UTF8). It is a character set
1657 which is "almost" compatible with ISO 8859-1, but for a few extra
1660 PHP-XMLRPC only supports the ISO 8859-1 and UTF8 character sets.
1661 The net result of this situation is that those extra characters will not
1662 be properly encoded, and will be received at the other end of the
1663 XML-RPC transmission as "garbled data". Unfortunately the library cannot
1664 provide real support for CP1252 because of limitations in the PHP 4 xml
1665 parser. Luckily, we tried our best to support this character set anyway,
1666 and, since version 2.2.1, there is some form of support, left commented
1669 To properly encode outgoing data that is natively in CP1252, you
1670 will have to uncomment all relative code in the file
1671 __xmlrpc.inc__ (you can search for the string "1252"),
1672 then set ++$$$GLOBALS['xmlrpc_internalencoding']='CP1252';$$++
1673 Please note that all incoming data will then be fed to your application
1674 as UTF-8 to avoid any potential data loss.
1677 ==== Does the library support using cookies / http sessions?
1679 In short: yes, but a little coding is needed to make it
1682 The code below uses sessions to e.g. let the client store a value
1683 on the server and retrieve it later.
1687 $resp = $client->send(new xmlrpcmsg('registervalue', array(new xmlrpcval('foo'), new xmlrpcval('bar'))));
1688 if (!$resp->faultCode())
1690 $cookies = $resp->cookies();
1691 if (array_key_exists('PHPSESSID', $cookies)) // nb: make sure to use the correct session cookie name
1693 $session_id = $cookies['PHPSESSID']['value'];
1695 // do some other stuff here...
1697 $client->setcookie('PHPSESSID', $session_id);
1698 $val = $client->send(new xmlrpcmsg('getvalue', array(new xmlrpcval('foo')));
1703 Server-side sessions are handled normally like in any other
1704 php application. Please see the php manual for more information about
1707 NB: unlike web browsers, not all xmlrpc clients support usage of
1708 http cookies. If you have troubles with sessions and control only the
1709 server side of the communication, please check with the makers of the
1710 xmlrpc client in use.
1715 == Integration with the PHP xmlrpc extension
1717 To be documented more...
1719 In short: for the fastest execution possible, you can enable the php
1720 native xmlrpc extension, and use it in conjunction with phpxmlrpc. The
1721 following code snippet gives an example of such integration
1726 /*** client side ***/
1727 $c = new xmlrpc_client('http://phpxmlrpc.sourceforge.net/server.php');
1729 // tell the client to return raw xml as response value
1730 $c->return_type = 'xml';
1732 // let the native xmlrpc extension take care of encoding request parameters
1733 $r = $c->send(xmlrpc_encode_request('examples.getStateName', $_POST['stateno']));
1735 if ($r->faultCode())
1736 // HTTP transport error
1737 echo 'Got error '.$r->faultCode();
1740 // HTTP request OK, but XML returned from server not parsed yet
1741 $v = xmlrpc_decode($r->value());
1742 // check if we got a valid xmlrpc response from server
1744 echo 'Got invalid response';
1746 // check if server sent a fault response
1747 if (xmlrpc_is_fault($v))
1748 echo 'Got xmlrpc fault '.$v['faultCode'];
1750 echo'Got response: '.htmlentities($v);
1756 == Substitution of the PHP xmlrpc extension
1758 Yet another interesting situation is when you are using a ready-made
1759 php application, that provides support for the XMLRPC protocol via the
1760 native php xmlrpc extension, but the extension is not available on your
1761 php install (e.g. because of shared hosting constraints).
1763 Since version 2.1, the PHP-XMLRPC library provides a compatibility
1764 layer that aims to be 100% compliant with the xmlrpc extension API. This
1765 means that any code written to run on the extension should obtain the
1766 exact same results, albeit using more resources and a longer processing
1767 time, using the PHP-XMLRPC library and the extension compatibility module.
1768 The module is part of the EXTRAS package, available as a separate download
1769 from the sourceforge.net website, since version 0.2
1774 == 'Enough of xmlrpcvals!': new style library usage
1778 In the meantime, see docs about xmlrpc_client::return_type and
1779 xmlrpc_server::functions_parameters_types, as well as php_xmlrpc_encode,
1780 php_xmlrpc_decode and php_xmlrpc_decode_xml
1785 == Usage of the debugger
1787 A webservice debugger is included in the library to help during
1788 development and testing.
1790 The interface should be self-explicative enough to need little
1793 image::debugger.gif[,,,,align="center"]
1795 The most useful feature of the debugger is without doubt the "Show
1796 debug info" option. It allows to have a screen dump of the complete http
1797 communication between client and server, including the http headers as
1798 well as the request and response payloads, and is invaluable when
1799 troubleshooting problems with charset encoding, authentication or http
1802 The debugger can take advantage of the JSONRPC library extension, to
1803 allow debugging of JSON-RPC webservices, and of the JS-XMLRPC library
1804 visual editor to allow easy mouse-driven construction of the payload for
1805 remote methods. Both components have to be downloaded separately from the
1806 sourceforge.net web pages and copied to the debugger directory to enable
1807 the extra functionality:
1810 * to enable jsonrpc functionality, download the PHP-XMLRPC
1811 EXTRAS package, and copy the file __jsonrpc.inc__
1812 either to the same directory as the debugger or somewhere in your
1815 * to enable the visual value editing dialog, download the
1816 JS-XMLRPC library, and copy somewhere in the web root files
1817 __visualeditor.php__,
1818 __visualeditor.css__ and the folders
1819 __yui__ and __img__. Then edit the
1820 debugger file __controller.php__ and set
1821 appropriately the variable $editorpath.
1827 CAUTION: not all items the following list have (yet) been fully documented, and some might not be present in any other
1828 chapter in the manual. To find a more detailed description of new functions and methods please take a look at the
1829 source code of the library, which is quite thoroughly commented in phpdoc form.
1833 * new: introduction of namespaces and full OOP.
1835 All php classes have been renamed and moved to separate files.
1837 Class autoloading can now be done in accord with the PSR-4 standard.
1839 All global variables and global functions have been removed.
1841 Iterating over xmlrpc value objects is now easier thank to support for ArrayAccess and Traversable interfaces.
1843 Backward compatibility is maintained via _lib/xmlrpc.inc_, _lib/xmlrpcs.inc_ and _lib/xmlrpc_wrappers.inc_.
1844 For more details, head on to doc/api_changes_v4.md
1846 * changed: the default character encoding delivered from the library to your code is now utf8.
1847 It can be changed at any time setting a value to `PhpXmlRpc\PhpXmlRpc::$xmlrpc_internalencoding`
1849 * improved: the library now accepts requests/responses sent using other character sets than UTF-8/ISO-8859-1/ASCII.
1850 This only works when the mbstring php extension is enabled.
1852 * improved: no need to call anymore `$client->setSSLVerifyHost(2)` to silence a curl warning when using https
1853 with recent curl builds
1855 * improved: the xmlrpcval class now supports the interfaces `Countable` and `IteratorAggregate`
1857 * improved: a specific option allows users to decide the version of SSL to use for https calls.
1858 This is useful f.e. for the testing suite, when the server target of calls has no proper ssl certificate,
1859 and the cURL extension has been compiled with GnuTLS
1861 * improved: the function `wrap_php_function()` now can be used to wrap closures (it is now a method btw)
1863 * improved: all _wrap_something()_ functions now return a closure by default instead of a function name
1865 * improved: debug messages are not html-escaped any more when executing from the command line
1867 * improved: the library is now tested using Travis ( https://travis-ci.org/ ).
1868 Tests are executed using all php versions from 5.3 to 7.0 nightly, plus HHVM; code-coverage information
1869 is generated using php 5.6 and uploaded to both Code Coverage and Scrutinizer online services
1871 * improved: phpunit is now installed via composer, not bundled anymore
1873 * improved: when phpunit is used to generate code-coverage data, the code executed server-side is accounted for
1875 * improved: the test suite has basic checks for the debugger and demo files
1877 * improved: more tests in the test suite
1879 * fixed: the server would not reset the user-set debug messages between subsequent `service()` calls
1881 * fixed: the server would not reset previous php error handlers when an exception was thrown by user code and
1882 exception_handling set to 2
1884 * fixed: the server would fail to decode a request with ISO-8859-1 payload and character set declaration in the xml
1887 * fixed: the client would fail to decode a response with ISO-8859-1 payload and character set declaration in the xml
1890 * fixed: the function `decode_xml()` would not decode an xml with character set declaration in the xml prolog
1892 * fixed: the client can now successfully call methods using ISO-8859-1 or UTF-8 characters in their name
1894 * fixed: the debugger would fail sending a request with ISO-8859-1 payload (it missed the character set declaration).
1895 It would have a hard time coping with ISO-8859-1 in other fields, such as e.g. the remote method name
1897 * fixed: the debugger would generate a bad payload via the 'load method synopsis' button for signatures containing NULL
1898 or undefined parameters
1900 * fixed: the debugger would generate a bad payload via the 'load method synopsis' button for methods with multiple
1903 * improved: the debugger is displayed using UTF-8, making it more useful to debug any kind of service
1905 * improved: echo all debug messages even when there are characters in them which php deems to be in a wrong encoding;
1906 previously those messages would just disappear (this is visible e.g. in the debugger)
1908 * changed: debug info handling
1909 - at debug level 1, the rebuilt php objects are not dumped to screen (server-side already did that)
1910 - at debug level 1, curl communication info are not dumped to screen
1911 - at debug level 1, the tests echo payloads of failures; at debug level 2 all payloads
1913 * improved: makefiles have been replaced with a php_based pakefile
1915 * improved: the source for the manual is stored in asciidoc format, which can be displayed natively by GitHub
1916 with nice html formatting. Also the HTML version generated by hand and bundled in tarballs is much nicer
1917 to look at than previous versions
1919 * improved: all php code is now formatted according to the PSR-2 standard
1923 __Note:__ this is the last release of the library that will support PHP 5.1 and up. Future releases will target php 5.3
1924 as minimum supported version.
1926 * when using curl and keepalive, reset curl handle if we did not get back an http 200 response (eg a 302)
1928 * omit port on http 'Host' header if it is 80
1930 * test suite allows interrogating https servers ignoring their certs
1932 * method `setAcceptedCompression` was failing to disable reception of compressed responses if the client supported them
1936 This is the first release of the library to only support PHP 5. Some legacy code has been removed, and support for
1937 features such as exceptions and dateTime objects introduced.
1939 The "beta" tag is meant to indicate the fact that the refactoring has been more widespread than in precedent releases
1940 and that more changes are likely to be introduced with time - the library is still considered to be production
1943 * improved: removed all usage of php functions deprecated in php 5.3, usage of assign-by-ref when creating new objects
1946 * improved: add support for the `<ex:nil>` tag used by the apache library, both in input and output
1948 * improved: add support for dateTime objects in both in php_xmlrpc_encode and as parameter for constructor of xmlrpcval
1950 * improved: add support for timestamps as parameter for constructor of xmlrpcval
1952 * improved: add option `dates_as_objects` to `php_xmlrpc_decode` to return dateTime objects for xmlrpc datetimes
1954 * improved: add new method `SetCurlOptions` to xmrlpc_client to allow extra flexibility in tweaking http config, such as
1955 explicitly binding to an ip address
1957 * improved: add new method `SetUserAgent` to xmrlpc_client to to allow having different user-agent http headers
1959 * improved: add a new member variable in server class to allow fine-tuning of the encoding of returned values when the
1960 server is in 'phpvals' mode
1962 * improved: allow servers in 'xmlrpcvals' mode to also register plain php functions by defining them in the dispatch map
1963 with an added option
1965 * improved: catch exceptions thrown during execution of php functions exposed as methods by the server
1967 * fixed: bad encoding if same object is encoded twice using `php_xmlrpc_encode`
1971 __Note:__ this is the last release of the library that will support PHP 4. Future releases (if any) should target
1972 php 5.0 as minimum supported version.
1974 * fixed: encoding of utf-8 characters outside of the BMP plane
1976 * fixed: character set declarations surrounded by double quotes were not recognized in http headers
1978 * fixed: be more tolerant in detection of charset in http headers
1980 * fixed: fix detection of zlib.output_compression
1982 * fixed: use `feof()` to test if socket connections are to be closed instead of the number of bytes read (rare bug when
1983 communicating with some servers)
1985 * fixed: format floating point values using the correct decimal separator even when php locale is set to one that uses
1988 * fixed: improve robustness of the debugger when parsing weird results from non-compliant servers
1990 * php warning when receiving `false` in a bool value
1992 * improved: allow the add_to_map server method to add docs for single params too
1994 * improved: added the possibility to wrap for exposure as xmlrpc methods plain php class methods, object methods and even
1999 * fixed: work aroung bug in php 5.2.2 which broke support of `HTTP_RAW_POST_DATA`
2001 * fixed: is_dir parameter of `setCaCertificate()` method is reversed
2003 * fixed: a php warning in xmlrpc_client creator method
2005 * fixed: parsing of `1e+1` as valid float
2007 * fixed: allow errorlevel 3 to work when prev. error handler was a static method
2009 * fixed: usage of `client::setcookie()` for multiple cookies in non-ssl mode
2011 * improved: support for CP1252 charset is not part or the library but almost possible
2013 * improved: more info when curl is enabled and debug mode is on
2017 * fixed: debugger errors on php installs with `magic_quotes_gpc` on
2019 * fixed: support for https connections via proxy
2021 * fixed: `wrap_xmlrpc_method()` generated code failed to properly encode php objects
2023 * improved: slightly faster encoding of data which is internally UTF-8
2025 * improved: debugger always generates a `null` id for jsonrpc if user omits it
2027 * new: debugger can take advantage of a graphical value builder (it has to be downloaded separately, as part of jsxmlrpc
2028 package. See Appendix D for more details)
2030 * new: support for the `<NIL/>` xmlrpc extension. see below for more details
2032 * new: server support for the `system.getCapabilities` xmlrpc extension
2034 * new: `wrap_xmlrpc_method`, `wrap_xmlrpc_method()` accepts two new options: debug and return_on_fault
2038 * The wrap_php_function and wrap_xmlrpc_method functions have been moved out of the base library file _xmlrpc.inc_
2039 into a file of their own: _xmlrpc_wrappers.php_. You will have to include() / require() it in your scripts if
2040 you have been using those functions.
2041 For increased security, the automatic rebuilding of php object instances out ofreceived xmlrpc structs in
2042 `wrap_xmlrpc_method()` has been disabled (but it can be optionally re-enabled).
2043 Both `wrap_php_function()` and `wrap_xmlrpc_method()` functions accept many more options to fine tune their behaviour,
2044 including one to return the php code to be saved and later used as standalone php script
2046 * The constructor of xmlrpcval() values has seen some internal changes, and it will not throw a php warning anymore when
2047 invoked using an unknown xmlrpc type: the error will only be written to php error log. Also
2048 `new xmlrpcval('true', 'boolean')` is not supported anymore
2050 * The new function `php_xmlrpc_decode_xml()` will take the xml representation of either an xmlrpc request, response or
2051 single value and return the corresponding php-xmlrpc object instance
2053 * A new function `wrap_xmlrpc_server()` has been added, to wrap all (or some) of the methods exposed by a remote xmlrpc
2054 server into a php class
2056 * A new file has been added: _verify_compat.php_, to help users diagnose the level of compliance of their php
2057 installation with the library
2059 * Restored compatibility with php 4.0.5 (for those poor souls still stuck on it)
2061 * Method `xmlrpc_server->service()` now returns a value: either the response payload or xmlrpcresp object instance
2063 * Method `xmlrpc_server->add_to_map()` now accepts xmlrpc methods with no param definitions
2065 * Documentation for single parameters of exposed methods can be added to the dispatch map (and turned into html docs in
2066 conjunction with a future release of the 'extras' package)
2068 * Full response payload is saved into xmlrpcresp object for further debugging
2070 * The debugger can now generate code that wraps a remote method into a php function (works for jsonrpc, too); it also
2071 has better support for being activated via a single GET call (e.g. for integration into other tools)
2073 * Stricter parsing of incoming xmlrpc messages: two more invalid cases are now detected (double `data` element inside
2074 `array` and `struct`/`array` after scalar inside `value` element)
2076 * More logging of errors in a lot of situations
2078 * Javadoc documentation of lib files (almost) complete
2080 * Many performance tweaks and code cleanups, plus the usual crop of bugs fixed (see NEWS file for complete list of bugs)
2082 * Lib internals have been modified to provide better support for grafting extra functionality on top of it. Stay tuned
2083 for future releases of the EXTRAS package (or go read Appendix B)...
2087 * Added to the client class the possibility to use Digest and NTLM authentication methods (when using the CURL library)
2088 for connecting to servers and NTLM for connecting to proxies
2090 * Added to the client class the possibility to specify alternate certificate files/directories for authenticating the
2091 peer with when using HTTPS communication
2093 * Reviewed all examples and added a new demo file, containing a proxy to forward xmlrpc requests to other servers
2094 (useful e.g. for ajax coding)
2096 * The debugger has been upgraded to reflect the new client capabilities
2098 * All known bugs have been squashed, and the lib is more tolerant than ever of commonly-found mistakes
2100 === 2.0 Release candidate 3
2102 * Added to server class the property functions_parameters_type, that allows the server to register plain php functions
2103 as xmlrpc methods (i.e. functions that do not take an xmlrpcmsg object as unique param)
2105 * let server and client objects serialize calls using a specified character set encoding for the produced xml instead of
2106 US-ASCII (ISO-8859-1 and UTF-8 supported)
2108 * let `php_xmlrpc_decode` accept xmlrpcmsg objects as valid input
2110 * 'class::method' syntax is now accepted in the server dispatch map
2112 * `xmlrpc_clent::SetDebug()` accepts integer values instead of a boolean value, with debugging level 2 adding to the
2113 information printed to screen the complete client request
2115 === 2.0 Release candidate 2
2117 * Added a new property of the client object: `xmlrpc_client->return_type`, indicating whether calls to the
2118 send() method will return xmlrpcresp objects whose value() is an xmlrpcval object, a php value (automatically
2119 decoded) or the raw xml received from the server.
2121 * Added in the extras dir. two new library files: _jsonrpc.inc_ and _jsonrpcs.inc_ containing new classes that
2122 implement support for the json-rpc protocol (alpha quality code)
2124 * Added a new client method: `setKey($key, $keypass)` to be used in HTTPS connections
2126 * Added a new file containing some benchmarks in the testsuite directory
2128 === 2.0 Release candidate 1
2130 * Support for HTTP proxies (new method: `xmlrpc_client::setProxy()`)
2132 * Support HTTP compression of both requests and responses.
2133 Clients can specify what kind of compression they accept for responses between deflate/gzip/any, and whether to
2134 compress the requests.
2135 Servers by default compress responses to clients that explicitly declare support for compression (new methods:
2136 `xmlrpc_client::setAcceptedCompression()`, `xmlrpc_client::setRequestCompression()`).
2137 Note that the ZLIB php extension needs to be enabled in PHP to support compression.
2139 * Implement HTTP 1.1 connections, but only if CURL is enabled (added an extra parameter to
2140 `xmlrpc_client::xmlrpc_client` to set the desired HTTP protocol at creation time and a new supported value for
2141 the last parameter of `xmlrpc_client::send`, which now can be safely omitted if it has been specified at
2144 With PHP versions greater than 4.3.8 keep-alives are enabled by default for HTTP 1.1 connections. This should yield
2145 faster execution times when making multiple calls in sequence to the same xml-rpc server from a single client.
2147 * Introduce support for cookies.
2148 Cookies to be sent to the server with a request can be set using `xmlrpc_client::setCookie()`, while cookies
2149 received from the server are found in ++xmlrpcresp::cookies()++. It is left to the user to check for validity of
2150 received cookies and decide whether they apply to successive calls or not.
2152 * Better support for detecting different character set encodings of xml-rpc requests and responses: both client and
2153 server objects will correctly detect the charset encoding of received xml, and use an appropriate xml parser.
2155 Supported encodings are US-ASCII, UTF-8 and ISO-8859-1.
2157 * Added one new xmlrpcmsg constructor syntax, allowing usage of a single string with the complete URL of the target
2160 * Convert xml-rpc boolean values into native php values instead of 0 and 1
2162 * Force the `php_xmlrpc_encode` function to properly encode numerically indexed php arrays into xml-rpc arrays
2163 (numerically indexed php arrays always start with a key of 0 and increment keys by values of 1)
2165 * Prevent the `php_xmlrpc_encode` function from further re-encoding any objects of class ++xmlrpcval++ that
2166 are passed to it. This allows to call the function with arguments consisting of mixed php values / xmlrpcval objects
2168 * Allow a server to NOT respond to system.* method calls (setting the `$server->allow_system_funcs` property).
2170 * Implement a new xmlrpcval method to determine if a value of type struct has a member of a given name without having to
2171 loop trough all members: `xmlrpcval::structMemExists()`
2173 * Expand methods `xmlrpcval::addArray`, `addScalar` and `addStruct` allowing extra php values to be added to
2174 xmlrpcval objects already formed.
2176 * Let the `xmlrpc_client::send` method accept an XML string for sending instead of an xmlrpcmsg object, to
2177 facilitate debugging and integration with the php native xmlrpc extension
2179 * Extend the `php_xmlrpc_encode` and `php_xmlrpc_decode` functions to allow serialization and rebuilding of
2180 PHP objects. To successfully rebuild a serialized object, the object class must be defined in the deserializing end
2181 of the transfer. Note that object members of type resource will be deserialized as NULL values.
2183 Note that his has been implemented adding a "php_class" attribute to xml representation of xmlrpcval of STRUCT type,
2184 which, strictly speaking, breaks the xml-rpc spec. Other xmlrpc implementations are supposed to ignore such an
2185 attribute (unless they implement a brain-dead custom xml parser...), so it should be safe enabling it in
2186 heterogeneous environments. The activation of this feature is done by usage of an option passed as second parameter
2187 to both `php_xmlrpc_encode` and `php_xmlrpc_decode`.
2189 * Extend the `php_xmlrpc_encode` function to allow automatic serialization of iso8601-conforming php strings as
2190 datetime.iso8601 xmlrpcvals, by usage of an optional parameter
2192 * Added an automatic stub code generator for converting xmlrpc methods to php functions and vice-versa.
2194 This is done via two new functions: `wrap_php_function` and `wrap_xmlrpc_method`, and has many caveats,
2195 with php being a typeless language and all...
2197 * Allow object methods to be used in server dispatch map
2199 * Added a complete debugger solution, in the __debugger__ folder
2201 * Added configurable server-side debug messages, controlled by the new method `xmlrpc_server::SetDebug()`.
2202 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
2203 more info is echoed back to the client, regarding the received call; at level 3 all warnings raised during server
2204 processing are trapped (this prevents breaking the xml to be echoed back to the client) and added to the debug info
2205 sent back to the client
2207 * New XML parsing code, yields smaller memory footprint and faster execution times, not to mention complete elimination
2208 of the dreaded __eval()__ construct, so prone to code injection exploits
2210 * Rewritten most of the error messages, making text more explicative
2212 ++++++++++++++++++++++++++++++++++++++
2213 <!-- Keep this comment at the end of the file
2218 sgml-minimize-attributes:nil
2219 sgml-always-quote-attributes:t
2222 sgml-parent-document:nil
2223 sgml-exposed-tags:nil
2224 sgml-local-catalogs:nil
2225 sgml-local-ecat-files:nil
2226 sgml-namecase-general:t
2227 sgml-general-insert-case:lower
2230 ++++++++++++++++++++++++++++++++++++++