XML-RPC for PHP: version 1.0b9
Prev | Chapter 5. Class documentation | Next

# xmlrpcval

This is where a lot of the hard work gets done. This class enables the creation and encapsulation of values for XML-RPC.

Ensure you've read the XML-RPC spec at http://www.xmlrpc.com/stories/storyReader$7 before reading on as it will make things clearer.

The `xmlrpcval` class can store arbitrarily complicated values using the following types: `i4 int boolean string double dateTime.iso8601 base64 array struct`. You should refer to the spec for more information on what each of these types mean.

## Notes on types

### int

The type `i4` is accepted as a synonym for `int`. The value 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. 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.

### boolean

The values `true` and `1` map to `true`. All other values (including the empty string) are converted to `false`.

### string

The characters `< > "` and `&` are converted to their entity equivalents `&lt; &gt; &quot;` and `&amp;` for transport through XML-RPC. The current XML-RPC spec recommends only encoding `< &` but this implementation goes further, for reasons explained by the XML 1.0 recommendation.

TODO: `&apos;` entity not yet supported

## Creation

The constructor is the normal way to create an `xmlrpcval`. The constructor can take these forms:

``$myVal=new xmlrpcval`();`

``$myVal=new xmlrpcval`($stringVal);`

``$myVal=new xmlrpcval`($scalarVal, "int" | "boolean" | "string" | "double" | "dateTime.iso8601" | "base64");`

``$myVal=new xmlrpcval`($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.

## Methods

### addScalar

``$ok=$val->addScalar`($stringVal);`

``$ok=$val->addScalar`($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.

### addArray

``$ok=$val->addArray`($arrayVal);`

Turns an empty `xmlrpcval` into an `array` with contents as specified by `$arrayVal`. See the fourth constructor form for more information.

### addStruct

``$ok=$val->addArray`($assocArrayVal);`

Turns an empty `xmlrpcval` into a `struct` with contents as specified by `$assocArrayVal`. See the fourth constructor form for more information.

### kindOf

``$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.

### serialize

``$outString=$val->serialize`();`

Returns a string containing the XML-RPC representation of this value.

### scalarval

``$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).

### scalartyp

``$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`.

### arraymem

``$xmlrpcVal=$val->arraymem`($n);`

Returns the `$n`th element in the array represented by the value `$val`. The value returned is an `xmlrpcval` object.

### arraysize

``$len=$val->arraysize`();`

If `$val` is an `array`, returns the number of elements in that array.

### structmem

``$xmlrpcVal=$val->structmem`($memberName);`

Returns the element called `$memberName` from the struct represented by the value `$val`. The value returned is an `xmlrpcval` object.

### structeach

``list($key,$value)=$val->structeach`();`

Returns the next (key,value) pair from the struct, when `$val` is a struct. See also structreset().

### structreset

``$val->structreset`();`

Resets the internal pointer for `structeach()` to the beginning of the struct, where `$val` is a struct.

Prev | Home | Next
xmlrpcresp | Up | xmlrpc_server