+++ /dev/null
-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.
+++ /dev/null
-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!
+++ /dev/null
-/*
- * 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;
-}
+++ /dev/null
-<?xml version="1.0"?>
-<bindings xmlns="http://www.mozilla.org/xbl"
- xmlns:html="http://www.w3.org/1999/xhtml">
- <binding id="ulink">
- <handlers>
- <handler event="click" button="0"
- action="window.location=this.attributes.url.value;"/>
- <handler event="mouseover"
- action="window.status=this.attributes.url.value;"/>
- <handler event="mouseout"
- action="window.status=null;"/>
- </handlers>
- </binding>
-
- <binding id="image">
- <content>
- <html:img xbl:inherits="src=fileref"/>
- </content>
-
- <implementation>
- <constructor>
- 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);
- </constructor>
- </implementation>
- </binding>
-</bindings>
+++ /dev/null
-/*
- * 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 <ver> with the version number):
- *
- * <?xml-stylesheet href="docbook-css-<ver>/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";
+++ /dev/null
-/*
- * 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";
+++ /dev/null
-@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: ";
-}
+++ /dev/null
-@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: ";
-}
+++ /dev/null
-@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: ";
-}
-
+++ /dev/null
-@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: ";
-}
+++ /dev/null
-/*
- * 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 <ulink>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;
-}
+++ /dev/null
-/*
- * 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)
-}
+++ /dev/null
-/*
- * 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 <abstract> 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="emptytag"]:after {
- 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="sgmlcomment"]:after {
- content: "-->";
-}
-
-sgmltag[class="xmlpi"]:before {
- content: "<?";
-}
-sgmltag[class="xmlpi"]:after {
- 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 <member> 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 <title> */
- 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;
-}
+++ /dev/null
-/*
- * 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;
-}
+++ /dev/null
-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:"";
-}
--- /dev/null
+= 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('κόÏ\83με'); // 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:
+-->
+++++++++++++++++++++++++++++++++++++++
+++ /dev/null
-<?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</title>
-
- <subtitle>version 3.0.0</subtitle>
-
- <bookinfo>
- <date>June 15, 2014</date>
-
- <authorgroup>
- <author>
- <firstname>Edd</firstname>
-
- <surname>Dumbill</surname>
- </author>
-
- <author>
- <firstname>Gaetano</firstname>
-
- <surname>Giunta</surname>
- </author>
-
- <author>
- <firstname>Miles</firstname>
-
- <surname>Lott</surname>
- </author>
-
- <author>
- <firstname>Justin R.</firstname>
-
- <surname>Miller</surname>
- </author>
-
- <author>
- <firstname>Andres</firstname>
-
- <surname>Salomon</surname>
- </author>
- </authorgroup>
-
- <copyright>
- <year>1999,2000,2001</year>
-
- <holder>Edd Dumbill, Useful Information Company</holder>
- </copyright>
-
- <legalnotice>
- <para>All rights reserved.</para>
-
- <para>Redistribution and use in source and binary forms, with or without
- modification, are permitted provided that the following conditions are
- met:</para>
-
- <para><itemizedlist>
- <listitem>
- <para>Redistributions of source code must retain the above
- copyright notice, this list of conditions and the following
- disclaimer.</para>
- </listitem>
-
- <listitem>
- <para>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.</para>
- </listitem>
-
- <listitem>
- <para>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.</para>
- </listitem>
- </itemizedlist></para>
-
- <para>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.</para>
- </legalnotice>
- </bookinfo>
-
- <chapter id="introduction">
- <title>Introduction</title>
-
- <para>XML-RPC is a format devised by <ulink
- url="http://www.userland.com/">Userland Software</ulink> for achieving
- remote procedure call via XML using HTTP as the transport. XML-RPC has its
- own web site, <ulink
- url="http://www.xmlrpc.com/">www.xmlrpc.com</ulink></para>
-
- <para>This collection of PHP classes provides a framework for writing
- XML-RPC clients and servers in PHP.</para>
-
- <para>Main goals of the project are ease of use, flexibility and
- completeness.</para>
-
- <para>The original author is Edd Dumbill of <ulink
- url="http://usefulinc.com/">Useful Information Company</ulink>. As of the
- 1.0 stable release, the project was opened to wider involvement and moved
- to <ulink
- url="http://phpxmlrpc.sourceforge.net/">SourceForge</ulink>; later, to <ulink
- url="https://github.com/">Github</ulink></para>
-
- <para>A list of XML-RPC implementations for other languages such as Perl
- and Python can be found on the <ulink
- url="http://www.xmlrpc.com/">www.xmlrpc.com</ulink> site.</para>
-
- <sect1>
- <title>Acknowledgements</title>
-
- <para>Daniel E. Baumann</para>
-
- <para>James Bercegay</para>
-
- <para>Leon Blackwell</para>
-
- <para>Stephane Bortzmeyer</para>
-
- <para>Daniel Convissor</para>
-
- <para>Geoffrey T. Dairiki</para>
-
- <para>Stefan Esser</para>
-
- <para>James Flemer</para>
-
- <para>Ernst de Haan</para>
-
- <para>Tom Knight</para>
-
- <para>Axel Kollmorgen</para>
-
- <para>Peter Kocks</para>
-
- <para>Daniel Krippner</para>
-
- <para>S. Kuip</para>
-
- <para>A. Lambert</para>
-
- <para>Frederic Lecointre</para>
-
- <para>Dan Libby</para>
-
- <para>Arnaud Limbourg</para>
-
- <para>Ernest MacDougal Campbell III</para>
-
- <para>Lukasz Mach</para>
-
- <para>Kjartan Mannes</para>
-
- <para>Ben Margolin</para>
-
- <para>Nicolay Mausz</para>
-
- <para>Justin Miller</para>
-
- <para>Jan Pfeifer</para>
-
- <para>Giancarlo Pinerolo</para>
-
- <para>Peter Russel</para>
-
- <para>Jean-Jacques Sarton</para>
-
- <para>Viliam Simko</para>
-
- <para>Idan Sofer</para>
-
- <para>Douglas Squirrel</para>
-
- <para>Heiko Stübner</para>
-
- <para>Anatoly Techtonik</para>
-
- <para>Tommaso Trani</para>
-
- <para>Eric van der Vlist</para>
-
- <para>Christian Wenz</para>
-
- <para>Jim Winstead</para>
-
- <para>Przemyslaw Wroblewski</para>
-
- <para>Bruno Zanetti Melotti</para>
- </sect1>
- </chapter>
-
- <chapter id="news">
- <title>What's new</title>
-
- <para><emphasis>Note:</emphasis> 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.</para>
-
- <sect1>
- <title>3.0.0</title>
-
- <para><emphasis>Note:</emphasis> 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.</para>
-
- <para><itemizedlist>
- <listitem>
- <para>when using curl and keepalive, reset curl handle if we did not get back an http 200 response (eg a 302)</para>
- </listitem>
-
- <listitem>
- <para>omit port on http 'Host' header if it is 80</para>
- </listitem>
-
- <listitem>
- <para>test suite allows interrogating https servers ignoring their certs</para>
- </listitem>
-
- <listitem>
- <para>method setAcceptedCompression was failing to disable reception of compressed responses if the
- client supported them</para>
- </listitem>
-
- </itemizedlist></para>
- </sect1>
-
- <sect1>
- <title>3.0.0 beta</title>
-
- <para>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.</para>
-
- <para>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.</para>
-
- <para><itemizedlist>
- <listitem>
- <para>improved: removed all usage of php functions deprecated in
- php 5.3, usage of assign-by-ref when creating new objects
- etc...</para>
- </listitem>
-
- <listitem>
- <para>improved: add support for the <ex:nil/> tag used by
- the apache library, both in input and output</para>
- </listitem>
-
- <listitem>
- <para>improved: add support for <classname>dateTime</classname>
- objects in both in <function>php_xmlrpc_encode</function> and as
- parameter for constructor of
- <classname>xmlrpcval</classname></para>
- </listitem>
-
- <listitem>
- <para>improved: add support for timestamps as parameter for
- constructor of <classname>xmlrpcval</classname></para>
- </listitem>
-
- <listitem>
- <para>improved: add option 'dates_as_objects' to
- <function>php_xmlrpc_decode</function> to return
- <classname>dateTime</classname> objects for xmlrpc
- datetimes</para>
- </listitem>
-
- <listitem>
- <para>improved: add new method
- <methodname>SetCurlOptions</methodname> to
- <classname>xmrlpc_client</classname> to allow extra flexibility in
- tweaking http config, such as explicitly binding to an ip
- address</para>
- </listitem>
-
- <listitem>
- <para>improved: add new method
- <methodname>SetUserAgent</methodname> to
- <classname>xmrlpc_client</classname> to to allow having different
- user-agent http headers</para>
- </listitem>
-
- <listitem>
- <para>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</para>
- </listitem>
-
- <listitem>
- <para>improved: allow servers in 'xmlrpcvals' mode to also
- register plain php functions by defining them in the dispatch map
- with an added option</para>
- </listitem>
-
- <listitem>
- <para>improved: catch exceptions thrown during execution of php
- functions exposed as methods by the server</para>
- </listitem>
-
- <listitem>
- <para>fixed: bad encoding if same object is encoded twice using
- php_xmlrpc_encode</para>
- </listitem>
- </itemizedlist></para>
- </sect1>
-
- <sect1>
- <title>2.2.2</title>
-
- <para><emphasis>Note:</emphasis> 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.</para>
-
- <para><itemizedlist>
- <listitem>
- <para>fixed: encoding of utf-8 characters outside of the BMP
- plane</para>
- </listitem>
-
- <listitem>
- <para>fixed: character set declarations surrounded by double
- quotes were not recognized in http headers</para>
- </listitem>
-
- <listitem>
- <para>fixed: be more tolerant in detection of charset in http
- headers</para>
- </listitem>
-
- <listitem>
- <para>fixed: fix detection of zlib.output_compression</para>
- </listitem>
-
- <listitem>
- <para>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)</para>
- </listitem>
-
- <listitem>
- <para>fixed: format floating point values using the correct
- decimal separator even when php locale is set to one that uses
- comma</para>
- </listitem>
-
- <listitem>
- <para>fixed: improve robustness of the debugger when parsing weird
- results from non-compliant servers</para>
- </listitem>
-
- <listitem>
- <para>php warning when receiving 'false' in a bool value</para>
- </listitem>
-
- <listitem>
- <para>improved: allow the add_to_map server method to add docs for
- single params too</para>
- </listitem>
-
- <listitem>
- <para>improved: added the possibility to wrap for exposure as
- xmlrpc methods plain php class methods, object methods and even
- whole classes</para>
- </listitem>
- </itemizedlist></para>
- </sect1>
-
- <sect1>
- <title>2.2.1</title>
-
- <itemizedlist>
- <listitem>
- <para>fixed: work aroung bug in php 5.2.2 which broke support of
- HTTP_RAW_POST_DATA</para>
- </listitem>
-
- <listitem>
- <para>fixed: is_dir parameter of setCaCertificate() method is
- reversed</para>
- </listitem>
-
- <listitem>
- <para>fixed: a php warning in xmlrpc_client creator method</para>
- </listitem>
-
- <listitem>
- <para>fixed: parsing of '1e+1' as valid float</para>
- </listitem>
-
- <listitem>
- <para>fixed: allow errorlevel 3 to work when prev. error handler was
- a static method</para>
- </listitem>
-
- <listitem>
- <para>fixed: usage of client::setcookie() for multiple cookies in
- non-ssl mode</para>
- </listitem>
-
- <listitem>
- <para>improved: support for CP1252 charset is not part or the
- library but almost possible</para>
- </listitem>
-
- <listitem>
- <para>improved: more info when curl is enabled and debug mode is
- on</para>
- </listitem>
- </itemizedlist>
- </sect1>
-
- <sect1>
- <title>2.2</title>
-
- <itemizedlist>
- <listitem>
- <para>fixed: debugger errors on php installs with magic_quotes_gpc
- on</para>
- </listitem>
-
- <listitem>
- <para>fixed: support for https connections via proxy</para>
- </listitem>
-
- <listitem>
- <para>fixed: wrap_xmlrpc_method() generated code failed to properly
- encode php objects</para>
- </listitem>
-
- <listitem>
- <para>improved: slightly faster encoding of data which is internally
- UTF-8</para>
- </listitem>
-
- <listitem>
- <para>improved: debugger always generates a 'null' id for jsonrpc if
- user omits it</para>
- </listitem>
-
- <listitem>
- <para>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)</para>
- </listitem>
-
- <listitem>
- <para>new: support for the <NIL/> xmlrpc extension. see below
- for more details</para>
- </listitem>
-
- <listitem>
- <para>new: server support for the system.getCapabilities xmlrpc
- extension</para>
- </listitem>
-
- <listitem>
- <para>new: <function><link
- linkend="wrap_xmlrpc_method">wrap_xmlrpc_method()</link></function>
- accepts two new options: debug and return_on_fault</para>
- </listitem>
- </itemizedlist>
- </sect1>
-
- <sect1>
- <title>2.1</title>
-
- <para><itemizedlist>
- <listitem>
- <para>The <function>wrap_php_function</function> and
- <function>wrap_xmlrpc_method</function> functions have been moved
- out of the base library file <filename>xmlrpc.inc</filename> into
- a file of their own: <filename>xmlrpc_wrappers.php</filename>. 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 <function>wrap_xmlrpc_method()</function> has been disabled
- (but it can be optionally re-enabled). Both
- <function>wrap_php_function()</function> and
- <function>wrap_xmlrpc_method()</function> 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</para>
- </listitem>
-
- <listitem>
- <para>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 <code>new xmlrpcval('true', 'boolean')</code>
- is not supported anymore</para>
- </listitem>
-
- <listitem>
- <para>The new function
- <function>php_xmlrpc_decode_xml()</function> will take the xml
- representation of either an xmlrpc request, response or single
- value and return the corresponding php-xmlrpc object
- instance</para>
- </listitem>
-
- <listitem>
- <para>A new function <function>wrap_xmlrpc_server()</function>has
- been added, to wrap all (or some) of the methods exposed by a
- remote xmlrpc server into a php class</para>
- </listitem>
-
- <listitem>
- <para>A new file has been added:
- <filename>verify_compat.php</filename>, to help users diagnose the
- level of compliance of their php installation with the
- library</para>
- </listitem>
-
- <listitem>
- <para>Restored compatibility with php 4.0.5 (for those poor souls
- still stuck on it)</para>
- </listitem>
-
- <listitem>
- <para>Method <methodname>xmlrpc_server->service()</methodname>
- now returns a value: either the response payload or xmlrpcresp
- object instance</para>
- </listitem>
-
- <listitem>
- <para>Method
- <methodname>xmlrpc_server->add_to_map()</methodname> now
- accepts xmlrpc methods with no param definitions</para>
- </listitem>
-
- <listitem>
- <para>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)</para>
- </listitem>
-
- <listitem>
- <para>Full response payload is saved into xmlrpcresp object for
- further debugging</para>
- </listitem>
-
- <listitem>
- <para>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)</para>
- </listitem>
-
- <listitem>
- <para>Stricter parsing of incoming xmlrpc messages: two more
- invalid cases are now detected (double <literal>data</literal>
- element inside <literal>array</literal> and
- <literal>struct</literal>/<literal>array</literal> after scalar
- inside <literal>value</literal> element)</para>
- </listitem>
-
- <listitem>
- <para>More logging of errors in a lot of situations</para>
- </listitem>
-
- <listitem>
- <para>Javadoc documentation of lib files (almost) complete</para>
- </listitem>
-
- <listitem>
- <para>Many performance tweaks and code cleanups, plus the usual
- crop of bugs fixed (see NEWS file for complete list of
- bugs)</para>
- </listitem>
-
- <listitem>
- <para>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)...</para>
- </listitem>
- </itemizedlist></para>
- </sect1>
-
- <sect1>
- <title>2.0 final</title>
-
- <para><itemizedlist>
- <listitem>
- <para>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</para>
- </listitem>
-
- <listitem>
- <para>Added to the client class the possibility to specify
- alternate certificate files/directories for authenticating the
- peer with when using HTTPS communication</para>
- </listitem>
-
- <listitem>
- <para>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)</para>
- </listitem>
-
- <listitem>
- <para>The debugger has been upgraded to reflect the new client
- capabilities</para>
- </listitem>
-
- <listitem>
- <para>All known bugs have been squashed, and the lib is more
- tolerant than ever of commonly-found mistakes</para>
- </listitem>
- </itemizedlist></para>
- </sect1>
-
- <sect1>
- <title>2.0 Release candidate 3</title>
-
- <para><itemizedlist>
- <listitem>
- <para>Added to server class the property
- <property>functions_parameters_type</property>, 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)</para>
- </listitem>
-
- <listitem>
- <para>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)</para>
- </listitem>
-
- <listitem>
- <para>let php_xmlrpc_decode accept xmlrpcmsg objects as valid
- input</para>
- </listitem>
-
- <listitem>
- <para>'class::method' syntax is now accepted in the server
- dispatch map</para>
- </listitem>
-
- <listitem>
- <para><function>xmlrpc_clent::SetDebug()</function> accepts
- integer values instead of a boolean value, with debugging level 2
- adding to the information printed to screen the complete client
- request</para>
- </listitem>
- </itemizedlist></para>
- </sect1>
-
- <sect1>
- <title>2.0 Release candidate 2</title>
-
- <para><itemizedlist>
- <listitem>
- <para>Added a new property of the client object:
- <code>xmlrpc_client->return_type</code>, 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.</para>
- </listitem>
-
- <listitem>
- <para>Added in the extras dir. two new library file:
- <filename>jsonrpc.inc</filename> and
- <filename>jsonrpcs.inc</filename> containing new classes that
- implement support for the json-rpc protocol (alpha quality
- code)</para>
- </listitem>
-
- <listitem>
- <para>Added a new client method: <code>setKey($key,
- $keypass)</code> to be used in HTTPS connections</para>
- </listitem>
-
- <listitem>
- <para>Added a new file containing some benchmarks in the testsuite
- directory</para>
- </listitem>
- </itemizedlist></para>
- </sect1>
-
- <sect1>
- <title>2.0 Release candidate 1</title>
-
- <itemizedlist>
- <listitem>
- <para>Support for HTTP proxies (new method:
- <code>xmlrpc_client::setProxy()</code>)</para>
- </listitem>
-
- <listitem>
- <para>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:
- <code>xmlrpc_client::setAcceptedCompression()</code>,
- <code>xmlrpc_client::setRequestCompression()</code>). Note that the
- ZLIB php extension needs to be enabled in PHP to support
- compression.</para>
- </listitem>
-
- <listitem>
- <para>Implement HTTP 1.1 connections, but only if CURL is enabled
- (added an extra parameter to
- <code>xmlrpc_client::xmlrpc_client</code> to set the desired HTTP
- protocol at creation time and a new supported value for the last
- parameter of <code>xmlrpc_client::send</code>, which now can be
- safely omitted if it has been specified at creation time)</para>
-
- <para>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.</para>
- </listitem>
-
- <listitem>
- <para>Introduce support for cookies. Cookies to be sent to the
- server with a request can be set using
- <code>xmlrpc_client::setCookie()</code>, while cookies received from
- the server are found in <code>xmlrpcresp::cookies()</code>. It is
- left to the user to check for validity of received cookies and
- decide whether they apply to successive calls or not.</para>
- </listitem>
-
- <listitem>
- <para>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.</para>
-
- <para>Supported encodings are US-ASCII, UTF-8 and ISO-8859-1.</para>
- </listitem>
-
- <listitem>
- <para>Added one new xmlrpcmsg constructor syntax, allowing usage of
- a single string with the complete URL of the target server</para>
- </listitem>
-
- <listitem>
- <para>Convert xml-rpc boolean values into native php values instead
- of 0 and 1</para>
- </listitem>
-
- <listitem>
- <para>Force the <code>php_xmlrpc_encode</code> 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)</para>
- </listitem>
-
- <listitem>
- <para>Prevent the <code>php_xmlrpc_encode</code> function from
- further re-encoding any objects of class <code>xmlrpcval</code> that
- are passed to it. This allows to call the function with arguments
- consisting of mixed php values / xmlrpcval objects.</para>
- </listitem>
-
- <listitem>
- <para>Allow a server to NOT respond to system.* method calls
- (setting the <code>$server->allow_system_funcs</code>
- property).</para>
- </listitem>
-
- <listitem>
- <para>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: <code>xmlrpcval::structMemExists()</code></para>
- </listitem>
-
- <listitem>
- <para>Expand methods <code>xmlrpcval::addArray</code>,
- <code>addScalar</code> and <code>addStruct</code> allowing extra php
- values to be added to xmlrpcval objects already formed.</para>
- </listitem>
-
- <listitem>
- <para>Let the <code>xmlrpc_client::send</code> method accept an XML
- string for sending instead of an xmlrpcmsg object, to facilitate
- debugging and integration with the php native xmlrpc
- extension</para>
- </listitem>
-
- <listitem>
- <para>Extend the <code>php_xmlrpc_encode</code> and
- <code>php_xmlrpc_decode</code> 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.</para>
-
- <para>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 <code>php_xmlrpc_encode</code> and
- <code>php_xmlrpc_decode</code>.</para>
- </listitem>
-
- <listitem>
- <para>Extend the <code>php_xmlrpc_encode</code> function to allow
- automatic serialization of iso8601-conforming php strings as
- datetime.iso8601 xmlrpcvals, by usage of an optional
- parameter</para>
- </listitem>
-
- <listitem>
- <para>Added an automatic stub code generator for converting xmlrpc
- methods to php functions and vice-versa.</para>
-
- <para>This is done via two new functions:
- <code>wrap_php_function</code> and <code>wrap_xmlrpc_method</code>,
- and has many caveats, with php being a typeless language and
- all...</para>
- </listitem>
-
- <listitem>
- <para>Allow object methods to be used in server dispatch map</para>
- </listitem>
-
- <listitem>
- <para>Added a complete debugger solution, in the
- <filename>debugger</filename> folder</para>
- </listitem>
-
- <listitem>
- <para>Added configurable server-side debug messages, controlled by
- the new method <code>xmlrpc_server::SetDebug()</code>. 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</para>
- </listitem>
-
- <listitem>
- <para>New XML parsing code, yields smaller memory footprint and
- faster execution times, not to mention complete elimination of the
- dreaded <filename>eval()</filename> construct, so prone to code
- injection exploits</para>
- </listitem>
-
- <listitem>
- <para>Rewritten most of the error messages, making text more
- explicative</para>
- </listitem>
- </itemizedlist>
- </sect1>
- </chapter>
-
- <chapter id="requirements">
- <title>System Requirements</title>
-
- <para>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.</para>
-
- <para>The <emphasis>minimum supported</emphasis> PHP version is
- 5.3.</para>
-
- <para>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.</para>
-
- <para>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.</para>
- </chapter>
-
- <chapter id="manifest">
- <title>Files in the distribution</title>
-
- <glosslist>
- <glossentry>
- <glossterm>lib/xmlrpc.inc</glossterm>
-
- <glossdef>
- <para>the XML-RPC classes. <function>include()</function> this in
- your PHP files to use the classes.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>lib/xmlrpcs.inc</glossterm>
-
- <glossdef>
- <para>the XML-RPC server class. <function>include()</function> this
- in addition to xmlrpc.inc to get server functionality</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>lib/xmlrpc_wrappers.php</glossterm>
-
- <glossdef>
- <para>helper functions to "automagically" convert plain php
- functions to xmlrpc services and vice versa</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>demo/server/proxy.php</glossterm>
-
- <glossdef>
- <para>a sample server implementing xmlrpc proxy
- functionality.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>demo/server/server.php</glossterm>
-
- <glossdef>
- <para>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</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>demo/client/client.php, demo/client/agesort.php,
- demo/client/which.php</glossterm>
-
- <glossdef>
- <para>client code to exercise some of the functions in server.php,
- including the <function>interopEchoTests.whichToolkit</function>
- method.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>demo/client/wrap.php</glossterm>
-
- <glossdef>
- <para>client code to illustrate 'wrapping' of remote methods into
- php functions.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>demo/client/introspect.php</glossterm>
-
- <glossdef>
- <para>client code to illustrate usage of introspection capabilities
- offered by server.php.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>demo/client/mail.php</glossterm>
-
- <glossdef>
- <para>client code to illustrate usage of an xmlrpc-to-email gateway
- using Dave Winer's XML-RPC server at userland.com.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>demo/client/zopetest.php</glossterm>
-
- <glossdef>
- <para>example client code that queries an xmlrpc server built in
- Zope.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>demo/vardemo.php</glossterm>
-
- <glossdef>
- <para>examples of how to construct xmlrpcval types</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>demo/demo1.xml, demo/demo2.xml, demo/demo3.xml</glossterm>
-
- <glossdef>
- <para>XML-RPC responses captured in a file for testing purposes (you
- can use these to test the
- <function>xmlrpcmsg->parseResponse()</function> method).</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>demo/server/discuss.php,
- demo/client/comment.php</glossterm>
-
- <glossdef>
- <para>Software used in the PHP chapter of <xref
- linkend="jellyfish" /> to provide a comment server and allow the
- attachment of comments to stories from Meerkat's data store.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>test/testsuite.php, test/parse_args.php</glossterm>
-
- <glossdef>
- <para>A unit test suite for this software package. If you do
- development on this software, please consider submitting tests for
- this suite.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>test/benchmark.php</glossterm>
-
- <glossdef>
- <para>A (very limited) benchmarking suite for this software package.
- If you do development on this software, please consider submitting
- benchmarks for this suite.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>test/phpunit.php, test/PHPUnit/*.php</glossterm>
-
- <glossdef>
- <para>An (incomplete) version PEAR's unit test framework for PHP.
- The complete package can be found at <ulink
- url="http://pear.php.net/package/PHPUnit">http://pear.php.net/package/PHPUnit</ulink></para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>test/verify_compat.php</glossterm>
-
- <glossdef>
- <para>Script designed to help the user to verify the level of
- compatibility of the library with the current php install</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>extras/test.pl, extras/test.py</glossterm>
-
- <glossdef>
- <para>Perl and Python programs to exercise server.php to test that
- some of the methods work.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>extras/workspace.testPhpServer.fttb</glossterm>
-
- <glossdef>
- <para>Frontier scripts to exercise the demo server. Thanks to Dave
- Winer for permission to include these. See <ulink
- url="http://www.xmlrpc.com/discuss/msgReader$853">Dave's
- announcement of these.</ulink></para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>extras/rsakey.pem</glossterm>
-
- <glossdef>
- <para>A test certificate key for the SSL support, which can be used
- to generate dummy certificates. It has the passphrase "test."</para>
- </glossdef>
- </glossentry>
- </glosslist>
- </chapter>
-
- <chapter id="bugs">
- <title>Known bugs and limitations</title>
-
- <para>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).</para>
-
- <para>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 <xref
- linkend="iso8601encode" /> and <xref linkend="iso8601decode" /> functions
- to do the encoding and decoding for you.</para>
-
- <para>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.</para>
-
- <para>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 <xref linkend="xmlrpc-defencoding" /></para>
-
- <para>Support for receiving from servers version 1 cookies (i.e.
- conforming to RFC 2965) is quite incomplete, and might cause unforeseen
- errors.</para>
- </chapter>
-
- <chapter id="support">
- <title>Support</title>
-
- <sect1>
- <title>Online Support</title>
-
- <para>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.</para>
-
- <itemizedlist>
- <listitem>
- <para>The <emphasis>XML-RPC for PHP</emphasis> development is hosted
- on <ulink
- url="https://github.com/gggeek/phpxmlrpc">github.com/gggeek/phpxmlrpc</ulink>.
- Bugs, feature requests and patches can be posted to the <ulink
- url="https://github.com/gggeek/phpxmlrpc/issues">project's
- website</ulink>.</para>
- </listitem>
-
- <listitem>
- <para>The <emphasis>PHP XML-RPC interest mailing list</emphasis> is
- run by the author. More details <ulink
- url="http://lists.gnomehack.com/mailman/listinfo/phpxmlrpc">can be
- found here</ulink>.</para>
- </listitem>
-
- <listitem>
- <para>For more general XML-RPC questions, there is a Yahoo! Groups
- <ulink url="http://groups.yahoo.com/group/xml-rpc/">XML-RPC mailing
- list</ulink>.</para>
- </listitem>
-
- <listitem>
- <para>The <ulink
- url="http://www.xmlrpc.com/discuss">XML-RPC.com</ulink> discussion
- group is a useful place to get help with using XML-RPC. This group
- is also gatewayed into the Yahoo! Groups mailing list.</para>
- </listitem>
- </itemizedlist>
- </sect1>
-
- <sect1 id="jellyfish" xreflabel="The Jellyfish Book">
- <title>The Jellyfish Book</title>
-
- <para><graphic align="right" depth="190" fileref="images/progxmlrpc.s.gif"
- format="GIF" width="145" />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.</para>
-
- <para>Complete details of the book are <ulink
- url="http://www.oreilly.com/catalog/progxmlrpc/">available from
- O'Reilly's web site.</ulink></para>
-
- <para>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
- <ulink url="http://meerkat.oreillynet.com/">Meerkat</ulink> service in
- order to allow commenting on news stories from around the Web.</para>
-
- <para>If you've benefited from the effort that has been put into writing
- this software, then please consider buying the book!</para>
- </sect1>
- </chapter>
-
- <chapter id="apidocs">
- <title>Class documentation</title>
-
- <sect1 id="xmlrpcval" xreflabel="xmlrpcval">
- <title>xmlrpcval</title>
-
- <para>This is where a lot of the hard work gets done. This class enables
- the creation and encapsulation of values for XML-RPC.</para>
-
- <para>Ensure you've read the XML-RPC spec at <ulink
- url="http://www.xmlrpc.com/stories/storyReader$7">http://www.xmlrpc.com/stories/storyReader$7</ulink>
- before reading on as it will make things clearer.</para>
-
- <para>The <classname>xmlrpcval</classname> class can store arbitrarily
- complicated values using the following types: <literal>i4 int boolean
- string double dateTime.iso8601 base64 array struct</literal>
- <literal>null</literal>. You should refer to the <ulink
- url="http://www.xmlrpc.com/spec">spec</ulink> for more information on
- what each of these types mean.</para>
-
- <sect2>
- <title>Notes on types</title>
-
- <sect3>
- <title>int</title>
-
- <para>The type <classname>i4</classname> is accepted as a synonym
- for <classname>int</classname> when creating xmlrpcval objects. The
- xml parsing code will always convert <classname>i4</classname> to
- <classname>int</classname>: <classname>int</classname> is regarded
- by this implementation as the canonical name for this type.</para>
- </sect3>
-
- <sect3>
- <title>base64</title>
-
- <para>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.</para>
- </sect3>
-
- <sect3>
- <title>boolean</title>
-
- <para>The php values <literal>true</literal> and
- <literal>1</literal> map to <literal>true</literal>. All other
- values (including the empty string) are converted to
- <literal>false</literal>.</para>
- </sect3>
-
- <sect3>
- <title>string</title>
-
- <para>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
- <literal>< &</literal> but this implementation goes further,
- for reasons explained by <ulink
- url="http://www.w3.org/TR/REC-xml#syntax">the XML 1.0
- recommendation</ulink>. In particular, using character reference
- representation has the advantage of producing XML that is valid
- independently of the charset encoding assumed.</para>
- </sect3>
-
- <sect3>
- <title>null</title>
-
- <para>There is no support for encoding <literal>null</literal>
- values in the XML-RPC spec, but at least a couple of extensions (and
- many toolkits) do support it. Before using <literal>null</literal>
- values in your messages, make sure that the responding party accepts
- them, and uses the same encoding convention (see ...).</para>
- </sect3>
- </sect2>
-
- <sect2 id="xmlrpcval-creation" xreflabel="xmlrpcval constructors">
- <title>Creation</title>
-
- <para>The constructor is the normal way to create an
- <classname>xmlrpcval</classname>. The constructor can take these
- forms:</para>
-
- <funcsynopsis>
- <funcprototype>
- <funcdef><type>xmlrpcval</type>new
- <function>xmlrpcval</function></funcdef>
-
- <void />
- </funcprototype>
-
- <funcprototype>
- <funcdef><type>xmlrpcval</type>new
- <function>xmlrpcval</function></funcdef>
-
- <paramdef><type>string</type><parameter>$stringVal</parameter></paramdef>
- </funcprototype>
-
- <funcprototype>
- <funcdef><type>xmlrpcval</type>new
- <function>xmlrpcval</function></funcdef>
-
- <paramdef><type>mixed</type><parameter>$scalarVal</parameter></paramdef>
-
- <paramdef><type>string</type><parameter>$scalartyp</parameter></paramdef>
- </funcprototype>
-
- <funcprototype>
- <funcdef><type>xmlrpcval</type>new
- <function>xmlrpcval</function></funcdef>
-
- <paramdef><type>array</type><parameter>$arrayVal</parameter></paramdef>
-
- <paramdef><type>string</type><parameter>$arraytyp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
-
- <para>The first constructor creates an empty value, which must be
- altered using the methods <function>addScalar</function>,
- <function>addArray</function> or <function>addStruct</function> before
- it can be used.</para>
-
- <para>The second constructor creates a simple string value.</para>
-
- <para>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:
- "<literal>int</literal>", "<literal>boolean</literal>",
- "<literal>string</literal>", "<literal>double</literal>",
- "<literal>dateTime.iso8601</literal>", "<literal>base64</literal>" or
- "null".</para>
-
- <para>Examples:</para>
-
- <programlisting language="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
-</programlisting>
-
- <para>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 <classname>array</classname> or an associative
- array in the case of a <classname>struct</classname>. The elements of
- the array <emphasis>must be <classname>xmlrpcval</classname> objects
- themselves</emphasis>.</para>
-
- <para>The second parameter must be either "<literal>array</literal>"
- or "<literal>struct</literal>".</para>
-
- <para>Examples:</para>
-
- <programlisting language="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");
-</programlisting>
-
- <para>See the file <literal>vardemo.php</literal> in this distribution
- for more examples.</para>
- </sect2>
-
- <sect2 id="xmlrpcval-methods" xreflabel="xmlrpcval methods">
- <title>Methods</title>
-
- <sect3>
- <title>addScalar</title>
-
- <funcsynopsis>
- <funcprototype>
- <funcdef><type>int</type><function>addScalar</function></funcdef>
-
- <paramdef><type>string</type><parameter>$stringVal</parameter></paramdef>
- </funcprototype>
-
- <funcprototype>
- <funcdef><type>int</type><function>addScalar</function></funcdef>
-
- <paramdef><type>mixed</type><parameter>$scalarVal</parameter></paramdef>
-
- <paramdef><type>string</type><parameter>$scalartyp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
-
- <para>If <parameter>$val</parameter> is an empty
- <classname>xmlrpcval</classname> this method makes it a scalar
- value, and sets that value.</para>
-
- <para>If <parameter>$val</parameter> is already a scalar value, then
- no more scalars can be added and <literal>0</literal> is
- returned.</para>
-
- <para>If <parameter>$val</parameter> is an xmlrpcval of type array,
- the php value <parameter>$scalarval</parameter> is added as its last
- element.</para>
-
- <para>If all went OK, <literal>1</literal> is returned, otherwise
- <literal>0</literal>.</para>
- </sect3>
-
- <sect3>
- <title>addArray</title>
-
- <funcsynopsis>
- <funcprototype>
- <funcdef><type>int</type><function>addArray</function></funcdef>
-
- <paramdef><type>array</type><parameter>$arrayVal</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
-
- <para>The argument is a simple (numerically indexed) array. The
- elements of the array <emphasis>must be
- <classname>xmlrpcval</classname> objects
- themselves</emphasis>.</para>
-
- <para>Turns an empty <classname>xmlrpcval</classname> into an
- <classname>array</classname> with contents as specified by
- <parameter>$arrayVal</parameter>.</para>
-
- <para>If <parameter>$val</parameter> is an xmlrpcval of type array,
- the elements of <parameter>$arrayVal</parameter> are appended to the
- existing ones.</para>
-
- <para>See the fourth constructor form for more information.</para>
-
- <para>If all went OK, <literal>1</literal> is returned, otherwise
- <literal>0</literal>.</para>
- </sect3>
-
- <sect3>
- <title>addStruct</title>
-
- <funcsynopsis>
- <funcprototype>
- <funcdef><type>int</type><function>addStruct</function></funcdef>
-
- <paramdef><type>array</type><parameter>$assocArrayVal</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
-
- <para>The argument is an associative array. The elements of the
- array <emphasis>must be <classname>xmlrpcval</classname> objects
- themselves</emphasis>.</para>
-
- <para>Turns an empty <classname>xmlrpcval</classname> into a
- <classname>struct</classname> with contents as specified by
- <parameter>$assocArrayVal</parameter>.</para>
-
- <para>If <parameter>$val</parameter> is an xmlrpcval of type struct,
- the elements of <parameter>$arrayVal</parameter> are merged with the
- existing ones.</para>
-
- <para>See the fourth constructor form for more information.</para>
-
- <para>If all went OK, <literal>1</literal> is returned, otherwise
- <literal>0</literal>.</para>
- </sect3>
-
- <sect3>
- <title>kindOf</title>
-
- <funcsynopsis>
- <funcprototype>
- <funcdef><type>string</type><function>kindOf</function></funcdef>
-
- <void />
- </funcprototype>
- </funcsynopsis>
-
- <para>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.</para>
- </sect3>
-
- <sect3>
- <title>serialize</title>
-
- <funcsynopsis>
- <funcprototype>
- <funcdef><type>string</type><function>serialize</function></funcdef>
-
- <void />
- </funcprototype>
- </funcsynopsis>
-
- <para>Returns a string containing the XML-RPC representation of this
- value.</para>
- </sect3>
-
- <sect3>
- <title>scalarVal</title>
-
- <funcsynopsis>
- <funcprototype>
- <funcdef><type>mixed</type><function>scalarVal</function></funcdef>
-
- <void />
- </funcprototype>
- </funcsynopsis>
-
- <para>If <function>$val->kindOf() == "scalar"</function>, this
- method returns the actual PHP-language value of the scalar (base 64
- decoding is automatically handled here).</para>
- </sect3>
-
- <sect3>
- <title>scalarTyp</title>
-
- <funcsynopsis>
- <funcprototype>
- <funcdef><type>string</type><function>scalarTyp</function></funcdef>
-
- <void />
- </funcprototype>
- </funcsynopsis>
-
- <para>If <function>$val->kindOf() == "scalar"</function>, this
- method returns a string denoting the type of the scalar. As
- mentioned before, <literal>i4</literal> is always coerced to
- <literal>int</literal>.</para>
- </sect3>
-
- <sect3>
- <title>arrayMem</title>
-
- <funcsynopsis>
- <funcprototype>
- <funcdef><type>xmlrpcval</type><function>arrayMem</function></funcdef>
-
- <paramdef><type>int</type><parameter>$n</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
-
- <para>If <function>$val->kindOf() == "array"</function>, returns
- the <parameter>$n</parameter>th element in the array represented by
- the value <parameter>$val</parameter>. The value returned is an
- <classname>xmlrpcval</classname> object.</para>
-
- <para><programlisting language="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();
-}
-</programlisting></para>
- </sect3>
-
- <sect3>
- <title>arraySize</title>
-
- <funcsynopsis>
- <funcprototype>
- <funcdef><type>int</type><function>arraySize</function></funcdef>
-
- <void />
- </funcprototype>
- </funcsynopsis>
-
- <para>If <parameter>$val</parameter> is an
- <classname>array</classname>, returns the number of elements in that
- array.</para>
- </sect3>
-
- <sect3>
- <title>structMem</title>
-
- <funcsynopsis>
- <funcprototype>
- <funcdef><type>xmlrpcval</type><function>structMem</function></funcdef>
-
- <paramdef><type>string</type><parameter>$memberName</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
-
- <para>If <function>$val->kindOf() == "struct"</function>, returns
- the element called <parameter>$memberName</parameter> from the
- struct represented by the value <parameter>$val</parameter>. The
- value returned is an <classname>xmlrpcval</classname> object.</para>
- </sect3>
-
- <sect3>
- <title>structEach</title>
-
- <funcsynopsis>
- <funcprototype>
- <funcdef><type>array</type><function>structEach</function></funcdef>
-
- <void />
- </funcprototype>
- </funcsynopsis>
-
- <para>Returns the next (key, value) pair from the struct, when
- <parameter>$val</parameter> is a struct.
- <parameter>$value</parameter> is an xmlrpcval itself. See also <xref
- linkend="structreset" />.</para>
-
- <para><programlisting language="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();
-}
-</programlisting></para>
- </sect3>
-
- <sect3 id="structreset" xreflabel="structreset()">
- <title>structReset</title>
-
- <funcsynopsis>
- <funcprototype>
- <funcdef><type>void</type><function>structReset</function></funcdef>
-
- <void />
- </funcprototype>
- </funcsynopsis>
-
- <para>Resets the internal pointer for
- <function>structEach()</function> to the beginning of the struct,
- where <parameter>$val</parameter> is a struct.</para>
- </sect3>
-
- <sect3 id="structmemexists" xreflabel="structmemexists()">
- <title>structMemExists</title>
-
- <funcsynopsis>
- <funcprototype>
- <funcdef><type>bool</type><function>structMemExsists</function></funcdef>
-
- <paramdef><type>string</type><parameter>$memberName</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
-
- <para>Returns <constant>TRUE</constant> or
- <constant>FALSE</constant> depending on whether a member of the
- given name exists in the struct.</para>
- </sect3>
- </sect2>
- </sect1>
-
- <sect1 id="xmlrpcmsg" xreflabel="xmlrpcmsg">
- <title>xmlrpcmsg</title>
-
- <para>This class provides a representation for a request to an XML-RPC
- server. A client sends an <classname>xmlrpcmsg</classname> to a server,
- and receives back an <classname>xmlrpcresp</classname> (see <xref
- linkend="xmlrpc-client-send" />).</para>
-
- <sect2>
- <title>Creation</title>
-
- <para>The constructor takes the following forms:</para>
-
- <funcsynopsis>
- <funcprototype>
- <funcdef><type>xmlrpcmsg</type>new
- <function>xmlrpcmsg</function></funcdef>
-
- <paramdef><type>string</type><parameter>$methodName</parameter></paramdef>
-
- <paramdef><type>array</type><parameter>$parameterArray</parameter><initializer>null</initializer></paramdef>
- </funcprototype>
- </funcsynopsis>
-
- <para>Where <parameter>methodName</parameter> is a string indicating
- the name of the method you wish to invoke, and
- <parameter>parameterArray</parameter> is a simple php
- <classname>Array</classname> of <classname>xmlrpcval</classname>
- objects. Here's an example message to the <emphasis>US state
- name</emphasis> server:</para>
-
- <programlisting language="php">
-$msg = new xmlrpcmsg("examples.getStateName", array(new xmlrpcval(23, "int")));
-</programlisting>
-
- <para>This example requests the name of state number 23. For more
- information on <classname>xmlrpcval</classname> objects, see <xref
- linkend="xmlrpcval" />.</para>
-
- <para>Note that the <parameter>parameterArray</parameter> parameter is
- optional and can be omitted for methods that take no input parameters
- or if you plan to add parameters one by one.</para>
- </sect2>
-
- <sect2>
- <title>Methods</title>
-
- <sect3>
- <title>addParam</title>
-
- <funcsynopsis>
- <funcprototype>
- <funcdef><type>bool</type><function>addParam</function></funcdef>
-
- <paramdef><type>xmlrpcval</type><parameter>$xmlrpcVal</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
-
- <para>Adds the <classname>xmlrpcval</classname>
- <parameter>xmlrpcVal</parameter> to the parameter list for this
- method call. Returns TRUE or FALSE on error.</para>
- </sect3>
-
- <sect3>
- <title>getNumParams</title>
-
- <funcsynopsis>
- <funcprototype>
- <funcdef><type>int</type><function>getNumParams</function></funcdef>
-
- <void />
- </funcprototype>
- </funcsynopsis>
-
- <para>Returns the number of parameters attached to this
- message.</para>
- </sect3>
-
- <sect3>
- <title>getParam</title>
-
- <funcsynopsis>
- <funcprototype>
- <funcdef><type>xmlrpcval</type><function>getParam</function></funcdef>
-
- <paramdef><type>int</type><parameter>$n</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
-
- <para>Gets the <parameter>n</parameter>th parameter in the message
- (with the index zero-based). Use this method in server
- implementations to retrieve the values sent by the client.</para>
- </sect3>
-
- <sect3>
- <title>method</title>
-
- <funcsynopsis>
- <funcprototype>
- <funcdef><type>string</type><function>method</function></funcdef>
-
- <void />
- </funcprototype>
-
- <funcprototype>
- <funcdef><type>string</type><function>method</function></funcdef>
-
- <paramdef><type>string</type><parameter>$methName</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
-
- <para>Gets or sets the method contained in the XML-RPC
- message.</para>
- </sect3>
-
- <sect3>
- <title>parseResponse</title>
-
- <funcsynopsis>
- <funcprototype>
- <funcdef><type>xmlrpcresp</type><function>parseResponse</function></funcdef>
-
- <paramdef><type>string</type><parameter>$xmlString</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
-
- <para>Given an incoming XML-RPC server response contained in the
- string <parameter>$xmlString</parameter>, this method constructs an
- <classname>xmlrpcresp</classname> response object and returns it,
- setting error codes as appropriate (see <xref
- linkend="xmlrpc-client-send" />).</para>
-
- <para>This method processes any HTTP/MIME headers it finds.</para>
- </sect3>
-
- <sect3>
- <title>parseResponseFile</title>
-
- <funcsynopsis>
- <funcprototype>
- <funcdef><type>xmlrpcresp</type><function>parseResponseFile</function></funcdef>
-
- <paramdef><type>file handle
- resource</type><parameter>$fileHandle</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
-
- <para>Given an incoming XML-RPC server response on the open file
- handle <parameter>fileHandle</parameter>, this method reads all the
- data it finds and passes it to
- <function>parseResponse.</function></para>
-
- <para>This method is useful to construct responses from pre-prepared
- files (see files <literal>demo1.xml, demo2.xml, demo3.xml</literal>
- in this distribution). It processes any HTTP headers it finds, and
- does not close the file handle.</para>
- </sect3>
-
- <sect3>
- <title>serialize</title>
-
- <funcsynopsis>
- <funcprototype>
- <funcdef><type>string
- </type><function>serialize</function></funcdef>
-
- <void />
- </funcprototype>
- </funcsynopsis>
-
- <para>Returns the an XML string representing the XML-RPC
- message.</para>
- </sect3>
- </sect2>
- </sect1>
-
- <sect1 id="xmlrpc-client" xreflabel="xmlrpc_client">
- <title>xmlrpc_client</title>
-
- <para>This is the basic class used to represent a client of an XML-RPC
- server.</para>
-
- <sect2>
- <title>Creation</title>
-
- <para>The constructor accepts one of two possible syntaxes:</para>
-
- <funcsynopsis>
- <funcprototype>
- <funcdef><type>xmlrpc_client</type>new
- <function>xmlrpc_client</function></funcdef>
-
- <paramdef><type>string</type><parameter>$server_url</parameter></paramdef>
- </funcprototype>
-
- <funcprototype>
- <funcdef><type>xmlrpc_client</type>new
- <function>xmlrpc_client</function></funcdef>
-
- <paramdef><type>string</type><parameter>$server_path</parameter></paramdef>
-
- <paramdef><type>string</type><parameter>$server_hostname</parameter></paramdef>
-
- <paramdef><type>int</type><parameter>$server_port</parameter><initializer>80</initializer></paramdef>
-
- <paramdef><type>string</type><parameter>$transport</parameter><initializer>'http'</initializer></paramdef>
- </funcprototype>
- </funcsynopsis>
-
- <para>Here are a couple of usage examples of the first form:</para>
-
- <programlisting language="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");
-</programlisting>
-
- <para>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.</para>
-
- <para>Here's another example client set up to query Userland's XML-RPC
- server at <emphasis>betty.userland.com</emphasis>:</para>
-
- <programlisting language="php">
-$client = new xmlrpc_client("/RPC2", "betty.userland.com", 80);
-</programlisting>
-
- <para>The <parameter>server_port</parameter> parameter is optional,
- and if omitted will default to 80 when using HTTP and 443 when using
- HTTPS (see the <xref linkend="xmlrpc-client-send" /> method
- below).</para>
-
- <para>The <parameter>transport</parameter> parameter is optional, and
- if omitted will default to 'http'. Allowed values are either
- '<symbol>http'</symbol>, '<symbol>https</symbol>' or
- '<symbol>http11'</symbol>. Its value can be overridden with every call
- to the <methodname>send</methodname> method. See the
- <methodname>send</methodname> method below for more details about the
- meaning of the different values.</para>
- </sect2>
-
- <sect2>
- <title>Methods</title>
-
- <para>This class supports the following methods.</para>
-
- <sect3 id="xmlrpc-client-send" xreflabel="xmlrpc_client->send">
- <title>send</title>
-
- <para>This method takes the forms:</para>
-
- <funcsynopsis>
- <funcprototype>
- <funcdef><type>xmlrpcresp</type><function>send</function></funcdef>
-
- <paramdef><type>xmlrpcmsg</type><parameter>$xmlrpc_message</parameter></paramdef>
-
- <paramdef><type>int</type><parameter>$timeout</parameter></paramdef>
-
- <paramdef><type>string</type><parameter>$transport</parameter></paramdef>
- </funcprototype>
-
- <funcprototype>
- <funcdef><type>array</type><function>send</function></funcdef>
-
- <paramdef><type>array</type><parameter>$xmlrpc_messages</parameter></paramdef>
-
- <paramdef><type>int</type><parameter>$timeout</parameter></paramdef>
-
- <paramdef><type>string</type><parameter>$transport</parameter></paramdef>
- </funcprototype>
-
- <funcprototype>
- <funcdef><type>xmlrpcresp</type><function>send</function></funcdef>
-
- <paramdef><type>string</type><parameter>$xml_payload</parameter></paramdef>
-
- <paramdef><type>int</type><parameter>$timeout</parameter></paramdef>
-
- <paramdef><type>string</type><parameter>$transport</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
-
- <para>Where <parameter>xmlrpc_message</parameter> is an instance of
- <classname>xmlrpcmsg</classname> (see <xref linkend="xmlrpcmsg" />),
- and <parameter>response</parameter> is an instance of
- <classname>xmlrpcresp</classname> (see <xref
- linkend="xmlrpcresp" />).</para>
-
- <para><parameter>If xmlrpc_messages</parameter> is an array of
- message instances, <code>responses</code> will be an array of
- response instances. The client will try to make use of a single
- <code>system.multicall</code> xml-rpc method call to forward to the
- server all the messages in a single HTTP round trip, unless
- <code>$client->no_multicall</code> has been previously set to
- <code>TRUE</code> (see the multicall method below), in which case
- many consecutive xmlrpc requests will be sent.</para>
-
- <para>The third syntax allows to build by hand (or any other means)
- a complete xmlrpc request message, and send it to the server.
- <parameter>xml_payload</parameter> 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 <ulink
- url="http://www.php.net/xmlrpc">the php manual on
- xmlrpc</ulink>).</para>
-
- <para>The <parameter>timeout</parameter> is optional, and will be
- set to <literal>0</literal> (wait for platform-specific predefined
- timeout) if omitted. This timeout value is passed to
- <function>fsockopen()</function>. It is also used for detecting
- server timeouts during communication (i.e. if the server does not
- send anything to the client for <parameter>timeout</parameter>
- seconds, the connection will be closed).</para>
-
- <para>The <parameter>transport</parameter> 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.</para>
-
- <warning>
- <para>PHP 4.0.6 has a bug which prevents SSL working.</para>
- </warning>
-
- <para>In addition to low-level errors, the XML-RPC server you were
- querying may return an error in the
- <classname>xmlrpcresp</classname> object. See <xref
- linkend="xmlrpcresp" /> for details of how to handle these
- errors.</para>
- </sect3>
-
- <sect3 id="multicall" xreflabel="xmlrpc_client->multicall">
- <title>multiCall</title>
-
- <para>This method takes the form:</para>
-
- <funcsynopsis>
- <funcprototype>
- <funcdef><type>array</type><function>multiCall</function></funcdef>
-
- <paramdef><type>array</type><parameter>$messages</parameter></paramdef>
-
- <paramdef><type>int</type><parameter>$timeout</parameter></paramdef>
-
- <paramdef><type>string</type><parameter>$transport</parameter></paramdef>
-
- <paramdef><type>bool</type><parameter>$fallback</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
-
- <para>This method is used to boxcar many method calls in a single
- xml-rpc request. It will try first to make use of the
- <code>system.multicall</code> xml-rpc method call, and fall back to
- executing many separate requests if the server returns any
- error.</para>
-
- <para><parameter>msgs</parameter> is an array of
- <classname>xmlrpcmsg</classname> objects (see <xref
- linkend="xmlrpcmsg" />), and <parameter>response</parameter> is an
- array of <classname>xmlrpcresp</classname> objects (see <xref
- linkend="xmlrpcresp" />).</para>
-
- <para>The <parameter>timeout</parameter> and
- <parameter>transport</parameter> parameters are optional, and behave
- as in the <methodname>send</methodname> method above.</para>
-
- <para>The <parameter>fallback</parameter> parameter is optional, and
- defaults to <constant>TRUE</constant>. When set to
- <constant>FALSE</constant> 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.</para>
- </sect3>
-
- <sect3>
- <title>setAcceptedCompression</title>
-
- <funcsynopsis>
- <funcprototype>
- <funcdef><type>void</type><function>setAcceptedCompression</function></funcdef>
-
- <paramdef><type>string</type><parameter>$compressionmethod</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
-
- <para>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
- <parameter>compressionmethod</parameter> are: 'gzip', 'deflate',
- 'any' or null (with any meaning either gzip or deflate).</para>
-
- <para>This requires the "zlib" extension to be enabled in your php
- install. If it is, by default <classname>xmlrpc_client</classname>
- instances will enable reception of compressed content.</para>
- </sect3>
-
- <sect3>
- <title>setCaCertificate</title>
-
- <funcsynopsis>
- <funcprototype>
- <funcdef><type>void</type><function>setCaCertificate</function></funcdef>
-
- <paramdef><type>string</type><parameter>$certificate</parameter></paramdef>
-
- <paramdef><type>bool</type><parameter>$is_dir</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
-
- <para>This method sets an optional certificate to be used in
- SSL-enabled communication to validate a remote server with (when the
- <parameter>server_method</parameter> is set to 'https' in the
- client's construction or in the send method and
- <methodname>SetSSLVerifypeer</methodname> has been set to
- <constant>TRUE</constant>).</para>
-
- <para>The <parameter>certificate</parameter> parameter must be the
- filename of a PEM formatted certificate, or a directory containing
- multiple certificate files. The <parameter>is_dir</parameter>
- parameter defaults to <constant>FALSE</constant>, set it to
- <constant>TRUE</constant> to specify that
- <parameter>certificate</parameter> indicates a directory instead of
- a single file.</para>
-
- <para>This requires the "curl" extension to be compiled into your
- installation of PHP. For more details see the man page for the
- <function>curl_setopt</function> function.</para>
- </sect3>
-
- <sect3>
- <title>setCertificate</title>
-
- <funcsynopsis>
- <funcprototype>
- <funcdef><type>void</type><function>setCertificate</function></funcdef>
-
- <paramdef><type>string</type><parameter>$certificate</parameter></paramdef>
-
- <paramdef><type>string</type><parameter>$passphrase</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
-
- <para>This method sets the optional certificate and passphrase used
- in SSL-enabled communication with a remote server (when the
- <parameter>server_method</parameter> is set to 'https' in the
- client's construction or in the send method).</para>
-
- <para>The <parameter>certificate</parameter> parameter must be the
- filename of a PEM formatted certificate. The
- <parameter>passphrase</parameter> parameter must contain the
- password required to use the certificate.</para>
-
- <para>This requires the "curl" extension to be compiled into your
- installation of PHP. For more details see the man page for the
- <function>curl_setopt</function> function.</para>
-
- <para>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.</para>
- </sect3>
-
- <sect3>
- <title>setCookie</title>
-
- <funcsynopsis>
- <funcprototype>
- <funcdef><type>void</type><function>setCookie</function></funcdef>
-
- <paramdef><type>string</type><parameter>$name</parameter></paramdef>
-
- <paramdef><type>string</type><parameter>$value</parameter></paramdef>
-
- <paramdef><type>string</type><parameter>$path</parameter></paramdef>
-
- <paramdef><type>string</type><parameter>$domain</parameter></paramdef>
-
- <paramdef><type>int</type><parameter>$port</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
-
- <para>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).</para>
-
- <para><parameter>$value</parameter> is optional, and defaults to
- null.</para>
-
- <para><parameter>$path, $domain and $port</parameter> 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).</para>
- </sect3>
-
- <sect3>
- <title>setCredentials</title>
-
- <funcsynopsis>
- <funcprototype>
- <funcdef><type>void</type><function>setCredentials</function></funcdef>
-
- <paramdef><type>string</type><parameter>$username</parameter></paramdef>
-
- <paramdef><type>string</type><parameter>$password</parameter></paramdef>
-
- <paramdef><type>int</type><parameter>$authtype</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
-
- <para>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
- <constant>CURLAUTH_DIGEST</constant> and
- <constant>CURLAUTH_NTLM</constant> as values for the authtype
- parameter.</para>
- </sect3>
-
- <sect3>
- <title>setCurlOptions</title>
-
- <para><funcsynopsis>
- <funcprototype>
- <funcdef><type>void</type><function>setCurlOptions</function></funcdef>
-
- <paramdef><type>array</type><parameter>$options</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>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</para>
- </sect3>
-
- <sect3>
- <title>setDebug</title>
-
- <funcsynopsis>
- <funcprototype>
- <funcdef><type>void</type><function>setDebug</function></funcdef>
-
- <paramdef><type>int</type><parameter>$debugLvl</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
-
- <para><parameter>debugLvl</parameter> is either <literal>0,
- 1</literal> 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).</para>
-
- <para>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.</para>
-
- <para>This option can be very useful when debugging servers as it
- allows you to see exactly what the client sends and the server
- returns.</para>
- </sect3>
-
- <sect3>
- <title>setKey</title>
-
- <funcsynopsis>
- <funcprototype>
- <funcdef><type>void</type><function>setKey</function></funcdef>
-
- <paramdef><type>int</type><parameter>$key</parameter></paramdef>
-
- <paramdef><type>int</type><parameter>$keypass</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
-
- <para>This method sets the optional certificate key and passphrase
- used in SSL-enabled communication with a remote server (when the
- <parameter>transport</parameter> is set to 'https' in the client's
- construction or in the send method).</para>
-
- <para>This requires the "curl" extension to be compiled into your
- installation of PHP. For more details see the man page for the
- <function>curl_setopt</function> function.</para>
- </sect3>
-
- <sect3>
- <title>setProxy</title>
-
- <funcsynopsis>
- <funcprototype>
- <funcdef><type>void</type><function>setProxy</function></funcdef>
-
- <paramdef><type>string</type><parameter>$proxyhost</parameter></paramdef>
-
- <paramdef><type>int</type><parameter>$proxyport</parameter></paramdef>
-
- <paramdef><type>string</type><parameter>$proxyusername</parameter></paramdef>
-
- <paramdef><type>string</type><parameter>$proxypassword</parameter></paramdef>
-
- <paramdef><type>int</type><parameter>$authtype</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
-
- <para>This method enables calling servers via an HTTP proxy. The
- <parameter>proxyusername</parameter>,<parameter>
- proxypassword</parameter> and <parameter>authtype</parameter>
- parameters are optional. <parameter>Authtype</parameter> defaults to
- <constant>CURLAUTH_BASIC</constant> (Basic authentication protocol);
- the only other valid value is the constant
- <constant>CURLAUTH_NTLM</constant>, and has effect only when the
- client uses the HTTP 1.1 protocol.</para>
-
- <para>NB: CURL versions before 7.11.10 cannot use a proxy to
- communicate with https servers.</para>
- </sect3>
-
- <sect3>
- <title>setRequestCompression</title>
-
- <funcsynopsis>
- <funcprototype>
- <funcdef><type>void</type><function>setRequestCompression</function></funcdef>
-
- <paramdef><type>string</type><parameter>$compressionmethod</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
-
- <para>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 <parameter>compressionmethod</parameter> 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.</para>
-
- <para>This requires the "zlib" extension to be enabled in your php
- install.</para>
- </sect3>
-
- <sect3>
- <title>setSSLVerifyHost</title>
-
- <funcsynopsis>
- <funcprototype>
- <funcdef><type>void</type><function>setSSLVerifyHost</function></funcdef>
-
- <paramdef><type>int</type><parameter>$i</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
-
- <para>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.
- <parameter><parameter>$i</parameter></parameter> 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.</para>
- </sect3>
-
- <sect3>
- <title>setSSLVerifyPeer</title>
-
- <funcsynopsis>
- <funcprototype>
- <funcdef><type>void</type><function>setSSLVerifyPeer</function></funcdef>
-
- <paramdef><type>bool</type><parameter>$i</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
-
- <para>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.
- <parameter><parameter>$i</parameter></parameter> should be a boolean
- value. Default value: <constant>TRUE</constant>. To specify custom
- SSL certificates to validate the server with, use the
- <methodname>setCaCertificate</methodname> method.</para>
- </sect3>
-
- <sect3>
- <title>setUserAgent</title>
-
- <para><funcsynopsis>
- <funcprototype>
- <funcdef><type>void</type><function>Useragent</function></funcdef>
-
- <paramdef><type>string</type><parameter>$useragent</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>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.</para>
- </sect3>
- </sect2>
-
- <sect2>
- <title>Variables</title>
-
- <para>NB: direct manipulation of these variables is only recommended
- for advanced users.</para>
-
- <sect3>
- <title>no_multicall</title>
-
- <para>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.</para>
- </sect3>
-
- <sect3>
- <title>request_charset_encoding</title>
-
- <para>This is the charset encoding that will be used for serializing
- request sent by the client.</para>
-
- <para>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).</para>
-
- <para>Valid values are 'US-ASCII', 'UTF-8' and 'ISO-8859-1'</para>
- </sect3>
-
- <sect3 id="return-type" xreflabel="return_type">
- <title>return_type</title>
-
- <para>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.</para>
-
- <para>Example usage:</para>
-
- <programlisting language="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();
-</programlisting>
-
- <para>For more details about usage of the 'xml' value, see Appendix
- A.</para>
- </sect3>
- </sect2>
- </sect1>
-
- <sect1 id="xmlrpcresp" xreflabel="xmlrpcresp">
- <title>xmlrpcresp</title>
-
- <para>This class is used to contain responses to XML-RPC requests. A
- server method handler will construct an
- <classname>xmlrpcresp</classname> and pass it as a return value. This
- same value will be returned by the result of an invocation of the
- <function>send</function> method of the
- <classname>xmlrpc_client</classname> class.</para>
-
- <sect2>
- <title>Creation</title>
-
- <funcsynopsis>
- <funcprototype>
- <funcdef><type>xmlrpcresp</type>new
- <function>xmlrpcresp</function></funcdef>
-
- <paramdef><type>xmlrpcval</type><parameter>$xmlrpcval</parameter></paramdef>
- </funcprototype>
-
- <funcprototype>
- <funcdef><type>xmlrpcresp</type>new
- <function>xmlrpcresp</function></funcdef>
-
- <paramdef><parameter>0</parameter></paramdef>
-
- <paramdef><type>int</type><parameter>$errcode</parameter></paramdef>
-
- <paramdef><type>string</type><parameter>$err_string</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
-
- <para>The first syntax is used when execution has happened without
- difficulty: <parameter>$xmlrpcval</parameter> is an
- <classname>xmlrpcval</classname> 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.</para>
-
- <para>The second type of constructor is used in case of failure.
- <parameter>errcode</parameter> and <parameter>err_string</parameter>
- are used to provide indication of what has gone wrong. See <xref
- linkend="xmlrpc-server" /> for more information on passing error
- codes.</para>
- </sect2>
-
- <sect2>
- <title>Methods</title>
-
- <sect3>
- <title>faultCode</title>
-
- <funcsynopsis>
- <funcprototype>
- <funcdef><type>int</type><function>faultCode</function></funcdef>
-
- <void />
- </funcprototype>
- </funcsynopsis>
-
- <para>Returns the integer fault code return from the XML-RPC
- response. A zero value indicates success, any other value indicates
- a failure response.</para>
- </sect3>
-
- <sect3>
- <title>faultString</title>
-
- <funcsynopsis>
- <funcprototype>
- <funcdef><type>string</type><function>faultString</function></funcdef>
-
- <void />
- </funcprototype>
- </funcsynopsis>
-
- <para>Returns the human readable explanation of the fault indicated
- by <function>$resp->faultCode</function>().</para>
- </sect3>
-
- <sect3>
- <title>value</title>
-
- <funcsynopsis>
- <funcprototype>
- <funcdef><type>xmlrpcval</type><function>value</function></funcdef>
-
- <void />
- </funcprototype>
- </funcsynopsis>
-
- <para>Returns an <classname>xmlrpcval</classname> object containing
- the return value sent by the server. If the response's
- <function>faultCode</function> is non-zero then the value returned
- by this method should not be used (it may not even be an
- object).</para>
-
- <para>Note: if the xmlrpcresp instance in question has been created
- by an <classname>xmlrpc_client</classname> object whose
- <varname>return_type</varname> was set to 'phpvals', then a plain
- php value will be returned instead of an
- <classname>xmlrpcval</classname> object. If the
- <varname>return_type</varname> was set to 'xml', an xml string will
- be returned (see the return_type member var above for more
- details).</para>
- </sect3>
-
- <sect3>
- <title>serialize</title>
-
- <funcsynopsis>
- <funcprototype>
- <funcdef><type>string</type><function>serialize</function></funcdef>
-
- <void />
- </funcprototype>
- </funcsynopsis>
-
- <para>Returns an XML string representation of the response (xml
- prologue not included).</para>
- </sect3>
- </sect2>
- </sect1>
-
- <sect1 id="xmlrpc-server" xreflabel="xmlrpc_server">
- <title>xmlrpc_server</title>
-
- <para>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:</para>
-
- <programlisting language="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"),
- ));
-</programlisting>
-
- <para>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
- <classname>xmlrpcresp</classname> object, that will be serialized back
- to the caller.</para>
-
- <sect2>
- <title>Method handler functions</title>
-
- <para>Both php functions and class methods can be registered as xmlrpc
- method handlers.</para>
-
- <para>The synopsis of a method handler function is:</para>
-
- <para><synopsis>xmlrpcresp $resp = function (xmlrpcmsg $msg)</synopsis></para>
-
- <para>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
- <varname>exception_handling</varname> member variable (see
- ...).</para>
-
- <para>Note that if you implement a method with a name prefixed by
- <code>system.</code> the handler function will be invoked by the
- server with two parameters, the first being the server itself and the
- second being the <classname>xmlrpcmsg</classname> object.</para>
-
- <para>The same php function can be registered as handler of multiple
- xmlrpc methods.</para>
-
- <para>Here is a more detailed example of what the handler function
- <function>foo</function> may do:</para>
-
- <programlisting language="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"));
- }
- }
-</programlisting>
-
- <para>See <filename>server.php</filename> in this distribution for
- more examples of how to do this.</para>
-
- <para>Since release 2.0RC3 there is a new, even simpler way of
- registering php functions with the server. See section 5.7
- below</para>
- </sect2>
-
- <sect2>
- <title>The dispatch map</title>
-
- <para>The first argument to the <function>xmlrpc_server</function>
- constructor is an array, called the <emphasis>dispatch map</emphasis>.
- In this array is the information the server needs to service the
- XML-RPC methods you define.</para>
-
- <para>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:</para>
-
- <itemizedlist>
- <listitem>
- <para><function><literal>function</literal></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).</para>
- </listitem>
-
- <listitem>
- <para><function><literal>signature</literal></function> - this
- entry is an array containing the possible signatures (see <xref
- linkend="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.</para>
- </listitem>
-
- <listitem>
- <para><function><literal>docstring</literal></function> - this
- entry is a string containing documentation for the method. The
- documentation may contain HTML markup.</para>
- </listitem>
-
- <listitem>
- <para><literal>signature_docs</literal> - this entry can be used
- to provide documentation for the single parameters. It must match
- in structure the 'signature' member. By default, only the
- <classname>documenting_xmlrpc_server</classname> class in the
- extras package will take advantage of this, since the
- "system.methodHelp" protocol does not support documenting method
- parameters individually.</para>
- </listitem>
-
- <listitem>
- <para><literal>parameters_type</literal> - 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 <literal>phpvals</literal>.</para>
- </listitem>
- </itemizedlist>
-
- <para>Look at the <filename>server.php</filename> example in the
- distribution to see what a dispatch map looks like.</para>
- </sect2>
-
- <sect2 id="signatures" xreflabel="Signatures">
- <title>Method signatures</title>
-
- <para>A signature is a description of a method's return type and its
- parameter types. A method may have more than one signature.</para>
-
- <para>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 <programlisting
- language="php">string examples.getStateName(int)
-</programlisting> has the signature <programlisting language="php">array($xmlrpcString, $xmlrpcInt)
-</programlisting> and, assuming that it is the only possible signature for the
- method, it might be used like this in server creation: <programlisting
- language="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
- )));
-</programlisting></para>
-
- <para>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.</para>
-
- <para>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 <varname>$xmlrpcValue</varname>, which can be
- used in method signatures as a placeholder for 'any xmlrpc
- type':</para>
-
- <para><programlisting language="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
- )));
-</programlisting></para>
-
- <para>Methods <methodname>system.listMethods</methodname>,
- <methodname>system.methodHelp</methodname>,
- <methodname>system.methodSignature</methodname> and
- <methodname>system.multicall</methodname> are already defined by the
- server, and should not be reimplemented (see Reserved Methods
- below).</para>
- </sect2>
-
- <sect2>
- <title>Delaying the server response</title>
-
- <para>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 <literal>0</literal> this will have the desired
- effect. You can then use the <function>service()</function> method of
- the server class to service the request. For example:</para>
-
- <programlisting language="php">
-$s = new xmlrpc_server($myDispMap, 0); // second parameter = 0 prevents automatic servicing of request
-
-// ... some code that does other stuff here
-
-$s->service();
-</programlisting>
-
- <para>Note that the <methodname>service</methodname> 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.</para>
-
- <para>To prevent the server from sending HTTP headers back to the
- client, you can pass a second parameter with a value of
- <literal>TRUE</literal> to the <methodname>service</methodname>
- method. In this case, the response payload will be returned instead of
- the response object.</para>
-
- <para>Xmlrpc requests retrieved by other means than HTTP POST bodies
- can also be processed. For example:</para>
-
- <programlisting language="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
-</programlisting>
- </sect2>
-
- <sect2>
- <title>Modifying the server behaviour</title>
-
- <para>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)</para>
-
- <sect3>
- <title>setDebug()</title>
-
- <para>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.</para>
- </sect3>
-
- <sect3>
- <title>allow_system_funcs</title>
-
- <para>Default_value: TRUE. When set to FALSE, disables support for
- <methodname>System.xxx</methodname> functions in the server. It
- might be useful e.g. if you do not wish the server to respond to
- requests to <methodname>System.ListMethods</methodname>.</para>
- </sect3>
-
- <sect3>
- <title>compress_response</title>
-
- <para>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.</para>
-
- <para>Note that the ZLIB php extension must be installed for this to
- work. If it is, <varname>compress_response</varname> will default to
- TRUE.</para>
- </sect3>
-
- <sect3>
- <title>exception_handling</title>
-
- <para>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</para>
- </sect3>
-
- <sect3>
- <title>response_charset_encoding</title>
-
- <para>Charset encoding to be used for response (only affects string
- values).</para>
-
- <para>If it can, the server will convert the generated response from
- internal_encoding to the intended one.</para>
-
- <para>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).</para>
- </sect3>
- </sect2>
-
- <sect2>
- <title>Fault reporting</title>
-
- <para>Fault codes for your servers should start at the value indicated
- by the global <literal>$xmlrpcerruser</literal> + 1.</para>
-
- <para>Standard errors returned by the server include:</para>
-
- <variablelist>
- <varlistentry>
- <term><literal>1</literal> <phrase>Unknown method</phrase></term>
-
- <listitem>
- <para>Returned if the server was asked to dispatch a method it
- didn't know about</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>2</literal> <phrase>Invalid return
- payload</phrase></term>
-
- <listitem>
- <para>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.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>3</literal> <phrase>Incorrect
- parameters</phrase></term>
-
- <listitem>
- <para>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.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>4</literal> <phrase>Can't introspect: method
- unknown</phrase></term>
-
- <listitem>
- <para>This error is generated by the builtin
- <function>system.*</function> methods when any kind of
- introspection is attempted on a method undefined by the
- server.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>5</literal> <phrase>Didn't receive 200 OK from
- remote server</phrase></term>
-
- <listitem>
- <para>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.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>6</literal> <phrase>No data received from
- server</phrase></term>
-
- <listitem>
- <para>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.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>7</literal> <phrase>No SSL support compiled
- in</phrase></term>
-
- <listitem>
- <para>This error is generated by the client when trying to send
- a request with HTTPS and the CURL extension is not available to
- PHP.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>8</literal> <phrase>CURL error</phrase></term>
-
- <listitem>
- <para>This error is generated by the client when trying to send
- a request with HTTPS and the HTTPS communication fails.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>9-14</literal> <phrase>multicall
- errors</phrase></term>
-
- <listitem>
- <para>These errors are generated by the server when something
- fails inside a system.multicall request.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>100-</literal> <phrase>XML parse
- errors</phrase></term>
-
- <listitem>
- <para>Returns 100 plus the XML parser error code for the fault
- that occurred. The <function>faultString</function> returned
- explains where the parse error was in the incoming XML
- stream.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect2>
-
- <sect2>
- <title>'New style' servers</title>
-
- <para>In the same spirit of simplification that inspired the
- <varname>xmlrpc_client::return_type</varname> class variable, a new
- class variable has been added to the server class:
- <varname>functions_parameters_type</varname>. 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:<programlisting language="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();
-</programlisting>There are a few things to keep in mind when using this
- simplified syntax:</para>
-
- <para>to return an xmlrpc error, the method handler function must
- return an instance of <classname>xmlrpcresp</classname>. 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
- <varname>exception_handling</varname> memeber var to 1;</para>
-
- <para>to return a base64 value, the method handler function must
- encode it on its own, creating an instance of an xmlrpcval
- object;</para>
-
- <para>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;</para>
-
- <para>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;</para>
-
- <para>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;</para>
-
- <para>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.</para>
- </sect2>
- </sect1>
- </chapter>
-
- <chapter id="globalvars">
- <title>Global variables</title>
-
- <para>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.</para>
-
- <sect1>
- <title>"Constant" variables</title>
-
- <sect2>
- <title>$xmlrpcerruser</title>
-
- <para><fieldsynopsis>
- <varname>$xmlrpcerruser</varname>
-
- <initializer>800</initializer>
- </fieldsynopsis>The minimum value for errors reported by user
- implemented XML-RPC servers. Error numbers lower than that are
- reserved for library usage.</para>
- </sect2>
-
- <sect2>
- <title>$xmlrpcI4, $xmlrpcInt, $xmlrpcBoolean, $xmlrpcDouble,
- $xmlrpcString, $xmlrpcDateTime, $xmlrpcBase64, $xmlrpcArray,
- $xmlrpcStruct, $xmlrpcValue, $xmlrpcNull</title>
-
- <para>For convenience the strings representing the XML-RPC types have
- been encoded as global variables:<programlisting language="php">
-$xmlrpcI4="i4";
-$xmlrpcInt="int";
-$xmlrpcBoolean="boolean";
-$xmlrpcDouble="double";
-$xmlrpcString="string";
-$xmlrpcDateTime="dateTime.iso8601";
-$xmlrpcBase64="base64";
-$xmlrpcArray="array";
-$xmlrpcStruct="struct";
-$xmlrpcValue="undefined";
-$xmlrpcNull="null";
-</programlisting></para>
- </sect2>
-
- <sect2>
- <title>$xmlrpcTypes, $xmlrpc_valid_parents, $xmlrpcerr, $xmlrpcstr,
- $xmlrpcerrxml, $xmlrpc_backslash, $_xh, $xml_iso88591_Entities,
- $xmlEntities, $xmlrpcs_capabilities</title>
-
- <para>Reserved for internal usage.</para>
- </sect2>
- </sect1>
-
- <sect1>
- <title>Variables whose value can be modified</title>
-
- <sect2 id="xmlrpc-defencoding" xreflabel="xmlrpc_defencoding">
- <title xreflabel="">xmlrpc_defencoding</title>
-
- <fieldsynopsis>
- <varname>$xmlrpc_defencoding</varname>
-
- <initializer>"UTF8"</initializer>
- </fieldsynopsis>
-
- <para>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).</para>
-
- <para>Allowed values: <literal>"UTF8"</literal>,
- <literal>"ISO-8859-1"</literal>, <literal>"ASCII".</literal></para>
-
- <para>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.</para>
- </sect2>
-
- <sect2>
- <title>xmlrpc_internalencoding</title>
-
- <para><fieldsynopsis>
- <varname>$xmlrpc_internalencoding</varname>
-
- <initializer>"ISO-8859-1"</initializer>
- </fieldsynopsis>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:</para>
-
- <para><programlisting language="php">
-<?php
-
-include('xmlrpc.inc');
-$xmlrpc_internalencoding = 'UTF-8'; // this has to be set after the inclusion above
-$v = new xmlrpcval('κόÏ\83με'); // This xmlrpc value will be correctly serialized as the greek word 'kosme'
-</programlisting></para>
- </sect2>
-
- <sect2>
- <title>xmlrpcName</title>
-
- <para><fieldsynopsis>
- <varname>$xmlrpcName</varname>
-
- <initializer>"XML-RPC for PHP"</initializer>
- </fieldsynopsis>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.</para>
- </sect2>
-
- <sect2>
- <title>xmlrpcVersion</title>
-
- <para><fieldsynopsis>
- <varname>$xmlrpcVersion</varname>
-
- <initializer>"2.2"</initializer>
- </fieldsynopsis>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.</para>
- </sect2>
-
- <sect2>
- <title>xmlrpc_null_extension</title>
-
- <para>When set to <constant>TRUE</constant>, 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
- <methodname>scalarTyp()</methodname>.</para>
- </sect2>
-
- <sect2>
- <title>xmlrpc_null_apache_encoding</title>
-
- <para>When set to <literal>TRUE</literal>, php NULL values encoded
- into <classname>xmlrpcval</classname> objects get serialized using the
- <literal><EX:NIL/></literal> tag instead of
- <literal><NIL/></literal>. Please note that both forms are
- always accepted as input regardless of the value of this
- variable.</para>
- </sect2>
- </sect1>
- </chapter>
-
- <chapter id="helpers">
- <title>Helper functions</title>
-
- <para>XML-RPC for PHP contains some helper functions which you can use to
- make processing of XML-RPC requests easier.</para>
-
- <sect1>
- <title>Date functions</title>
-
- <para>The XML-RPC specification has this to say on dates:</para>
-
- <blockquote>
- <para id="wrap_xmlrpc_method">Don't assume a timezone. It should be
- specified by the server in its documentation what assumptions it makes
- about timezones.</para>
- </blockquote>
-
- <para>Unfortunately, this means that date processing isn't
- straightforward. Although XML-RPC uses ISO 8601 format dates, it doesn't
- use the timezone specifier.</para>
-
- <para>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.</para>
-
- <para>For more information about dates, see <ulink
- url="http://www.uic.edu/year2000/datefmt.html">ISO 8601: The Right
- Format for Dates</ulink>, 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.</para>
-
- <sect2 id="iso8601encode" xreflabel="iso8601_encode()">
- <title>iso8601_encode</title>
-
- <funcsynopsis>
- <funcprototype>
- <funcdef><type>string</type><function>iso8601_encode</function></funcdef>
-
- <paramdef><type>string</type><parameter>$time_t</parameter></paramdef>
-
- <paramdef
- choice="opt"><type>int</type><parameter>$utc</parameter><initializer>0</initializer></paramdef>
- </funcprototype>
- </funcsynopsis>
-
- <para>Returns an ISO 8601 formatted date generated from the UNIX
- timestamp <parameter>$time_t</parameter>, as returned by the PHP
- function <function>time()</function>.</para>
-
- <para>The argument <parameter>$utc</parameter> can be omitted, in
- which case it defaults to <literal>0</literal>. If it is set to
- <literal>1</literal>, then the function corrects the time passed in
- for UTC. Example: if you're in the GMT-6:00 timezone and set
- <parameter>$utc</parameter>, you will receive a date representation
- six hours ahead of your local time.</para>
-
- <para>The included demo program <filename>vardemo.php</filename>
- includes a demonstration of this function.</para>
- </sect2>
-
- <sect2 id="iso8601decode" xreflabel="iso8601_decode()">
- <title>iso8601_decode</title>
-
- <funcsynopsis>
- <funcprototype>
- <funcdef><type>int</type><function>iso8601_decode</function></funcdef>
-
- <paramdef><type>string</type><parameter>$isoString</parameter></paramdef>
-
- <paramdef><type>int</type><parameter>$utc</parameter><initializer>0</initializer></paramdef>
- </funcprototype>
- </funcsynopsis>
-
- <para>Returns a UNIX timestamp from an ISO 8601 encoded time and date
- string passed in. If <parameter>$utc</parameter> is
- <literal>1</literal> then <parameter>$isoString</parameter> 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.</para>
- </sect2>
- </sect1>
-
- <sect1 id="arrayuse">
- <title>Easy use with nested PHP values</title>
-
- <para>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
- <type>int</type>, <type>double</type>, <type>string</type>,
- <type>array</type>, <type>datetime</type> and <type>struct</type>
- 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.</para>
-
- <para>These functions reside in <filename>xmlrpc.inc</filename>.</para>
-
- <sect2 id="phpxmlrpcdecode">
- <title>php_xmlrpc_decode</title>
-
- <funcsynopsis>
- <funcprototype>
- <funcdef><type>mixed</type><function>php_xmlrpc_decode</function></funcdef>
-
- <paramdef><type>xmlrpcval</type><parameter>$xmlrpc_val</parameter></paramdef>
-
- <paramdef><type>array</type><parameter>$options</parameter></paramdef>
- </funcprototype>
-
- <funcprototype>
- <funcdef><type>array</type><function>php_xmlrpc_decode</function></funcdef>
-
- <paramdef><type>xmlrpcmsg</type><parameter>$xmlrpcmsg_val</parameter></paramdef>
-
- <paramdef><type>string</type><parameter>$options</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
-
- <para>Returns a native PHP value corresponding to the values found in
- the <type>xmlrpcval</type> <parameter>$xmlrpc_val</parameter>,
- translated into PHP types. Base-64 and datetime values are
- automatically decoded to strings.</para>
-
- <para>In the second form, returns an array containing the parameters
- of the given
- <parameter><classname>xmlrpcmsg</classname>_val</parameter>, decoded
- to php types.</para>
-
- <para>The <parameter>options</parameter> 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
- <symbol>decode_php_objs</symbol> and
- <literal>dates_as_objects</literal>. When the first is set, php
- objects that have been converted to xml-rpc structs using the
- <function>php_xmlrpc_encode</function> 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 <classname>dateTime</classname> objects
- instead of strings.</para>
-
- <para><emphasis><emphasis>WARNING</emphasis>:</emphasis> please take
- extreme care before enabling the <symbol>decode_php_objs</symbol>
- 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.</para>
-
- <para>Example:<programlisting language="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" => ...
- )));
-</programlisting></para>
- </sect2>
-
- <sect2 id="phpxmlrpcencode">
- <title>php_xmlrpc_encode</title>
-
- <funcsynopsis>
- <funcprototype>
- <funcdef><type>xmlrpcval</type><function>php_xmlrpc_encode</function></funcdef>
-
- <paramdef><type>mixed</type><parameter>$phpval</parameter></paramdef>
-
- <paramdef><type>array</type><parameter>$options</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
-
- <para>Returns an <type>xmlrpcval</type> object populated with the PHP
- values in <parameter>$phpval</parameter>. 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.</para>
-
- <para>The <parameter>options</parameter> 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
- <symbol>encode_php_objs</symbol>, <literal>null_extension</literal>
- and <symbol>auto_dates</symbol>.</para>
-
- <para>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 <literal>NULL</literal> values to the
- <literal><NIL/></literal> (or
- <literal><EX:NIL/></literal>, see ...) tag. The last encodes any
- string that matches the ISO8601 format into an XML-RPC
- datetime.</para>
-
- <para>Example:<programlisting language="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'));
-</programlisting></para>
- </sect2>
-
- <sect2>
- <title>php_xmlrpc_decode_xml</title>
-
- <funcsynopsis>
- <funcprototype>
- <funcdef><type>xmlrpcval | xmlrpcresp |
- xmlrpcmsg</type><function>php_xmlrpc_decode_xml</function></funcdef>
-
- <paramdef><type>string</type><parameter>$xml</parameter></paramdef>
-
- <paramdef><type>array</type><parameter>$options</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
-
- <para>Decodes the xml representation of either an xmlrpc request,
- response or single value, returning the corresponding php-xmlrpc
- object, or <literal>FALSE</literal> in case of an error.</para>
-
- <para>The <parameter>options</parameter> 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.</para>
-
- <para>Example:<programlisting language="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';
-</programlisting></para>
- </sect2>
- </sect1>
-
- <sect1>
- <title>Automatic conversion of php functions into xmlrpc methods (and
- vice versa)</title>
-
- <para>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.</para>
-
- <sect2>
- <title>wrap_xmlrpc_method</title>
-
- <funcsynopsis>
- <funcprototype>
- <funcdef><type>string</type><function>wrap_xmlrpc_method</function></funcdef>
-
- <paramdef>$client</paramdef>
-
- <paramdef>$methodname</paramdef>
-
- <paramdef>$extra_options</paramdef>
- </funcprototype>
-
- <funcprototype>
- <funcdef><type>string</type><function>wrap_xmlrpc_method</function></funcdef>
-
- <paramdef>$client</paramdef>
-
- <paramdef>$methodname</paramdef>
-
- <paramdef>$signum</paramdef>
-
- <paramdef>$timeout</paramdef>
-
- <paramdef>$protocol</paramdef>
-
- <paramdef>$funcname</paramdef>
- </funcprototype>
- </funcsynopsis>
-
- <para>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.</para>
-
- <para>The second syntax is deprecated, and is listed here only for
- backward compatibility.</para>
-
- <para>The server must support the
- <methodname>system.methodSignature</methodname> xmlrpc method call for
- this function to work.</para>
-
- <para>The <parameter>client</parameter> 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.</para>
-
- <para>The optional parameters can be passed as array key,value pairs
- in the <parameter>extra_options</parameter> param.</para>
-
- <para>The <parameter>signum</parameter> optional param has the purpose
- of indicating which method signature to use, if the given server
- method has multiple signatures (defaults to 0).</para>
-
- <para>The <parameter>timeout</parameter> and
- <parameter>protocol</parameter> optional params are the same as in the
- <methodname>xmlrpc_client::send()</methodname> method.</para>
-
- <para>If set, the optional <parameter>new_function_name</parameter>
- parameter indicates which name should be used for the generated
- function. In case it is not set the function name will be
- auto-generated.</para>
-
- <para>If the <literal>return_source</literal> 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).</para>
-
- <para>If the <literal>encode_php_objs</literal> 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.</para>
-
- <para>If the <literal>decode_php_objs</literal> 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).</para>
-
- <para><emphasis>Note that this might pose a security risk</emphasis>,
- 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.</para>
-
- <para>In case of an error during generation of the wrapper function,
- FALSE is returned, otherwise the name (or source code) of the new
- function.</para>
-
- <para>Known limitations: server must support
- <methodname>system.methodsignature</methodname> 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.</para>
-
- <para>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.</para>
-
- <para>Example usage:</para>
-
- <programlisting language="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";
-}
-</programlisting>
- </sect2>
-
- <sect2 id="wrap_php_function">
- <title>wrap_php_function</title>
-
- <funcsynopsis>
- <funcprototype>
- <funcdef><type>array</type><function>wrap_php_function</function></funcdef>
-
- <paramdef><type>string</type><parameter>$funcname</parameter></paramdef>
-
- <paramdef><type>string</type><parameter>$wrapper_function_name</parameter></paramdef>
-
- <paramdef><type>array</type><parameter>$extra_options</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
-
- <para>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.</para>
-
- <para>The optional <parameter>$wrapper_function_name</parameter>
- specifies the name that will be used for the auto-generated
- function.</para>
-
- <para>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).</para>
-
- <para>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.</para>
-
- <para>If the <literal>return_source</literal> 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
- <literal>source</literal> member of the returned array.</para>
-
- <para>If the <literal>suppress_warnings</literal> 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.</para>
-
- <para>If the <parameter>extra_options</parameter> array contains the
- <literal>encode_php_objs</literal> 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.</para>
-
- <para>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)</para>
-
- <para>If the <literal>decode_php_objs</literal> 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).</para>
-
- <para><emphasis>Note that this might pose a security risk</emphasis>,
- 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.</para>
-
- <para>Example usage:</para>
-
- <para><programlisting language="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);
-</programlisting></para>
- </sect2>
- </sect1>
-
- <sect1 id="deprecated">
- <title>Functions removed from the library</title>
-
- <para>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.</para>
-
- <para>To ease the transition to the new naming scheme and avoid breaking
- existing implementations, the following scheme has been adopted:
- <itemizedlist>
- <listitem>
- <para>If EPI-XMLRPC is not active in the current PHP installation,
- the constant <literal>XMLRPC_EPI_ENABLED</literal> will be set to
- <literal>'0'</literal></para>
- </listitem>
-
- <listitem>
- <para>If EPI-XMLRPC is active in the current PHP installation, the
- constant <literal>XMLRPC_EPI_ENABLED</literal> will be set to
- <literal>'1'</literal></para>
- </listitem>
- </itemizedlist></para>
-
- <para>The following documentation is kept for historical
- reference:</para>
-
- <sect2 id="xmlrpcdecode">
- <title>xmlrpc_decode</title>
-
- <funcsynopsis>
- <funcprototype>
- <funcdef><type>mixed</type><function>xmlrpc_decode</function></funcdef>
-
- <paramdef><type>xmlrpcval</type><parameter>$xmlrpc_val</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
-
- <para>Alias for php_xmlrpc_decode.</para>
- </sect2>
-
- <sect2 id="xmlrpcencode">
- <title>xmlrpc_encode</title>
-
- <funcsynopsis>
- <funcprototype>
- <funcdef><type>xmlrpcval</type><function>xmlrpc_encode</function></funcdef>
-
- <paramdef><type>mixed</type><parameter>$phpval</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
-
- <para>Alias for php_xmlrpc_encode.</para>
- </sect2>
- </sect1>
-
- <sect1 id="debugging">
- <title>Debugging aids</title>
-
- <sect2>
- <title>xmlrpc_debugmsg</title>
-
- <funcsynopsis>
- <funcprototype>
- <funcdef><type>void</type><function>xmlrpc_debugmsg</function></funcdef>
-
- <paramdef><type>string</type><parameter>$debugstring</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
-
- <para>Sends the contents of <parameter>$debugstring</parameter> 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.</para>
-
- <para>Use this function in your methods so you can pass back
- diagnostic information. It is only available from
- <filename>xmlrpcs.inc</filename>.</para>
- </sect2>
- </sect1>
- </chapter>
-
- <chapter id="reserved" xreflabel="Reserved methods">
- <title>Reserved methods</title>
-
- <para>In order to extend the functionality offered by XML-RPC servers
- without impacting on the protocol, reserved methods are supported in this
- release.</para>
-
- <para>All methods starting with <function>system.</function> are
- considered reserved by the server. PHP for XML-RPC itself provides four
- special methods, detailed in this chapter.</para>
-
- <para>Note that all server objects will automatically respond to clients
- querying these methods, unless the property
- <property>allow_system_funcs</property> has been set to
- <constant>false</constant> before calling the
- <methodname>service()</methodname> method. This might pose a security risk
- if the server is exposed to public access, e.g. on the internet.</para>
-
- <sect1>
- <title>system.getCapabilities</title>
-
- <para></para>
- </sect1>
-
- <sect1>
- <title>system.listMethods</title>
-
- <para>This method may be used to enumerate the methods implemented by
- the XML-RPC server.</para>
-
- <para>The <function>system.listMethods</function> method requires no
- parameters. It returns an array of strings, each of which is the name of
- a method implemented by the server.</para>
- </sect1>
-
- <sect1 id="sysmethodsig">
- <title>system.methodSignature</title>
-
- <para>This method takes one parameter, the name of a method implemented
- by the XML-RPC server.</para>
-
- <para>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.</para>
-
- <para>Multiple signatures (i.e. overloading) are permitted: this is the
- reason that an array of signatures are returned by this method.</para>
-
- <para>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".</para>
-
- <para>For parameters that can be of more than one type, the "undefined"
- string is supported.</para>
-
- <para>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
- <parameter>$resp</parameter> below is the response object from a method
- call to <function>system.methodSignature</function>:</para>
-
- <programlisting language="php">
-$v = $resp->value();
-if ($v->kindOf() != "array") {
- // then the method did not have a signature defined
-}
-</programlisting>
-
- <para>See the <filename>introspect.php</filename> demo included in this
- distribution for an example of using this method.</para>
- </sect1>
-
- <sect1 id="sysmethhelp">
- <title>system.methodHelp</title>
-
- <para>This method takes one parameter, the name of a method implemented
- by the XML-RPC server.</para>
-
- <para>It returns a documentation string describing the use of that
- method. If no such string is available, an empty string is
- returned.</para>
-
- <para>The documentation string may contain HTML markup.</para>
- </sect1>
-
- <sect1>
- <title>system.multicall</title>
-
- <para>This method takes one parameter, an array of 'request' struct
- types. Each request struct must contain a
- <parameter>methodName</parameter> member of type string and a
- <parameter>params</parameter> member of type array, and corresponds to
- the invocation of the corresponding method.</para>
-
- <para>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.</para>
- </sect1>
- </chapter>
-
- <chapter id="examples" xreflabel="Examples">
- <title>Examples</title>
-
- <para>The best examples are to be found in the sample files included with
- the distribution. Some are included here.</para>
-
- <sect1 id="statename">
- <title>XML-RPC client: state name query</title>
-
- <para>Code to get the corresponding state name from a number (1-50) from
- the demo server available on SourceForge</para>
-
- <programlisting language="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>";
- }
-</programlisting>
- </sect1>
-
- <sect1>
- <title>Executing a multicall call</title>
-
- <para>To be documented...</para>
- </sect1>
- </chapter>
-
- <chapter id="faq">
- <title>Frequently Asked Questions</title>
-
- <sect1>
- <title>How to send custom XML as payload of a method call</title>
-
- <para>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.</para>
-
- <para>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).</para>
- </sect1>
-
- <sect1>
- <title>Is there any limitation on the size of the requests / responses
- that can be successfully sent?</title>
-
- <para>Yes. But I have no hard figure to give; it most likely will depend
- on the version of PHP in usage and its configuration.</para>
-
- <para>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).</para>
-
- <para>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.</para>
-
- <para>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 <varname>xmlrpc_client::return_type</varname>
- and <varname>xmlrpc_server::functions_parameters_type</varname> for more
- details).</para>
- </sect1>
-
- <sect1>
- <title>My server (client) returns an error whenever the client (server)
- returns accented characters</title>
-
- <para>To be documented...</para>
- </sect1>
-
- <sect1>
- <title>How to enable long-lasting method calls</title>
-
- <para>To be documented...</para>
- </sect1>
-
- <sect1>
- <title>My client returns "XML-RPC Fault #2: Invalid return payload:
- enable debugging to examine incoming payload": what should I do?</title>
-
- <para>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.</para>
-
- <para>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.</para>
-
- <para>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);</para>
- </sect1>
-
- <sect1>
- <title>How can I save to a file the xml of the xmlrpc responses received
- from servers?</title>
-
- <para>If what you need is to save the responses received from the server
- as xml, you have two options:</para>
-
- <para>1- use the serialize() method on the response object.</para>
-
- <programlisting language="php">
-$resp = $client->send($msg);
-if (!$resp->faultCode())
- $data_to_be_saved = $resp->serialize();
-</programlisting>
-
- <para>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).</para>
-
- <para>2 - set the client object to return the raw xml received instead
- of the decoded objects:</para>
-
- <programlisting language="php">
-$client = new xmlrpc_client($url);
-$client->return_type = 'xml';
-$resp = $client->send($msg);
-if (!$resp->faultCode())
- $data_to_be_saved = $resp->value();
-</programlisting>
-
- <para>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...</para>
- </sect1>
-
- <sect1>
- <title>Can I use the ms windows character set?</title>
-
- <para>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.</para>
-
- <para>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.</para>
-
- <para>To properly encode outgoing data that is natively in CP1252, you
- will have to uncomment all relative code in the file
- <filename>xmlrpc.inc</filename> (you can search for the string "1252"),
- then set <code>$GLOBALS['xmlrpc_internalencoding']='CP1252';</code>
- Please note that all incoming data will then be fed to your application
- as UTF-8 to avoid any potential data loss.</para>
- </sect1>
-
- <sect1>
- <title>Does the library support using cookies / http sessions?</title>
-
- <para>In short: yes, but a little coding is needed to make it
- happen.</para>
-
- <para>The code below uses sessions to e.g. let the client store a value
- on the server and retrieve it later.</para>
-
- <para><programlisting>
-$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')));
- }
-}
-</programlisting>Server-side sessions are handled normally like in any other
- php application. Please see the php manual for more information about
- sessions.</para>
-
- <para>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.</para>
- </sect1>
- </chapter>
-
- <appendix id="integration">
- <title>Integration with the PHP xmlrpc extension</title>
-
- <para>To be documented more...</para>
-
- <para>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</para>
-
- <programlisting language="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);
-}
-</programlisting>
- </appendix>
-
- <appendix id="substitution">
- <title>Substitution of the PHP xmlrpc extension</title>
-
- <para>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).</para>
-
- <para>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</para>
- </appendix>
-
- <appendix id="enough">
- <title>'Enough of xmlrpcvals!': new style library usage</title>
-
- <para>To be documented...</para>
-
- <para>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</para>
- </appendix>
-
- <appendix id="debugger">
- <title>Usage of the debugger</title>
-
- <para>A webservice debugger is included in the library to help during
- development and testing.</para>
-
- <para>The interface should be self-explicative enough to need little
- documentation.</para>
-
- <para><graphic align="center" fileref="images/debugger.gif"
- format="GIF" /></para>
-
- <para>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.</para>
-
- <para>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:</para>
-
- <para><itemizedlist>
- <listitem>
- <para>to enable jsonrpc functionality, download the PHP-XMLRPC
- EXTRAS package, and copy the file <filename>jsonrpc.inc</filename>
- either to the same directory as the debugger or somewhere in your
- php include path</para>
- </listitem>
- </itemizedlist><itemizedlist>
- <listitem>
- <para>to enable the visual value editing dialog, download the
- JS-XMLRPC library, and copy somewhere in the web root files
- <filename>visualeditor.php</filename>,
- <filename>visualeditor.css</filename> and the folders
- <filename>yui</filename> and <filename>img</filename>. Then edit the
- debugger file <filename>controller.php</filename> and set
- appropriately the variable <varname>$editorpath</varname>.</para>
- </listitem>
- </itemizedlist></para>
- </appendix>
-</book>
-<!-- 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:
--->
*
* @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
*/
{
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',
);
}
- /// @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])) {
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";
}
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');
}
/**
{
$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
# -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
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');
}
git://git.onelab.eu / plcapi.git / commitdiff