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
. 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
. The value 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. Therefore you ought to consider it as a "binary" data type, for use when you want to pass none 7-bit clean data. Decoding is also transparent.
The 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 non-ASCII characters are encoded using their character reference representation (e.g. È for é). The current 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:
$myVal=new xmlrpcval(
)
;
;
$myVal=new xmlrpcval(
$stringVal)
;$stringVal
;
$myVal=new xmlrpcval( | $scalarVal, | |
"int" | "boolean" | "string" | "double" | "dateTime.iso8601" | "base64") ; |
$scalarVal; | |
"int" | "boolean" | "string" | "double" | "dateTime.iso8601" | "base64"; |
$myVal=new xmlrpcval( | $arrayVal, | |
"array" | "struct") ; |
$arrayVal; | |
"array" | "struct"; |
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. Examples:
$myInt=new xmlrpcvalue(1267, "int"); $myString=new xmlrpcvalue("Hello, World!", "string"); $myBool=new xmlrpcvalue(1, "boolean");
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. Examples:
$myArray=new xmlrpcval(array( new xmlrpcval("Tom"), new xmlrpcval("Dick"), new xmlrpcval("Harry")), "array"); $myStruct=new xmlrpcval(array( "name" => new xmlrpcval("Tom"), "age" => new xmlrpcval(34, "int"), "geek" => new xmlrpcval(1, "boolean")), "struct");
See the file vardemo.php
in this distribution for more examples.
$ok=$val->addScalar(
$stringVal)
;$stringVal
;
$ok=$val->addScalar( | $scalarVal, | |
"int" | "boolean" | "string" | "double" | "dateTime.iso8601" | "base64") ; |
$scalarVal; | |
"int" | "boolean" | "string" | "double" | "dateTime.iso8601" | "base64"; |
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 all went OK, 1
is returned.
There is a special case if $val
is an array
: the scalar value passed is appended to the array.
$ok=$val->addArray(
$arrayVal)
;$arrayVal
;
Turns an empty xmlrpcval
into an array
with contents as specified by $arrayVal
. See the fourth constructor form for more information.
$ok=$val->addArray(
$assocArrayVal)
;$assocArrayVal
;
Turns an empty xmlrpcval
into a struct
with contents as specified by $assocArrayVal
. See the fourth constructor form for more information.
$kind=$val->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.
$outString=$val->serialize(
)
;
;
Returns a string containing the XML-RPC representation of this value.
$scalarVal=$val->scalarval(
)
;
;
If $val->kindOf()=="scalar"
, this method returns the actual PHP-language value of the scalar (base 64 decoding is automatically handled here).
$typeName=$val->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
.
$xmlrpcVal=$val->arraymem(
$n)
;$n
;
Returns the $n
th element in the array represented by the value $val
. The value returned is an xmlrpcval
object.
$len=$val->arraysize(
)
;
;
If $val
is an array
, returns the number of elements in that array.
$xmlrpcVal=$val->structmem(
$memberName)
;$memberName
;
Returns the element called $memberName
from the struct represented by the value $val
. The value returned is an xmlrpcval
object.
list($key,$value)=$val->structeach(
)
;
;
Returns the next (key,value) pair from the struct, when $val
is a struct. See also structreset().