From f140ea8aba41c3628c0e5e729d072729d3353558 Mon Sep 17 00:00:00 2001 From: gggeek Date: Wed, 29 Apr 2015 00:20:41 +0100 Subject: [PATCH] Move to asciidoc as principal documentation format --- doc/manual/css-docbook/COPYING | 17 - doc/manual/css-docbook/CREDITS | 10 - doc/manual/css-docbook/core.css | 70 - doc/manual/css-docbook/db-bindings.xml | 31 - doc/manual/css-docbook/driver.css | 31 - doc/manual/css-docbook/l10n.css | 24 - doc/manual/css-docbook/l10n/de.css | 37 - doc/manual/css-docbook/l10n/en.css | 48 - doc/manual/css-docbook/l10n/es.css | 39 - doc/manual/css-docbook/l10n/pl.css | 44 - doc/manual/css-docbook/mozilla.css | 44 - doc/manual/css-docbook/opera.css | 33 - doc/manual/css-docbook/styles.css | 641 ---- doc/manual/css-docbook/tables.css | 59 - doc/manual/css-docbook/xmlrpc.css | 42 - doc/manual/phpxmlrpc_manual.adoc | 3117 +++++++++++++++++ doc/manual/phpxmlrpc_manual.xml | 4274 ------------------------ pakefile.php | 49 +- 18 files changed, 3148 insertions(+), 5462 deletions(-) delete mode 100644 doc/manual/css-docbook/COPYING delete mode 100644 doc/manual/css-docbook/CREDITS delete mode 100644 doc/manual/css-docbook/core.css delete mode 100644 doc/manual/css-docbook/db-bindings.xml delete mode 100644 doc/manual/css-docbook/driver.css delete mode 100644 doc/manual/css-docbook/l10n.css delete mode 100644 doc/manual/css-docbook/l10n/de.css delete mode 100644 doc/manual/css-docbook/l10n/en.css delete mode 100644 doc/manual/css-docbook/l10n/es.css delete mode 100644 doc/manual/css-docbook/l10n/pl.css delete mode 100644 doc/manual/css-docbook/mozilla.css delete mode 100644 doc/manual/css-docbook/opera.css delete mode 100644 doc/manual/css-docbook/styles.css delete mode 100644 doc/manual/css-docbook/tables.css delete mode 100644 doc/manual/css-docbook/xmlrpc.css create mode 100644 doc/manual/phpxmlrpc_manual.adoc delete mode 100644 doc/manual/phpxmlrpc_manual.xml diff --git a/doc/manual/css-docbook/COPYING b/doc/manual/css-docbook/COPYING deleted file mode 100644 index 735dca1..0000000 --- a/doc/manual/css-docbook/COPYING +++ /dev/null @@ -1,17 +0,0 @@ -Copyright (c) 2004 David Holroyd, and contributors. - -Permission to use, copy, modify and distribute this software and its -documentation for any purpose and without fee is hereby granted in -perpetuity, provided that the above copyright notice appear in all -copies, and that both the copyright notice and this permission notice -appear in supporting documentation. The contributors make no -representations about the suitability of this software for any -purpose. It is provided "as is" without express or implied warranty. - -THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS -SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND -FITNESS. IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY -SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER -RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF -CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN -CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. diff --git a/doc/manual/css-docbook/CREDITS b/doc/manual/css-docbook/CREDITS deleted file mode 100644 index cbc51ee..0000000 --- a/doc/manual/css-docbook/CREDITS +++ /dev/null @@ -1,10 +0,0 @@ -This stylesheet was writen by David Holroyd, with patches, suggestions, -translations, and other help from these people: - - David Leppik - Martin Gautier - Asia Magiera - Federico Koessler - Katie McSweenie - -Many thanks to all of them! diff --git a/doc/manual/css-docbook/core.css b/doc/manual/css-docbook/core.css deleted file mode 100644 index d9d4ba0..0000000 --- a/doc/manual/css-docbook/core.css +++ /dev/null @@ -1,70 +0,0 @@ -/* - * core.css - * - * Copyright (c) 2004 David Holroyd, and contributors - * See the file 'COPYING' for terms of use - * - * Part of the Docbook-CSS stylesheet - * http://www.badgers-in-foil.co.uk/projects/docbook-css/ - */ - -/* Generated 2002-12-12 */ -abbrev, accel, acronym, action, application, artpagenums, authorinitials, -bibliocoverage, biblioid, bibliomisc, bibliorelation, bibliosource, citation, -citebiblioid, citerefentry, citetitle, city, classname, co, command, -computeroutput, constant, coref, country, database, date, email, emphasis, -envar, errorcode, errorname, errortext, errortype, exceptionname, fax, -filename, firstname, firstterm, funcdef, funcparams, function, group, -guibutton, guiicon, guilabel, guimenu, guimenuitem, guisubmenu, hardware, -honorific, initializer, inlineequation, inlinegraphic, inlinemediaobject, -interface, interfacename, invpartnumber, isbn, issn, keycap, keycode, -keycombo, keysym, lineage, lineannotation, link, literal, markup, medialabel, -member, menuchoice, methodname, methodparam, modifier, mousebutton, olink, -ooclass, ooexception, oointerface, option, optional, orgdiv, orgname, -otheraddr, othername, pagenums, paramdef, parameter, phone, phrase, pob, -postcode, productname, productnumber, prompt, property, pubdate, pubsnumber, -quote, refpurpose, replaceable, returnvalue, revnumber, seriesvolnums, -sgmltag, shortcut, state, street, structfield, structname, subscript, -superscript, surname, symbol, systemitem, token, trademark, type, ulink, -userinput, varname, volumenum, wordasword, year { - display:inline; -} - -abstract, ackno, address, answer, appendix, article, attribution, authorblurb, -bibliodiv, biblioentry, bibliography, bibliomixed, bibliomset, biblioset, -blockquote, book, callout, calloutlist, caption, caution, chapter, -cmdsynopsis, colophon, constraintdef, dedication, epigraph, equation, example, -figure, formalpara, glossary, glossdef, glossdiv, glossentry, glosslist, -graphic, graphicco, highlights, imagedata, imageobjectco, important, index, -indexdiv, indexentry, informalequation, informalexample, informalfigure, -informaltable, itemizedlist, legalnotice, listitem, lot, lotentry, -mediaobject, mediaobjectco, msg, msgentry, msgexplan, msgmain, msgset, note, -orderedlist, para, part, partintro, personblurb, preface, primaryie, -printhistory, procedure, productionset, programlistingco, qandadiv, qandaentry, -qandaset, question, refentry, refentrytitle, reference, refnamediv, refsect1, -refsect2, refsect3, refsection, refsynopsisdiv, revhistory, screenco, -screenshot, secondaryie, sect2, sect3, sect4, sect5, section, seealsoie, seeie, -set, setindex, sidebar, simpara, simplemsgentry, simplesect, step, substeps, -subtitle, synopfragment, synopfragmentref, table, term, tertiaryie, tip, -title, toc, tocback, tocchap, tocentry, tocfront, toclevel1, toclevel2, -toclevel3, toclevel4, toclevel5, tocpart, variablelist, varlistentry, warning, -sect1 { - display:block; -} - -appendixinfo, area, areaset, areaspec, articleinfo, bibliographyinfo, -blockinfo, bookinfo, chapterinfo, colspec, glossaryinfo, indexinfo, indexterm, -itermset, modespec, objectinfo, partinfo, prefaceinfo, primary, refentryinfo, -referenceinfo, refmeta, refsect1info, refsect2info, refsect3info, -refsectioninfo, refsynopsisdivinfo, screeninfo, secondary, sect1info, -sect2info, sect3info, sect4info, sect5info, sectioninfo, see, seealso, -setindexinfo, setinfo, sidebarinfo, spanspec, tertiary { - display:none; -} - -classsynopsisinfo, funcsynopsisinfo, literallayout, programlisting, screen, -synopsis { - white-space:pre; - font-family:monospace; - display:block; -} diff --git a/doc/manual/css-docbook/db-bindings.xml b/doc/manual/css-docbook/db-bindings.xml deleted file mode 100644 index f3c0059..0000000 --- a/doc/manual/css-docbook/db-bindings.xml +++ /dev/null @@ -1,31 +0,0 @@ - - - - - - - - - - - - - - - - - - var img = document.getAnonymousNodes(this)[0]; - var file = this.getAttribute("fileref"); - // HACK: using img.src=file 'inline' doesn't seem to work - // but it does when called from a setTimeout() - var f = function() { img.src = file; } - setTimeout(f, 0); - - - - diff --git a/doc/manual/css-docbook/driver.css b/doc/manual/css-docbook/driver.css deleted file mode 100644 index 1e7a2de..0000000 --- a/doc/manual/css-docbook/driver.css +++ /dev/null @@ -1,31 +0,0 @@ -/* - * driver.css - * - * Copyright (c) 2004 David Holroyd, and contributors - * See the file 'COPYING' for terms of use - * - * Part of the Docbook-CSS stylesheet - * http://www.badgers-in-foil.co.uk/projects/docbook-css/ - * - * This is the 'driver' file of the stylesheet. It imports all the major - * stylesheet components. If you want to make use of this stylesheet in your - * XML document (e.g. for display in a web browser), include a line like this - * at the top of the XML file (replacing with the version number): - * - * /driver.css" type="text/css"?> - * - * If you want to customise the stylesheet, a customisation layer can be - * created by simply witing a new CSS file, and including a declaration to - * import this file at the top. The customisation layer can then override any - * of the existing stylesheet rules, or create new ones. - */ - -/* add xmlrpc css customizations... */ -@import "xmlrpc.css"; - -@import "core.css"; -@import "tables.css"; -@import "styles.css"; -@import "l10n.css"; -@import "mozilla.css"; -@import "opera.css"; diff --git a/doc/manual/css-docbook/l10n.css b/doc/manual/css-docbook/l10n.css deleted file mode 100644 index caeaa03..0000000 --- a/doc/manual/css-docbook/l10n.css +++ /dev/null @@ -1,24 +0,0 @@ -/* - * i10n.css - * - * Copyright (c) 2004 David Holroyd, and contributors - * See the file 'COPYING' for terms of use - * - * Part of the Docbook-CSS stylesheet - * http://www.badgers-in-foil.co.uk/projects/docbook-css/ - * - * This file deals with localisation ('l10n') of CSS generated content by - * delegating to each of the locale-specific files in the l10n directory. - */ - - -/* - * 'en' doesn't specify 'lang()' selectors, so its settings will be the - * default where no localisation is available for a particular language. - * It must come first; other lauguages override it. - */ -@import "l10n/en.css"; - -@import "l10n/pl.css"; -@import "l10n/de.css"; -@import "l10n/es.css"; diff --git a/doc/manual/css-docbook/l10n/de.css b/doc/manual/css-docbook/l10n/de.css deleted file mode 100644 index 261be58..0000000 --- a/doc/manual/css-docbook/l10n/de.css +++ /dev/null @@ -1,37 +0,0 @@ -@charset "utf-8"; -/* - * l10n/de.css - * - * Copyright (c) 2004 David Holroyd, and contributors - * See the file 'COPYING' for terms of use - * - * Part of the Docbook-CSS stylesheet - * http://www.badgers-in-foil.co.uk/projects/docbook-css/ - */ - -question:lang(de):before { - content: "F: "; -} -answer:lang(de):before { - content: "A: "; -} - -example > title:lang(de):before { - content: "Beispiel: "; -} - -warning:lang(de):before { - content: "Warnung: "; -} -caution:lang(de):before { - content: "Achtung: "; -} -important:lang(de):before { - content: "Wichtig: "; -} -tip:lang(de):before { - content: "Hinweis: "; -} -note:lang(de):before { - content: "Erläuterung: "; -} diff --git a/doc/manual/css-docbook/l10n/en.css b/doc/manual/css-docbook/l10n/en.css deleted file mode 100644 index 497e5f5..0000000 --- a/doc/manual/css-docbook/l10n/en.css +++ /dev/null @@ -1,48 +0,0 @@ -@charset "utf-8"; -/* - * l10n/en.css - * - * Copyright (c) 2004 David Holroyd, and contributors - * See the file 'COPYING' for terms of use - * - * Part of the Docbook-CSS stylesheet - * http://www.badgers-in-foil.co.uk/projects/docbook-css/ - */ - -/* Generated content for English documents */ - -question:before { - content: "Q: "; -} -answer:before { - content: "A: "; -} - -example > title:before { - content: "Example: "; -} - -quote { - quotes: "“" "”"; -} -quote quote { - quotes: "‘" "’"; -} - -/* Admonitions */ - -warning:before { - content: "Warning: "; -} -caution:before { - content: "Caution: "; -} -important:before { - content: "Important: "; -} -tip:before { - content: "Tip: "; -} -note:before { - content: "Note: "; -} diff --git a/doc/manual/css-docbook/l10n/es.css b/doc/manual/css-docbook/l10n/es.css deleted file mode 100644 index 9b435fd..0000000 --- a/doc/manual/css-docbook/l10n/es.css +++ /dev/null @@ -1,39 +0,0 @@ -@charset "utf-8"; -/* - * l10n/es.css - * - * Copyright (c) 2004 David Holroyd, and contributors - * See the file 'COPYING' for terms of use - * - * Part of the Docbook-CSS stylesheet - * http://www.badgers-in-foil.co.uk/projects/docbook-css/ - */ - -question:lang(es):before { - content: "P: "; -} -answer:lang(es):before { - content: "R: "; -} - -example > title:lang(es):before { - content: "Ejemplo: "; -} - - -warning:lang(es):before { - content: "Aviso: "; -} -caution:lang(es):before { - content: "Atención: "; -} -important:lang(es):before { - content: "Importante: "; -} -tip:lang(es):before { - content: "Consejo: "; -} -note:lang(es):before { - content: "Nota: "; -} - diff --git a/doc/manual/css-docbook/l10n/pl.css b/doc/manual/css-docbook/l10n/pl.css deleted file mode 100644 index 7e3504f..0000000 --- a/doc/manual/css-docbook/l10n/pl.css +++ /dev/null @@ -1,44 +0,0 @@ -@charset "utf-8"; -/* - * l10n/pl.css - * - * Copyright (c) 2004 David Holroyd, and contributors - * See the file 'COPYING' for terms of use - * - * Part of the Docbook-CSS stylesheet - * http://www.badgers-in-foil.co.uk/projects/docbook-css/ - */ - -question:lang(pl):before { - content: "P: "; -} -answer:lang(pl):before { - content: "O: "; -} - -example > title:lang(pl):before { - content: "Przykład: "; -} - -:lang(pl) > quote { - quotes: "„" "”"; -} -:lang(pl) > quote quote { - quotes: "«" "»"; -} - -warning:lang(pl):before { - content: "Ostrzeżenie: "; -} -caution:lang(pl):before { - content: "Uwaga: "; -} -important:lang(pl):before { - content: "Ważne: "; -} -tip:lang(pl):before { - content: "Pomoc: "; -} -note:lang(pl):before { - content: "Notatka: "; -} diff --git a/doc/manual/css-docbook/mozilla.css b/doc/manual/css-docbook/mozilla.css deleted file mode 100644 index 4f15519..0000000 --- a/doc/manual/css-docbook/mozilla.css +++ /dev/null @@ -1,44 +0,0 @@ -/* - * mozilla.css - * - * Copyright (c) 2004 David Holroyd, and contributors - * See the file 'COPYING' for terms of use - * - * Part of the Docbook-CSS stylesheet - * http://www.badgers-in-foil.co.uk/projects/docbook-css/ - * - * This file contains CSS specific to mozilla.org's Gecko rendering engine. - * - * Some of the rules here will take effect even if you aren't using a Mozilla- - * based browser. - */ - - -/* make s clickable */ -ulink { - -moz-binding:url('db-bindings.xml#ulink'); - cursor: pointer; - -moz-user-focus: normal; -} - -ulink:active { - color: red; -} - -ulink:focus { - -moz-outline: 1px dotted invert; -} - -imagedata { - -moz-binding:url('db-bindings.xml#image'); -} - - -guimenu, guimenuitem, guisubmenu { - font: menu; -} - -orderedlist, itemizedlist, procedure { - /* this seems to be required to make auto-numbering work */ - -moz-counter-reset: -html-counter 0; -} diff --git a/doc/manual/css-docbook/opera.css b/doc/manual/css-docbook/opera.css deleted file mode 100644 index a00a7c2..0000000 --- a/doc/manual/css-docbook/opera.css +++ /dev/null @@ -1,33 +0,0 @@ -/* - * opera.css - * - * Copyright (c) 2004 David Holroyd, and contributors - * See the file 'COPYING' for terms of use - * - * Part of the Docbook-CSS stylesheet - * http://www.badgers-in-foil.co.uk/projects/docbook-css/ - * - * This file contains CSS specific to the Opera browser. - */ - -/* - * Discovered -o-link from, - * http://groups.google.com/groups?q=opera+styles+xml&start=10&hl=en&lr=&ie=UTF-8&newwindow=1&selm=opr6pgr0tgicz8n2%40news.opera.com&rnum=18 - */ -ulink { - -o-link: attr(url); - -o-link-source: current; -} - -/* - * Given the above rule, it makes sense to have this here too, though it's - * not Opera-specific - */ -ulink:focus { - outline: 1px dotted invert; -} - -/* this was in the example I found, but it doesn't achive much */ -imagedata { - -o-replace: attr(fileref) -} diff --git a/doc/manual/css-docbook/styles.css b/doc/manual/css-docbook/styles.css deleted file mode 100644 index fae29b7..0000000 --- a/doc/manual/css-docbook/styles.css +++ /dev/null @@ -1,641 +0,0 @@ -/* - * styles.css - * - * Copyright (c) 2004 David Holroyd, and contributors - * See the file 'COPYING' for terms of use - * - * Part of the Docbook-CSS stylesheet - * http://www.badgers-in-foil.co.uk/projects/docbook-css/ - */ - -/* - * CSS2 styling for DocBook XML - * - * To be included in the cascade _after_ core.css. Defines styling that can't - * be generated mechanically from another source. - */ - -/* - * TODO: - * - * - do I remember correctly that be hidden for screen media? - */ - - -article, book { - margin:.5em; -} -title, subtitle { - font-family:sans-serif; -} -title { - font-weight:bolder; - margin-bottom:.5em; -} - -/* - * Sectioning elements that may contain paragraph-level elements get left/right - * margins - */ -section>*, chapter>*, bibliography>*, appendix>*, glossary>*, preface>*, -dedication>*, colophon>*, sect1>*, sect2>*, sect3>*, sect4>*, sect5>*, -bibliodiv>* { - margin-left:10%; - margin-right:10%; -} - -/* - * Give admonitions bigger margins, to set them more apart from the main - * flow of text. - */ -warning, caution, important, tip, note { - margin-left: 15%; - margin-right: 15%; -} - -/* - * Remove any margin defined be the previous rule when the child in question - * is a section or title. Titles should be allowed to take up the maximum - * available width, as they're usually is larger type. Sections must not - * be given margins because, the *contents* of the section will alreay have - * them; we don't want to recursively increase margins with the nesting depth - * of the document. - */ -section, title, sect1, sect2, sect3, sect4, sect5, bibliodiv { - margin-left:0; - margin-right:0; -} - -book>title, article>title { - font-size:xx-large; - text-align:center; - border-bottom-style:solid; -} - -appendix>title, bibliography>title, chapter>title, colophon>title, dedication>title, glossary>title, part>title, preface>title { - font-size:xx-large; - text-align:center; -} - -section>title, sect1>title, bibliodiv>title { - font-size:xx-large; -} - -section>section>title, sect2>title { - font-size:x-large; - margin-left:5%; -} - -section>section>section>title, sect3>title { - font-size:large; - margin-left:7.5%; -} - -section>section>section>section>title, sect4>title { - font-size:large; - margin-left:10%; -} - -section>section>section>section>section>title, sect5>title { - font-size:inherit; - margin-left:10%; -} - -biblioentry > title { - display: inline; -} - -/* Give vertical spacing between compoments of the document */ - -*+section, *+chapter, *+bibliography, *+bibliodiv, *+appendix, *+glossary { - margin-top: 3em; -} -section>*+section { - margin-top: 2em; -} -section>section>*+section { - margin-top: 1em; -} - - -/* - * Give paragraph-level elements some leading space when they aren't the first - * item in their containing block. - */ -*+para, *+formalpara, *+blockquote, *+glossentry, *+table, *+variablelist, -*+example, *+informalexample, *+programlisting, *+cmdsynopsis, -*+orderedlist, *+itemizedlist, *+figure, -*>warning, *>caution, *>important, *>tip, *>note { - margin-top:.5em; -} - - -/* - * BiblioEntry blocks need a bit more space, since they may contain multiple - * paragraphs, and so need greater-than-paragraph spacing to make it clear - * which gap is the end just of a paragraph, and which gap is the end of the - * entry - */ -*+biblioentry { - margin-top: 1em; -} - -/* - * REVISIT: I think this is the proper way; but deson't work in Firefox 0.8 - -formalpara > title { - display: run-in; -} - - * Make all children of formalpara inline, instead... - */ - -formalpara > * { - display: inline; -} - -formalpara > title:after { - content: "."; -} - -para, formalpara { - text-align: justify; -} - -quote:before { - content: open-quote; -} - -quote:after { - content: close-quote; -} - -question, answer { - margin-top:.5em; - display:list-item; -} - -question>para, answer>para { - display:inline; -} - -/* see language specific files for content */ -question:before { - display:marker; - font-weight:bolder; -} -answer:before { - display:marker; - font-weight: bolder; -} - -emphasis { - font-style:italic; -} -emphasis[role="strong"] { - font-weight:bolder; -} -emphasis[role="bold"] { - font-weight:bolder; - font-style:inherit; -} -emphasis[role="underline"] { - text-decoration:underline; - font-style:inherit; -} -emphasis[role="strikethrough"] { - text-decoration:line-through; - font-style:inherit; -} -emphasis>emphasis { - font-weight:bolder; -} - -foreignphrase, wordasword, productname { - font-style:italic; -} - -replaceable { - font-style:italic; -} - -sgmltag[class="starttag"]:before, sgmltag[class="emptytag"]:before { - content: "<"; -} - -sgmltag[class="starttag"]:after, sgmltag[class="endtag"]:after { - content: ">"; -} - -sgmltag[class="endtag"]:before { - content: ""; -} - -sgmltag[class="attvalue"]:before, sgmltag[class="attvalue"]:after { - content: '"'; -} - -sgmltag[class="genentity"]:before { - content: "&"; -} -sgmltag[class="genentity"]:after { - content: ";"; -} - -sgmltag[class="sgmlcomment"]:before { - content: ""; -} - -sgmltag[class="xmlpi"]:before { - content: ""; -} - - -application, keycap, guimenu, guimenuitem, guisubmenu { - font-family: sans-serif; -} - -/* - * ensure there's some whitespace between elements of an author's name - */ -author>* + *:before { - content: " "; -} - -/* give keycaps a '3D' shaded look */ -keycap { - padding-left: .2em; - padding-right: .2em; - border-style: solid; - border-top-width: 2px; - border-left-width: 3px; - border-right-width: 3px; - border-bottom-width: 4px; - border-top-color: #eeeecc; - border-left-color: #eeeecc; - border-right-color: #999977; - border-bottom-color: #999977; - background-color: #ddddbb; - /* All these borders may interfere with text on the line bellow. Make - the text a little smaller to try and 'pull up' the bottom edge, */ - font-size: smaller; -} - -keycombo>keycap+keycap:before { - /* FIXME: this appears inside the second keycap's 3D boarder, but - * ideally, we'd like it to appear inbetween the two keycaps */ - content: "-"; -} - -menuchoice>guimenu+guimenuitem:before, -menuchoice>guimenuitem+guimenuitem:before, -menuchoice>guimenuitem+guisubmenu:before { - /*content: "->";*/ - /* a 'proper' left-arrow character */ - content: "\2192"; -} - -guibutton { - border: 2px outset #dddddd; - background-color: #dddddd; -/* - border: 2px solid; - border-top-color: #eeeeee; - border-left-color: #eeeeee; - border-right-color: #999999; - border-bottom-color: #999999; - background-color: #dddddd; -*/} - - -/* render link-like elements per HTML's normal styling */ -link, ulink, email { - /* When ulink contains no body text, the url should be rendered - * at this point in the document. Can't see how to do this with CSS */ - color:#0000ff; - text-decoration:underline; -} - -/*ulink:after { - content: " <" attr(url) ">"; -}*/ - -email:before { - content: "<"; -} -email:after { - content: ">"; -} - -citation:before { - content: "["; -} -citation:after { - content: "]"; -} - -xref:after { - /* simple symbol - content: "#" attr(linkend);*/ - /* 'section' symbol */ - content: "\00a7" attr(linkend); - color:#0000ff; - text-decoration: underline; -} - -blockquote { - padding-left:3em; - padding-bottom: 1em; -} - -blockquote>attribution { - text-align:right; - font-style: italic; -} -blockquote>attribution:after { - /* I've tried various things to position the attribution after the - * other blockquote content (e.g. relative/absolute positioning), but - * none of the things I tried produced satisfactory results (e.g. the - * attribution appears at the bottom of the containing block, but it - * overlaps preceeding content). */ - content:":" -} -blockquote>para:before { - content: open-quote; -} -blockquote>para:after { - content: no-close-quote; -} -blockquote>para:last-child:after { - content: close-quote; -} - -/* lists */ - -itemizedlist { - padding-left: 1em; - list-style-type: disc; -} - -listitem+listitem { - padding-top: .5em; -} - -/* 2 deep nested lists */ -itemizedlist itemizedlist { - list-style-type: circle; -} - -/* 3 or more deep nested lists */ -itemizedlist itemizedlist itemizedlist { - list-style-type: square; -} - - -itemizedlist>listitem { - display:list-item; -} - -orderedlist { - padding-left: 1.5em; - list-style-type: decimal; -} - -orderedlist>listitem { - display:list-item; -} - -/* - * We've got no way of properly implementing call-out lists with CSS, so just - * present as a list of bullet points. - */ -calloutlist { - padding-left: 1em; - list-style-type: disc; -} -calloutlist>callout { - display:list-item; -} - - - -/* - * The list of possible mark names is not defined by Docbook, but "opencircle" - * and "bullet" are used in T.D.G. example - */ -itemizedlist[mark="opencircle"], listitem[override="opencircle"] { - list-style-type: circle; -} - -itemizedlist[mark="bullet"], listitem[override="bullet"] { - list-style-type: disc; -} - - -varlistentry>listitem { - margin-left: 2em; -} -varlistentry+varlistentry { - margin-top: .5em; -} - -simplelist[type=horiz] { - display: block; -} - -simplelist[type=inline]>member+member:before { - /* typically, we end up with unwanted whitespace before the comma - * (i.e. whitespace between elements). I see no way of - * suppressing this with CSS. - * TODO: try a combination of :after and :first-child instead to - * avoid the above issue */ - content: ", "; -} - -cmdsynopsis, code, command, computeroutput, envar, filename, keycode, keysym, -literal, option, parameter, sgmltag, systemitem { - font-family: monospace; -} - -filename[class=directory]:after { - content: "/"; -} - -/* TODO: Are these specific to 'en' locales or not? */ -trademark:after { - content: "\2122" -} -trademark[class="copyright"]:after { - content: "\A9" -} -trademark[class="registered"]:after { - content: "\AE" -} -trademark[class="service"]:after { - content: "\2120" -} - -example, informalexample, programlisting { - background-color:#dddddd; - padding: .5em; - border: 1px dashed black; -} - - -example programlisting, informalexample programlisting { - background-color: none; - padding: 0; - border: none; -} - -/* admonitions */ - -warning, caution, tip, note, important { - border: 1px dashed gray; - padding: .5em; -} - -/* Have admonition titles appear inline with generated content ("Note:" etc.) */ -warning>title, caution>title, tip>title, note>title, important>title { - display: inline; - -} - -warning:before, caution:before, tip:before, note:before, important:before { - /* Match the style of */ - font-weight: bolder; - font-family: sans-serif; -} - -/* FIXME: background colours are cheezy :S ... */ -/* see language specific css for content: */ -warning:before { - background-color: red; -} -caution:before { - background-color: yellow; -} -tip:before { - background-color: #aaaddd; -} -note:before { - background-color: #dddddd; -} -important:before { - background-color: plum; -} - -/* Tables */ - -thead > row > entry { - /* FIXME: will under-rule every row in the <thead>, not just the last - * (I tried adding this style to <thead> itself, but this doesn't - * appear to work in combination with display:table-header-group, as - * defined in tables.css) */ - border-bottom: 2px solid black; -} - -thead { - font-weight: bolder; -} - -entry { - padding: .2em; -} - - -/* Footnotes */ - - -/* - * Attempt to display footnotes on-mouseover. This may well break if a - * footnote element has multiple children (I think the children will end up - * stacked on top of each other). - */ - -footnote { - position: relative; - cursor: help; -} -footnote:hover { -} -footnote>* { - display: none; - z-index: 100; -} -footnote:hover>* { - display: block; - position: fixed; - border: 2px dotted black; - background-color: #ffeeaa; - padding: .5em; - left: 0px; - bottom: 0px; -} -footnote:before { - content: "?"; - background-color: #ffeeaa; - border: 2px dotted black; - font-size: smaller; -} - - -/* - -Attempting to format <footnote> as a sitebar, floating it to the right. -Sometimes works for footnotes in the 'main body' of some text, but works badly -when the containing block is, for instance, a table cell. - -footnote:before { - content: "*"; - display: block; - border: 2px dotted black; -} - -footnote>* { - display: block; - float: right; - border: 2px dotted black; - padding: .5em; - width: 25%; - top: -1em; -} - -footnote>*:before { - content: "*Footnote"; - display: block; - font-weight: bold; - font-family: sans-serif; -} -*/ - -glossentry>glossterm { - font-weight: bolder; - font-style: italic; -} - - -userinput { - font-weight: bolder; -} - -figure { - text-align: center; -} - -imageobject { - display: block; -} - -mediaobject>textobject { - font-size: smaller; -} diff --git a/doc/manual/css-docbook/tables.css b/doc/manual/css-docbook/tables.css deleted file mode 100644 index da148a3..0000000 --- a/doc/manual/css-docbook/tables.css +++ /dev/null @@ -1,59 +0,0 @@ -/* - * tables.css - * - * Copyright (c) 2004 David Holroyd, and contributors - * See the file 'COPYING' for terms of use - * - * Part of the Docbook-CSS stylesheet - * http://www.badgers-in-foil.co.uk/projects/docbook-css/ - * - */ - -tgroup { - display: table; -} - -row { - display: table-row; -} - -thead { - display: table-header-group; -} - -tbody { - display: table-row-group; -} - -entry, entrytbl { - display: table-cell; -} - -entry[valign=top] { - vertical-align: top; -} -entry[valign=bottom] { - vertical-align: bottom; -} - -/* - * CSS can't generate the indended formatting for segmented lists, so we turn - * them into tables instead. - * - * TODO: seems to break formatting when nested in a table entry - */ -segmentedlist { - display: table; -} - -seglistitem { - display: table-row; -} - -seg, segtitle { - display: table-cell; -} - -segmentedlist>title { - display: table-caption; -} diff --git a/doc/manual/css-docbook/xmlrpc.css b/doc/manual/css-docbook/xmlrpc.css deleted file mode 100644 index 08425ef..0000000 --- a/doc/manual/css-docbook/xmlrpc.css +++ /dev/null @@ -1,42 +0,0 @@ -funcsynopsis>* { - margin-left:10%; - margin-right:10%; -} - -funcprototype { - display: block; - text-align: justify; - font-family:monospace; -} - -funcprototype:after { - content:");"; -} - -funcdef:after { - content:"("; -} - -paramdef type:after { - content:" "; -} - -funcdef function { - font-weight:bold; -} - -paramdef initializer:before -{ - content:" = "; -} - -paramdef:after -{ - content:","; -} - -/* remove the extra comma after the last paramdef of a funcprotoype */ -paramdef:last-child:after -{ - content:""; -} diff --git a/doc/manual/phpxmlrpc_manual.adoc b/doc/manual/phpxmlrpc_manual.adoc new file mode 100644 index 0000000..1480b40 --- /dev/null +++ b/doc/manual/phpxmlrpc_manual.adoc @@ -0,0 +1,3117 @@ += XML-RPC for PHP +:revision: 4.0.0 +:keywords: xml, rpc, xmlrpc, webservices, http +:toc: left +:imagesdir: images + +[preface] +== Introduction + +XML-RPC is a format devised by link:$$http://www.userland.com/$$[Userland Software] for achieving + remote procedure call via XML using HTTP as the transport. XML-RPC has its + own web site, link:$$http://www.xmlrpc.com/$$[www.xmlrpc.com] + +This collection of PHP classes provides a framework for writing + XML-RPC clients and servers in PHP. + +Main goals of the project are ease of use, flexibility and + completeness. + +The original author is Edd Dumbill of link:$$http://usefulinc.com/$$[Useful Information Company]. As of the + 1.0 stable release, the project was opened to wider involvement and moved + to link:$$http://phpxmlrpc.sourceforge.net/$$[SourceForge]; later, to link:$$https://github.com/gggeek/phpxmlrpc$$[Github] + +A list of XML-RPC implementations for other languages such as Perl + and Python can be found on the link:$$http://www.xmlrpc.com/$$[www.xmlrpc.com] site. + +=== Acknowledgements + +Daniel E. Baumann + +James Bercegay + +Leon Blackwell + +Stephane Bortzmeyer + +Daniel Convissor + +Geoffrey T. Dairiki + +Stefan Esser + +James Flemer + +Ernst de Haan + +Tom Knight + +Axel Kollmorgen + +Peter Kocks + +Daniel Krippner + +{empty}S. Kuip + +{empty}A. Lambert + +Frederic Lecointre + +Dan Libby + +Arnaud Limbourg + +Ernest MacDougal Campbell III + +Lukasz Mach + +Kjartan Mannes + +Ben Margolin + +Nicolay Mausz + +Justin Miller + +Jan Pfeifer + +Giancarlo Pinerolo + +Peter Russel + +Jean-Jacques Sarton + +Viliam Simko + +Idan Sofer + +Douglas Squirrel + +Heiko Stübner + +Anatoly Techtonik + +Tommaso Trani + +Eric van der Vlist + +Christian Wenz + +Jim Winstead + +Przemyslaw Wroblewski + +Bruno Zanetti Melotti + + +[[requirements]] +== System Requirements + +The library has been designed with goals of scalability and backward + compatibility. As such, it supports a wide range of PHP installs. Note + that not all features of the lib are available in every + configuration. + +The __minimum supported__ PHP version is + 5.3. + +If you wish to use HTTPS or HTTP 1.1 to communicate with remote + servers, you need the "curl" extension compiled into your PHP + installation. + +The "xmlrpc" native extension is not required to be compiled into + your PHP installation, but if it is, there will be no interference with + the operation of this library. + + +[[manifest]] +== Files in the distribution + +lib/xmlrpc.inc:: + the XML-RPC classes. include() this in + your PHP files to use the classes. + +lib/xmlrpcs.inc:: + the XML-RPC server class. include() this + in addition to xmlrpc.inc to get server functionality + +lib/xmlrpc_wrappers.php:: + helper functions to "automagically" convert plain php + functions to xmlrpc services and vice versa + +demo/server/proxy.php:: + a sample server implementing xmlrpc proxy + functionality. + +demo/server/server.php:: + a sample server hosting various demo functions, as well as a + full suite of functions used for interoperability testing. It is + used by testsuite.php (see below) for unit testing the library, and + is not to be copied literally into your production servers + +demo/client/client.php, demo/client/agesort.php, + demo/client/which.php:: + client code to exercise some of the functions in server.php, + including the interopEchoTests.whichToolkit + method. + +demo/client/wrap.php:: + client code to illustrate 'wrapping' of remote methods into + php functions. + +demo/client/introspect.php:: + client code to illustrate usage of introspection capabilities + offered by server.php. + +demo/client/mail.php:: + client code to illustrate usage of an xmlrpc-to-email gateway + using Dave Winer's XML-RPC server at userland.com. + +demo/client/zopetest.php:: + example client code that queries an xmlrpc server built in + Zope. + +demo/vardemo.php:: + examples of how to construct xmlrpcval types + +demo/demo1.xml, demo/demo2.xml, demo/demo3.xml:: + XML-RPC responses captured in a file for testing purposes (you + can use these to test the + xmlrpcmsg->parseResponse() method). + +demo/server/discuss.php, + demo/client/comment.php:: + Software used in the PHP chapter of <<jellyfish>> to provide a comment server and allow the + attachment of comments to stories from Meerkat's data store. + +test/testsuite.php, test/parse_args.php:: + A unit test suite for this software package. If you do + development on this software, please consider submitting tests for + this suite. + +test/benchmark.php:: + A (very limited) benchmarking suite for this software package. + If you do development on this software, please consider submitting + benchmarks for this suite. + +test/phpunit.php, test/PHPUnit/*.php:: + An (incomplete) version PEAR's unit test framework for PHP. + The complete package can be found at link:$$http://pear.php.net/package/PHPUnit$$[http://pear.php.net/package/PHPUnit] + +test/verify_compat.php:: + Script designed to help the user to verify the level of + compatibility of the library with the current php install + +extras/test.pl, extras/test.py:: + Perl and Python programs to exercise server.php to test that + some of the methods work. + +extras/workspace.testPhpServer.fttb:: + Frontier scripts to exercise the demo server. Thanks to Dave + Winer for permission to include these. See link:$$http://www.xmlrpc.com/discuss/msgReader$853$$[Dave's announcement of these.] + +extras/rsakey.pem:: + A test certificate key for the SSL support, which can be used + to generate dummy certificates. It has the passphrase "test." + + +[[bugs]] + +== Known bugs and limitations + +This started out as a bare framework. Many "nice" bits haven't been + put in yet. Specifically, very little type validation or coercion has been + put in. PHP being a loosely-typed language, this is going to have to be + done explicitly (in other words: you can call a lot of library functions + passing them arguments of the wrong type and receive an error message only + much further down the code, where it will be difficult to + understand). + +dateTime.iso8601 is supported opaquely. It can't be done natively as + the XML-RPC specification explicitly forbids passing of timezone + specifiers in ISO8601 format dates. You can, however, use the <<iso8601encode>> and <<iso8601decode>> functions + to do the encoding and decoding for you. + +Very little HTTP response checking is performed (e.g. HTTP redirects + are not followed and the Content-Length HTTP header, mandated by the + xml-rpc spec, is not validated); cookie support still involves quite a bit + of coding on the part of the user. + +If a specific character set encoding other than US-ASCII, ISO-8859-1 + or UTF-8 is received in the HTTP header or XML prologue of xml-rpc request + or response messages then it will be ignored for the moment, and the + content will be parsed as if it had been encoded using the charset defined + by <<xmlrpc-defencoding>> + +Support for receiving from servers version 1 cookies (i.e. + conforming to RFC 2965) is quite incomplete, and might cause unforeseen + errors. + + +[[support]] + +== Support + + +=== Online Support + +XML-RPC for PHP is offered "as-is" without any warranty or + commitment to support. However, informal advice and help is available + via the XML-RPC for PHP website and mailing list and from + XML-RPC.com. + +* The __XML-RPC for PHP__ development is hosted + on link:$$https://github.com/gggeek/phpxmlrpc$$[github.com/gggeek/phpxmlrpc]. + Bugs, feature requests and patches can be posted to the link:$$https://github.com/gggeek/phpxmlrpc/issues$$[project's website]. + +* The __PHP XML-RPC interest mailing list__ is + run by the author. More details link:$$http://lists.gnomehack.com/mailman/listinfo/phpxmlrpc$$[can be found here]. + +* For more general XML-RPC questions, there is a Yahoo! Groups + link:$$http://groups.yahoo.com/group/xml-rpc/$$[XML-RPC mailing list]. + +* The link:$$http://www.xmlrpc.com/discuss$$[XML-RPC.com] discussion + group is a useful place to get help with using XML-RPC. This group + is also gatewayed into the Yahoo! Groups mailing list. + +[[jellyfish]] + +=== The Jellyfish Book + +image::progxmlrpc.s.gif[The Jellyfish Book] +Together with Simon St.Laurent and Joe + Johnston, Edd Dumbill wrote a book on XML-RPC for O'Reilly and + Associates on XML-RPC. It features a rather fetching jellyfish on the + cover. + +Complete details of the book are link:$$http://www.oreilly.com/catalog/progxmlrpc/$$[available from O'Reilly's web site.] + +Edd is responsible for the chapter on PHP, which includes a worked + example of creating a forum server, and hooking it up the O'Reilly's + link:$$http://meerkat.oreillynet.com/$$[Meerkat] service in + order to allow commenting on news stories from around the Web. + +If you've benefited from the effort that has been put into writing + this software, then please consider buying the book! + + +[[apidocs]] + +== Class documentation + +[[xmlrpcval]] + +=== xmlrpcval + +This is where a lot of the hard work gets done. This class enables + the creation and encapsulation of values for XML-RPC. + +Ensure you've read the XML-RPC spec at link:$$http://www.xmlrpc.com/stories/storyReader$7$$[http://www.xmlrpc.com/stories/storyReader$7] + before reading on as it will make things clearer. + +The xmlrpcval class can store arbitrarily + complicated values using the following types: ++i4 int boolean string double dateTime.iso8601 base64 array struct++ + ++null++. You should refer to the link:$$http://www.xmlrpc.com/spec$$[spec] for more information on + what each of these types mean. + +==== Notes on types + +===== int + +The type i4 is accepted as a synonym + for int when creating xmlrpcval objects. The + xml parsing code will always convert i4 to + int: int is regarded + by this implementation as the canonical name for this type. + +===== base64 + +Base 64 encoding is performed transparently to the caller when + using this type. Decoding is also transparent. Therefore you ought + to consider it as a "binary" data type, for use when you want to + pass data that is not 7-bit clean. + +===== boolean + +The php values ++true++ and + ++1++ map to ++true++. All other + values (including the empty string) are converted to + ++false++. + +===== string + +Characters <, >, ', ", &, are encoded using their + entity reference as &lt; &gt; &apos; &quot; and + &amp; All other characters outside of the ASCII range are + encoded using their character reference representation (e.g. + &#200 for é). The XML-RPC spec recommends only encoding + ++< &++ but this implementation goes further, + for reasons explained by link:$$http://www.w3.org/TR/REC-xml#syntax$$[the XML 1.0 recommendation]. In particular, using character reference + representation has the advantage of producing XML that is valid + independently of the charset encoding assumed. + +===== null + +There is no support for encoding ++null++ + values in the XML-RPC spec, but at least a couple of extensions (and + many toolkits) do support it. Before using ++null++ + values in your messages, make sure that the responding party accepts + them, and uses the same encoding convention (see ...). + +[[xmlrpcval-creation]] + +==== Creation + +The constructor is the normal way to create an + xmlrpcval. The constructor can take these + forms: + +xmlrpcvalnew + xmlrpcval xmlrpcvalnew + xmlrpcval string $stringVal xmlrpcvalnew + xmlrpcval mixed $scalarVal string$scalartyp xmlrpcvalnew + xmlrpcval array $arrayVal string $arraytyp The first constructor creates an empty value, which must be + altered using the methods addScalar, + addArray or addStruct before + it can be used. + +The second constructor creates a simple string value. + +The third constructor is used to create a scalar value. The + second parameter must be a name of an XML-RPC type. Valid types are: + "++int++", "++boolean++", + "++string++", "++double++", + "++dateTime.iso8601++", "++base64++" or + "null". + +Examples: + +[source, php] +---- + +$myInt = new xmlrpcval(1267, "int"); +$myString = new xmlrpcval("Hello, World!", "string"); +$myBool = new xmlrpcval(1, "boolean"); +$myString2 = new xmlrpcval(1.24, "string"); // note: this will serialize a php float value as xmlrpc string + +---- + +The fourth constructor form can be used to compose complex + XML-RPC values. The first argument is either a simple array in the + case of an XML-RPC array or an associative + array in the case of a struct. The elements of + the array __must be xmlrpcval objects themselves__. + +The second parameter must be either "++array++" + or "++struct++". + +Examples: + +[source, php] +---- + +$myArray = new xmlrpcval( + array( + new xmlrpcval("Tom"), + new xmlrpcval("Dick"), + new xmlrpcval("Harry") + ), + "array"); + +// recursive struct +$myStruct = new xmlrpcval( + array( + "name" => new xmlrpcval("Tom", "string"), + "age" => new xmlrpcval(34, "int"), + "address" => new xmlrpcval( + array( + "street" => new xmlrpcval("Fifht Ave", "string"), + "city" => new xmlrpcval("NY", "string") + ), + "struct") + ), + "struct"); + +---- + +See the file ++vardemo.php++ in this distribution + for more examples. + +[[xmlrpcval-methods]] + +==== Methods + +===== addScalar + +int addScalarstring$stringValintaddScalarmixed$scalarValstring$scalartypIf $val is an empty + xmlrpcval this method makes it a scalar + value, and sets that value. + +If $val is already a scalar value, then + no more scalars can be added and ++0++ is + returned. + +If $val is an xmlrpcval of type array, + the php value $scalarval is added as its last + element. + +If all went OK, ++1++ is returned, otherwise + ++0++. + +===== addArray + +intaddArrayarray$arrayValThe argument is a simple (numerically indexed) array. The + elements of the array __must be xmlrpcval objects themselves__. + +Turns an empty xmlrpcval into an + array with contents as specified by + $arrayVal. + +If $val is an xmlrpcval of type array, + the elements of $arrayVal are appended to the + existing ones. + +See the fourth constructor form for more information. + +If all went OK, ++1++ is returned, otherwise + ++0++. + +===== addStruct + +int addStructarray$assocArrayValThe argument is an associative array. The elements of the + array __must be xmlrpcval objects themselves__. + +Turns an empty xmlrpcval into a + struct with contents as specified by + $assocArrayVal. + +If $val is an xmlrpcval of type struct, + the elements of $arrayVal are merged with the + existing ones. + +See the fourth constructor form for more information. + +If all went OK, ++1++ is returned, otherwise + ++0++. + +===== kindOf + +string kindOf Returns a string containing "struct", "array" or "scalar" + describing the base type of the value. If it returns "undef" it + means that the value hasn't been initialised. + +===== serialize + +string serialize Returns a string containing the XML-RPC representation of this + value. + + +===== scalarVal + +mixed scalarVal If $val->kindOf() == "scalar", this + method returns the actual PHP-language value of the scalar (base 64 + decoding is automatically handled here). + +===== scalarTyp + +string scalarTyp If $val->kindOf() == "scalar", this + method returns a string denoting the type of the scalar. As + mentioned before, ++i4++ is always coerced to + ++int++. + +===== arrayMem + +xmlrpcval arrayMem int $n If $val->kindOf() == "array", returns + the $nth element in the array represented by + the value $val. The value returned is an + xmlrpcval object. + +[source, php] +---- + +// iterating over values of an array object +for ($i = 0; $i < $val->arraySize(); $i++) +{ + $v = $val->arrayMem($i); + echo "Element $i of the array is of type ".$v->kindOf(); +} + +---- + +===== arraySize + +int arraySize If $val is an + array, returns the number of elements in that + array. + +===== structMem + +xmlrpcval structMem string $memberName If $val->kindOf() == "struct", returns + the element called $memberName from the + struct represented by the value $val. The + value returned is an xmlrpcval object. + +===== structEach + +array structEach Returns the next (key, value) pair from the struct, when + $val is a struct. + $value is an xmlrpcval itself. See also <<structreset>>. + +[source, php] +---- + +// iterating over all values of a struct object +$val->structreset(); +while (list($key, $v) = $val->structEach()) +{ + echo "Element $key of the struct is of type ".$v->kindOf(); +} + +---- + +[[structreset]] + +===== structReset + +void structReset Resets the internal pointer for + structEach() to the beginning of the struct, + where $val is a struct. + +[[structmemexists]] + +===== structMemExists + +bool structMemExsists string $memberName Returns TRUE or + FALSE depending on whether a member of the + given name exists in the struct. + +[[xmlrpcmsg]] + +=== xmlrpcmsg + +This class provides a representation for a request to an XML-RPC + server. A client sends an xmlrpcmsg to a server, + and receives back an xmlrpcresp (see <<xmlrpc-client-send>>). + +==== Creation + +The constructor takes the following forms: + +xmlrpcmsgnew + xmlrpcmsgstring$methodNamearray$parameterArraynullWhere methodName is a string indicating + the name of the method you wish to invoke, and + parameterArray is a simple php + Array of xmlrpcval + objects. Here's an example message to the __US state name__ server: + +[source, php] +---- + +$msg = new xmlrpcmsg("examples.getStateName", array(new xmlrpcval(23, "int"))); + +---- + +This example requests the name of state number 23. For more + information on xmlrpcval objects, see <<xmlrpcval>>. + +Note that the parameterArray parameter is + optional and can be omitted for methods that take no input parameters + or if you plan to add parameters one by one. + +==== Methods + + +===== addParam + +bool addParam xmlrpcval $xmlrpcVal Adds the xmlrpcval + xmlrpcVal to the parameter list for this + method call. Returns TRUE or FALSE on error. + +===== getNumParams + +int getNumParams Returns the number of parameters attached to this + message. + +===== getParam + +xmlrpcval getParam int $n Gets the nth parameter in the message + (with the index zero-based). Use this method in server + implementations to retrieve the values sent by the client. + +===== method + +string method string method string $methNameGets or sets the method contained in the XML-RPC + message. + +===== parseResponse + +xmlrpcresp parseResponsestring $xmlString Given an incoming XML-RPC server response contained in the + string $xmlString, this method constructs an + xmlrpcresp response object and returns it, + setting error codes as appropriate (see <<xmlrpc-client-send>>). + +This method processes any HTTP/MIME headers it finds. + +===== parseResponseFile + +xmlrpcresp parseResponseFile file handle + resource$fileHandleGiven an incoming XML-RPC server response on the open file + handle fileHandle, this method reads all the + data it finds and passes it to + parseResponse. + +This method is useful to construct responses from pre-prepared + files (see files ++demo1.xml, demo2.xml, demo3.xml++ + in this distribution). It processes any HTTP headers it finds, and + does not close the file handle. + +===== serialize + +string + serializeReturns the an XML string representing the XML-RPC + message. + +[[xmlrpc-client]] + +=== xmlrpc_client + +This is the basic class used to represent a client of an XML-RPC + server. + +==== Creation + +The constructor accepts one of two possible syntaxes: + +xmlrpc_clientnew + xmlrpc_clientstring$server_urlxmlrpc_clientnew + xmlrpc_clientstring$server_pathstring$server_hostnameint$server_port80string$transport'http'Here are a couple of usage examples of the first form: + + +[source, php] +---- + +$client = new xmlrpc_client("http://phpxmlrpc.sourceforge.net/server.php"); +$another_client = new xmlrpc_client("https://james:bond@secret.service.com:443/xmlrpcserver?agent=007"); + +---- + +The second syntax does not allow to express a username and + password to be used for basic HTTP authorization as in the second + example above, but instead it allows to choose whether xmlrpc calls + will be made using the HTTP 1.0 or 1.1 protocol. + +Here's another example client set up to query Userland's XML-RPC + server at __betty.userland.com__: + +[source, php] +---- + +$client = new xmlrpc_client("/RPC2", "betty.userland.com", 80); + +---- + +The server_port parameter is optional, + and if omitted will default to 80 when using HTTP and 443 when using + HTTPS (see the <<xmlrpc-client-send>> method + below). + +The transport parameter is optional, and + if omitted will default to 'http'. Allowed values are either + 'http', 'https' or + 'http11'. Its value can be overridden with every call + to the send method. See the + send method below for more details about the + meaning of the different values. + + +==== Methods + +This class supports the following methods. + +[[xmlrpc-client-send]] + +===== send + +This method takes the forms: + +xmlrpcresp send xmlrpcmsg $xmlrpc_message int $timeout string $transport array sendarray $xmlrpc_messages int $timeout string $transportxmlrpcrespsendstring$xml_payloadint$timeoutstring$transportWhere xmlrpc_message is an instance of + xmlrpcmsg (see <<xmlrpcmsg>>), + and response is an instance of + xmlrpcresp (see <<xmlrpcresp>>). + +If xmlrpc_messages is an array of + message instances, ++responses++ will be an array of + response instances. The client will try to make use of a single + ++system.multicall++ xml-rpc method call to forward to the + server all the messages in a single HTTP round trip, unless + ++$$$client->no_multicall$$++ has been previously set to + ++TRUE++ (see the multicall method below), in which case + many consecutive xmlrpc requests will be sent. + +The third syntax allows to build by hand (or any other means) + a complete xmlrpc request message, and send it to the server. + xml_payload should be a string containing the + complete xml representation of the request. It is e.g. useful when, + for maximal speed of execution, the request is serialized into a + string using the native php xmlrpc functions (see link:$$http://www.php.net/xmlrpc$$[the php manual on xmlrpc]). + +The timeout is optional, and will be + set to ++0++ (wait for platform-specific predefined + timeout) if omitted. This timeout value is passed to + fsockopen(). It is also used for detecting + server timeouts during communication (i.e. if the server does not + send anything to the client for timeout + seconds, the connection will be closed). + +The transport parameter is optional, + and if omitted will default to the transport set using instance + creator or 'http' if omitted. The only other valid values are + 'https', which will use an SSL HTTP connection to connect to the + remote server, and 'http11'. Note that your PHP must have the "curl" + extension compiled in order to use both these features. Note that + when using SSL you should normally set your port number to 443, + unless the SSL server you are contacting runs at any other + port. + +In addition to low-level errors, the XML-RPC server you were + querying may return an error in the + xmlrpcresp object. See <<xmlrpcresp>> for details of how to handle these + errors. + +[[multicall]] + +===== multiCall + +This method takes the form: + +array multiCall array $messages int $timeout string $transport bool $fallback This method is used to boxcar many method calls in a single + xml-rpc request. It will try first to make use of the + ++system.multicall++ xml-rpc method call, and fall back to + executing many separate requests if the server returns any + error. + +msgs is an array of + xmlrpcmsg objects (see <<xmlrpcmsg>>), and response is an + array of xmlrpcresp objects (see <<xmlrpcresp>>). + +The timeout and + transport parameters are optional, and behave + as in the send method above. + +The fallback parameter is optional, and + defaults to TRUE. When set to + FALSE it will prevent the client to try using + many single method calls in case of failure of the first multicall + request. It should be set only when the server is known to support + the multicall extension. + +===== setAcceptedCompression + +void setAcceptedCompression string $compressionmethod This method defines whether the client will accept compressed + xml payload forming the bodies of the xmlrpc responses received from + servers. Note that enabling reception of compressed responses merely + adds some standard http headers to xmlrpc requests. It is up to the + xmlrpc server to return compressed responses when receiving such + requests. Allowed values for + compressionmethod are: 'gzip', 'deflate', + 'any' or null (with any meaning either gzip or deflate). + +This requires the "zlib" extension to be enabled in your php + install. If it is, by default xmlrpc_client + instances will enable reception of compressed content. + +===== setCaCertificate + +voidsetCaCertificatestring$certificatebool$is_dirThis method sets an optional certificate to be used in + SSL-enabled communication to validate a remote server with (when the + server_method is set to 'https' in the + client's construction or in the send method and + SetSSLVerifypeer has been set to + TRUE). + +The certificate parameter must be the + filename of a PEM formatted certificate, or a directory containing + multiple certificate files. The is_dir + parameter defaults to FALSE, set it to + TRUE to specify that + certificate indicates a directory instead of + a single file. + +This requires the "curl" extension to be compiled into your + installation of PHP. For more details see the man page for the + curl_setopt function. + + +===== setCertificate + +voidsetCertificatestring$certificatestring$passphraseThis method sets the optional certificate and passphrase used + in SSL-enabled communication with a remote server (when the + server_method is set to 'https' in the + client's construction or in the send method). + +The certificate parameter must be the + filename of a PEM formatted certificate. The + passphrase parameter must contain the + password required to use the certificate. + +This requires the "curl" extension to be compiled into your + installation of PHP. For more details see the man page for the + curl_setopt function. + +Note: to retrieve information about the client certificate on + the server side, you will need to look into the environment + variables which are set up by the webserver. Different webservers + will typically set up different variables. + +===== setCookie + +void setCookiestring $name string $value string $path string $domain int $portThis method sets a cookie that will be sent to the xmlrpc + server along with every further request (useful e.g. for keeping + session info outside of the xml-rpc payload). + +$value is optional, and defaults to + null. + +$path, $domain and $port are optional, + and will be omitted from the cookie header if unspecified. Note that + setting any of these values will turn the cookie into a 'version 1' + cookie, that might not be fully supported by the server (see RFC2965 + for more details). + +===== setCredentials + +voidsetCredentialsstring$usernamestring$passwordint$authtypeThis method sets the username and password for authorizing the + client to a server. With the default (HTTP) transport, this + information is used for HTTP Basic authorization. Note that username + and password can also be set using the class constructor. With HTTP + 1.1 and HTTPS transport, NTLM and Digest authentication protocols + are also supported. To enable them use the constants + CURLAUTH_DIGEST and + CURLAUTH_NTLM as values for the authtype + parameter. + + +===== setCurlOptions + +voidsetCurlOptionsarray$optionsThis method allows to directly set any desired + option to manipulate the usage of the cURL client (when in cURL + mode). It can be used eg. to explicitly bind to an outgoing ip + address when the server is multihomed + + +===== setDebug + +void setDebugint$debugLvldebugLvl is either ++0, 1++ or 2 depending on whether you require the client to + print debugging information to the browser. The default is not to + output this information (0). + +The debugging information at level 1includes the raw data + returned from the XML-RPC server it was querying (including bot HTTP + headers and the full XML payload), and the PHP value the client + attempts to create to represent the value returned by the server. At + level2, the complete payload of the xmlrpc request is also printed, + before being sent t the server. + +This option can be very useful when debugging servers as it + allows you to see exactly what the client sends and the server + returns. + + +===== setKey + +voidsetKeyint$keyint$keypassThis method sets the optional certificate key and passphrase + used in SSL-enabled communication with a remote server (when the + transport is set to 'https' in the client's + construction or in the send method). + +This requires the "curl" extension to be compiled into your + installation of PHP. For more details see the man page for the + curl_setopt function. + + +===== setProxy + +voidsetProxystring$proxyhostint$proxyportstring$proxyusernamestring$proxypasswordint$authtypeThis method enables calling servers via an HTTP proxy. The + proxyusername, + proxypassword and authtype + parameters are optional. Authtype defaults to + CURLAUTH_BASIC (Basic authentication protocol); + the only other valid value is the constant + CURLAUTH_NTLM, and has effect only when the + client uses the HTTP 1.1 protocol. + +NB: CURL versions before 7.11.10 cannot use a proxy to + communicate with https servers. + + +===== setRequestCompression + +voidsetRequestCompressionstring$compressionmethodThis method defines whether the xml payload forming the + request body will be sent to the server in compressed format, as per + the HTTP specification. This is particularly useful for large + request parameters and over slow network connections. Allowed values + for compressionmethod are: 'gzip', 'deflate', + 'any' or null (with any meaning either gzip or deflate). Note that + there is no automatic fallback mechanism in place for errors due to + servers not supporting receiving compressed request bodies, so make + sure that the particular server you are querying does accept + compressed requests before turning it on. + +This requires the "zlib" extension to be enabled in your php + install. + + +===== setSSLVerifyHost + +voidsetSSLVerifyHostint$iThis method defines whether connections made to XML-RPC + backends via HTTPS should verify the remote host's SSL certificate's + common name (CN). By default, only the existence of a CN is checked. + $i should be an + integer value; 0 to not check the CN at all, 1 to merely check for + its existence, and 2 to check that the CN on the certificate matches + the hostname that is being connected to. + + +===== setSSLVerifyPeer + +voidsetSSLVerifyPeerbool$iThis method defines whether connections made to XML-RPC + backends via HTTPS should verify the remote host's SSL certificate, + and cause the connection to fail if the cert verification fails. + $i should be a boolean + value. Default value: TRUE. To specify custom + SSL certificates to validate the server with, use the + setCaCertificate method. + + +===== setUserAgent + +voidUseragentstring$useragentThis method sets a custom user-agent that will be + used by the client in the http headers sent with the request. The + default value is built using the library name and version + constants. + + +==== Variables + +NB: direct manipulation of these variables is only recommended + for advanced users. + + +===== no_multicall + +This member variable determines whether the multicall() method + will try to take advantage of the system.multicall xmlrpc method to + dispatch to the server an array of requests in a single http + roundtrip or simply execute many consecutive http calls. Defaults to + FALSE, but it will be enabled automatically on the first failure of + execution of system.multicall. + + +===== request_charset_encoding + +This is the charset encoding that will be used for serializing + request sent by the client. + +If defaults to NULL, which means using US-ASCII and encoding + all characters outside of the ASCII range using their xml character + entity representation (this has the benefit that line end characters + will not be mangled in the transfer, a CR-LF will be preserved as + well as a singe LF). + +Valid values are 'US-ASCII', 'UTF-8' and 'ISO-8859-1' + +[[return-type]] + +===== return_type + +This member variable determines whether the value returned + inside an xmlrpcresp object as results of calls to the send() and + multicall() methods will be an xmlrpcval object, a plain php value + or a raw xml string. Allowed values are 'xmlrpcvals' (the default), + 'phpvals' and 'xml'. To allow the user to differentiate between a + correct and a faulty response, fault responses will be returned as + xmlrpcresp objects in any case. Note that the 'phpvals' setting will + yield faster execution times, but some of the information from the + original response will be lost. It will be e.g. impossible to tell + whether a particular php string value was sent by the server as an + xmlrpc string or base64 value. + +Example usage: + + +[source, php] +---- + +$client = new xmlrpc_client("phpxmlrpc.sourceforge.net/server.php"); +$client->return_type = 'phpvals'; +$message = new xmlrpcmsg("examples.getStateName", array(new xmlrpcval(23, "int"))); +$resp = $client->send($message); +if ($resp->faultCode()) echo 'KO. Error: '.$resp->faultString(); else echo 'OK: got '.$resp->value(); + +---- + +For more details about usage of the 'xml' value, see Appendix + A. + +[[xmlrpcresp]] + +=== xmlrpcresp + +This class is used to contain responses to XML-RPC requests. A + server method handler will construct an + xmlrpcresp and pass it as a return value. This + same value will be returned by the result of an invocation of the + send method of the + xmlrpc_client class. + + +==== Creation + +xmlrpcrespnew + xmlrpcrespxmlrpcval$xmlrpcvalxmlrpcrespnew + xmlrpcresp0int$errcodestring$err_stringThe first syntax is used when execution has happened without + difficulty: $xmlrpcval is an + xmlrpcval value with the result of the method + execution contained in it. Alternatively it can be a string containing + the xml serialization of the single xml-rpc value result of method + execution. + +The second type of constructor is used in case of failure. + errcode and err_string + are used to provide indication of what has gone wrong. See <<xmlrpc-server>> for more information on passing error + codes. + + +==== Methods + + +===== faultCode + +intfaultCodeReturns the integer fault code return from the XML-RPC + response. A zero value indicates success, any other value indicates + a failure response. + + +===== faultString + +stringfaultStringReturns the human readable explanation of the fault indicated + by $resp->faultCode(). + + +===== value + +xmlrpcvalvalueReturns an xmlrpcval object containing + the return value sent by the server. If the response's + faultCode is non-zero then the value returned + by this method should not be used (it may not even be an + object). + +Note: if the xmlrpcresp instance in question has been created + by an xmlrpc_client object whose + return_type was set to 'phpvals', then a plain + php value will be returned instead of an + xmlrpcval object. If the + return_type was set to 'xml', an xml string will + be returned (see the return_type member var above for more + details). + + +===== serialize + +stringserializeReturns an XML string representation of the response (xml + prologue not included). + +[[xmlrpc-server]] + +=== xmlrpc_server + +The implementation of this class has been kept as simple to use as + possible. The constructor for the server basically does all the work. + Here's a minimal example: + + +[source, php] +---- + + function foo ($xmlrpcmsg) { + ... + return new xmlrpcresp($some_xmlrpc_val); + } + + class bar { + function foobar($xmlrpcmsg) { + ... + return new xmlrpcresp($some_xmlrpc_val); + } + } + + $s = new xmlrpc_server( + array( + "examples.myFunc1" => array("function" => "foo"), + "examples.myFunc2" => array("function" => "bar::foobar"), + )); + +---- + +This performs everything you need to do with a server. The single + constructor argument is an associative array from xmlrpc method names to + php function names. The incoming request is parsed and dispatched to the + relevant php function, which is responsible for returning a + xmlrpcresp object, that will be serialized back + to the caller. + + +==== Method handler functions + +Both php functions and class methods can be registered as xmlrpc + method handlers. + +The synopsis of a method handler function is: + +xmlrpcresp $resp = function (xmlrpcmsg $msg) + +No text should be echoed 'to screen' by the handler function, or + it will break the xml response sent back to the client. This applies + also to error and warning messages that PHP prints to screen unless + the appropriate parameters have been set in the php.in file. Another + way to prevent echoing of errors inside the response and facilitate + debugging is to use the server SetDebug method with debug level 3 (see + ...). Exceptions thrown duting execution of handler functions are + caught by default and a XML-RPC error reponse is generated instead. + This behaviour can be finetuned by usage of the + exception_handling member variable (see + ...). + +Note that if you implement a method with a name prefixed by + ++system.++ the handler function will be invoked by the + server with two parameters, the first being the server itself and the + second being the xmlrpcmsg object. + +The same php function can be registered as handler of multiple + xmlrpc methods. + +Here is a more detailed example of what the handler function + foo may do: + + +[source, php] +---- + + function foo ($xmlrpcmsg) { + global $xmlrpcerruser; // import user errcode base value + + $meth = $xmlrpcmsg->method(); // retrieve method name + $par = $xmlrpcmsg->getParam(0); // retrieve value of first parameter - assumes at least one param received + $val = $par->scalarval(); // decode value of first parameter - assumes it is a scalar value + + ... + + if ($err) { + // this is an error condition + return new xmlrpcresp(0, $xmlrpcerruser+1, // user error 1 + "There's a problem, Captain"); + } else { + // this is a successful value being returned + return new xmlrpcresp(new xmlrpcval("All's fine!", "string")); + } + } + +---- + +See __server.php__ in this distribution for + more examples of how to do this. + +Since release 2.0RC3 there is a new, even simpler way of + registering php functions with the server. See section 5.7 + below + + +==== The dispatch map + +The first argument to the xmlrpc_server + constructor is an array, called the __dispatch map__. + In this array is the information the server needs to service the + XML-RPC methods you define. + +The dispatch map takes the form of an associative array of + associative arrays: the outer array has one entry for each method, the + key being the method name. The corresponding value is another + associative array, which can have the following members: + + +* ++function++ - this + entry is mandatory. It must be either a name of a function in the + global scope which services the XML-RPC method, or an array + containing an instance of an object and a static method name (for + static class methods the 'class::method' syntax is also + supported). + + +* ++signature++ - this + entry is an array containing the possible signatures (see <<signatures>>) for the method. If this entry is present + then the server will check that the correct number and type of + parameters have been sent for this method before dispatching + it. + + +* ++docstring++ - this + entry is a string containing documentation for the method. The + documentation may contain HTML markup. + + +* ++$$signature_docs$$++ - this entry can be used + to provide documentation for the single parameters. It must match + in structure the 'signature' member. By default, only the + documenting_xmlrpc_server class in the + extras package will take advantage of this, since the + "system.methodHelp" protocol does not support documenting method + parameters individually. + + +* ++$$parameters_type$$++ - this entry can be used + when the server is working in 'xmlrpcvals' mode (see ...) to + define one or more entries in the dispatch map as being functions + that follow the 'phpvals' calling convention. The only useful + value is currently the string ++phpvals++. + +Look at the __server.php__ example in the + distribution to see what a dispatch map looks like. + +[[signatures]] + +==== Method signatures + +A signature is a description of a method's return type and its + parameter types. A method may have more than one signature. + +Within a server's dispatch map, each method has an array of + possible signatures. Each signature is an array of types. The first + entry is the return type. For instance, the method +[source, php] +---- +string examples.getStateName(int) + +---- + + has the signature +[source, php] +---- +array($xmlrpcString, $xmlrpcInt) + +---- + + and, assuming that it is the only possible signature for the + method, it might be used like this in server creation: +[source, php] +---- + +$findstate_sig = array(array($xmlrpcString, $xmlrpcInt)); + +$findstate_doc = 'When passed an integer between 1 and 51 returns the +name of a US state, where the integer is the index of that state name +in an alphabetic order.'; + +$s = new xmlrpc_server( array( + "examples.getStateName" => array( + "function" => "findstate", + "signature" => $findstate_sig, + "docstring" => $findstate_doc + ))); + +---- + + + +Note that method signatures do not allow to check nested + parameters, e.g. the number, names and types of the members of a + struct param cannot be validated. + +If a method that you want to expose has a definite number of + parameters, but each of those parameters could reasonably be of + multiple types, the array of acceptable signatures will easily grow + into a combinatorial explosion. To avoid such a situation, the lib + defines the global var $xmlrpcValue, which can be + used in method signatures as a placeholder for 'any xmlrpc + type': + + +[source, php] +---- + +$echoback_sig = array(array($xmlrpcValue, $xmlrpcValue)); + +$findstate_doc = 'Echoes back to the client the received value, regardless of its type'; + +$s = new xmlrpc_server( array( + "echoBack" => array( + "function" => "echoback", + "signature" => $echoback_sig, // this sig guarantees that the method handler will be called with one and only one parameter + "docstring" => $echoback_doc + ))); + +---- + +Methods system.listMethods, + system.methodHelp, + system.methodSignature and + system.multicall are already defined by the + server, and should not be reimplemented (see Reserved Methods + below). + + +==== Delaying the server response + +You may want to construct the server, but for some reason not + fulfill the request immediately (security verification, for instance). + If you omit to pass to the constructor the dispatch map or pass it a + second argument of ++0++ this will have the desired + effect. You can then use the service() method of + the server class to service the request. For example: + + +[source, php] +---- + +$s = new xmlrpc_server($myDispMap, 0); // second parameter = 0 prevents automatic servicing of request + +// ... some code that does other stuff here + +$s->service(); + +---- + +Note that the service method will print + the complete result payload to screen and send appropriate HTTP + headers back to the client, but also return the response object. This + permits further manipulation of the response, possibly in combination + with output buffering. + +To prevent the server from sending HTTP headers back to the + client, you can pass a second parameter with a value of + ++TRUE++ to the service + method. In this case, the response payload will be returned instead of + the response object. + +Xmlrpc requests retrieved by other means than HTTP POST bodies + can also be processed. For example: + + +[source, php] +---- + +$s = new xmlrpc_server(); // not passing a dispatch map prevents automatic servicing of request + +// ... some code that does other stuff here, including setting dispatch map into server object + +$resp = $s->service($xmlrpc_request_body, true); // parse a variable instead of POST body, retrieve response payload + +// ... some code that does other stuff with xml response $resp here + +---- + + +==== Modifying the server behaviour + +A couple of methods / class variables are available to modify + the behaviour of the server. The only way to take advantage of their + existence is by usage of a delayed server response (see above) + + +===== setDebug() + +This function controls weather the server is going to echo + debugging messages back to the client as comments in response body. + Valid values: 0,1,2,3, with 1 being the default. At level 0, no + debug info is returned to the client. At level 2, the complete + client request is added to the response, as part of the xml + comments. At level 3, a new PHP error handler is set when executing + user functions exposed as server methods, and all non-fatal errors + are trapped and added as comments into the response. + + +===== allow_system_funcs + +Default_value: TRUE. When set to FALSE, disables support for + System.xxx functions in the server. It + might be useful e.g. if you do not wish the server to respond to + requests to System.ListMethods. + + +===== compress_response + +When set to TRUE, enables the server to take advantage of HTTP + compression, otherwise disables it. Responses will be transparently + compressed, but only when an xmlrpc-client declares its support for + compression in the HTTP headers of the request. + +Note that the ZLIB php extension must be installed for this to + work. If it is, compress_response will default to + TRUE. + + +===== exception_handling + +This variable controls the behaviour of the server when an + exception is thrown by a method handler php function. Valid values: + 0,1,2, with 0 being the default. At level 0, the server catches the + exception and return an 'internal error' xmlrpc response; at 1 it + catches the exceptions and return an xmlrpc response with the error + code and error message corresponding to the exception that was + thron; at 2 = the exception is floated to the upper layers in the + code + + +===== response_charset_encoding + +Charset encoding to be used for response (only affects string + values). + +If it can, the server will convert the generated response from + internal_encoding to the intended one. + +Valid values are: a supported xml encoding (only UTF-8 and + ISO-8859-1 at present, unless mbstring is enabled), null (leave + charset unspecified in response and convert output stream to + US_ASCII), 'default' (use xmlrpc library default as specified in + xmlrpc.inc, convert output stream if needed), or 'auto' (use + client-specified charset encoding or same as request if request + headers do not specify it (unless request is US-ASCII: then use + library default anyway). + + +==== Fault reporting + +Fault codes for your servers should start at the value indicated + by the global ++$xmlrpcerruser++ + 1. + +Standard errors returned by the server include: + +++1++ Unknown method:: Returned if the server was asked to dispatch a method it + didn't know about + +++2++ Invalid return payload:: This error is actually generated by the client, not + server, code, but signifies that a server returned something it + couldn't understand. A more detailed error report is sometimes + added onto the end of the phrase above. + +++3++ Incorrect parameters:: This error is generated when the server has signature(s) + defined for a method, and the parameters passed by the client do + not match any of signatures. + +++4++ Can't introspect: method unknown:: This error is generated by the builtin + system.* methods when any kind of + introspection is attempted on a method undefined by the + server. + +++5++ Didn't receive 200 OK from remote server:: This error is generated by the client when a remote server + doesn't return HTTP/1.1 200 OK in response to a request. A more + detailed error report is added onto the end of the phrase + above. + +++6++ No data received from server:: This error is generated by the client when a remote server + returns HTTP/1.1 200 OK in response to a request, but no + response body follows the HTTP headers. + +++7++ No SSL support compiled in:: This error is generated by the client when trying to send + a request with HTTPS and the CURL extension is not available to + PHP. + +++8++ CURL error:: This error is generated by the client when trying to send + a request with HTTPS and the HTTPS communication fails. + +++9-14++ multicall errors:: These errors are generated by the server when something + fails inside a system.multicall request. + +++100-++ XML parse errors:: Returns 100 plus the XML parser error code for the fault + that occurred. The faultString returned + explains where the parse error was in the incoming XML + stream. + + +==== 'New style' servers + +In the same spirit of simplification that inspired the + xmlrpc_client::return_type class variable, a new + class variable has been added to the server class: + functions_parameters_type. When set to 'phpvals', + the functions registered in the server dispatch map will be called + with plain php values as parameters, instead of a single xmlrpcmsg + instance parameter. The return value of those functions is expected to + be a plain php value, too. An example is worth a thousand + words: +[source, php] +---- + + function foo($usr_id, $out_lang='en') { + global $xmlrpcerruser; + + ... + + if ($someErrorCondition) + return new xmlrpcresp(0, $xmlrpcerruser+1, 'DOH!'); + else + return array( + 'name' => 'Joe', + 'age' => 27, + 'picture' => new xmlrpcval(file_get_contents($picOfTheGuy), 'base64') + ); + } + + $s = new xmlrpc_server( + array( + "examples.myFunc" => array( + "function" => "bar::foobar", + "signature" => array( + array($xmlrpcString, $xmlrpcInt), + array($xmlrpcString, $xmlrpcInt, $xmlrpcString) + ) + ) + ), false); + $s->functions_parameters_type = 'phpvals'; + $s->service(); + +---- + +There are a few things to keep in mind when using this + simplified syntax: + +to return an xmlrpc error, the method handler function must + return an instance of xmlrpcresp. The only + other way for the server to know when an error response should be + served to the client is to throw an exception and set the server's + exception_handling memeber var to 1; + +to return a base64 value, the method handler function must + encode it on its own, creating an instance of an xmlrpcval + object; + +the method handler function cannot determine the name of the + xmlrpc method it is serving, unlike standard handler functions that + can retrieve it from the message object; + +when receiving nested parameters, the method handler function + has no way to distinguish a php string that was sent as base64 value + from one that was sent as a string value; + +this has a direct consequence on the support of + system.multicall: a method whose signature contains datetime or base64 + values will not be available to multicall calls; + +last but not least, the direct parsing of xml to php values is + much faster than using xmlrpcvals, and allows the library to handle + much bigger messages without allocating all available server memory or + smashing PHP recursive call stack. + + +[[globalvars]] + +== Global variables + +Many global variables are defined in the xmlrpc.inc file. Some of + those are meant to be used as constants (and modifying their value might + cause unpredictable behaviour), while some others can be modified in your + php scripts to alter the behaviour of the xml-rpc client and + server. + + +=== "Constant" variables + + +==== $xmlrpcerruser + +$xmlrpcerruser800The minimum value for errors reported by user + implemented XML-RPC servers. Error numbers lower than that are + reserved for library usage. + + +==== $xmlrpcI4, $xmlrpcInt, $xmlrpcBoolean, $xmlrpcDouble, $xmlrpcString, $xmlrpcDateTime, $xmlrpcBase64, $xmlrpcArray, $xmlrpcStruct, $xmlrpcValue, $xmlrpcNull + +For convenience the strings representing the XML-RPC types have + been encoded as global variables: +[source, php] +---- + +$xmlrpcI4="i4"; +$xmlrpcInt="int"; +$xmlrpcBoolean="boolean"; +$xmlrpcDouble="double"; +$xmlrpcString="string"; +$xmlrpcDateTime="dateTime.iso8601"; +$xmlrpcBase64="base64"; +$xmlrpcArray="array"; +$xmlrpcStruct="struct"; +$xmlrpcValue="undefined"; +$xmlrpcNull="null"; + +---- + +==== $xmlrpcTypes, $xmlrpc_valid_parents, $xmlrpcerr, $xmlrpcstr, $xmlrpcerrxml, $xmlrpc_backslash, $_xh, $xml_iso88591_Entities, $xmlEntities, $xmlrpcs_capabilities + +Reserved for internal usage. + + +=== Variables whose value can be modified + +[[xmlrpc-defencoding]] + +==== xmlrpc_defencoding + +$xmlrpc_defencoding"UTF8"This variable defines the character set encoding that will be + used by the xml-rpc client and server to decode the received messages, + when a specific charset declaration is not found (in the messages sent + non-ascii chars are always encoded using character references, so that + the produced xml is valid regardless of the charset encoding + assumed). + +Allowed values: ++"UTF8"++, + ++"ISO-8859-1"++, ++"ASCII".++ + +Note that the appropriate RFC actually mandates that XML + received over HTTP without indication of charset encoding be treated + as US-ASCII, but many servers and clients 'in the wild' violate the + standard, and assume the default encoding is UTF-8. + + +==== xmlrpc_internalencoding + +$xmlrpc_internalencoding"ISO-8859-1"This variable defines the character set encoding + that the library uses to transparently encode into valid XML the + xml-rpc values created by the user and to re-encode the received + xml-rpc values when it passes them to the PHP application. It only + affects xml-rpc values of string type. It is a separate value from + xmlrpc_defencoding, allowing e.g. to send/receive xml messages encoded + on-the-wire in US-ASCII and process them as UTF-8. It defaults to the + character set used internally by PHP (unless you are running an + MBString-enabled installation), so you should change it only in + special situations, if e.g. the string values exchanged in the xml-rpc + messages are directly inserted into / fetched from a database + configured to return UTF8 encoded strings to PHP. Example + usage: + +[source, php] +---- + +<?php + +include('xmlrpc.inc'); +$xmlrpc_internalencoding = 'UTF-8'; // this has to be set after the inclusion above +$v = new xmlrpcval('κόσμε'); // This xmlrpc value will be correctly serialized as the greek word 'kosme' + +---- + +==== xmlrpcName + +$xmlrpcName"XML-RPC for PHP"The string representation of the name of the XML-RPC + for PHP library. It is used by the client for building the User-Agent + HTTP header that is sent with every request to the server. You can + change its value if you need to customize the User-Agent + string. + + +==== xmlrpcVersion + +$xmlrpcVersion"2.2"The string representation of the version number of + the XML-RPC for PHP library in use. It is used by the client for + building the User-Agent HTTP header that is sent with every request to + the server. You can change its value if you need to customize the + User-Agent string. + + +==== xmlrpc_null_extension + +When set to TRUE, the lib will enable + support for the <NIL/> (and <EX:NIL/>) xmlrpc value, as + per the extension to the standard proposed here. This means that + <NIL/> and <EX:NIL/> tags received will be parsed as valid + xmlrpc, and the corresponding xmlrpcvals will return "null" for + scalarTyp(). + + +==== xmlrpc_null_apache_encoding + +When set to ++TRUE++, php NULL values encoded + into xmlrpcval objects get serialized using the + ++<EX:NIL/>++ tag instead of + ++<NIL/>++. Please note that both forms are + always accepted as input regardless of the value of this + variable. + + +[[helpers]] + +== Helper functions + +XML-RPC for PHP contains some helper functions which you can use to + make processing of XML-RPC requests easier. + + +=== Date functions + +The XML-RPC specification has this to say on dates: + +[quote] +____ +[[wrap_xmlrpc_method]] +Don't assume a timezone. It should be + specified by the server in its documentation what assumptions it makes + about timezones. +____ + + +Unfortunately, this means that date processing isn't + straightforward. Although XML-RPC uses ISO 8601 format dates, it doesn't + use the timezone specifier. + +We strongly recommend that in every case where you pass dates in + XML-RPC calls, you use UTC (GMT) as your timezone. Most computer + languages include routines for handling GMT times natively, and you + won't have to translate between timezones. + +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 + 8601 specification. Note that XML-RPC uses exactly one of the available + representations: CCYYMMDDTHH:MM:SS. + +[[iso8601encode]] + +==== iso8601_encode + +stringiso8601_encodestring$time_tint$utc0Returns an ISO 8601 formatted date generated from the UNIX + timestamp $time_t, as returned by the PHP + function time(). + +The argument $utc can be omitted, in + which case it defaults to ++0++. If it is set to + ++1++, then the function corrects the time passed in + for UTC. Example: if you're in the GMT-6:00 timezone and set + $utc, you will receive a date representation + six hours ahead of your local time. + +The included demo program __vardemo.php__ + includes a demonstration of this function. + +[[iso8601decode]] + +==== iso8601_decode + +intiso8601_decodestring$isoStringint$utc0Returns a UNIX timestamp from an ISO 8601 encoded time and date + string passed in. If $utc is + ++1++ then $isoString is assumed + to be in the UTC timezone, and thus the result is also UTC: otherwise, + the timezone is assumed to be your local timezone and you receive a + local timestamp. + +[[arrayuse]] + +=== Easy use with nested PHP values + +Dan Libby was kind enough to contribute two helper functions that + make it easier to translate to and from PHP values. This makes it easier + to deal with complex structures. At the moment support is limited to + int, double, string, + array, datetime and struct + datatypes; note also that all PHP arrays are encoded as structs, except + arrays whose keys are integer numbers starting with 0 and incremented by + 1. + +These functions reside in __xmlrpc.inc__. + +[[phpxmlrpcdecode]] + +==== php_xmlrpc_decode + +mixedphp_xmlrpc_decodexmlrpcval$xmlrpc_valarray$optionsarrayphp_xmlrpc_decodexmlrpcmsg$xmlrpcmsg_valstring$optionsReturns a native PHP value corresponding to the values found in + the xmlrpcval $xmlrpc_val, + translated into PHP types. Base-64 and datetime values are + automatically decoded to strings. + +In the second form, returns an array containing the parameters + of the given + xmlrpcmsg_val, decoded + to php types. + +The options parameter is optional. If + specified, it must consist of an array of options to be enabled in the + decoding process. At the moment the only valid option are + decode_php_objs and + ++$$dates_as_objects$$++. When the first is set, php + objects that have been converted to xml-rpc structs using the + php_xmlrpc_encode function and a corresponding + encoding option will be converted back into object values instead of + arrays (provided that the class definition is available at + reconstruction time). When the second is set, XML-RPC datetime values + will be converted into native dateTime objects + instead of strings. + +____WARNING__:__ please take + extreme care before enabling the decode_php_objs + option: when php objects are rebuilt from the received xml, their + constructor function will be silently invoked. This means that you are + allowing the remote end to trigger execution of uncontrolled PHP code + on your server, opening the door to code injection exploits. Only + enable this option when you have complete trust of the remote + server/client. + +Example: +[source, php] +---- + +// wrapper to expose an existing php function as xmlrpc method handler +function foo_wrapper($m) +{ + $params = php_xmlrpc_decode($m); + $retval = call_user_func_array('foo', $params); + return new xmlrpcresp(new xmlrpcval($retval)); // foo return value will be serialized as string +} + +$s = new xmlrpc_server(array( + "examples.myFunc1" => array( + "function" => "foo_wrapper", + "signatures" => ... + ))); + +---- + +[[phpxmlrpcencode]] + +==== php_xmlrpc_encode + +xmlrpcvalphp_xmlrpc_encodemixed$phpvalarray$optionsReturns an xmlrpcval object populated with the PHP + values in $phpval. Works recursively on arrays + and objects, encoding numerically indexed php arrays into array-type + xmlrpcval objects and non numerically indexed php arrays into + struct-type xmlrpcval objects. Php objects are encoded into + struct-type xmlrpcvals, excepted for php values that are already + instances of the xmlrpcval class or descendants thereof, which will + not be further encoded. Note that there's no support for encoding php + values into base-64 values. Encoding of date-times is optionally + carried on on php strings with the correct format. + +The options parameter is optional. If + specified, it must consist of an array of options to be enabled in the + encoding process. At the moment the only valid options are + encode_php_objs, ++$$null_extension$$++ + and auto_dates. + +The first will enable the creation of 'particular' xmlrpcval + objects out of php objects, that add a "php_class" xml attribute to + their serialized representation. This attribute allows the function + php_xmlrpc_decode to rebuild the native php objects (provided that the + same class definition exists on both sides of the communication). The + second allows to encode php ++NULL++ values to the + ++<NIL/>++ (or + ++<EX:NIL/>++, see ...) tag. The last encodes any + string that matches the ISO8601 format into an XML-RPC + datetime. + +Example: +[source, php] +---- + +// the easy way to build a complex xml-rpc struct, showing nested base64 value and datetime values +$val = php_xmlrpc_encode(array( + 'first struct_element: an int' => 666, + 'second: an array' => array ('apple', 'orange', 'banana'), + 'third: a base64 element' => new xmlrpcval('hello world', 'base64'), + 'fourth: a datetime' => '20060107T01:53:00' + ), array('auto_dates')); + +---- + +==== php_xmlrpc_decode_xml + +xmlrpcval | xmlrpcresp | + xmlrpcmsgphp_xmlrpc_decode_xmlstring$xmlarray$optionsDecodes the xml representation of either an xmlrpc request, + response or single value, returning the corresponding php-xmlrpc + object, or ++FALSE++ in case of an error. + +The options parameter is optional. If + specified, it must consist of an array of options to be enabled in the + decoding process. At the moment, no option is supported. + +Example: +[source, php] +---- + +$text = '<value><array><data><value>Hello world</value></data></array></value>'; +$val = php_xmlrpc_decode_xml($text); +if ($val) echo 'Found a value of type '.$val->kindOf(); else echo 'Found invalid xml'; + +---- + +=== Automatic conversion of php functions into xmlrpc methods (and vice versa) + +For the extremely lazy coder, helper functions have been added + that allow to convert a php function into an xmlrpc method, and a + remotely exposed xmlrpc method into a local php function - or a set of + methods into a php class. Note that these comes with many caveat. + + +==== wrap_xmlrpc_method + +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 + function that will call the remote method and return results using + native php types for both params and results. The generated php + function will return an xmlrpcresp object for failed xmlrpc + calls. + +The second syntax is deprecated, and is listed here only for + backward compatibility. + +The server must support the + system.methodSignature xmlrpc method call for + this function to work. + +The client param must be a valid + xmlrpc_client object, previously created with the address of the + target xmlrpc server, and to which the preferred communication options + have been set. + +The optional parameters can be passed as array key,value pairs + in the extra_options param. + +The signum optional param has the purpose + of indicating which method signature to use, if the given server + method has multiple signatures (defaults to 0). + +The timeout and + protocol optional params are the same as in the + xmlrpc_client::send() method. + +If set, the optional new_function_name + parameter indicates which name should be used for the generated + function. In case it is not set the function name will be + auto-generated. + +If the ++$$return_source$$++ optional parameter is + set, the function will return the php source code to build the wrapper + function, instead of evaluating it (useful to save the code and use it + later as stand-alone xmlrpc client). + +If the ++$$encode_php_objs$$++ optional parameter is + set, instances of php objects later passed as parameters to the newly + created function will receive a 'special' treatment that allows the + server to rebuild them as php objects instead of simple arrays. Note + that this entails using a "slightly augmented" version of the xmlrpc + protocol (ie. using element attributes), which might not be understood + by xmlrpc servers implemented using other libraries. + +If the ++$$decode_php_objs$$++ optional parameter is + set, instances of php objects that have been appropriately encoded by + the server using a coordinate option will be deserialized as php + objects instead of simple arrays (the same class definition should be + present server side and client side). + +__Note that this might pose a security risk__, + since in order to rebuild the object instances their constructor + method has to be invoked, and this means that the remote server can + trigger execution of unforeseen php code on the client: not really a + code injection, but almost. Please enable this option only when you + trust the remote server. + +In case of an error during generation of the wrapper function, + FALSE is returned, otherwise the name (or source code) of the new + function. + +Known limitations: server must support + system.methodsignature for the wanted xmlrpc + method; for methods that expose multiple signatures, only one can be + picked; for remote calls with nested xmlrpc params, the caller of the + generated php function has to encode on its own the params passed to + the php function if these are structs or arrays whose (sub)members + include values of type base64. + +Note: calling the generated php function 'might' be slow: a new + xmlrpc client is created on every invocation and an xmlrpc-connection + opened+closed. An extra 'debug' param is appended to the parameter + list of the generated php function, useful for debugging + purposes. + +Example usage: + + +[source, php] +---- + +$c = new xmlrpc_client('http://phpxmlrpc.sourceforge.net/server.php'); + +$function = wrap_xmlrpc_method($client, 'examples.getStateName'); + +if (!$function) + die('Cannot introspect remote method'); +else { + $stateno = 15; + $statename = $function($a); + if (is_a($statename, 'xmlrpcresp')) // call failed + { + echo 'Call failed: '.$statename->faultCode().'. Calling again with debug on'; + $function($a, true); + } + else + echo "OK, state nr. $stateno is $statename"; +} + +---- + +[[wrap_php_function]] + +==== wrap_php_function + +arraywrap_php_functionstring$funcnamestring$wrapper_function_namearray$extra_optionsGiven a user-defined PHP function, create a PHP 'wrapper' + function that can be exposed as xmlrpc method from an xmlrpc_server + object and called from remote clients, and return the appropriate + definition to be added to a server's dispatch map. + +The optional $wrapper_function_name + specifies the name that will be used for the auto-generated + function. + +Since php is a typeless language, to infer types of input and + output parameters, it relies on parsing the javadoc-style comment + block associated with the given function. Usage of xmlrpc native types + (such as datetime.dateTime.iso8601 and base64) in the docblock @param + tag is also allowed, if you need the php function to receive/send data + in that particular format (note that base64 encoding/decoding is + transparently carried out by the lib, while datetime vals are passed + around as strings). + +Known limitations: only works for + user-defined functions, not for PHP internal functions (reflection + does not support retrieving number/type of params for those); the + wrapped php function will not be able to programmatically return an + xmlrpc error response. + +If the ++$$return_source$$++ optional parameter is + set, the function will return the php source code to build the wrapper + function, instead of evaluating it (useful to save the code and use it + later in a stand-alone xmlrpc server). It will be in the stored in the + ++source++ member of the returned array. + +If the ++$$suppress_warnings$$++ optional parameter + is set, any runtime warning generated while processing the + user-defined php function will be catched and not be printed in the + generated xml response. + +If the extra_options array contains the + ++$$encode_php_objs$$++ value, wrapped functions returning + php objects will generate "special" xmlrpc responses: when the xmlrpc + decoding of those responses is carried out by this same lib, using the + appropriate param in php_xmlrpc_decode(), the objects will be + rebuilt. + +In short: php objects can be serialized, too (except for their + resource members), using this function. Other libs might choke on the + very same xml that will be generated in this case (i.e. it has a + nonstandard attribute on struct element tags) + +If the ++$$decode_php_objs$$++ optional parameter is + set, instances of php objects that have been appropriately encoded by + the client using a coordinate option will be deserialized and passed + to the user function as php objects instead of simple arrays (the same + class definition should be present server side and client + side). + +__Note that this might pose a security risk__, + since in order to rebuild the object instances their constructor + method has to be invoked, and this means that the remote client can + trigger execution of unforeseen php code on the server: not really a + code injection, but almost. Please enable this option only when you + trust the remote clients. + +Example usage: + + +[source, php] +---- +/** +* State name from state number decoder. NB: do NOT remove this comment block. +* @param integer $stateno the state number +* @return string the name of the state (or error description) +*/ +function findstate($stateno) +{ + global $stateNames; + if (isset($stateNames[$stateno-1])) + { + return $stateNames[$stateno-1]; + } + else + { + return "I don't have a state for the index '" . $stateno . "'"; + } +} + +// wrap php function, build xmlrpc server +$methods = array(); +$findstate_sig = wrap_php_function('findstate'); +if ($findstate_sig) + $methods['examples.getStateName'] = $findstate_sig; +$srv = new xmlrpc_server($methods); + +---- + +[[deprecated]] + +=== Functions removed from the library + +The following two functions have been deprecated in version 1.1 of + the library, and removed in version 2, in order to avoid conflicts with + the EPI xml-rpc library, which also defines two functions with the same + names. + +To ease the transition to the new naming scheme and avoid breaking + existing implementations, the following scheme has been adopted: + +* If EPI-XMLRPC is not active in the current PHP installation, + the constant ++$$XMLRPC_EPI_ENABLED$$++ will be set to + ++$$'0'$$++ + + +* If EPI-XMLRPC is active in the current PHP installation, the + constant ++$$XMLRPC_EPI_ENABLED$$++ will be set to + ++$$'1'$$++ + + + +The following documentation is kept for historical + reference: + +[[xmlrpcdecode]] + +==== xmlrpc_decode + +mixedx mlrpc_decode xmlrpcval $xmlrpc_val Alias for php_xmlrpc_decode. + +[[xmlrpcencode]] + +==== xmlrpc_encode + +xmlrpcval xmlrpc_encode mixed $phpvalAlias for php_xmlrpc_encode. + +[[debugging]] + +=== Debugging aids + +==== xmlrpc_debugmsg + +void xmlrpc_debugmsgstring$debugstringSends the contents of $debugstring in XML + comments in the server return payload. If a PHP client has debugging + turned on, the user will be able to see server debug + information. + +Use this function in your methods so you can pass back + diagnostic information. It is only available from + __xmlrpcs.inc__. + + +[[reserved]] + +== Reserved methods + +In order to extend the functionality offered by XML-RPC servers + without impacting on the protocol, reserved methods are supported in this + release. + +All methods starting with system. are + considered reserved by the server. PHP for XML-RPC itself provides four + special methods, detailed in this chapter. + +Note that all server objects will automatically respond to clients + querying these methods, unless the property + allow_system_funcs has been set to + false before calling the + service() method. This might pose a security risk + if the server is exposed to public access, e.g. on the internet. + + +=== system.getCapabilities + + +=== system.listMethods + +This method may be used to enumerate the methods implemented by + the XML-RPC server. + +The system.listMethods method requires no + parameters. It returns an array of strings, each of which is the name of + a method implemented by the server. + +[[sysmethodsig]] + +=== system.methodSignature + +This method takes one parameter, the name of a method implemented + by the XML-RPC server. + +It returns an array of possible signatures for this method. A + signature is an array of types. The first of these types is the return + type of the method, the rest are parameters. + +Multiple signatures (i.e. overloading) are permitted: this is the + reason that an array of signatures are returned by this method. + +Signatures themselves are restricted to the top level parameters + expected by a method. For instance if a method expects one array of + structs as a parameter, and it returns a string, its signature is simply + "string, array". If it expects three integers, its signature is "string, + int, int, int". + +For parameters that can be of more than one type, the "undefined" + string is supported. + +If no signature is defined for the method, a not-array value is + returned. Therefore this is the way to test for a non-signature, if + $resp below is the response object from a method + call to system.methodSignature: + +[source, php] +---- + +$v = $resp->value(); +if ($v->kindOf() != "array") { + // then the method did not have a signature defined +} + +---- + +See the __introspect.php__ demo included in this + distribution for an example of using this method. + +[[sysmethhelp]] + +=== system.methodHelp + +This method takes one parameter, the name of a method implemented + by the XML-RPC server. + +It returns a documentation string describing the use of that + method. If no such string is available, an empty string is + returned. + +The documentation string may contain HTML markup. + +=== system.multicall + +This method takes one parameter, an array of 'request' struct + types. Each request struct must contain a + methodName member of type string and a + params member of type array, and corresponds to + the invocation of the corresponding method. + +It returns a response of type array, with each value of the array + being either an error struct (containing the faultCode and faultString + members) or the successful response value of the corresponding single + method call. + + +[[examples]] + +== Examples + +The best examples are to be found in the sample files included with + the distribution. Some are included here. + +[[statename]] + +=== XML-RPC client: state name query + +Code to get the corresponding state name from a number (1-50) from + the demo server available on SourceForge + +[source, php] +---- + + $m = new xmlrpcmsg('examples.getStateName', + array(new xmlrpcval($HTTP_POST_VARS["stateno"], "int"))); + $c = new xmlrpc_client("/server.php", "phpxmlrpc.sourceforge.net", 80); + $r = $c->send($m); + if (!$r->faultCode()) { + $v = $r->value(); + print "State number " . htmlentities($HTTP_POST_VARS["stateno"]) . " is " . + htmlentities($v->scalarval()) . "<BR>"; + print "<HR>I got this value back<BR><PRE>" . + htmlentities($r->serialize()) . "</PRE><HR>\n"; + } else { + print "Fault <BR>"; + print "Code: " . htmlentities($r->faultCode()) . "<BR>" . + "Reason: '" . htmlentities($r->faultString()) . "'<BR>"; + } + +---- + +=== Executing a multicall call + +To be documented... + + +[[faq]] + +[qanda] +== Frequently Asked Questions + +=== Hi + +==== How to send custom XML as payload of a method call:: + +Unfortunately, at the time the XML-RPC spec was designed, support + for namespaces in XML was not as ubiquitous as it is now. As a + consequence, no support was provided in the protocol for embedding XML + elements from other namespaces into an xmlrpc request. + +To send an XML "chunk" as payload of a method call or response, + two options are available: either send the complete XML block as a + string xmlrpc value, or as a base64 value. Since the '<' character in + string values is encoded as '&lt;' in the xml payload of the method + call, the XML string will not break the surrounding xmlrpc, unless + characters outside of the assumed character set are used. The second + method has the added benefits of working independently of the charset + encoding used for the xml to be transmitted, and preserving exactly + whitespace, whilst incurring in some extra message length and cpu load + (for carrying out the base64 encoding/decoding). + + +==== Is there any limitation on the size of the requests / responses that can be successfully sent?:: + +Yes. But I have no hard figure to give; it most likely will depend + on the version of PHP in usage and its configuration. + +Keep in mind that this library is not optimized for speed nor for + memory usage. Better alternatives exist when there are strict + requirements on throughput or resource usage, such as the php native + xmlrpc extension (see the PHP manual for more information). + +Keep in mind also that HTTP is probably not the best choice in + such a situation, and XML is a deadly enemy. CSV formatted data over + socket would be much more efficient. + +If you really need to move a massive amount of data around, and + you are crazy enough to do it using phpxmlrpc, your best bet is to + bypass usage of the xmlrpcval objects, at least in the decoding phase, + and have the server (or client) object return to the calling function + directly php values (see xmlrpc_client::return_type + and xmlrpc_server::functions_parameters_type for more + details). + + +==== My server (client) returns an error whenever the client (server) returns accented characters + +To be documented... + + +==== How to enable long-lasting method calls + +To be documented... + + +==== My client returns "XML-RPC Fault #2: Invalid return payload: enable debugging to examine incoming payload": what should I do? + +The response you are seeing is a default error response that the + client object returns to the php application when the server did not + respond to the call with a valid xmlrpc response. + +The most likely cause is that you are not using the correct URL + when creating the client object, or you do not have appropriate access + rights to the web page you are requesting, or some other common http + misconfiguration. + +To find out what the server is really returning to your client, + you have to enable the debug mode of the client, using + $client->setdebug(1); + + +==== How can I save to a file the xml of the xmlrpc responses received from servers? + +If what you need is to save the responses received from the server + as xml, you have two options: + +1- use the serialize() method on the response object. + + +[source, php] +---- + +$resp = $client->send($msg); +if (!$resp->faultCode()) + $data_to_be_saved = $resp->serialize(); + +---- + +Note that this will not be 100% accurate, since the xml generated + by the response object can be different from the xml received, + especially if there is some character set conversion involved, or such + (eg. if you receive an empty string tag as <string/>, serialize() + will output <string></string>), or if the server sent back + as response something invalid (in which case the xml generated client + side using serialize() will correspond to the error response generated + internally by the lib). + +2 - set the client object to return the raw xml received instead + of the decoded objects: + + +[source, php] +---- + +$client = new xmlrpc_client($url); +$client->return_type = 'xml'; +$resp = $client->send($msg); +if (!$resp->faultCode()) + $data_to_be_saved = $resp->value(); + +---- + +Note that using this method the xml response response will not be + parsed at all by the library, only the http communication protocol will + be checked. This means that xmlrpc responses sent by the server that + would have generated an error response on the client (eg. malformed xml, + responses that have faultcode set, etc...) now will not be flagged as + invalid, and you might end up saving not valid xml but random + junk... + + +==== Can I use the ms windows character set? + +If the data your application is using comes from a Microsoft + application, there are some chances that the character set used to + encode it is CP1252 (the same might apply to data received from an + external xmlrpc server/client, but it is quite rare to find xmlrpc + toolkits that encode to CP1252 instead of UTF8). It is a character set + which is "almost" compatible with ISO 8859-1, but for a few extra + characters. + +PHP-XMLRPC only supports the ISO 8859-1 and UTF8 character sets. + The net result of this situation is that those extra characters will not + be properly encoded, and will be received at the other end of the + XML-RPC transmission as "garbled data". Unfortunately the library cannot + provide real support for CP1252 because of limitations in the PHP 4 xml + parser. Luckily, we tried our best to support this character set anyway, + and, since version 2.2.1, there is some form of support, left commented + in the code. + +To properly encode outgoing data that is natively in CP1252, you + will have to uncomment all relative code in the file + __xmlrpc.inc__ (you can search for the string "1252"), + then set ++$$$GLOBALS['xmlrpc_internalencoding']='CP1252';$$++ + Please note that all incoming data will then be fed to your application + as UTF-8 to avoid any potential data loss. + + +==== Does the library support using cookies / http sessions? + +In short: yes, but a little coding is needed to make it + happen. + +The code below uses sessions to e.g. let the client store a value + on the server and retrieve it later. + +[source, php] +---- + +$resp = $client->send(new xmlrpcmsg('registervalue', array(new xmlrpcval('foo'), new xmlrpcval('bar')))); +if (!$resp->faultCode()) +{ + $cookies = $resp->cookies(); + if (array_key_exists('PHPSESSID', $cookies)) // nb: make sure to use the correct session cookie name + { + $session_id = $cookies['PHPSESSID']['value']; + + // do some other stuff here... + + $client->setcookie('PHPSESSID', $session_id); + $val = $client->send(new xmlrpcmsg('getvalue', array(new xmlrpcval('foo'))); + } +} + +---- + +Server-side sessions are handled normally like in any other + php application. Please see the php manual for more information about + sessions. + +NB: unlike web browsers, not all xmlrpc clients support usage of + http cookies. If you have troubles with sessions and control only the + server side of the communication, please check with the makers of the + xmlrpc client in use. + + +[[integration]] + +[appendix] +== Integration with the PHP xmlrpc extension + +To be documented more... + +In short: for the fastest execution possible, you can enable the php + native xmlrpc extension, and use it in conjunction with phpxmlrpc. The + following code snippet gives an example of such integration + + +[source, php] +---- + +/*** client side ***/ +$c = new xmlrpc_client('http://phpxmlrpc.sourceforge.net/server.php'); + +// tell the client to return raw xml as response value +$c->return_type = 'xml'; + +// let the native xmlrpc extension take care of encoding request parameters +$r = $c->send(xmlrpc_encode_request('examples.getStateName', $_POST['stateno'])); + +if ($r->faultCode()) + // HTTP transport error + echo 'Got error '.$r->faultCode(); +else +{ + // HTTP request OK, but XML returned from server not parsed yet + $v = xmlrpc_decode($r->value()); + // check if we got a valid xmlrpc response from server + if ($v === NULL) + echo 'Got invalid response'; + else + // check if server sent a fault response + if (xmlrpc_is_fault($v)) + echo 'Got xmlrpc fault '.$v['faultCode']; + else + echo'Got response: '.htmlentities($v); +} + +---- + + +[[substitution]] + +[appendix] +== Substitution of the PHP xmlrpc extension + +Yet another interesting situation is when you are using a ready-made + php application, that provides support for the XMLRPC protocol via the + native php xmlrpc extension, but the extension is not available on your + php install (e.g. because of shared hosting constraints). + +Since version 2.1, the PHP-XMLRPC library provides a compatibility + layer that aims to be 100% compliant with the xmlrpc extension API. This + means that any code written to run on the extension should obtain the + exact same results, albeit using more resources and a longer processing + time, using the PHP-XMLRPC library and the extension compatibility module. + The module is part of the EXTRAS package, available as a separate download + from the sourceforge.net website, since version 0.2 + + +[[enough]] + +[appendix] +== 'Enough of xmlrpcvals!': new style library usage + +To be documented... + +In the meantime, see docs about xmlrpc_client::return_type and + xmlrpc_server::functions_parameters_types, as well as php_xmlrpc_encode, + php_xmlrpc_decode and php_xmlrpc_decode_xml + + +[[debugger]] + +[appendix] +== Usage of the debugger + +A webservice debugger is included in the library to help during + development and testing. + +The interface should be self-explicative enough to need little + documentation. + +image::debugger.gif[,,,,align="center"] + +The most useful feature of the debugger is without doubt the "Show + debug info" option. It allows to have a screen dump of the complete http + communication between client and server, including the http headers as + well as the request and response payloads, and is invaluable when + troubleshooting problems with charset encoding, authentication or http + compression. + +The debugger can take advantage of the JSONRPC library extension, to + allow debugging of JSON-RPC webservices, and of the JS-XMLRPC library + visual editor to allow easy mouse-driven construction of the payload for + remote methods. Both components have to be downloaded separately from the + sourceforge.net web pages and copied to the debugger directory to enable + the extra functionality: + + +* to enable jsonrpc functionality, download the PHP-XMLRPC + EXTRAS package, and copy the file __jsonrpc.inc__ + either to the same directory as the debugger or somewhere in your + php include path + + +* to enable the visual value editing dialog, download the + JS-XMLRPC library, and copy somewhere in the web root files + __visualeditor.php__, + __visualeditor.css__ and the folders + __yui__ and __img__. Then edit the + debugger file __controller.php__ and set + appropriately the variable $editorpath. + + +[[news]] + +[appendix] +== Whats's new + +__Note:__ not all items the following list have + (yet) been fully documented, and some might not be present in any other + chapter in the manual. To find a more detailed description of new + functions and methods please take a look at the source code of the + library, which is quite thoroughly commented in phpdoc form. + +=== 4.0.0 + +...to be documented... + +=== 3.0.0 + +__Note:__ this is the last release of the library that will support PHP 5.1 and up. + Future releases will target php 5.3 as minimum supported version. + +* when using curl and keepalive, reset curl handle if we did not get back an http 200 response (eg a 302) + +* omit port on http 'Host' header if it is 80 + +* test suite allows interrogating https servers ignoring their certs + +* method setAcceptedCompression was failing to disable reception of compressed responses if the + client supported them + +=== 3.0.0 beta + +This is the first release of the library to only support PHP 5. + Some legacy code has been removed, and support for features such as + exceptions and dateTime objects introduced. + +The "beta" tag is meant to indicate the fact that the refactoring + has been more widespread than in precedent releases and that more + changes are likely to be introduced with time - the library is still + considered to be production quality. + +* improved: removed all usage of php functions deprecated in + php 5.3, usage of assign-by-ref when creating new objects + etc... + +* improved: add support for the <ex:nil/> tag used by + the apache library, both in input and output + +* improved: add support for dateTime + objects in both in php_xmlrpc_encode and as + parameter for constructor of + xmlrpcval + +* improved: add support for timestamps as parameter for + constructor of xmlrpcval + +* improved: add option 'dates_as_objects' to + php_xmlrpc_decode to return + dateTime objects for xmlrpc + datetimes + +* improved: add new method + SetCurlOptions to + xmrlpc_client to allow extra flexibility in + tweaking http config, such as explicitly binding to an ip + address + +* improved: add new method + SetUserAgent to + xmrlpc_client to to allow having different + user-agent http headers + +* improved: add a new member variable in server class to allow + fine-tuning of the encoding of returned values when the server is + in 'phpvals' mode + +* improved: allow servers in 'xmlrpcvals' mode to also + register plain php functions by defining them in the dispatch map + with an added option + +* improved: catch exceptions thrown during execution of php + functions exposed as methods by the server + +* fixed: bad encoding if same object is encoded twice using + php_xmlrpc_encode + +=== 2.2.2 + +__Note:__ this is the last release of the + library that will support PHP 4. Future releases (if any) should target + php 5.0 as minimum supported version. + +* fixed: encoding of utf-8 characters outside of the BMP + plane + +* fixed: character set declarations surrounded by double + quotes were not recognized in http headers + +* fixed: be more tolerant in detection of charset in http + headers + +* fixed: fix detection of zlib.output_compression + +* fixed: use feof() to test if socket connections are to be + closed instead of the number of bytes read (rare bug when + communicating with some servers) + +* fixed: format floating point values using the correct + decimal separator even when php locale is set to one that uses + comma + +* fixed: improve robustness of the debugger when parsing weird + results from non-compliant servers + +* php warning when receiving 'false' in a bool value + +* improved: allow the add_to_map server method to add docs for + single params too + +* improved: added the possibility to wrap for exposure as + xmlrpc methods plain php class methods, object methods and even + whole classes + +=== 2.2.1 + +* fixed: work aroung bug in php 5.2.2 which broke support of + HTTP_RAW_POST_DATA + +* fixed: is_dir parameter of setCaCertificate() method is + reversed + +* fixed: a php warning in xmlrpc_client creator method + +* fixed: parsing of '1e+1' as valid float + +* fixed: allow errorlevel 3 to work when prev. error handler was + a static method + +* fixed: usage of client::setcookie() for multiple cookies in + non-ssl mode + +* improved: support for CP1252 charset is not part or the + library but almost possible + +* improved: more info when curl is enabled and debug mode is + on +=== 2.2 + +* fixed: debugger errors on php installs with magic_quotes_gpc + on + +* fixed: support for https connections via proxy + +* fixed: wrap_xmlrpc_method() generated code failed to properly + encode php objects + +* improved: slightly faster encoding of data which is internally + UTF-8 + +* improved: debugger always generates a 'null' id for jsonrpc if + user omits it + +* new: debugger can take advantage of a graphical value builder + (it has to be downloaded separately, as part of jsxmlrpc package. + See Appendix D for more details) + +* new: support for the <NIL/> xmlrpc extension. see below + for more details + +* new: server support for the system.getCapabilities xmlrpc + extension + +* new: <<wrap_xmlrpc_method,wrap_xmlrpc_method()>> + accepts two new options: debug and return_on_fault + +=== 2.1 + +* The wrap_php_function and + wrap_xmlrpc_method functions have been moved + out of the base library file __xmlrpc.inc__ into + a file of their own: __$$xmlrpc_wrappers.php$$__. You + will have to include() / require() it in your scripts if you have + been using those functions. For increased security, the automatic + rebuilding of php object instances out of received xmlrpc structs + in wrap_xmlrpc_method() has been disabled + (but it can be optionally re-enabled). Both + wrap_php_function() and + wrap_xmlrpc_method() functions accept many + more options to fine tune their behaviour, including one to return + the php code to be saved and later used as standalone php + script + +* The constructor of xmlrpcval() values has seen some internal + changes, and it will not throw a php warning anymore when invoked + using an unknown xmlrpc type: the error will only be written to + php error log. Also ++$$new xmlrpcval('true', 'boolean')$$++ + is not supported anymore + +* The new function + php_xmlrpc_decode_xml() will take the xml + representation of either an xmlrpc request, response or single + value and return the corresponding php-xmlrpc object + instance + +* A new function wrap_xmlrpc_server()has + been added, to wrap all (or some) of the methods exposed by a + remote xmlrpc server into a php class + +* A new file has been added: + __$$verify_compat.php$$__, to help users diagnose the + level of compliance of their php installation with the + library + +* Restored compatibility with php 4.0.5 (for those poor souls + still stuck on it) + +* Method xmlrpc_server->service() + now returns a value: either the response payload or xmlrpcresp + object instance + +* Method + xmlrpc_server->add_to_map() now + accepts xmlrpc methods with no param definitions + +* Documentation for single parameters of exposed methods can + be added to the dispatch map (and turned into html docs in + conjunction with a future release of the 'extras' package) + +* Full response payload is saved into xmlrpcresp object for + further debugging + +* The debugger can now generate code that wraps a remote + method into a php function (works for jsonrpc, too); it also has + better support for being activated via a single GET call (e.g. for + integration into other tools) + +* Stricter parsing of incoming xmlrpc messages: two more + invalid cases are now detected (double ++data++ + element inside ++array++ and + ++struct++/++array++ after scalar + inside ++value++ element) + +* More logging of errors in a lot of situations + +* Javadoc documentation of lib files (almost) complete + +* Many performance tweaks and code cleanups, plus the usual + crop of bugs fixed (see NEWS file for complete list of + bugs) + +* Lib internals have been modified to provide better support + for grafting extra functionality on top of it. Stay tuned for + future releases of the EXTRAS package (or go read Appendix + B)... + +=== 2.0 final + +* Added to the client class the possibility to use Digest and + NTLM authentication methods (when using the CURL library) for + connecting to servers and NTLM for connecting to proxies + +* Added to the client class the possibility to specify + alternate certificate files/directories for authenticating the + peer with when using HTTPS communication + +* Reviewed all examples and added a new demo file, containing + a proxy to forward xmlrpc requests to other servers (useful e.g. + for ajax coding) + +* The debugger has been upgraded to reflect the new client + capabilities + +* All known bugs have been squashed, and the lib is more + tolerant than ever of commonly-found mistakes + +=== 2.0 Release candidate 3 + +* Added to server class the property + functions_parameters_type, that allows the + server to register plain php functions as xmlrpc methods (i.e. + functions that do not take an xmlrpcmsg object as unique + param) + +* let server and client objects serialize calls using a + specified character set encoding for the produced xml instead of + US-ASCII (ISO-8859-1 and UTF-8 supported) + +* let php_xmlrpc_decode accept xmlrpcmsg objects as valid + input + +* 'class::method' syntax is now accepted in the server + dispatch map + +* xmlrpc_clent::SetDebug() accepts + integer values instead of a boolean value, with debugging level 2 + adding to the information printed to screen the complete client + request + +=== 2.0 Release candidate 2 + +* Added a new property of the client object: + ++$$xmlrpc_client->return_type$$++, indicating whether + calls to the send() method will return xmlrpcresp objects whose + value() is an xmlrpcval object, a php value (automatically + decoded) or the raw xml received from the server. + +* Added in the extras dir. two new library file: + __jsonrpc.inc__ and + __jsonrpcs.inc__ containing new classes that + implement support for the json-rpc protocol (alpha quality + code) + +* Added a new client method: ++setKey($key, + $keypass)++ to be used in HTTPS connections + +* Added a new file containing some benchmarks in the testsuite + directory + +=== 2.0 Release candidate 1 + +* Support for HTTP proxies (new method: + ++$$xmlrpc_client::setProxy()$$++) + +* Support HTTP compression of both requests and responses. + Clients can specify what kind of compression they accept for + responses between deflate/gzip/any, and whether to compress the + requests. Servers by default compress responses to clients that + explicitly declare support for compression (new methods: + ++$$xmlrpc_client::setAcceptedCompression()$$++, + ++$$xmlrpc_client::setRequestCompression()$$++). Note that the + ZLIB php extension needs to be enabled in PHP to support + compression. + +* Implement HTTP 1.1 connections, but only if CURL is enabled + (added an extra parameter to + ++$$xmlrpc_client::xmlrpc_client$$++ to set the desired HTTP + protocol at creation time and a new supported value for the last + parameter of ++$$xmlrpc_client::send$$++, which now can be + safely omitted if it has been specified at creation time) ++ +With PHP versions greater than 4.3.8 keep-alives are enabled + by default for HTTP 1.1 connections. This should yield faster + execution times when making multiple calls in sequence to the same + xml-rpc server from a single client. + +* Introduce support for cookies. Cookies to be sent to the + server with a request can be set using + ++$$xmlrpc_client::setCookie()$$++, while cookies received from + the server are found in ++xmlrpcresp::cookies()++. It is + left to the user to check for validity of received cookies and + decide whether they apply to successive calls or not. + +* Better support for detecting different character set encodings + of xml-rpc requests and responses: both client and server objects + will correctly detect the charset encoding of received xml, and use + an appropriate xml parser. ++ +Supported encodings are US-ASCII, UTF-8 and ISO-8859-1. + +* Added one new xmlrpcmsg constructor syntax, allowing usage of + a single string with the complete URL of the target server + +* Convert xml-rpc boolean values into native php values instead + of 0 and 1 + +* Force the ++$$php_xmlrpc_encode$$++ function to properly + encode numerically indexed php arrays into xml-rpc arrays + (numerically indexed php arrays always start with a key of 0 and + increment keys by values of 1) + +* Prevent the ++$$php_xmlrpc_encode$$++ function from + further re-encoding any objects of class ++xmlrpcval++ that + are passed to it. This allows to call the function with arguments + consisting of mixed php values / xmlrpcval objects. + +* Allow a server to NOT respond to system.* method calls + (setting the ++$$$server->allow_system_funcs$$++ + property). + +* Implement a new xmlrpcval method to determine if a value of + type struct has a member of a given name without having to loop + trough all members: ++xmlrpcval::structMemExists()++ + +* Expand methods ++xmlrpcval::addArray++, + ++addScalar++ and ++addStruct++ allowing extra php + values to be added to xmlrpcval objects already formed. + +* Let the ++$$xmlrpc_client::send$$++ method accept an XML + string for sending instead of an xmlrpcmsg object, to facilitate + debugging and integration with the php native xmlrpc + extension + +* Extend the ++$$php_xmlrpc_encode$$++ and + ++$$php_xmlrpc_decode$$++ functions to allow serialization and + rebuilding of PHP objects. To successfully rebuild a serialized + object, the object class must be defined in the deserializing end of + the transfer. Note that object members of type resource will be + deserialized as NULL values. ++ +Note that his has been implemented adding a "php_class" + attribute to xml representation of xmlrpcval of STRUCT type, which, + strictly speaking, breaks the xml-rpc spec. Other xmlrpc + implementations are supposed to ignore such an attribute (unless + they implement a brain-dead custom xml parser...), so it should be + safe enabling it in heterogeneous environments. The activation of + this feature is done by usage of an option passed as second + parameter to both ++$$php_xmlrpc_encode$$++ and + ++$$php_xmlrpc_decode$$++. + +* Extend the ++$$php_xmlrpc_encode$$++ function to allow + automatic serialization of iso8601-conforming php strings as + datetime.iso8601 xmlrpcvals, by usage of an optional + parameter + +* Added an automatic stub code generator for converting xmlrpc + methods to php functions and vice-versa. ++ +This is done via two new functions: + ++$$wrap_php_function$$++ and ++$$wrap_xmlrpc_method$$++, + and has many caveats, with php being a typeless language and + all... + +* Allow object methods to be used in server dispatch map + +* Added a complete debugger solution, in the + __debugger__ folder + +* Added configurable server-side debug messages, controlled by + the new method ++$$xmlrpc_server::SetDebug()$$++. 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 more info is echoed back to the + client, regarding the received call; at level 3 all warnings raised + during server processing are trapped (this prevents breaking the xml + to be echoed back to the client) and added to the debug info sent + back to the client + +* New XML parsing code, yields smaller memory footprint and + faster execution times, not to mention complete elimination of the + dreaded __eval()__ construct, so prone to code + injection exploits + +* Rewritten most of the error messages, making text more + explicative + +++++++++++++++++++++++++++++++++++++++ +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:nil +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:2 +sgml-indent-data:t +sgml-parent-document:nil +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +sgml-namecase-general:t +sgml-general-insert-case:lower +End: +--> +++++++++++++++++++++++++++++++++++++++ diff --git a/doc/manual/phpxmlrpc_manual.xml b/doc/manual/phpxmlrpc_manual.xml deleted file mode 100644 index 5c69ba7..0000000 --- a/doc/manual/phpxmlrpc_manual.xml +++ /dev/null @@ -1,4274 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<?xml-stylesheet href="css-docbook/driver.css" type="text/css"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" -"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<!-- -PHP-XMLRPC User manual ---> -<book lang="en"> - <title>XML-RPC for PHP - - version 3.0.0 - - - June 15, 2014 - - - - Edd - - Dumbill - - - - Gaetano - - Giunta - - - - Miles - - Lott - - - - Justin R. - - Miller - - - - Andres - - Salomon - - - - - 1999,2000,2001 - - Edd Dumbill, Useful Information Company - - - - All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions are - met: - - - - Redistributions of source code must retain the above - copyright notice, this list of conditions and the following - disclaimer. - - - - Redistributions in binary form must reproduce the above - copyright notice, this list of conditions and the following - disclaimer in the documentation and/or other materials provided - with the distribution. - - - - Neither the name of the "XML-RPC for PHP" nor the names of - its contributors may be used to endorse or promote products - derived from this software without specific prior written - permission. - - - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND - CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, - BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND - FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE - REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED - TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR - PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF - LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING - NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS - SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - - - - - Introduction - - XML-RPC is a format devised by Userland Software for achieving - remote procedure call via XML using HTTP as the transport. XML-RPC has its - own web site, www.xmlrpc.com - - This collection of PHP classes provides a framework for writing - XML-RPC clients and servers in PHP. - - Main goals of the project are ease of use, flexibility and - completeness. - - The original author is Edd Dumbill of Useful Information Company. As of the - 1.0 stable release, the project was opened to wider involvement and moved - to SourceForge; later, to Github - - A list of XML-RPC implementations for other languages such as Perl - and Python can be found on the www.xmlrpc.com site. - - - Acknowledgements - - Daniel E. Baumann - - James Bercegay - - Leon Blackwell - - Stephane Bortzmeyer - - Daniel Convissor - - Geoffrey T. Dairiki - - Stefan Esser - - James Flemer - - Ernst de Haan - - Tom Knight - - Axel Kollmorgen - - Peter Kocks - - Daniel Krippner - - S. Kuip - - A. Lambert - - Frederic Lecointre - - Dan Libby - - Arnaud Limbourg - - Ernest MacDougal Campbell III - - Lukasz Mach - - Kjartan Mannes - - Ben Margolin - - Nicolay Mausz - - Justin Miller - - Jan Pfeifer - - Giancarlo Pinerolo - - Peter Russel - - Jean-Jacques Sarton - - Viliam Simko - - Idan Sofer - - Douglas Squirrel - - Heiko Stübner - - Anatoly Techtonik - - Tommaso Trani - - Eric van der Vlist - - Christian Wenz - - Jim Winstead - - Przemyslaw Wroblewski - - Bruno Zanetti Melotti - - - - - What's new - - Note: not all items the following list have - (yet) been fully documented, and some might not be present in any other - chapter in the manual. To find a more detailed description of new - functions and methods please take a look at the source code of the - library, which is quite thoroughly commented in javadoc-like form. - - - 3.0.0 - - Note: this is the last release of the library that will support PHP 5.1 and up. - Future releases will target php 5.3 as minimum supported version. - - - - when using curl and keepalive, reset curl handle if we did not get back an http 200 response (eg a 302) - - - - omit port on http 'Host' header if it is 80 - - - - test suite allows interrogating https servers ignoring their certs - - - - method setAcceptedCompression was failing to disable reception of compressed responses if the - client supported them - - - - - - - 3.0.0 beta - - This is the first release of the library to only support PHP 5. - Some legacy code has been removed, and support for features such as - exceptions and dateTime objects introduced. - - The "beta" tag is meant to indicate the fact that the refactoring - has been more widespread than in precedent releases and that more - changes are likely to be introduced with time - the library is still - considered to be production quality. - - - - improved: removed all usage of php functions deprecated in - php 5.3, usage of assign-by-ref when creating new objects - etc... - - - - improved: add support for the <ex:nil/> tag used by - the apache library, both in input and output - - - - improved: add support for dateTime - objects in both in php_xmlrpc_encode and as - parameter for constructor of - xmlrpcval - - - - improved: add support for timestamps as parameter for - constructor of xmlrpcval - - - - improved: add option 'dates_as_objects' to - php_xmlrpc_decode to return - dateTime objects for xmlrpc - datetimes - - - - improved: add new method - SetCurlOptions to - xmrlpc_client to allow extra flexibility in - tweaking http config, such as explicitly binding to an ip - address - - - - improved: add new method - SetUserAgent to - xmrlpc_client to to allow having different - user-agent http headers - - - - improved: add a new member variable in server class to allow - fine-tuning of the encoding of returned values when the server is - in 'phpvals' mode - - - - improved: allow servers in 'xmlrpcvals' mode to also - register plain php functions by defining them in the dispatch map - with an added option - - - - improved: catch exceptions thrown during execution of php - functions exposed as methods by the server - - - - fixed: bad encoding if same object is encoded twice using - php_xmlrpc_encode - - - - - - 2.2.2 - - Note: this might the last release of the - library that will support PHP 4. Future releases (if any) should target - php 5.0 as minimum supported version. - - - - fixed: encoding of utf-8 characters outside of the BMP - plane - - - - fixed: character set declarations surrounded by double - quotes were not recognized in http headers - - - - fixed: be more tolerant in detection of charset in http - headers - - - - fixed: fix detection of zlib.output_compression - - - - fixed: use feof() to test if socket connections are to be - closed instead of the number of bytes read (rare bug when - communicating with some servers) - - - - fixed: format floating point values using the correct - decimal separator even when php locale is set to one that uses - comma - - - - fixed: improve robustness of the debugger when parsing weird - results from non-compliant servers - - - - php warning when receiving 'false' in a bool value - - - - improved: allow the add_to_map server method to add docs for - single params too - - - - improved: added the possibility to wrap for exposure as - xmlrpc methods plain php class methods, object methods and even - whole classes - - - - - - 2.2.1 - - - - fixed: work aroung bug in php 5.2.2 which broke support of - HTTP_RAW_POST_DATA - - - - fixed: is_dir parameter of setCaCertificate() method is - reversed - - - - fixed: a php warning in xmlrpc_client creator method - - - - fixed: parsing of '1e+1' as valid float - - - - fixed: allow errorlevel 3 to work when prev. error handler was - a static method - - - - fixed: usage of client::setcookie() for multiple cookies in - non-ssl mode - - - - improved: support for CP1252 charset is not part or the - library but almost possible - - - - improved: more info when curl is enabled and debug mode is - on - - - - - - 2.2 - - - - fixed: debugger errors on php installs with magic_quotes_gpc - on - - - - fixed: support for https connections via proxy - - - - fixed: wrap_xmlrpc_method() generated code failed to properly - encode php objects - - - - improved: slightly faster encoding of data which is internally - UTF-8 - - - - improved: debugger always generates a 'null' id for jsonrpc if - user omits it - - - - new: debugger can take advantage of a graphical value builder - (it has to be downloaded separately, as part of jsxmlrpc package. - See Appendix D for more details) - - - - new: support for the <NIL/> xmlrpc extension. see below - for more details - - - - new: server support for the system.getCapabilities xmlrpc - extension - - - - new: wrap_xmlrpc_method() - accepts two new options: debug and return_on_fault - - - - - - 2.1 - - - - The wrap_php_function and - wrap_xmlrpc_method functions have been moved - out of the base library file xmlrpc.inc into - a file of their own: xmlrpc_wrappers.php. You - will have to include() / require() it in your scripts if you have - been using those functions. For increased security, the automatic - rebuilding of php object instances out of received xmlrpc structs - in wrap_xmlrpc_method() has been disabled - (but it can be optionally re-enabled). Both - wrap_php_function() and - wrap_xmlrpc_method() functions accept many - more options to fine tune their behaviour, including one to return - the php code to be saved and later used as standalone php - script - - - - The constructor of xmlrpcval() values has seen some internal - changes, and it will not throw a php warning anymore when invoked - using an unknown xmlrpc type: the error will only be written to - php error log. Also new xmlrpcval('true', 'boolean') - is not supported anymore - - - - The new function - php_xmlrpc_decode_xml() will take the xml - representation of either an xmlrpc request, response or single - value and return the corresponding php-xmlrpc object - instance - - - - A new function wrap_xmlrpc_server()has - been added, to wrap all (or some) of the methods exposed by a - remote xmlrpc server into a php class - - - - A new file has been added: - verify_compat.php, to help users diagnose the - level of compliance of their php installation with the - library - - - - Restored compatibility with php 4.0.5 (for those poor souls - still stuck on it) - - - - Method xmlrpc_server->service() - now returns a value: either the response payload or xmlrpcresp - object instance - - - - Method - xmlrpc_server->add_to_map() now - accepts xmlrpc methods with no param definitions - - - - Documentation for single parameters of exposed methods can - be added to the dispatch map (and turned into html docs in - conjunction with a future release of the 'extras' package) - - - - Full response payload is saved into xmlrpcresp object for - further debugging - - - - The debugger can now generate code that wraps a remote - method into a php function (works for jsonrpc, too); it also has - better support for being activated via a single GET call (e.g. for - integration into other tools) - - - - Stricter parsing of incoming xmlrpc messages: two more - invalid cases are now detected (double data - element inside array and - struct/array after scalar - inside value element) - - - - More logging of errors in a lot of situations - - - - Javadoc documentation of lib files (almost) complete - - - - Many performance tweaks and code cleanups, plus the usual - crop of bugs fixed (see NEWS file for complete list of - bugs) - - - - Lib internals have been modified to provide better support - for grafting extra functionality on top of it. Stay tuned for - future releases of the EXTRAS package (or go read Appendix - B)... - - - - - - 2.0 final - - - - Added to the client class the possibility to use Digest and - NTLM authentication methods (when using the CURL library) for - connecting to servers and NTLM for connecting to proxies - - - - Added to the client class the possibility to specify - alternate certificate files/directories for authenticating the - peer with when using HTTPS communication - - - - Reviewed all examples and added a new demo file, containing - a proxy to forward xmlrpc requests to other servers (useful e.g. - for ajax coding) - - - - The debugger has been upgraded to reflect the new client - capabilities - - - - All known bugs have been squashed, and the lib is more - tolerant than ever of commonly-found mistakes - - - - - - 2.0 Release candidate 3 - - - - Added to server class the property - functions_parameters_type, that allows the - server to register plain php functions as xmlrpc methods (i.e. - functions that do not take an xmlrpcmsg object as unique - param) - - - - let server and client objects serialize calls using a - specified character set encoding for the produced xml instead of - US-ASCII (ISO-8859-1 and UTF-8 supported) - - - - let php_xmlrpc_decode accept xmlrpcmsg objects as valid - input - - - - 'class::method' syntax is now accepted in the server - dispatch map - - - - xmlrpc_clent::SetDebug() accepts - integer values instead of a boolean value, with debugging level 2 - adding to the information printed to screen the complete client - request - - - - - - 2.0 Release candidate 2 - - - - Added a new property of the client object: - xmlrpc_client->return_type, indicating whether - calls to the send() method will return xmlrpcresp objects whose - value() is an xmlrpcval object, a php value (automatically - decoded) or the raw xml received from the server. - - - - Added in the extras dir. two new library file: - jsonrpc.inc and - jsonrpcs.inc containing new classes that - implement support for the json-rpc protocol (alpha quality - code) - - - - Added a new client method: setKey($key, - $keypass) to be used in HTTPS connections - - - - Added a new file containing some benchmarks in the testsuite - directory - - - - - - 2.0 Release candidate 1 - - - - Support for HTTP proxies (new method: - xmlrpc_client::setProxy()) - - - - Support HTTP compression of both requests and responses. - Clients can specify what kind of compression they accept for - responses between deflate/gzip/any, and whether to compress the - requests. Servers by default compress responses to clients that - explicitly declare support for compression (new methods: - xmlrpc_client::setAcceptedCompression(), - xmlrpc_client::setRequestCompression()). Note that the - ZLIB php extension needs to be enabled in PHP to support - compression. - - - - Implement HTTP 1.1 connections, but only if CURL is enabled - (added an extra parameter to - xmlrpc_client::xmlrpc_client to set the desired HTTP - protocol at creation time and a new supported value for the last - parameter of xmlrpc_client::send, which now can be - safely omitted if it has been specified at creation time) - - With PHP versions greater than 4.3.8 keep-alives are enabled - by default for HTTP 1.1 connections. This should yield faster - execution times when making multiple calls in sequence to the same - xml-rpc server from a single client. - - - - Introduce support for cookies. Cookies to be sent to the - server with a request can be set using - xmlrpc_client::setCookie(), while cookies received from - the server are found in xmlrpcresp::cookies(). It is - left to the user to check for validity of received cookies and - decide whether they apply to successive calls or not. - - - - Better support for detecting different character set encodings - of xml-rpc requests and responses: both client and server objects - will correctly detect the charset encoding of received xml, and use - an appropriate xml parser. - - Supported encodings are US-ASCII, UTF-8 and ISO-8859-1. - - - - Added one new xmlrpcmsg constructor syntax, allowing usage of - a single string with the complete URL of the target server - - - - Convert xml-rpc boolean values into native php values instead - of 0 and 1 - - - - Force the php_xmlrpc_encode function to properly - encode numerically indexed php arrays into xml-rpc arrays - (numerically indexed php arrays always start with a key of 0 and - increment keys by values of 1) - - - - Prevent the php_xmlrpc_encode function from - further re-encoding any objects of class xmlrpcval that - are passed to it. This allows to call the function with arguments - consisting of mixed php values / xmlrpcval objects. - - - - Allow a server to NOT respond to system.* method calls - (setting the $server->allow_system_funcs - property). - - - - Implement a new xmlrpcval method to determine if a value of - type struct has a member of a given name without having to loop - trough all members: xmlrpcval::structMemExists() - - - - Expand methods xmlrpcval::addArray, - addScalar and addStruct allowing extra php - values to be added to xmlrpcval objects already formed. - - - - Let the xmlrpc_client::send method accept an XML - string for sending instead of an xmlrpcmsg object, to facilitate - debugging and integration with the php native xmlrpc - extension - - - - Extend the php_xmlrpc_encode and - php_xmlrpc_decode functions to allow serialization and - rebuilding of PHP objects. To successfully rebuild a serialized - object, the object class must be defined in the deserializing end of - the transfer. Note that object members of type resource will be - deserialized as NULL values. - - Note that his has been implemented adding a "php_class" - attribute to xml representation of xmlrpcval of STRUCT type, which, - strictly speaking, breaks the xml-rpc spec. Other xmlrpc - implementations are supposed to ignore such an attribute (unless - they implement a brain-dead custom xml parser...), so it should be - safe enabling it in heterogeneous environments. The activation of - this feature is done by usage of an option passed as second - parameter to both php_xmlrpc_encode and - php_xmlrpc_decode. - - - - Extend the php_xmlrpc_encode function to allow - automatic serialization of iso8601-conforming php strings as - datetime.iso8601 xmlrpcvals, by usage of an optional - parameter - - - - Added an automatic stub code generator for converting xmlrpc - methods to php functions and vice-versa. - - This is done via two new functions: - wrap_php_function and wrap_xmlrpc_method, - and has many caveats, with php being a typeless language and - all... - - - - Allow object methods to be used in server dispatch map - - - - Added a complete debugger solution, in the - debugger folder - - - - Added configurable server-side debug messages, controlled by - the new method xmlrpc_server::SetDebug(). 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 more info is echoed back to the - client, regarding the received call; at level 3 all warnings raised - during server processing are trapped (this prevents breaking the xml - to be echoed back to the client) and added to the debug info sent - back to the client - - - - New XML parsing code, yields smaller memory footprint and - faster execution times, not to mention complete elimination of the - dreaded eval() construct, so prone to code - injection exploits - - - - Rewritten most of the error messages, making text more - explicative - - - - - - - System Requirements - - The library has been designed with goals of scalability and backward - compatibility. As such, it supports a wide range of PHP installs. Note - that not all features of the lib are available in every - configuration. - - The minimum supported PHP version is - 5.3. - - If you wish to use SSL or HTTP 1.1 to communicate with remote - servers, you need the "curl" extension compiled into your PHP - installation. - - The "xmlrpc" native extension is not required to be compiled into - your PHP installation, but if it is, there will be no interference with - the operation of this library. - - - - Files in the distribution - - - - lib/xmlrpc.inc - - - the XML-RPC classes. include() this in - your PHP files to use the classes. - - - - - lib/xmlrpcs.inc - - - the XML-RPC server class. include() this - in addition to xmlrpc.inc to get server functionality - - - - - lib/xmlrpc_wrappers.php - - - helper functions to "automagically" convert plain php - functions to xmlrpc services and vice versa - - - - - demo/server/proxy.php - - - a sample server implementing xmlrpc proxy - functionality. - - - - - demo/server/server.php - - - a sample server hosting various demo functions, as well as a - full suite of functions used for interoperability testing. It is - used by testsuite.php (see below) for unit testing the library, and - is not to be copied literally into your production servers - - - - - demo/client/client.php, demo/client/agesort.php, - demo/client/which.php - - - client code to exercise some of the functions in server.php, - including the interopEchoTests.whichToolkit - method. - - - - - demo/client/wrap.php - - - client code to illustrate 'wrapping' of remote methods into - php functions. - - - - - demo/client/introspect.php - - - client code to illustrate usage of introspection capabilities - offered by server.php. - - - - - demo/client/mail.php - - - client code to illustrate usage of an xmlrpc-to-email gateway - using Dave Winer's XML-RPC server at userland.com. - - - - - demo/client/zopetest.php - - - example client code that queries an xmlrpc server built in - Zope. - - - - - demo/vardemo.php - - - examples of how to construct xmlrpcval types - - - - - demo/demo1.xml, demo/demo2.xml, demo/demo3.xml - - - XML-RPC responses captured in a file for testing purposes (you - can use these to test the - xmlrpcmsg->parseResponse() method). - - - - - demo/server/discuss.php, - demo/client/comment.php - - - Software used in the PHP chapter of to provide a comment server and allow the - attachment of comments to stories from Meerkat's data store. - - - - - test/testsuite.php, test/parse_args.php - - - A unit test suite for this software package. If you do - development on this software, please consider submitting tests for - this suite. - - - - - test/benchmark.php - - - A (very limited) benchmarking suite for this software package. - If you do development on this software, please consider submitting - benchmarks for this suite. - - - - - test/phpunit.php, test/PHPUnit/*.php - - - An (incomplete) version PEAR's unit test framework for PHP. - The complete package can be found at http://pear.php.net/package/PHPUnit - - - - - test/verify_compat.php - - - Script designed to help the user to verify the level of - compatibility of the library with the current php install - - - - - extras/test.pl, extras/test.py - - - Perl and Python programs to exercise server.php to test that - some of the methods work. - - - - - extras/workspace.testPhpServer.fttb - - - Frontier scripts to exercise the demo server. Thanks to Dave - Winer for permission to include these. See Dave's - announcement of these. - - - - - extras/rsakey.pem - - - A test certificate key for the SSL support, which can be used - to generate dummy certificates. It has the passphrase "test." - - - - - - - Known bugs and limitations - - This started out as a bare framework. Many "nice" bits haven't been - put in yet. Specifically, very little type validation or coercion has been - put in. PHP being a loosely-typed language, this is going to have to be - done explicitly (in other words: you can call a lot of library functions - passing them arguments of the wrong type and receive an error message only - much further down the code, where it will be difficult to - understand). - - dateTime.iso8601 is supported opaquely. It can't be done natively as - the XML-RPC specification explicitly forbids passing of timezone - specifiers in ISO8601 format dates. You can, however, use the and functions - to do the encoding and decoding for you. - - Very little HTTP response checking is performed (e.g. HTTP redirects - are not followed and the Content-Length HTTP header, mandated by the - xml-rpc spec, is not validated); cookie support still involves quite a bit - of coding on the part of the user. - - If a specific character set encoding other than US-ASCII, ISO-8859-1 - or UTF-8 is received in the HTTP header or XML prologue of xml-rpc request - or response messages then it will be ignored for the moment, and the - content will be parsed as if it had been encoded using the charset defined - by - - Support for receiving from servers version 1 cookies (i.e. - conforming to RFC 2965) is quite incomplete, and might cause unforeseen - errors. - - - - Support - - - Online Support - - XML-RPC for PHP is offered "as-is" without any warranty or - commitment to support. However, informal advice and help is available - via the XML-RPC for PHP website and mailing list and from - XML-RPC.com. - - - - The XML-RPC for PHP development is hosted - on github.com/gggeek/phpxmlrpc. - Bugs, feature requests and patches can be posted to the project's - website. - - - - The PHP XML-RPC interest mailing list is - run by the author. More details can be - found here. - - - - For more general XML-RPC questions, there is a Yahoo! Groups - XML-RPC mailing - list. - - - - The XML-RPC.com discussion - group is a useful place to get help with using XML-RPC. This group - is also gatewayed into the Yahoo! Groups mailing list. - - - - - - The Jellyfish Book - - Together with Simon St.Laurent and Joe - Johnston, Edd Dumbill wrote a book on XML-RPC for O'Reilly and - Associates on XML-RPC. It features a rather fetching jellyfish on the - cover. - - Complete details of the book are available from - O'Reilly's web site. - - Edd is responsible for the chapter on PHP, which includes a worked - example of creating a forum server, and hooking it up the O'Reilly's - Meerkat service in - order to allow commenting on news stories from around the Web. - - If you've benefited from the effort that has been put into writing - this software, then please consider buying the book! - - - - - Class documentation - - - xmlrpcval - - This is where a lot of the hard work gets done. This class enables - the creation and encapsulation of values for XML-RPC. - - Ensure you've read the XML-RPC spec at http://www.xmlrpc.com/stories/storyReader$7 - before reading on as it will make things clearer. - - The xmlrpcval class can store arbitrarily - complicated values using the following types: i4 int boolean - string double dateTime.iso8601 base64 array struct - null. You should refer to the spec for more information on - what each of these types mean. - - - Notes on types - - - int - - The type i4 is accepted as a synonym - for int when creating xmlrpcval objects. The - xml parsing code will always convert i4 to - int: int is regarded - by this implementation as the canonical name for this type. - - - - base64 - - Base 64 encoding is performed transparently to the caller when - using this type. Decoding is also transparent. Therefore you ought - to consider it as a "binary" data type, for use when you want to - pass data that is not 7-bit clean. - - - - boolean - - The php values true and - 1 map to true. All other - values (including the empty string) are converted to - false. - - - - string - - Characters <, >, ', ", &, are encoded using their - entity reference as &lt; &gt; &apos; &quot; and - &amp; All other characters outside of the ASCII range are - encoded using their character reference representation (e.g. - &#200 for é). The XML-RPC spec recommends only encoding - < & but this implementation goes further, - for reasons explained by the XML 1.0 - recommendation. In particular, using character reference - representation has the advantage of producing XML that is valid - independently of the charset encoding assumed. - - - - null - - There is no support for encoding null - values in the XML-RPC spec, but at least a couple of extensions (and - many toolkits) do support it. Before using null - values in your messages, make sure that the responding party accepts - them, and uses the same encoding convention (see ...). - - - - - Creation - - The constructor is the normal way to create an - xmlrpcval. The constructor can take these - forms: - - - - xmlrpcvalnew - xmlrpcval - - - - - - xmlrpcvalnew - xmlrpcval - - string$stringVal - - - - xmlrpcvalnew - xmlrpcval - - mixed$scalarVal - - string$scalartyp - - - - xmlrpcvalnew - xmlrpcval - - array$arrayVal - - string$arraytyp - - - - The first constructor creates an empty value, which must be - altered using the methods addScalar, - addArray or addStruct before - it can be used. - - The second constructor creates a simple string value. - - The third constructor is used to create a scalar value. The - second parameter must be a name of an XML-RPC type. Valid types are: - "int", "boolean", - "string", "double", - "dateTime.iso8601", "base64" or - "null". - - Examples: - - -$myInt = new xmlrpcval(1267, "int"); -$myString = new xmlrpcval("Hello, World!", "string"); -$myBool = new xmlrpcval(1, "boolean"); -$myString2 = new xmlrpcval(1.24, "string"); // note: this will serialize a php float value as xmlrpc string - - - The fourth constructor form can be used to compose complex - XML-RPC values. The first argument is either a simple array in the - case of an XML-RPC array or an associative - array in the case of a struct. The elements of - the array must be xmlrpcval objects - themselves. - - The second parameter must be either "array" - or "struct". - - Examples: - - -$myArray = new xmlrpcval( - array( - new xmlrpcval("Tom"), - new xmlrpcval("Dick"), - new xmlrpcval("Harry") - ), - "array"); - -// recursive struct -$myStruct = new xmlrpcval( - array( - "name" => new xmlrpcval("Tom", "string"), - "age" => new xmlrpcval(34, "int"), - "address" => new xmlrpcval( - array( - "street" => new xmlrpcval("Fifht Ave", "string"), - "city" => new xmlrpcval("NY", "string") - ), - "struct") - ), - "struct"); - - - See the file vardemo.php in this distribution - for more examples. - - - - Methods - - - addScalar - - - - intaddScalar - - string$stringVal - - - - intaddScalar - - mixed$scalarVal - - string$scalartyp - - - - If $val is an empty - xmlrpcval this method makes it a scalar - value, and sets that value. - - If $val is already a scalar value, then - no more scalars can be added and 0 is - returned. - - If $val is an xmlrpcval of type array, - the php value $scalarval is added as its last - element. - - If all went OK, 1 is returned, otherwise - 0. - - - - addArray - - - - intaddArray - - array$arrayVal - - - - The argument is a simple (numerically indexed) array. The - elements of the array must be - xmlrpcval objects - themselves. - - Turns an empty xmlrpcval into an - array with contents as specified by - $arrayVal. - - If $val is an xmlrpcval of type array, - the elements of $arrayVal are appended to the - existing ones. - - See the fourth constructor form for more information. - - If all went OK, 1 is returned, otherwise - 0. - - - - addStruct - - - - intaddStruct - - array$assocArrayVal - - - - The argument is an associative array. The elements of the - array must be xmlrpcval objects - themselves. - - Turns an empty xmlrpcval into a - struct with contents as specified by - $assocArrayVal. - - If $val is an xmlrpcval of type struct, - the elements of $arrayVal are merged with the - existing ones. - - See the fourth constructor form for more information. - - If all went OK, 1 is returned, otherwise - 0. - - - - kindOf - - - - stringkindOf - - - - - - Returns a string containing "struct", "array" or "scalar" - describing the base type of the value. If it returns "undef" it - means that the value hasn't been initialised. - - - - serialize - - - - stringserialize - - - - - - Returns a string containing the XML-RPC representation of this - value. - - - - scalarVal - - - - mixedscalarVal - - - - - - If $val->kindOf() == "scalar", this - method returns the actual PHP-language value of the scalar (base 64 - decoding is automatically handled here). - - - - scalarTyp - - - - stringscalarTyp - - - - - - If $val->kindOf() == "scalar", this - method returns a string denoting the type of the scalar. As - mentioned before, i4 is always coerced to - int. - - - - arrayMem - - - - xmlrpcvalarrayMem - - int$n - - - - If $val->kindOf() == "array", returns - the $nth element in the array represented by - the value $val. The value returned is an - xmlrpcval object. - - -// iterating over values of an array object -for ($i = 0; $i < $val->arraySize(); $i++) -{ - $v = $val->arrayMem($i); - echo "Element $i of the array is of type ".$v->kindOf(); -} - - - - - arraySize - - - - intarraySize - - - - - - If $val is an - array, returns the number of elements in that - array. - - - - structMem - - - - xmlrpcvalstructMem - - string$memberName - - - - If $val->kindOf() == "struct", returns - the element called $memberName from the - struct represented by the value $val. The - value returned is an xmlrpcval object. - - - - structEach - - - - arraystructEach - - - - - - Returns the next (key, value) pair from the struct, when - $val is a struct. - $value is an xmlrpcval itself. See also . - - -// iterating over all values of a struct object -$val->structreset(); -while (list($key, $v) = $val->structEach()) -{ - echo "Element $key of the struct is of type ".$v->kindOf(); -} - - - - - structReset - - - - voidstructReset - - - - - - Resets the internal pointer for - structEach() to the beginning of the struct, - where $val is a struct. - - - - structMemExists - - - - boolstructMemExsists - - string$memberName - - - - Returns TRUE or - FALSE depending on whether a member of the - given name exists in the struct. - - - - - - xmlrpcmsg - - This class provides a representation for a request to an XML-RPC - server. A client sends an xmlrpcmsg to a server, - and receives back an xmlrpcresp (see ). - - - Creation - - The constructor takes the following forms: - - - - xmlrpcmsgnew - xmlrpcmsg - - string$methodName - - array$parameterArraynull - - - - Where methodName is a string indicating - the name of the method you wish to invoke, and - parameterArray is a simple php - Array of xmlrpcval - objects. Here's an example message to the US state - name server: - - -$msg = new xmlrpcmsg("examples.getStateName", array(new xmlrpcval(23, "int"))); - - - This example requests the name of state number 23. For more - information on xmlrpcval objects, see . - - Note that the parameterArray parameter is - optional and can be omitted for methods that take no input parameters - or if you plan to add parameters one by one. - - - - Methods - - - addParam - - - - booladdParam - - xmlrpcval$xmlrpcVal - - - - Adds the xmlrpcval - xmlrpcVal to the parameter list for this - method call. Returns TRUE or FALSE on error. - - - - getNumParams - - - - intgetNumParams - - - - - - Returns the number of parameters attached to this - message. - - - - getParam - - - - xmlrpcvalgetParam - - int$n - - - - Gets the nth parameter in the message - (with the index zero-based). Use this method in server - implementations to retrieve the values sent by the client. - - - - method - - - - stringmethod - - - - - - stringmethod - - string$methName - - - - Gets or sets the method contained in the XML-RPC - message. - - - - parseResponse - - - - xmlrpcrespparseResponse - - string$xmlString - - - - Given an incoming XML-RPC server response contained in the - string $xmlString, this method constructs an - xmlrpcresp response object and returns it, - setting error codes as appropriate (see ). - - This method processes any HTTP/MIME headers it finds. - - - - parseResponseFile - - - - xmlrpcrespparseResponseFile - - file handle - resource$fileHandle - - - - Given an incoming XML-RPC server response on the open file - handle fileHandle, this method reads all the - data it finds and passes it to - parseResponse. - - This method is useful to construct responses from pre-prepared - files (see files demo1.xml, demo2.xml, demo3.xml - in this distribution). It processes any HTTP headers it finds, and - does not close the file handle. - - - - serialize - - - - string - serialize - - - - - - Returns the an XML string representing the XML-RPC - message. - - - - - - xmlrpc_client - - This is the basic class used to represent a client of an XML-RPC - server. - - - Creation - - The constructor accepts one of two possible syntaxes: - - - - xmlrpc_clientnew - xmlrpc_client - - string$server_url - - - - xmlrpc_clientnew - xmlrpc_client - - string$server_path - - string$server_hostname - - int$server_port80 - - string$transport'http' - - - - Here are a couple of usage examples of the first form: - - -$client = new xmlrpc_client("http://phpxmlrpc.sourceforge.net/server.php"); -$another_client = new xmlrpc_client("https://james:bond@secret.service.com:443/xmlrpcserver?agent=007"); - - - The second syntax does not allow to express a username and - password to be used for basic HTTP authorization as in the second - example above, but instead it allows to choose whether xmlrpc calls - will be made using the HTTP 1.0 or 1.1 protocol. - - Here's another example client set up to query Userland's XML-RPC - server at betty.userland.com: - - -$client = new xmlrpc_client("/RPC2", "betty.userland.com", 80); - - - The server_port parameter is optional, - and if omitted will default to 80 when using HTTP and 443 when using - HTTPS (see the method - below). - - The transport parameter is optional, and - if omitted will default to 'http'. Allowed values are either - 'http', 'https' or - 'http11'. Its value can be overridden with every call - to the send method. See the - send method below for more details about the - meaning of the different values. - - - - Methods - - This class supports the following methods. - - - send - - This method takes the forms: - - - - xmlrpcrespsend - - xmlrpcmsg$xmlrpc_message - - int$timeout - - string$transport - - - - arraysend - - array$xmlrpc_messages - - int$timeout - - string$transport - - - - xmlrpcrespsend - - string$xml_payload - - int$timeout - - string$transport - - - - Where xmlrpc_message is an instance of - xmlrpcmsg (see ), - and response is an instance of - xmlrpcresp (see ). - - If xmlrpc_messages is an array of - message instances, responses will be an array of - response instances. The client will try to make use of a single - system.multicall xml-rpc method call to forward to the - server all the messages in a single HTTP round trip, unless - $client->no_multicall has been previously set to - TRUE (see the multicall method below), in which case - many consecutive xmlrpc requests will be sent. - - The third syntax allows to build by hand (or any other means) - a complete xmlrpc request message, and send it to the server. - xml_payload should be a string containing the - complete xml representation of the request. It is e.g. useful when, - for maximal speed of execution, the request is serialized into a - string using the native php xmlrpc functions (see the php manual on - xmlrpc). - - The timeout is optional, and will be - set to 0 (wait for platform-specific predefined - timeout) if omitted. This timeout value is passed to - fsockopen(). It is also used for detecting - server timeouts during communication (i.e. if the server does not - send anything to the client for timeout - seconds, the connection will be closed). - - The transport parameter is optional, - and if omitted will default to the transport set using instance - creator or 'http' if omitted. The only other valid values are - 'https', which will use an SSL HTTP connection to connect to the - remote server, and 'http11'. Note that your PHP must have the "curl" - extension compiled in order to use both these features. Note that - when using SSL you should normally set your port number to 443, - unless the SSL server you are contacting runs at any other - port. - - - PHP 4.0.6 has a bug which prevents SSL working. - - - In addition to low-level errors, the XML-RPC server you were - querying may return an error in the - xmlrpcresp object. See for details of how to handle these - errors. - - - - multiCall - - This method takes the form: - - - - arraymultiCall - - array$messages - - int$timeout - - string$transport - - bool$fallback - - - - This method is used to boxcar many method calls in a single - xml-rpc request. It will try first to make use of the - system.multicall xml-rpc method call, and fall back to - executing many separate requests if the server returns any - error. - - msgs is an array of - xmlrpcmsg objects (see ), and response is an - array of xmlrpcresp objects (see ). - - The timeout and - transport parameters are optional, and behave - as in the send method above. - - The fallback parameter is optional, and - defaults to TRUE. When set to - FALSE it will prevent the client to try using - many single method calls in case of failure of the first multicall - request. It should be set only when the server is known to support - the multicall extension. - - - - setAcceptedCompression - - - - voidsetAcceptedCompression - - string$compressionmethod - - - - This method defines whether the client will accept compressed - xml payload forming the bodies of the xmlrpc responses received from - servers. Note that enabling reception of compressed responses merely - adds some standard http headers to xmlrpc requests. It is up to the - xmlrpc server to return compressed responses when receiving such - requests. Allowed values for - compressionmethod are: 'gzip', 'deflate', - 'any' or null (with any meaning either gzip or deflate). - - This requires the "zlib" extension to be enabled in your php - install. If it is, by default xmlrpc_client - instances will enable reception of compressed content. - - - - setCaCertificate - - - - voidsetCaCertificate - - string$certificate - - bool$is_dir - - - - This method sets an optional certificate to be used in - SSL-enabled communication to validate a remote server with (when the - server_method is set to 'https' in the - client's construction or in the send method and - SetSSLVerifypeer has been set to - TRUE). - - The certificate parameter must be the - filename of a PEM formatted certificate, or a directory containing - multiple certificate files. The is_dir - parameter defaults to FALSE, set it to - TRUE to specify that - certificate indicates a directory instead of - a single file. - - This requires the "curl" extension to be compiled into your - installation of PHP. For more details see the man page for the - curl_setopt function. - - - - setCertificate - - - - voidsetCertificate - - string$certificate - - string$passphrase - - - - This method sets the optional certificate and passphrase used - in SSL-enabled communication with a remote server (when the - server_method is set to 'https' in the - client's construction or in the send method). - - The certificate parameter must be the - filename of a PEM formatted certificate. The - passphrase parameter must contain the - password required to use the certificate. - - This requires the "curl" extension to be compiled into your - installation of PHP. For more details see the man page for the - curl_setopt function. - - Note: to retrieve information about the client certificate on - the server side, you will need to look into the environment - variables which are set up by the webserver. Different webservers - will typically set up different variables. - - - - setCookie - - - - voidsetCookie - - string$name - - string$value - - string$path - - string$domain - - int$port - - - - This method sets a cookie that will be sent to the xmlrpc - server along with every further request (useful e.g. for keeping - session info outside of the xml-rpc payload). - - $value is optional, and defaults to - null. - - $path, $domain and $port are optional, - and will be omitted from the cookie header if unspecified. Note that - setting any of these values will turn the cookie into a 'version 1' - cookie, that might not be fully supported by the server (see RFC2965 - for more details). - - - - setCredentials - - - - voidsetCredentials - - string$username - - string$password - - int$authtype - - - - This method sets the username and password for authorizing the - client to a server. With the default (HTTP) transport, this - information is used for HTTP Basic authorization. Note that username - and password can also be set using the class constructor. With HTTP - 1.1 and HTTPS transport, NTLM and Digest authentication protocols - are also supported. To enable them use the constants - CURLAUTH_DIGEST and - CURLAUTH_NTLM as values for the authtype - parameter. - - - - setCurlOptions - - - - voidsetCurlOptions - - array$options - - This method allows to directly set any desired - option to manipulate the usage of the cURL client (when in cURL - mode). It can be used eg. to explicitly bind to an outgoing ip - address when the server is multihomed - - - - setDebug - - - - voidsetDebug - - int$debugLvl - - - - debugLvl is either 0, - 1 or 2 depending on whether you require the client to - print debugging information to the browser. The default is not to - output this information (0). - - The debugging information at level 1includes the raw data - returned from the XML-RPC server it was querying (including bot HTTP - headers and the full XML payload), and the PHP value the client - attempts to create to represent the value returned by the server. At - level2, the complete payload of the xmlrpc request is also printed, - before being sent t the server. - - This option can be very useful when debugging servers as it - allows you to see exactly what the client sends and the server - returns. - - - - setKey - - - - voidsetKey - - int$key - - int$keypass - - - - This method sets the optional certificate key and passphrase - used in SSL-enabled communication with a remote server (when the - transport is set to 'https' in the client's - construction or in the send method). - - This requires the "curl" extension to be compiled into your - installation of PHP. For more details see the man page for the - curl_setopt function. - - - - setProxy - - - - voidsetProxy - - string$proxyhost - - int$proxyport - - string$proxyusername - - string$proxypassword - - int$authtype - - - - This method enables calling servers via an HTTP proxy. The - proxyusername, - proxypassword and authtype - parameters are optional. Authtype defaults to - CURLAUTH_BASIC (Basic authentication protocol); - the only other valid value is the constant - CURLAUTH_NTLM, and has effect only when the - client uses the HTTP 1.1 protocol. - - NB: CURL versions before 7.11.10 cannot use a proxy to - communicate with https servers. - - - - setRequestCompression - - - - voidsetRequestCompression - - string$compressionmethod - - - - This method defines whether the xml payload forming the - request body will be sent to the server in compressed format, as per - the HTTP specification. This is particularly useful for large - request parameters and over slow network connections. Allowed values - for compressionmethod are: 'gzip', 'deflate', - 'any' or null (with any meaning either gzip or deflate). Note that - there is no automatic fallback mechanism in place for errors due to - servers not supporting receiving compressed request bodies, so make - sure that the particular server you are querying does accept - compressed requests before turning it on. - - This requires the "zlib" extension to be enabled in your php - install. - - - - setSSLVerifyHost - - - - voidsetSSLVerifyHost - - int$i - - - - This method defines whether connections made to XML-RPC - backends via HTTPS should verify the remote host's SSL certificate's - common name (CN). By default, only the existence of a CN is checked. - $i should be an - integer value; 0 to not check the CN at all, 1 to merely check for - its existence, and 2 to check that the CN on the certificate matches - the hostname that is being connected to. - - - - setSSLVerifyPeer - - - - voidsetSSLVerifyPeer - - bool$i - - - - This method defines whether connections made to XML-RPC - backends via HTTPS should verify the remote host's SSL certificate, - and cause the connection to fail if the cert verification fails. - $i should be a boolean - value. Default value: TRUE. To specify custom - SSL certificates to validate the server with, use the - setCaCertificate method. - - - - setUserAgent - - - - voidUseragent - - string$useragent - - This method sets a custom user-agent that will be - used by the client in the http headers sent with the request. The - default value is built using the library name and version - constants. - - - - - Variables - - NB: direct manipulation of these variables is only recommended - for advanced users. - - - no_multicall - - This member variable determines whether the multicall() method - will try to take advantage of the system.multicall xmlrpc method to - dispatch to the server an array of requests in a single http - roundtrip or simply execute many consecutive http calls. Defaults to - FALSE, but it will be enabled automatically on the first failure of - execution of system.multicall. - - - - request_charset_encoding - - This is the charset encoding that will be used for serializing - request sent by the client. - - If defaults to NULL, which means using US-ASCII and encoding - all characters outside of the ASCII range using their xml character - entity representation (this has the benefit that line end characters - will not be mangled in the transfer, a CR-LF will be preserved as - well as a singe LF). - - Valid values are 'US-ASCII', 'UTF-8' and 'ISO-8859-1' - - - - return_type - - This member variable determines whether the value returned - inside an xmlrpcresp object as results of calls to the send() and - multicall() methods will be an xmlrpcval object, a plain php value - or a raw xml string. Allowed values are 'xmlrpcvals' (the default), - 'phpvals' and 'xml'. To allow the user to differentiate between a - correct and a faulty response, fault responses will be returned as - xmlrpcresp objects in any case. Note that the 'phpvals' setting will - yield faster execution times, but some of the information from the - original response will be lost. It will be e.g. impossible to tell - whether a particular php string value was sent by the server as an - xmlrpc string or base64 value. - - Example usage: - - -$client = new xmlrpc_client("phpxmlrpc.sourceforge.net/server.php"); -$client->return_type = 'phpvals'; -$message = new xmlrpcmsg("examples.getStateName", array(new xmlrpcval(23, "int"))); -$resp = $client->send($message); -if ($resp->faultCode()) echo 'KO. Error: '.$resp->faultString(); else echo 'OK: got '.$resp->value(); - - - For more details about usage of the 'xml' value, see Appendix - A. - - - - - - xmlrpcresp - - This class is used to contain responses to XML-RPC requests. A - server method handler will construct an - xmlrpcresp and pass it as a return value. This - same value will be returned by the result of an invocation of the - send method of the - xmlrpc_client class. - - - Creation - - - - xmlrpcrespnew - xmlrpcresp - - xmlrpcval$xmlrpcval - - - - xmlrpcrespnew - xmlrpcresp - - 0 - - int$errcode - - string$err_string - - - - The first syntax is used when execution has happened without - difficulty: $xmlrpcval is an - xmlrpcval value with the result of the method - execution contained in it. Alternatively it can be a string containing - the xml serialization of the single xml-rpc value result of method - execution. - - The second type of constructor is used in case of failure. - errcode and err_string - are used to provide indication of what has gone wrong. See for more information on passing error - codes. - - - - Methods - - - faultCode - - - - intfaultCode - - - - - - Returns the integer fault code return from the XML-RPC - response. A zero value indicates success, any other value indicates - a failure response. - - - - faultString - - - - stringfaultString - - - - - - Returns the human readable explanation of the fault indicated - by $resp->faultCode(). - - - - value - - - - xmlrpcvalvalue - - - - - - Returns an xmlrpcval object containing - the return value sent by the server. If the response's - faultCode is non-zero then the value returned - by this method should not be used (it may not even be an - object). - - Note: if the xmlrpcresp instance in question has been created - by an xmlrpc_client object whose - return_type was set to 'phpvals', then a plain - php value will be returned instead of an - xmlrpcval object. If the - return_type was set to 'xml', an xml string will - be returned (see the return_type member var above for more - details). - - - - serialize - - - - stringserialize - - - - - - Returns an XML string representation of the response (xml - prologue not included). - - - - - - xmlrpc_server - - The implementation of this class has been kept as simple to use as - possible. The constructor for the server basically does all the work. - Here's a minimal example: - - - function foo ($xmlrpcmsg) { - ... - return new xmlrpcresp($some_xmlrpc_val); - } - - class bar { - function foobar($xmlrpcmsg) { - ... - return new xmlrpcresp($some_xmlrpc_val); - } - } - - $s = new xmlrpc_server( - array( - "examples.myFunc1" => array("function" => "foo"), - "examples.myFunc2" => array("function" => "bar::foobar"), - )); - - - This performs everything you need to do with a server. The single - constructor argument is an associative array from xmlrpc method names to - php function names. The incoming request is parsed and dispatched to the - relevant php function, which is responsible for returning a - xmlrpcresp object, that will be serialized back - to the caller. - - - Method handler functions - - Both php functions and class methods can be registered as xmlrpc - method handlers. - - The synopsis of a method handler function is: - - xmlrpcresp $resp = function (xmlrpcmsg $msg) - - No text should be echoed 'to screen' by the handler function, or - it will break the xml response sent back to the client. This applies - also to error and warning messages that PHP prints to screen unless - the appropriate parameters have been set in the php.in file. Another - way to prevent echoing of errors inside the response and facilitate - debugging is to use the server SetDebug method with debug level 3 (see - ...). Exceptions thrown duting execution of handler functions are - caught by default and a XML-RPC error reponse is generated instead. - This behaviour can be finetuned by usage of the - exception_handling member variable (see - ...). - - Note that if you implement a method with a name prefixed by - system. the handler function will be invoked by the - server with two parameters, the first being the server itself and the - second being the xmlrpcmsg object. - - The same php function can be registered as handler of multiple - xmlrpc methods. - - Here is a more detailed example of what the handler function - foo may do: - - - function foo ($xmlrpcmsg) { - global $xmlrpcerruser; // import user errcode base value - - $meth = $xmlrpcmsg->method(); // retrieve method name - $par = $xmlrpcmsg->getParam(0); // retrieve value of first parameter - assumes at least one param received - $val = $par->scalarval(); // decode value of first parameter - assumes it is a scalar value - - ... - - if ($err) { - // this is an error condition - return new xmlrpcresp(0, $xmlrpcerruser+1, // user error 1 - "There's a problem, Captain"); - } else { - // this is a successful value being returned - return new xmlrpcresp(new xmlrpcval("All's fine!", "string")); - } - } - - - See server.php in this distribution for - more examples of how to do this. - - Since release 2.0RC3 there is a new, even simpler way of - registering php functions with the server. See section 5.7 - below - - - - The dispatch map - - The first argument to the xmlrpc_server - constructor is an array, called the dispatch map. - In this array is the information the server needs to service the - XML-RPC methods you define. - - The dispatch map takes the form of an associative array of - associative arrays: the outer array has one entry for each method, the - key being the method name. The corresponding value is another - associative array, which can have the following members: - - - - function - this - entry is mandatory. It must be either a name of a function in the - global scope which services the XML-RPC method, or an array - containing an instance of an object and a static method name (for - static class methods the 'class::method' syntax is also - supported). - - - - signature - this - entry is an array containing the possible signatures (see ) for the method. If this entry is present - then the server will check that the correct number and type of - parameters have been sent for this method before dispatching - it. - - - - docstring - this - entry is a string containing documentation for the method. The - documentation may contain HTML markup. - - - - signature_docs - this entry can be used - to provide documentation for the single parameters. It must match - in structure the 'signature' member. By default, only the - documenting_xmlrpc_server class in the - extras package will take advantage of this, since the - "system.methodHelp" protocol does not support documenting method - parameters individually. - - - - parameters_type - this entry can be used - when the server is working in 'xmlrpcvals' mode (see ...) to - define one or more entries in the dispatch map as being functions - that follow the 'phpvals' calling convention. The only useful - value is currently the string phpvals. - - - - Look at the server.php example in the - distribution to see what a dispatch map looks like. - - - - Method signatures - - A signature is a description of a method's return type and its - parameter types. A method may have more than one signature. - - Within a server's dispatch map, each method has an array of - possible signatures. Each signature is an array of types. The first - entry is the return type. For instance, the method string examples.getStateName(int) - has the signature array($xmlrpcString, $xmlrpcInt) - and, assuming that it is the only possible signature for the - method, it might be used like this in server creation: -$findstate_sig = array(array($xmlrpcString, $xmlrpcInt)); - -$findstate_doc = 'When passed an integer between 1 and 51 returns the -name of a US state, where the integer is the index of that state name -in an alphabetic order.'; - -$s = new xmlrpc_server( array( - "examples.getStateName" => array( - "function" => "findstate", - "signature" => $findstate_sig, - "docstring" => $findstate_doc - ))); - - - Note that method signatures do not allow to check nested - parameters, e.g. the number, names and types of the members of a - struct param cannot be validated. - - If a method that you want to expose has a definite number of - parameters, but each of those parameters could reasonably be of - multiple types, the array of acceptable signatures will easily grow - into a combinatorial explosion. To avoid such a situation, the lib - defines the global var $xmlrpcValue, which can be - used in method signatures as a placeholder for 'any xmlrpc - type': - - -$echoback_sig = array(array($xmlrpcValue, $xmlrpcValue)); - -$findstate_doc = 'Echoes back to the client the received value, regardless of its type'; - -$s = new xmlrpc_server( array( - "echoBack" => array( - "function" => "echoback", - "signature" => $echoback_sig, // this sig guarantees that the method handler will be called with one and only one parameter - "docstring" => $echoback_doc - ))); - - - Methods system.listMethods, - system.methodHelp, - system.methodSignature and - system.multicall are already defined by the - server, and should not be reimplemented (see Reserved Methods - below). - - - - Delaying the server response - - You may want to construct the server, but for some reason not - fulfill the request immediately (security verification, for instance). - If you omit to pass to the constructor the dispatch map or pass it a - second argument of 0 this will have the desired - effect. You can then use the service() method of - the server class to service the request. For example: - - -$s = new xmlrpc_server($myDispMap, 0); // second parameter = 0 prevents automatic servicing of request - -// ... some code that does other stuff here - -$s->service(); - - - Note that the service method will print - the complete result payload to screen and send appropriate HTTP - headers back to the client, but also return the response object. This - permits further manipulation of the response, possibly in combination - with output buffering. - - To prevent the server from sending HTTP headers back to the - client, you can pass a second parameter with a value of - TRUE to the service - method. In this case, the response payload will be returned instead of - the response object. - - Xmlrpc requests retrieved by other means than HTTP POST bodies - can also be processed. For example: - - -$s = new xmlrpc_server(); // not passing a dispatch map prevents automatic servicing of request - -// ... some code that does other stuff here, including setting dispatch map into server object - -$resp = $s->service($xmlrpc_request_body, true); // parse a variable instead of POST body, retrieve response payload - -// ... some code that does other stuff with xml response $resp here - - - - - Modifying the server behaviour - - A couple of methods / class variables are available to modify - the behaviour of the server. The only way to take advantage of their - existence is by usage of a delayed server response (see above) - - - setDebug() - - This function controls weather the server is going to echo - debugging messages back to the client as comments in response body. - Valid values: 0,1,2,3, with 1 being the default. At level 0, no - debug info is returned to the client. At level 2, the complete - client request is added to the response, as part of the xml - comments. At level 3, a new PHP error handler is set when executing - user functions exposed as server methods, and all non-fatal errors - are trapped and added as comments into the response. - - - - allow_system_funcs - - Default_value: TRUE. When set to FALSE, disables support for - System.xxx functions in the server. It - might be useful e.g. if you do not wish the server to respond to - requests to System.ListMethods. - - - - compress_response - - When set to TRUE, enables the server to take advantage of HTTP - compression, otherwise disables it. Responses will be transparently - compressed, but only when an xmlrpc-client declares its support for - compression in the HTTP headers of the request. - - Note that the ZLIB php extension must be installed for this to - work. If it is, compress_response will default to - TRUE. - - - - exception_handling - - This variable controls the behaviour of the server when an - exception is thrown by a method handler php function. Valid values: - 0,1,2, with 0 being the default. At level 0, the server catches the - exception and return an 'internal error' xmlrpc response; at 1 it - catches the exceptions and return an xmlrpc response with the error - code and error message corresponding to the exception that was - thron; at 2 = the exception is floated to the upper layers in the - code - - - - response_charset_encoding - - Charset encoding to be used for response (only affects string - values). - - If it can, the server will convert the generated response from - internal_encoding to the intended one. - - Valid values are: a supported xml encoding (only UTF-8 and - ISO-8859-1 at present, unless mbstring is enabled), null (leave - charset unspecified in response and convert output stream to - US_ASCII), 'default' (use xmlrpc library default as specified in - xmlrpc.inc, convert output stream if needed), or 'auto' (use - client-specified charset encoding or same as request if request - headers do not specify it (unless request is US-ASCII: then use - library default anyway). - - - - - Fault reporting - - Fault codes for your servers should start at the value indicated - by the global $xmlrpcerruser + 1. - - Standard errors returned by the server include: - - - - 1 Unknown method - - - Returned if the server was asked to dispatch a method it - didn't know about - - - - - 2 Invalid return - payload - - - This error is actually generated by the client, not - server, code, but signifies that a server returned something it - couldn't understand. A more detailed error report is sometimes - added onto the end of the phrase above. - - - - - 3 Incorrect - parameters - - - This error is generated when the server has signature(s) - defined for a method, and the parameters passed by the client do - not match any of signatures. - - - - - 4 Can't introspect: method - unknown - - - This error is generated by the builtin - system.* methods when any kind of - introspection is attempted on a method undefined by the - server. - - - - - 5 Didn't receive 200 OK from - remote server - - - This error is generated by the client when a remote server - doesn't return HTTP/1.1 200 OK in response to a request. A more - detailed error report is added onto the end of the phrase - above. - - - - - 6 No data received from - server - - - This error is generated by the client when a remote server - returns HTTP/1.1 200 OK in response to a request, but no - response body follows the HTTP headers. - - - - - 7 No SSL support compiled - in - - - This error is generated by the client when trying to send - a request with HTTPS and the CURL extension is not available to - PHP. - - - - - 8 CURL error - - - This error is generated by the client when trying to send - a request with HTTPS and the HTTPS communication fails. - - - - - 9-14 multicall - errors - - - These errors are generated by the server when something - fails inside a system.multicall request. - - - - - 100- XML parse - errors - - - Returns 100 plus the XML parser error code for the fault - that occurred. The faultString returned - explains where the parse error was in the incoming XML - stream. - - - - - - - 'New style' servers - - In the same spirit of simplification that inspired the - xmlrpc_client::return_type class variable, a new - class variable has been added to the server class: - functions_parameters_type. When set to 'phpvals', - the functions registered in the server dispatch map will be called - with plain php values as parameters, instead of a single xmlrpcmsg - instance parameter. The return value of those functions is expected to - be a plain php value, too. An example is worth a thousand - words: - function foo($usr_id, $out_lang='en') { - global $xmlrpcerruser; - - ... - - if ($someErrorCondition) - return new xmlrpcresp(0, $xmlrpcerruser+1, 'DOH!'); - else - return array( - 'name' => 'Joe', - 'age' => 27, - 'picture' => new xmlrpcval(file_get_contents($picOfTheGuy), 'base64') - ); - } - - $s = new xmlrpc_server( - array( - "examples.myFunc" => array( - "function" => "bar::foobar", - "signature" => array( - array($xmlrpcString, $xmlrpcInt), - array($xmlrpcString, $xmlrpcInt, $xmlrpcString) - ) - ) - ), false); - $s->functions_parameters_type = 'phpvals'; - $s->service(); -There are a few things to keep in mind when using this - simplified syntax: - - to return an xmlrpc error, the method handler function must - return an instance of xmlrpcresp. The only - other way for the server to know when an error response should be - served to the client is to throw an exception and set the server's - exception_handling memeber var to 1; - - to return a base64 value, the method handler function must - encode it on its own, creating an instance of an xmlrpcval - object; - - the method handler function cannot determine the name of the - xmlrpc method it is serving, unlike standard handler functions that - can retrieve it from the message object; - - when receiving nested parameters, the method handler function - has no way to distinguish a php string that was sent as base64 value - from one that was sent as a string value; - - this has a direct consequence on the support of - system.multicall: a method whose signature contains datetime or base64 - values will not be available to multicall calls; - - last but not least, the direct parsing of xml to php values is - much faster than using xmlrpcvals, and allows the library to handle - much bigger messages without allocating all available server memory or - smashing PHP recursive call stack. - - - - - - Global variables - - Many global variables are defined in the xmlrpc.inc file. Some of - those are meant to be used as constants (and modifying their value might - cause unpredictable behaviour), while some others can be modified in your - php scripts to alter the behaviour of the xml-rpc client and - server. - - - "Constant" variables - - - $xmlrpcerruser - - - $xmlrpcerruser - - 800 - The minimum value for errors reported by user - implemented XML-RPC servers. Error numbers lower than that are - reserved for library usage. - - - - $xmlrpcI4, $xmlrpcInt, $xmlrpcBoolean, $xmlrpcDouble, - $xmlrpcString, $xmlrpcDateTime, $xmlrpcBase64, $xmlrpcArray, - $xmlrpcStruct, $xmlrpcValue, $xmlrpcNull - - For convenience the strings representing the XML-RPC types have - been encoded as global variables: -$xmlrpcI4="i4"; -$xmlrpcInt="int"; -$xmlrpcBoolean="boolean"; -$xmlrpcDouble="double"; -$xmlrpcString="string"; -$xmlrpcDateTime="dateTime.iso8601"; -$xmlrpcBase64="base64"; -$xmlrpcArray="array"; -$xmlrpcStruct="struct"; -$xmlrpcValue="undefined"; -$xmlrpcNull="null"; - - - - - $xmlrpcTypes, $xmlrpc_valid_parents, $xmlrpcerr, $xmlrpcstr, - $xmlrpcerrxml, $xmlrpc_backslash, $_xh, $xml_iso88591_Entities, - $xmlEntities, $xmlrpcs_capabilities - - Reserved for internal usage. - - - - - Variables whose value can be modified - - - xmlrpc_defencoding - - - $xmlrpc_defencoding - - "UTF8" - - - This variable defines the character set encoding that will be - used by the xml-rpc client and server to decode the received messages, - when a specific charset declaration is not found (in the messages sent - non-ascii chars are always encoded using character references, so that - the produced xml is valid regardless of the charset encoding - assumed). - - Allowed values: "UTF8", - "ISO-8859-1", "ASCII". - - Note that the appropriate RFC actually mandates that XML - received over HTTP without indication of charset encoding be treated - as US-ASCII, but many servers and clients 'in the wild' violate the - standard, and assume the default encoding is UTF-8. - - - - xmlrpc_internalencoding - - - $xmlrpc_internalencoding - - "ISO-8859-1" - This variable defines the character set encoding - that the library uses to transparently encode into valid XML the - xml-rpc values created by the user and to re-encode the received - xml-rpc values when it passes them to the PHP application. It only - affects xml-rpc values of string type. It is a separate value from - xmlrpc_defencoding, allowing e.g. to send/receive xml messages encoded - on-the-wire in US-ASCII and process them as UTF-8. It defaults to the - character set used internally by PHP (unless you are running an - MBString-enabled installation), so you should change it only in - special situations, if e.g. the string values exchanged in the xml-rpc - messages are directly inserted into / fetched from a database - configured to return UTF8 encoded strings to PHP. Example - usage: - - -<?php - -include('xmlrpc.inc'); -$xmlrpc_internalencoding = 'UTF-8'; // this has to be set after the inclusion above -$v = new xmlrpcval('κόσμε'); // This xmlrpc value will be correctly serialized as the greek word 'kosme' - - - - - xmlrpcName - - - $xmlrpcName - - "XML-RPC for PHP" - The string representation of the name of the XML-RPC - for PHP library. It is used by the client for building the User-Agent - HTTP header that is sent with every request to the server. You can - change its value if you need to customize the User-Agent - string. - - - - xmlrpcVersion - - - $xmlrpcVersion - - "2.2" - The string representation of the version number of - the XML-RPC for PHP library in use. It is used by the client for - building the User-Agent HTTP header that is sent with every request to - the server. You can change its value if you need to customize the - User-Agent string. - - - - xmlrpc_null_extension - - When set to TRUE, the lib will enable - support for the <NIL/> (and <EX:NIL/>) xmlrpc value, as - per the extension to the standard proposed here. This means that - <NIL/> and <EX:NIL/> tags received will be parsed as valid - xmlrpc, and the corresponding xmlrpcvals will return "null" for - scalarTyp(). - - - - xmlrpc_null_apache_encoding - - When set to TRUE, php NULL values encoded - into xmlrpcval objects get serialized using the - <EX:NIL/> tag instead of - <NIL/>. Please note that both forms are - always accepted as input regardless of the value of this - variable. - - - - - - Helper functions - - XML-RPC for PHP contains some helper functions which you can use to - make processing of XML-RPC requests easier. - - - Date functions - - The XML-RPC specification has this to say on dates: - -
- Don't assume a timezone. It should be - specified by the server in its documentation what assumptions it makes - about timezones. -
- - Unfortunately, this means that date processing isn't - straightforward. Although XML-RPC uses ISO 8601 format dates, it doesn't - use the timezone specifier. - - We strongly recommend that in every case where you pass dates in - XML-RPC calls, you use UTC (GMT) as your timezone. Most computer - languages include routines for handling GMT times natively, and you - won't have to translate between timezones. - - For more information about dates, see ISO 8601: The Right - Format for Dates, which has a handy link to a PDF of the ISO - 8601 specification. Note that XML-RPC uses exactly one of the available - representations: CCYYMMDDTHH:MM:SS. - - - iso8601_encode - - - - stringiso8601_encode - - string$time_t - - int$utc0 - - - - Returns an ISO 8601 formatted date generated from the UNIX - timestamp $time_t, as returned by the PHP - function time(). - - The argument $utc can be omitted, in - which case it defaults to 0. If it is set to - 1, then the function corrects the time passed in - for UTC. Example: if you're in the GMT-6:00 timezone and set - $utc, you will receive a date representation - six hours ahead of your local time. - - The included demo program vardemo.php - includes a demonstration of this function. - - - - iso8601_decode - - - - intiso8601_decode - - string$isoString - - int$utc0 - - - - Returns a UNIX timestamp from an ISO 8601 encoded time and date - string passed in. If $utc is - 1 then $isoString is assumed - to be in the UTC timezone, and thus the result is also UTC: otherwise, - the timezone is assumed to be your local timezone and you receive a - local timestamp. - - - - - Easy use with nested PHP values - - Dan Libby was kind enough to contribute two helper functions that - make it easier to translate to and from PHP values. This makes it easier - to deal with complex structures. At the moment support is limited to - int, double, string, - array, datetime and struct - datatypes; note also that all PHP arrays are encoded as structs, except - arrays whose keys are integer numbers starting with 0 and incremented by - 1. - - These functions reside in xmlrpc.inc. - - - php_xmlrpc_decode - - - - mixedphp_xmlrpc_decode - - xmlrpcval$xmlrpc_val - - array$options - - - - arrayphp_xmlrpc_decode - - xmlrpcmsg$xmlrpcmsg_val - - string$options - - - - Returns a native PHP value corresponding to the values found in - the xmlrpcval $xmlrpc_val, - translated into PHP types. Base-64 and datetime values are - automatically decoded to strings. - - In the second form, returns an array containing the parameters - of the given - xmlrpcmsg_val, decoded - to php types. - - The options parameter is optional. If - specified, it must consist of an array of options to be enabled in the - decoding process. At the moment the only valid option are - decode_php_objs and - dates_as_objects. When the first is set, php - objects that have been converted to xml-rpc structs using the - php_xmlrpc_encode function and a corresponding - encoding option will be converted back into object values instead of - arrays (provided that the class definition is available at - reconstruction time). When the second is set, XML-RPC datetime values - will be converted into native dateTime objects - instead of strings. - - WARNING: please take - extreme care before enabling the decode_php_objs - option: when php objects are rebuilt from the received xml, their - constructor function will be silently invoked. This means that you are - allowing the remote end to trigger execution of uncontrolled PHP code - on your server, opening the door to code injection exploits. Only - enable this option when you have complete trust of the remote - server/client. - - Example: -// wrapper to expose an existing php function as xmlrpc method handler -function foo_wrapper($m) -{ - $params = php_xmlrpc_decode($m); - $retval = call_user_func_array('foo', $params); - return new xmlrpcresp(new xmlrpcval($retval)); // foo return value will be serialized as string -} - -$s = new xmlrpc_server(array( - "examples.myFunc1" => array( - "function" => "foo_wrapper", - "signatures" => ... - ))); - - - - - php_xmlrpc_encode - - - - xmlrpcvalphp_xmlrpc_encode - - mixed$phpval - - array$options - - - - Returns an xmlrpcval object populated with the PHP - values in $phpval. Works recursively on arrays - and objects, encoding numerically indexed php arrays into array-type - xmlrpcval objects and non numerically indexed php arrays into - struct-type xmlrpcval objects. Php objects are encoded into - struct-type xmlrpcvals, excepted for php values that are already - instances of the xmlrpcval class or descendants thereof, which will - not be further encoded. Note that there's no support for encoding php - values into base-64 values. Encoding of date-times is optionally - carried on on php strings with the correct format. - - The options parameter is optional. If - specified, it must consist of an array of options to be enabled in the - encoding process. At the moment the only valid options are - encode_php_objs, null_extension - and auto_dates. - - The first will enable the creation of 'particular' xmlrpcval - objects out of php objects, that add a "php_class" xml attribute to - their serialized representation. This attribute allows the function - php_xmlrpc_decode to rebuild the native php objects (provided that the - same class definition exists on both sides of the communication). The - second allows to encode php NULL values to the - <NIL/> (or - <EX:NIL/>, see ...) tag. The last encodes any - string that matches the ISO8601 format into an XML-RPC - datetime. - - Example: -// the easy way to build a complex xml-rpc struct, showing nested base64 value and datetime values -$val = php_xmlrpc_encode(array( - 'first struct_element: an int' => 666, - 'second: an array' => array ('apple', 'orange', 'banana'), - 'third: a base64 element' => new xmlrpcval('hello world', 'base64'), - 'fourth: a datetime' => '20060107T01:53:00' - ), array('auto_dates')); - - - - - php_xmlrpc_decode_xml - - - - xmlrpcval | xmlrpcresp | - xmlrpcmsgphp_xmlrpc_decode_xml - - string$xml - - array$options - - - - Decodes the xml representation of either an xmlrpc request, - response or single value, returning the corresponding php-xmlrpc - object, or FALSE in case of an error. - - The options parameter is optional. If - specified, it must consist of an array of options to be enabled in the - decoding process. At the moment, no option is supported. - - Example: -$text = '<value><array><data><value>Hello world</value></data></array></value>'; -$val = php_xmlrpc_decode_xml($text); -if ($val) echo 'Found a value of type '.$val->kindOf(); else echo 'Found invalid xml'; - - - - - - Automatic conversion of php functions into xmlrpc methods (and - vice versa) - - For the extremely lazy coder, helper functions have been added - that allow to convert a php function into an xmlrpc method, and a - remotely exposed xmlrpc method into a local php function - or a set of - methods into a php class. Note that these comes with many caveat. - - - wrap_xmlrpc_method - - - - stringwrap_xmlrpc_method - - $client - - $methodname - - $extra_options - - - - stringwrap_xmlrpc_method - - $client - - $methodname - - $signum - - $timeout - - $protocol - - $funcname - - - - Given an xmlrpc server and a method name, creates a php wrapper - function that will call the remote method and return results using - native php types for both params and results. The generated php - function will return an xmlrpcresp object for failed xmlrpc - calls. - - The second syntax is deprecated, and is listed here only for - backward compatibility. - - The server must support the - system.methodSignature xmlrpc method call for - this function to work. - - The client param must be a valid - xmlrpc_client object, previously created with the address of the - target xmlrpc server, and to which the preferred communication options - have been set. - - The optional parameters can be passed as array key,value pairs - in the extra_options param. - - The signum optional param has the purpose - of indicating which method signature to use, if the given server - method has multiple signatures (defaults to 0). - - The timeout and - protocol optional params are the same as in the - xmlrpc_client::send() method. - - If set, the optional new_function_name - parameter indicates which name should be used for the generated - function. In case it is not set the function name will be - auto-generated. - - If the return_source optional parameter is - set, the function will return the php source code to build the wrapper - function, instead of evaluating it (useful to save the code and use it - later as stand-alone xmlrpc client). - - If the encode_php_objs optional parameter is - set, instances of php objects later passed as parameters to the newly - created function will receive a 'special' treatment that allows the - server to rebuild them as php objects instead of simple arrays. Note - that this entails using a "slightly augmented" version of the xmlrpc - protocol (ie. using element attributes), which might not be understood - by xmlrpc servers implemented using other libraries. - - If the decode_php_objs optional parameter is - set, instances of php objects that have been appropriately encoded by - the server using a coordinate option will be deserialized as php - objects instead of simple arrays (the same class definition should be - present server side and client side). - - Note that this might pose a security risk, - since in order to rebuild the object instances their constructor - method has to be invoked, and this means that the remote server can - trigger execution of unforeseen php code on the client: not really a - code injection, but almost. Please enable this option only when you - trust the remote server. - - In case of an error during generation of the wrapper function, - FALSE is returned, otherwise the name (or source code) of the new - function. - - Known limitations: server must support - system.methodsignature for the wanted xmlrpc - method; for methods that expose multiple signatures, only one can be - picked; for remote calls with nested xmlrpc params, the caller of the - generated php function has to encode on its own the params passed to - the php function if these are structs or arrays whose (sub)members - include values of type base64. - - Note: calling the generated php function 'might' be slow: a new - xmlrpc client is created on every invocation and an xmlrpc-connection - opened+closed. An extra 'debug' param is appended to the parameter - list of the generated php function, useful for debugging - purposes. - - Example usage: - - -$c = new xmlrpc_client('http://phpxmlrpc.sourceforge.net/server.php'); - -$function = wrap_xmlrpc_method($client, 'examples.getStateName'); - -if (!$function) - die('Cannot introspect remote method'); -else { - $stateno = 15; - $statename = $function($a); - if (is_a($statename, 'xmlrpcresp')) // call failed - { - echo 'Call failed: '.$statename->faultCode().'. Calling again with debug on'; - $function($a, true); - } - else - echo "OK, state nr. $stateno is $statename"; -} - - - - - wrap_php_function - - - - arraywrap_php_function - - string$funcname - - string$wrapper_function_name - - array$extra_options - - - - Given a user-defined PHP function, create a PHP 'wrapper' - function that can be exposed as xmlrpc method from an xmlrpc_server - object and called from remote clients, and return the appropriate - definition to be added to a server's dispatch map. - - The optional $wrapper_function_name - specifies the name that will be used for the auto-generated - function. - - Since php is a typeless language, to infer types of input and - output parameters, it relies on parsing the javadoc-style comment - block associated with the given function. Usage of xmlrpc native types - (such as datetime.dateTime.iso8601 and base64) in the docblock @param - tag is also allowed, if you need the php function to receive/send data - in that particular format (note that base64 encoding/decoding is - transparently carried out by the lib, while datetime vals are passed - around as strings). - - Known limitations: only works for - user-defined functions, not for PHP internal functions (reflection - does not support retrieving number/type of params for those); the - wrapped php function will not be able to programmatically return an - xmlrpc error response. - - If the return_source optional parameter is - set, the function will return the php source code to build the wrapper - function, instead of evaluating it (useful to save the code and use it - later in a stand-alone xmlrpc server). It will be in the stored in the - source member of the returned array. - - If the suppress_warnings optional parameter - is set, any runtime warning generated while processing the - user-defined php function will be catched and not be printed in the - generated xml response. - - If the extra_options array contains the - encode_php_objs value, wrapped functions returning - php objects will generate "special" xmlrpc responses: when the xmlrpc - decoding of those responses is carried out by this same lib, using the - appropriate param in php_xmlrpc_decode(), the objects will be - rebuilt. - - In short: php objects can be serialized, too (except for their - resource members), using this function. Other libs might choke on the - very same xml that will be generated in this case (i.e. it has a - nonstandard attribute on struct element tags) - - If the decode_php_objs optional parameter is - set, instances of php objects that have been appropriately encoded by - the client using a coordinate option will be deserialized and passed - to the user function as php objects instead of simple arrays (the same - class definition should be present server side and client - side). - - Note that this might pose a security risk, - since in order to rebuild the object instances their constructor - method has to be invoked, and this means that the remote client can - trigger execution of unforeseen php code on the server: not really a - code injection, but almost. Please enable this option only when you - trust the remote clients. - - Example usage: - - /** -* State name from state number decoder. NB: do NOT remove this comment block. -* @param integer $stateno the state number -* @return string the name of the state (or error description) -*/ -function findstate($stateno) -{ - global $stateNames; - if (isset($stateNames[$stateno-1])) - { - return $stateNames[$stateno-1]; - } - else - { - return "I don't have a state for the index '" . $stateno . "'"; - } -} - -// wrap php function, build xmlrpc server -$methods = array(); -$findstate_sig = wrap_php_function('findstate'); -if ($findstate_sig) - $methods['examples.getStateName'] = $findstate_sig; -$srv = new xmlrpc_server($methods); - - - - - - Functions removed from the library - - The following two functions have been deprecated in version 1.1 of - the library, and removed in version 2, in order to avoid conflicts with - the EPI xml-rpc library, which also defines two functions with the same - names. - - To ease the transition to the new naming scheme and avoid breaking - existing implementations, the following scheme has been adopted: - - - If EPI-XMLRPC is not active in the current PHP installation, - the constant XMLRPC_EPI_ENABLED will be set to - '0' - - - - If EPI-XMLRPC is active in the current PHP installation, the - constant XMLRPC_EPI_ENABLED will be set to - '1' - - - - The following documentation is kept for historical - reference: - - - xmlrpc_decode - - - - mixedxmlrpc_decode - - xmlrpcval$xmlrpc_val - - - - Alias for php_xmlrpc_decode. - - - - xmlrpc_encode - - - - xmlrpcvalxmlrpc_encode - - mixed$phpval - - - - Alias for php_xmlrpc_encode. - - - - - Debugging aids - - - xmlrpc_debugmsg - - - - voidxmlrpc_debugmsg - - string$debugstring - - - - Sends the contents of $debugstring in XML - comments in the server return payload. If a PHP client has debugging - turned on, the user will be able to see server debug - information. - - Use this function in your methods so you can pass back - diagnostic information. It is only available from - xmlrpcs.inc. - - - - - - Reserved methods - - In order to extend the functionality offered by XML-RPC servers - without impacting on the protocol, reserved methods are supported in this - release. - - All methods starting with system. are - considered reserved by the server. PHP for XML-RPC itself provides four - special methods, detailed in this chapter. - - Note that all server objects will automatically respond to clients - querying these methods, unless the property - allow_system_funcs has been set to - false before calling the - service() method. This might pose a security risk - if the server is exposed to public access, e.g. on the internet. - - - system.getCapabilities - - - - - - system.listMethods - - This method may be used to enumerate the methods implemented by - the XML-RPC server. - - The system.listMethods method requires no - parameters. It returns an array of strings, each of which is the name of - a method implemented by the server. - - - - system.methodSignature - - This method takes one parameter, the name of a method implemented - by the XML-RPC server. - - It returns an array of possible signatures for this method. A - signature is an array of types. The first of these types is the return - type of the method, the rest are parameters. - - Multiple signatures (i.e. overloading) are permitted: this is the - reason that an array of signatures are returned by this method. - - Signatures themselves are restricted to the top level parameters - expected by a method. For instance if a method expects one array of - structs as a parameter, and it returns a string, its signature is simply - "string, array". If it expects three integers, its signature is "string, - int, int, int". - - For parameters that can be of more than one type, the "undefined" - string is supported. - - If no signature is defined for the method, a not-array value is - returned. Therefore this is the way to test for a non-signature, if - $resp below is the response object from a method - call to system.methodSignature: - - -$v = $resp->value(); -if ($v->kindOf() != "array") { - // then the method did not have a signature defined -} - - - See the introspect.php demo included in this - distribution for an example of using this method. - - - - system.methodHelp - - This method takes one parameter, the name of a method implemented - by the XML-RPC server. - - It returns a documentation string describing the use of that - method. If no such string is available, an empty string is - returned. - - The documentation string may contain HTML markup. - - - - system.multicall - - This method takes one parameter, an array of 'request' struct - types. Each request struct must contain a - methodName member of type string and a - params member of type array, and corresponds to - the invocation of the corresponding method. - - It returns a response of type array, with each value of the array - being either an error struct (containing the faultCode and faultString - members) or the successful response value of the corresponding single - method call. - - - - - Examples - - The best examples are to be found in the sample files included with - the distribution. Some are included here. - - - XML-RPC client: state name query - - Code to get the corresponding state name from a number (1-50) from - the demo server available on SourceForge - - - $m = new xmlrpcmsg('examples.getStateName', - array(new xmlrpcval($HTTP_POST_VARS["stateno"], "int"))); - $c = new xmlrpc_client("/server.php", "phpxmlrpc.sourceforge.net", 80); - $r = $c->send($m); - if (!$r->faultCode()) { - $v = $r->value(); - print "State number " . htmlentities($HTTP_POST_VARS["stateno"]) . " is " . - htmlentities($v->scalarval()) . "<BR>"; - print "<HR>I got this value back<BR><PRE>" . - htmlentities($r->serialize()) . "</PRE><HR>\n"; - } else { - print "Fault <BR>"; - print "Code: " . htmlentities($r->faultCode()) . "<BR>" . - "Reason: '" . htmlentities($r->faultString()) . "'<BR>"; - } - - - - - Executing a multicall call - - To be documented... - - - - - Frequently Asked Questions - - - How to send custom XML as payload of a method call - - Unfortunately, at the time the XML-RPC spec was designed, support - for namespaces in XML was not as ubiquitous as it is now. As a - consequence, no support was provided in the protocol for embedding XML - elements from other namespaces into an xmlrpc request. - - To send an XML "chunk" as payload of a method call or response, - two options are available: either send the complete XML block as a - string xmlrpc value, or as a base64 value. Since the '<' character in - string values is encoded as '&lt;' in the xml payload of the method - call, the XML string will not break the surrounding xmlrpc, unless - characters outside of the assumed character set are used. The second - method has the added benefits of working independently of the charset - encoding used for the xml to be transmitted, and preserving exactly - whitespace, whilst incurring in some extra message length and cpu load - (for carrying out the base64 encoding/decoding). - - - - Is there any limitation on the size of the requests / responses - that can be successfully sent? - - Yes. But I have no hard figure to give; it most likely will depend - on the version of PHP in usage and its configuration. - - Keep in mind that this library is not optimized for speed nor for - memory usage. Better alternatives exist when there are strict - requirements on throughput or resource usage, such as the php native - xmlrpc extension (see the PHP manual for more information). - - Keep in mind also that HTTP is probably not the best choice in - such a situation, and XML is a deadly enemy. CSV formatted data over - socket would be much more efficient. - - If you really need to move a massive amount of data around, and - you are crazy enough to do it using phpxmlrpc, your best bet is to - bypass usage of the xmlrpcval objects, at least in the decoding phase, - and have the server (or client) object return to the calling function - directly php values (see xmlrpc_client::return_type - and xmlrpc_server::functions_parameters_type for more - details). - - - - My server (client) returns an error whenever the client (server) - returns accented characters - - To be documented... - - - - How to enable long-lasting method calls - - To be documented... - - - - My client returns "XML-RPC Fault #2: Invalid return payload: - enable debugging to examine incoming payload": what should I do? - - The response you are seeing is a default error response that the - client object returns to the php application when the server did not - respond to the call with a valid xmlrpc response. - - The most likely cause is that you are not using the correct URL - when creating the client object, or you do not have appropriate access - rights to the web page you are requesting, or some other common http - misconfiguration. - - To find out what the server is really returning to your client, - you have to enable the debug mode of the client, using - $client->setdebug(1); - - - - How can I save to a file the xml of the xmlrpc responses received - from servers? - - If what you need is to save the responses received from the server - as xml, you have two options: - - 1- use the serialize() method on the response object. - - -$resp = $client->send($msg); -if (!$resp->faultCode()) - $data_to_be_saved = $resp->serialize(); - - - Note that this will not be 100% accurate, since the xml generated - by the response object can be different from the xml received, - especially if there is some character set conversion involved, or such - (eg. if you receive an empty string tag as <string/>, serialize() - will output <string></string>), or if the server sent back - as response something invalid (in which case the xml generated client - side using serialize() will correspond to the error response generated - internally by the lib). - - 2 - set the client object to return the raw xml received instead - of the decoded objects: - - -$client = new xmlrpc_client($url); -$client->return_type = 'xml'; -$resp = $client->send($msg); -if (!$resp->faultCode()) - $data_to_be_saved = $resp->value(); - - - Note that using this method the xml response response will not be - parsed at all by the library, only the http communication protocol will - be checked. This means that xmlrpc responses sent by the server that - would have generated an error response on the client (eg. malformed xml, - responses that have faultcode set, etc...) now will not be flagged as - invalid, and you might end up saving not valid xml but random - junk... - - - - Can I use the ms windows character set? - - If the data your application is using comes from a Microsoft - application, there are some chances that the character set used to - encode it is CP1252 (the same might apply to data received from an - external xmlrpc server/client, but it is quite rare to find xmlrpc - toolkits that encode to CP1252 instead of UTF8). It is a character set - which is "almost" compatible with ISO 8859-1, but for a few extra - characters. - - PHP-XMLRPC only supports the ISO 8859-1 and UTF8 character sets. - The net result of this situation is that those extra characters will not - be properly encoded, and will be received at the other end of the - XML-RPC transmission as "garbled data". Unfortunately the library cannot - provide real support for CP1252 because of limitations in the PHP 4 xml - parser. Luckily, we tried our best to support this character set anyway, - and, since version 2.2.1, there is some form of support, left commented - in the code. - - To properly encode outgoing data that is natively in CP1252, you - will have to uncomment all relative code in the file - xmlrpc.inc (you can search for the string "1252"), - then set $GLOBALS['xmlrpc_internalencoding']='CP1252'; - Please note that all incoming data will then be fed to your application - as UTF-8 to avoid any potential data loss. - - - - Does the library support using cookies / http sessions? - - In short: yes, but a little coding is needed to make it - happen. - - The code below uses sessions to e.g. let the client store a value - on the server and retrieve it later. - - -$resp = $client->send(new xmlrpcmsg('registervalue', array(new xmlrpcval('foo'), new xmlrpcval('bar')))); -if (!$resp->faultCode()) -{ - $cookies = $resp->cookies(); - if (array_key_exists('PHPSESSID', $cookies)) // nb: make sure to use the correct session cookie name - { - $session_id = $cookies['PHPSESSID']['value']; - - // do some other stuff here... - - $client->setcookie('PHPSESSID', $session_id); - $val = $client->send(new xmlrpcmsg('getvalue', array(new xmlrpcval('foo'))); - } -} -Server-side sessions are handled normally like in any other - php application. Please see the php manual for more information about - sessions. - - NB: unlike web browsers, not all xmlrpc clients support usage of - http cookies. If you have troubles with sessions and control only the - server side of the communication, please check with the makers of the - xmlrpc client in use. - - - - - Integration with the PHP xmlrpc extension - - To be documented more... - - In short: for the fastest execution possible, you can enable the php - native xmlrpc extension, and use it in conjunction with phpxmlrpc. The - following code snippet gives an example of such integration - - -/*** client side ***/ -$c = new xmlrpc_client('http://phpxmlrpc.sourceforge.net/server.php'); - -// tell the client to return raw xml as response value -$c->return_type = 'xml'; - -// let the native xmlrpc extension take care of encoding request parameters -$r = $c->send(xmlrpc_encode_request('examples.getStateName', $_POST['stateno'])); - -if ($r->faultCode()) - // HTTP transport error - echo 'Got error '.$r->faultCode(); -else -{ - // HTTP request OK, but XML returned from server not parsed yet - $v = xmlrpc_decode($r->value()); - // check if we got a valid xmlrpc response from server - if ($v === NULL) - echo 'Got invalid response'; - else - // check if server sent a fault response - if (xmlrpc_is_fault($v)) - echo 'Got xmlrpc fault '.$v['faultCode']; - else - echo'Got response: '.htmlentities($v); -} - - - - - Substitution of the PHP xmlrpc extension - - Yet another interesting situation is when you are using a ready-made - php application, that provides support for the XMLRPC protocol via the - native php xmlrpc extension, but the extension is not available on your - php install (e.g. because of shared hosting constraints). - - Since version 2.1, the PHP-XMLRPC library provides a compatibility - layer that aims to be 100% compliant with the xmlrpc extension API. This - means that any code written to run on the extension should obtain the - exact same results, albeit using more resources and a longer processing - time, using the PHP-XMLRPC library and the extension compatibility module. - The module is part of the EXTRAS package, available as a separate download - from the sourceforge.net website, since version 0.2 - - - - 'Enough of xmlrpcvals!': new style library usage - - To be documented... - - In the meantime, see docs about xmlrpc_client::return_type and - xmlrpc_server::functions_parameters_types, as well as php_xmlrpc_encode, - php_xmlrpc_decode and php_xmlrpc_decode_xml - - - - Usage of the debugger - - A webservice debugger is included in the library to help during - development and testing. - - The interface should be self-explicative enough to need little - documentation. - - - - The most useful feature of the debugger is without doubt the "Show - debug info" option. It allows to have a screen dump of the complete http - communication between client and server, including the http headers as - well as the request and response payloads, and is invaluable when - troubleshooting problems with charset encoding, authentication or http - compression. - - The debugger can take advantage of the JSONRPC library extension, to - allow debugging of JSON-RPC webservices, and of the JS-XMLRPC library - visual editor to allow easy mouse-driven construction of the payload for - remote methods. Both components have to be downloaded separately from the - sourceforge.net web pages and copied to the debugger directory to enable - the extra functionality: - - - - to enable jsonrpc functionality, download the PHP-XMLRPC - EXTRAS package, and copy the file jsonrpc.inc - either to the same directory as the debugger or somewhere in your - php include path - - - - to enable the visual value editing dialog, download the - JS-XMLRPC library, and copy somewhere in the web root files - visualeditor.php, - visualeditor.css and the folders - yui and img. Then edit the - debugger file controller.php and set - appropriately the variable $editorpath. - - - - - diff --git a/pakefile.php b/pakefile.php index 35a3301..30acead 100644 --- a/pakefile.php +++ b/pakefile.php @@ -5,7 +5,6 @@ * * @copyright (c) 2015 G. Giunta * - * @todo allow user to specify release number and tag/branch to use * @todo !important allow user to specify location of docbook xslt instead of the one installed via composer */ @@ -15,11 +14,11 @@ class Builder { protected static $buildDir = 'build'; protected static $libVersion; - protected static $sourceBranch = 'master'; protected static $tools = array( - 'zip' => 'zip', + 'asciidoctor' => 'asciidoctor', 'fop' => 'fop', - 'php' => 'php' + 'php' => 'php', + 'zip' => 'zip', ); protected static $options = array( 'repo' => 'https://github.com/gggeek/phpxmlrpc', @@ -58,14 +57,11 @@ class Builder ); } - /// @todo move git branch to be a named option? public static function getOpts($args=array(), $cliOpts=array()) { if (count($args) > 0) // throw new \Exception('Missing library version argument'); self::$libVersion = $args[0]; - if (count($args) > 1) - self::$sourceBranch = $args[1]; foreach (self::$tools as $name => $binary) { if (isset($cliOpts[$name])) { @@ -186,10 +182,11 @@ function run_default($task=null, $args=array(), $cliOpts=array()) echo " Run 'pake -P' to list all available tasks (including hidden ones) and their dependencies\n"; echo "\n"; echo " Task options:\n"; - echo " --repo=REPO URL of the source repository to clone. defaults to the github repo.\n"; + echo " --repo=REPO URL of the source repository to clone. Defaults to the github repo.\n"; echo " --branch=BRANCH The git branch to build from.\n"; + echo " --asciidoctor=ASCIIDOCTOR Location of the asciidoctor command-line tool\n"; + echo " --fop=FOP Location of the apache fop command-line tool\n"; echo " --php=PHP Location of the php command-line interpreter\n"; - echo " --fop=FOP Location of the fop command-line tool\n"; echo " --zip=ZIP Location of the zip tool\n"; } @@ -235,10 +232,11 @@ function run_build($task=null, $args=array(), $cliOpts=array()) function run_clean_doc() { - //pake_remove_dir(Builder::workspaceDir().'/doc/out'); pake_remove_dir(Builder::workspaceDir().'/doc/api'); $finder = pakeFinder::type('file')->name('*.html'); pake_remove($finder, Builder::workspaceDir().'/doc/manual'); + $finder = pakeFinder::type('file')->name('*.xml'); + pake_remove($finder, Builder::workspaceDir().'/doc/manual'); } /** @@ -248,11 +246,26 @@ function run_doc($task=null, $args=array(), $cliOpts=array()) { $docDir = Builder::workspaceDir().'/doc'; - // API docs from phpdoc comments using phpdocumentor + // API docs + + // from phpdoc comments using phpdocumentor $cmd = Builder::tool('php'); pake_sh("$cmd vendor/phpdocumentor/phpdocumentor/bin/phpdoc run -d ".Builder::workspaceDir().'/src'." -t ".Builder::workspaceDir().'/doc/api --title PHP-XMLRPC'); - # Jade cmd yet to be rebuilt, starting from xml file and putting output in ./out dir, e.g. + // User Manual + + // html (single file) from asciidoc + $cmd = Builder::tool('asciidoctor'); + pake_sh("$cmd -d book $docDir/manual/phpxmlrpc_manual.adoc"); + + // then docbook from asciidoc + /// @todo create phpxmlrpc_manual.xml with the good version number + /// @todo create phpxmlrpc_manual.xml with the date set to the one of last commit (or today?) + pake_sh("$cmd -d book -b docbook $docDir/manual/phpxmlrpc_manual.adoc"); + + # Other tools for docbook... + # + # jade cmd yet to be rebuilt, starting from xml file and putting output in ./out dir, e.g. # jade -t xml -d custom.dsl xmlrpc_php.xml # # convertdoc command for xmlmind xxe editor @@ -267,16 +280,13 @@ function run_doc($task=null, $args=array(), $cliOpts=array()) # -Dxslthl.config=file:///c:/htdocs/xmlrpc_cvs/docbook-xsl/highlighting/xslthl-config.xml \ # com.icl.saxon.StyleSheet -o xmlrpc_php.fo.xml xmlrpc_php.xml custom.fo.xsl use.extensions=1 - //pake_mkdirs($docDir.'/out'); - - // HTML files from docbook - - Builder::applyXslt($docDir.'/manual/phpxmlrpc_manual.xml', $docDir.'/build/custom.xsl', $docDir.'/manual'); + // HTML (multiple files) from docbook - discontinued, as we use the nicer-looking html gotten from asciidoc + /*Builder::applyXslt($docDir.'/manual/phpxmlrpc_manual.xml', $docDir.'/build/custom.xsl', $docDir.'/manual'); // post process html files to highlight php code samples foreach(pakeFinder::type('file')->name('*.html')->in($docDir.'/manual') as $file) { file_put_contents($file, Builder::highlightPhpInHtml(file_get_contents($file))); - } + }*/ // PDF file from docbook @@ -284,6 +294,9 @@ function run_doc($task=null, $args=array(), $cliOpts=array()) Builder::applyXslt($docDir.'/manual/phpxmlrpc_manual.xml', $docDir.'/build/custom.fo.xsl', $docDir.'/manual/phpxmlrpc_manual.fo.xml'); $cmd = Builder::tool('fop'); pake_sh("$cmd $docDir/manual/phpxmlrpc_manual.fo.xml $docDir/manual/phpxmlrpc_manual.pdf"); + + // cleanup + unlink($docDir.'/manual/phpxmlrpc_manual.xml'); unlink($docDir.'/manual/phpxmlrpc_manual.fo.xml'); } -- 2.43.0