mirror of
https://github.com/ACSPRI/queXS
synced 2024-04-02 12:12:16 +00:00
72 lines
14 KiB
HTML
72 lines
14 KiB
HTML
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Easy use with nested PHP values</title><link rel="stylesheet" href="xmlrpc.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.74.3" /><link rel="home" href="index.html" title="XML-RPC for PHP" /><link rel="up" href="ch09.html" title="Chapter 9. Helper functions" /><link rel="prev" href="ch09.html" title="Chapter 9. Helper functions" /><link rel="next" href="ch09s03.html" title="Automatic conversion of php functions into xmlrpc methods (and vice versa)" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Easy use with nested PHP values</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch09.html">Prev</a> </td><th width="60%" align="center">Chapter 9. Helper functions</th><td width="20%" align="right"> <a accesskey="n" href="ch09s03.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="arrayuse"></a>Easy use with nested PHP values</h2></div></div></div><p>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
|
||
<span class="type">int</span>, <span class="type">double</span>, <span class="type">string</span>,
|
||
<span class="type">array</span>, <span class="type">datetime</span> and <span class="type">struct</span>
|
||
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.</p><p>These functions reside in <code class="filename">xmlrpc.inc</code>.</p><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="phpxmlrpcdecode"></a>php_xmlrpc_decode</h3></div></div></div><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">mixed<b class="fsfunc">php_xmlrpc_decode</b>(</code></td><td>xmlrpcval<var class="pdparam">$xmlrpc_val</var>, </td></tr><tr><td> </td><td>array<var class="pdparam">$options</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">array<b class="fsfunc">php_xmlrpc_decode</b>(</code></td><td>xmlrpcmsg<var class="pdparam">$xmlrpcmsg_val</var>, </td></tr><tr><td> </td><td>string<var class="pdparam">$options</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div><p>Returns a native PHP value corresponding to the values found in
|
||
the <span class="type">xmlrpcval</span> <em class="parameter"><code>$xmlrpc_val</code></em>,
|
||
translated into PHP types. Base-64 and datetime values are
|
||
automatically decoded to strings.</p><p>In the second form, returns an array containing the parameters
|
||
of the given
|
||
<em class="parameter"><code><code class="classname">xmlrpcmsg</code>_val</code></em>, decoded
|
||
to php types.</p><p>The <em class="parameter"><code>options</code></em> 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
|
||
<span class="symbol">decode_php_objs</span> and
|
||
<code class="literal">dates_as_objects</code>. When the first is set, php
|
||
objects that have been converted to xml-rpc structs using the
|
||
<code class="function">php_xmlrpc_encode</code> 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 <code class="classname">dateTime</code> objects
|
||
instead of strings.</p><p><span class="emphasis"><em><span class="emphasis"><em>WARNING</em></span>:</em></span> please take
|
||
extreme care before enabling the <span class="symbol">decode_php_objs</span>
|
||
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.</p><p>Example:</p><pre class="programlisting"><code><span style="color: #000000">
|
||
<span style="color: #0000BB"></span><span style="color: #FF8000">// wrapper to expose an existing php function as xmlrpc method handler<br /></span><span style="color: #007700">function </span><span style="color: #0000BB">foo_wrapper</span><span style="color: #007700">(</span><span style="color: #0000BB">$m</span><span style="color: #007700">)<br />{<br /> </span><span style="color: #0000BB">$params </span><span style="color: #007700">= </span><span style="color: #0000BB">php_xmlrpc_decode</span><span style="color: #007700">(</span><span style="color: #0000BB">$m</span><span style="color: #007700">);<br /> </span><span style="color: #0000BB">$retval </span><span style="color: #007700">= </span><span style="color: #0000BB">call_user_func_array</span><span style="color: #007700">(</span><span style="color: #DD0000">'foo'</span><span style="color: #007700">, </span><span style="color: #0000BB">$params</span><span style="color: #007700">);<br /> return new </span><span style="color: #0000BB">xmlrpcresp</span><span style="color: #007700">(new </span><span style="color: #0000BB">xmlrpcval</span><span style="color: #007700">(</span><span style="color: #0000BB">$retval</span><span style="color: #007700">)); </span><span style="color: #FF8000">// foo return value will be serialized as string<br /></span><span style="color: #007700">}<br /><br /></span><span style="color: #0000BB">$s </span><span style="color: #007700">= new </span><span style="color: #0000BB">xmlrpc_server</span><span style="color: #007700">(array(<br /> </span><span style="color: #DD0000">"examples.myFunc1" </span><span style="color: #007700">=> array(<br /> </span><span style="color: #DD0000">"function" </span><span style="color: #007700">=> </span><span style="color: #DD0000">"foo_wrapper"</span><span style="color: #007700">,<br /> </span><span style="color: #DD0000">"signatures" </span><span style="color: #007700">=> ...<br /> )));</span>
|
||
</span>
|
||
</code></pre></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="phpxmlrpcencode"></a>php_xmlrpc_encode</h3></div></div></div><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">xmlrpcval<b class="fsfunc">php_xmlrpc_encode</b>(</code></td><td>mixed<var class="pdparam">$phpval</var>, </td></tr><tr><td> </td><td>array<var class="pdparam">$options</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div><p>Returns an <span class="type">xmlrpcval</span> object populated with the PHP
|
||
values in <em class="parameter"><code>$phpval</code></em>. 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.</p><p>The <em class="parameter"><code>options</code></em> 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
|
||
<span class="symbol">encode_php_objs</span>, <code class="literal">null_extension</code>
|
||
and <span class="symbol">auto_dates</span>.</p><p>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 <code class="literal">NULL</code> values to the
|
||
<code class="literal"><NIL/></code> (or
|
||
<code class="literal"><EX:NIL/></code>, see ...) tag. The last encodes any
|
||
string that matches the ISO8601 format into an XML-RPC
|
||
datetime.</p><p>Example:</p><pre class="programlisting"><code><span style="color: #000000">
|
||
<span style="color: #0000BB"></span><span style="color: #FF8000">// the easy way to build a complex xml-rpc struct, showing nested base64 value and datetime values<br /></span><span style="color: #0000BB">$val </span><span style="color: #007700">= </span><span style="color: #0000BB">php_xmlrpc_encode</span><span style="color: #007700">(array(<br /> </span><span style="color: #DD0000">'first struct_element: an int' </span><span style="color: #007700">=> </span><span style="color: #0000BB">666</span><span style="color: #007700">,<br /> </span><span style="color: #DD0000">'second: an array' </span><span style="color: #007700">=> array (</span><span style="color: #DD0000">'apple'</span><span style="color: #007700">, </span><span style="color: #DD0000">'orange'</span><span style="color: #007700">, </span><span style="color: #DD0000">'banana'</span><span style="color: #007700">),<br /> </span><span style="color: #DD0000">'third: a base64 element' </span><span style="color: #007700">=> new </span><span style="color: #0000BB">xmlrpcval</span><span style="color: #007700">(</span><span style="color: #DD0000">'hello world'</span><span style="color: #007700">, </span><span style="color: #DD0000">'base64'</span><span style="color: #007700">),<br /> </span><span style="color: #DD0000">'fourth: a datetime' </span><span style="color: #007700">=> </span><span style="color: #DD0000">'20060107T01:53:00'<br /> </span><span style="color: #007700">), array(</span><span style="color: #DD0000">'auto_dates'</span><span style="color: #007700">));</span>
|
||
</span>
|
||
</code></pre></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id938212"></a>php_xmlrpc_decode_xml</h3></div></div></div><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">xmlrpcval | xmlrpcresp |
|
||
xmlrpcmsg<b class="fsfunc">php_xmlrpc_decode_xml</b>(</code></td><td>string<var class="pdparam">$xml</var>, </td></tr><tr><td> </td><td>array<var class="pdparam">$options</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div><p>Decodes the xml representation of either an xmlrpc request,
|
||
response or single value, returning the corresponding php-xmlrpc
|
||
object, or <code class="literal">FALSE</code> in case of an error.</p><p>The <em class="parameter"><code>options</code></em> 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.</p><p>Example:</p><pre class="programlisting"><code><span style="color: #000000">
|
||
<span style="color: #0000BB">$text </span><span style="color: #007700">= </span><span style="color: #DD0000">'<value><array><data><value>Hello world</value></data></array></value>'</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$val </span><span style="color: #007700">= </span><span style="color: #0000BB">php_xmlrpc_decode_xml</span><span style="color: #007700">(</span><span style="color: #0000BB">$text</span><span style="color: #007700">);<br />if (</span><span style="color: #0000BB">$val</span><span style="color: #007700">) echo </span><span style="color: #DD0000">'Found a value of type '</span><span style="color: #007700">.</span><span style="color: #0000BB">$val</span><span style="color: #007700">-></span><span style="color: #0000BB">kindOf</span><span style="color: #007700">(); else echo </span><span style="color: #DD0000">'Found invalid xml'</span><span style="color: #007700">;</span>
|
||
</span>
|
||
</code></pre></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch09.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch09.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ch09s03.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 9. Helper functions </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Automatic conversion of php functions into xmlrpc methods (and
|
||
vice versa)</td></tr></table></div></body></html>
|