Extensions

XRL supports several extensions to the original XML-RPC specification. These extensions are known to be widely supported by other implementations and generally do not conflict with the original specification.

Supported extensions

getCapabilities

The getCapabilities extension has been designed for two reasons:

  • To let XML-RPC servers announce (non-standard) features they support.
  • To provide an easy way for XML-RPC clients to adapt their behaviour depending on the non-standard features supported by a server.

XRL servers implement the following additional methods when this extension is enabled:

  • system.getCapabilities

introspection

The introspection extension makes it possible for a client to retrieve information about a remote method by querying the XML-RPC server providing it.

XRL servers implement the following additional methods when this extension is enabled:

  • system.listMethods
  • system.methodSignature
  • system.methodHelp

multicall

The multicall extension has been designed to avoid the latency incurred by HTTP round-trips when making several method calls against the same XML-RPC server.

XRL servers implement the following additional methods when this extension is enabled:

  • system.multicall

faults_interop

The faults_interop extension contains specifications for a set of standard error conditions (faults), to promote interoperability between XML-RPC implementations.

This extension is always enabled and does not add any additional methods to an XML-RPC server. A developer willing to use the interoperability faults defined in this extension can throw the associated exception from the \fpoirotte\XRL\Faults namespace.

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

The following exceptions can be used for interoperability faults:

  • ApplicationErrorException
  • InternalErrorException
  • InvalidCharacterException
  • InvalidParameterException
  • InvalidXmlRpcException
  • MethodNotFoundException
  • NotWellFormedException
  • SystemErrorException
  • TransportErrorException
  • UnsupportedEncodingException

Also, the ImplementationDefinedErrorException exception can be used for implementation-defined errors, but please note than an error code conforming to the specification must be passed explicitly when creating such an error:

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

Apache types

The Apache types extension is kind of special. It does not define any additional methods, but instead focuses on defining additional XML-RPC types.

This extension is always enabled. See also the documentation on supported XML-RPC types for more information on these types and how they are used in XRL.

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);

Note

It is not currently possible to enable each extension separately when using \fpoirotte\XRL\CapableServer::enable(). It’s an all-or-nothing kind of situation.