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.