Table of Contents
This is where a lot of the hard work gets done. This class enables the creation and encapsulation of values for XML-RPC.
Ensure you've read the XML-RPC spec at http://www.xmlrpc.com/stories/storyReader$7 before reading on as it will make things clearer.
The xmlrpcval
class can store arbitrarily
complicated values using the following types: i4 int boolean
string double dateTime.iso8601 base64 array struct
null
. You should refer to the spec for more information on
what each of these types mean.
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.
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.
The php values true
and
1
map to true
. All other
values (including the empty string) are converted to
false
.
Characters <, >, ', ", &, are encoded using their
entity reference as < > ' " and
& All other characters outside of the ASCII range are
encoded using their character reference representation (e.g.
È for é). The XML-RPC spec recommends only encoding
< &
but this implementation goes further,
for reasons explained by the XML 1.0
recommendation. In particular, using character reference
representation has the advantage of producing XML that is valid
independently of the charset encoding assumed.
The constructor is the normal way to create an
xmlrpcval
. The constructor can take these
forms:
xmlrpcvalnew
xmlrpcval( | void) ; |
xmlrpcvalnew
xmlrpcval( | string$stringVal) ; |
xmlrpcvalnew
xmlrpcval( | mixed$scalarVal, |
string$scalartyp) ; |
xmlrpcvalnew
xmlrpcval( | array$arrayVal, |
string$arraytyp) ; |
The first constructor creates an empty value, which must be
altered using the methods addScalar
,
addArray
or addStruct
before
it can be used.
The second constructor creates a simple string value.
The third constructor is used to create a scalar value. The
second parameter must be a name of an XML-RPC type. Valid types are:
"int
", "boolean
",
"string
", "double
",
"dateTime.iso8601
", "base64
" or
"null".
Examples:
$myInt = new xmlrpcvalue(1267, "int");
$myString = new xmlrpcvalue("Hello, World!", "string");
$myBool = new xmlrpcvalue(1, "boolean");
$myString2 = new xmlrpcvalue(1.24, "string"); // note: this will serialize a php float value as xmlrpc string
The fourth constructor form can be used to compose complex
XML-RPC values. The first argument is either a simple array in the
case of an XML-RPC array
or an associative
array in the case of a struct
. The elements of
the array must be xmlrpcval
objects
themselves.
The second parameter must be either "array
"
or "struct
".
Examples:
$myArray = new xmlrpcval(
array(
new xmlrpcval("Tom"),
new xmlrpcval("Dick"),
new xmlrpcval("Harry")
),
"array");
// recursive struct
$myStruct = new xmlrpcval(
array(
"name" => new xmlrpcval("Tom", "string"),
"age" => new xmlrpcval(34, "int"),
"address" => new xmlrpcval(
array(
"street" => new xmlrpcval("Fifht Ave", "string"),
"city" => new xmlrpcval("NY", "string")
),
"struct")
),
"struct");
See the file vardemo.php
in this distribution
for more examples.
intaddScalar( | string$stringVal) ; |
intaddScalar( | mixed$scalarVal, |
string$scalartyp) ; |
If $val
is an empty
xmlrpcval
this method makes it a scalar
value, and sets that value.
If $val
is already a scalar value, then
no more scalars can be added and 0
is
returned.
If $val
is an xmlrpcval of type array,
the php value $scalarval
is added as its last
element.
If all went OK, 1
is returned, otherwise
0
.
intaddArray( | array$arrayVal) ; |
The argument is a simple (numerically indexed) array. The
elements of the array must be
xmlrpcval
objects
themselves.
Turns an empty xmlrpcval
into an
array
with contents as specified by
$arrayVal
.
If $val
is an xmlrpcval of type array,
the elements of $arrayVal
are appended to the
existing ones.
See the fourth constructor form for more information.
If all went OK, 1
is returned, otherwise
0
.
intaddStruct( | array$assocArrayVal) ; |
The argument is an associative array. The elements of the
array must be xmlrpcval
objects
themselves.
Turns an empty xmlrpcval
into a
struct
with contents as specified by
$assocArrayVal
.
If $val
is an xmlrpcval of type struct,
the elements of $arrayVal
are merged with the
existing ones.
See the fourth constructor form for more information.
If all went OK, 1
is returned, otherwise
0
.
stringkindOf( | void) ; |
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.
stringserialize( | void) ; |
Returns a string containing the XML-RPC representation of this value.
mixedscalarVal( | void) ; |
If $val->kindOf() == "scalar"
, this
method returns the actual PHP-language value of the scalar (base 64
decoding is automatically handled here).
stringscalarTyp( | void) ; |
If $val->kindOf() == "scalar"
, this
method returns a string denoting the type of the scalar. As
mentioned before, i4
is always coerced to
int
.
xmlrpcvalarrayMem( | int$n) ; |
If $val->kindOf() == "array"
, returns
the $n
th element in the array represented by
the value $val
. The value returned is an
xmlrpcval
object.
// iterating over values of an array object
for ($i = 0; $i < $val->arraySize(); $i++)
{
$v = $val->arrayMem($i);
echo "Element $i of the array is of type ".$v->kindOf();
}
xmlrpcvalstructMem( | string$memberName) ; |
If $val->kindOf() == "struct"
, returns
the element called $memberName
from the
struct represented by the value $val
. The
value returned is an xmlrpcval
object.
arraystructEach( | void) ; |
Returns the next (key, value) pair from the struct, when
$val
is a struct.
$value
is an xmlrpcval itself. See also structreset().
// 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();
}
voidstructReset( | void) ; |
Resets the internal pointer for
structEach()
to the beginning of the struct,
where $val
is a struct.