PHAR archive¶

Download the latest PHAR available on https://github.com/fpoirotte/XRL/releases and save it to your computer.

(For Unix/Linux users) Optionally, make the file executable.

Composer¶

XRL can be installed using the Composer dependency manager. Just add fpoirotte/xrl to the dependencies in your composer.json :

$ php composer.phar require fpoirotte/xrl

Sources¶

To install XRL from sources, use git to clone the repository:

$ git clone https://github.com/fpoirotte/XRL.git /new/path/for/XRL

Writing an XML-RPC client¶

1. Load and register the autoloader [1]

   require_once('/path/to/XRL/src/Autoload.php');
   \fpoirotte\XRL\Autoload::register();
   

2. Create a new client configured to query the remote XML-RPC server

   $client = new \fpoirotte\XRL\Client("http://xmlrpc.example.com/server");
   

3. Call a method provided by that server, like it were just any other code

   // Call the remote procedure named "hello",
   // with "world" as its parameter.
   $result = $client->hello('world');
   
   // $result now contains the remote procedure's result,
   // as a regular PHP type (integer, string, double, array, etc.)
   var_dump($result); // string(12) "hello world!"
   
   // Methods with names that are not valid PHP identifiers
   // can still be called!
   var_dump($client->{'string.up'}('game over')); // string(9) "GAME OVER"
   

Writing an XML-RPC server¶

1. Load and register the autoloader [1]

   require_once('/path/to/XRL/src/Autoload.php');
   \fpoirotte\XRL\Autoload::register();
   

2. Create a new server instance

   $server = new \fpoirotte\XRL\Server();
   

3. Attach some methods to that server

   • You can register anonymous functions, closures, global functions, public methods on objects, etc. using the attribute access operator ->. You may even use invokable objects!

     class Simpson
     {
         private $speech = array(
             'Homer'     => 'Doh!',
             'Marge'     => 'Hmm...',
             'Bart'      => 'Aie, caramba!',
             'Lisa'      => M_PI,
             'Maggie'    => null,
         );
         private $character;
     
         public function __construct($character)
         {
             if (!array_key_exists($character, $this->speech)) {
                 throw new InvalidArgumentException("Who's that?");
             }
             $this->character = $character;
         }
     
         public function __invoke()
         {
             return $this->speech[$this->character];
         }
     }
     $server->homer  = new Simpson('Homer');
     $server->marge  = new Simpson('Marge');
     $server->bart   = new Simpson('Bart');
     $server->lisa   = new Simpson('Lisa');
     $server->maggie = new Simpson('Maggie');
     

   • Alternatively, you can use the array syntax [] instead. This is recommended as it avoids potential conflicts with XRL’s own attributes and it makes things easier when the method’s name is not a valid PHP identifier.

     $server['hello'] = function ($s) { return "Hello $s!"; };
     $server['string.up'] = 'strtoupper';
     

4. Handle incoming XML-RPC requests and publish the results

   $server->handle()->publish();
   

Supported types¶

XRL supports all the datatypes defined in the official XML-RPC specification, namely:

• int and i4: 32-bit signed integer value
• boolean: your usual boolean type
• string: regular string
• double: double-precision signed floating point number
• dateTime.iso8601: date/time (without milliseconds/timezone information)
• base64: base64-encoded binary string
• struct: associative array
• array: numeric array

It also accepts the following types, which are pretty common, despite them not being part of the official specification:

• nil: null value
• i8: 64-bit signed integer value

Last but not least, it supports the following namespaced types, defined by the Apache Foundation. Please note that in this particular case, the types must belong to the namespace URI http://ws.apache.org/xmlrpc/namespaces/extensions to be correctly interpreted.

• nil: null value (same as the non-namespaced type)
• i1: 8-bit signed integer value
• i2: 16-bit signed integer value
• i8: 64-bits signed integer value (same as the non-namespaced type)
• biginteger: arbitrary-length integer
• dom: a DOM node, transmitted as an XML fragment
• dateTime: date/time with milliseconds and timezone information

When transmitting non-standard types, XRL always uses namespaced types. See the next chapter for more information.

Type conversions¶

By default, XRL automatically converts values between PHP & XML-RPC types where appropriate.

The following table shows how XRL converts PHP types to XML-RPC types.

The XML-RPC ``dateTime.iso8601`` data type does not support
milliseconds, nor passing timezone information.
Only use this type when the actual timezone is known beforehand
(using contextual information or a pre-established convention),
or when potential errors in date/time handling are not an issue.

The following table shows how XRL converts XML-RPC types to PHP types.

An exception will be thrown in this case if PHP's native
``integer`` type cannot be used and the GMP extension
is not available.

An exception will be thrown in this case if PHP's native
``integer`` type cannot be used and the GMP extension
is not available.

An exception will be thrown in this case if the GMP extension
is not available.

Under the hood¶

Type conversions are handled by the \fpoirotte\XRL\NativeEncoder class (for PHP to XML-RPC conversions) and \fpoirotte\XRL\NativeDecoder class (for XML-RPC to PHP conversions), with support from classes in the \fpoirotte\XRL\Types\ namespace.

You may override or disable the conversion by passing another encoder/decoder to the XML-RPC client or server constructor.

Supported extensions¶

$server->error = function () {
    throw new \fpoirotte\XRL\Faults\SystemErrorException();
};

$server->error = function () {
    throw new \fpoirotte\XRL\Faults\ImplementationDefinedErrorException(
        -32000,                 // Implementation-defined error code
        "You're out of memory"  // Implementation-defined error message
    );
};

Enabling the extensions¶

By default, XRL enables only a few extensions (namely, the faults_interop and Apache types extensions).

To enable the rest of the extensions, you must call \fpoirotte\XRL\CapableServer::enable() on the server:

// Create a regular XML-RPC server.
$server = new \fpoirotte\XRL\Server();

// Enable additional extensions (capabilities) for that server.
\fpoirotte\XRL\CapableServer::enable($server);

Try it!¶

The more people use it, the better, because it means bugs and regressions can be detected more quickly.

Report Bugs / Suggest Features¶

If you use XRL and find issues with it, please let us know on GitHub. Try to provide as much detail as possible on how to reproduce your issue. As a rule of thumb, the easier it is to reproduce an issue, the quicker it gets fixed.

Improve the Documentation¶

We try to document XRL as much as we can, but acting both as developers and documentation writers, we tend to be biased as to what needs documentation.

So if you feel like some parts could be clearer, send us a pull request with your modifications and we’ll try to review them as soon as possible. Any help to improve the documentation will be greatly appreciated!

Fork It! And Improve the Code¶

If you find a bug and have some PHP knowledge and time to spare, grab a copy of the code and have a go at fixing it.

If you already have a GitHub account, it’s quite simple:

1. Fork the code
2. Hack away
3. Send a pull request for review
4. Repeat again starting at step 2