Documentation de XRL¶
XRL (abréviation de XML-RPC Library) est un ensemble de classes PHP facilitant la création de clients et de serveurs XML-RPC.
Vue dâensemble¶
- Installation facileârĂ©cupĂ©rez lâarchive PHAR ou ajoutez
fpoirotte/xrl
aux dépendances de votrecomposer.json
et vous ĂȘtes fin prĂȘt. - Syntaxe trĂšs intuitiveâĂ©crivez des clients et serveurs XML-RPC comme nâimporte quel autre code.
- Conversion automatique des typesâutilisez les types PHP natifs sans vous prĂ©occuper des particularitĂ©s liĂ©es Ă XML-RPC.
- Support pour de nombreuses extensionsâvous utilisez les capabilities ? lâintrospection ? le multicall ? ⊠oui, nous les supportons !
Installation et usage¶
Installation¶
Avant dâinstaller XRL, assurez-vous de disposer dâune installation de PHP fonctionnelle.
XRL nécessite PHP 5.3.4 ou plus récent, ainsi que les extensions PHP suivantes :
- XMLReader
- XMLWriter
- libxml
- GMP
- PCRE
- SPL
- Reflection
Note
Utilisez php -v
et php -m
pour obtenir des informations sur votre version de PHP et les extensions disponibles.
XRL peut ĂȘtre installĂ© en utilisant Archive PHAR, Composer, ou depuis les Sources. Lâutilisation de PHAR est recommandĂ©e.
Archive PHAR¶
Téléchargez la derniÚre archive PHAR disponible sur https://github.com/fpoirotte/XRL/releases et sauvegardez la sur votre ordinateur.
(Pour les utilisateurs dâUnix/Linux) Si vous le souhaitez, rendez le fichier exĂ©cutable.
Composer¶
XRL peut ĂȘtre installĂ© grĂące au gestionnaire de dĂ©pendances Composer. Ajoutez simplement fpoirotte/xrl
aux dépendances de votre fichier file:composer.json :
$ php composer.phar require fpoirotte/xrl
Sources¶
Pour installer XRL à partir des sources, utilisez git afin de cloner le dépÎt :
$ git clone https://github.com/fpoirotte/XRL.git /new/path/for/XRL
Démarrage rapide¶
En supposant que XRL est correctement installé sur votre ordinateur, vous pouvez à présent coder des clients et serveurs XML-RPC.
Coder un client XML-RPC¶
Chargez et enregistrez le chargeur automatique [1]
require_once('/path/to/XRL/src/Autoload.php'); \fpoirotte\XRL\Autoload::register();
CrĂ©ez le nouveau client en le configurant pour quâil interroge le serveur XML-RPC distant
$client = new \fpoirotte\XRL\Client("http://xmlrpc.example.com/server");
Appelez une mĂ©thode fournie par ce serveur, comme vous le feriez avec nâimporte quel autre 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"
Coder un serveur XML-RPC¶
Chargez et enregistrez le chargeur automatique [1]
require_once('/path/to/XRL/src/Autoload.php'); \fpoirotte\XRL\Autoload::register();
Créez une nouvelle instance de serveur
$server = new \fpoirotte\XRL\Server();
Attachez quelques méthodes à ce serveur
Vous pouvez attacher des fonctions anonymes, des closures, des fonctions globales, des mĂ©thodes publiques dâobjets, etc. en utilisant lâopĂ©rateur dâaccĂšs aux attributs
->
. Vous pouvez mĂȘme utiliser des objets invocables !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');
Ou bien, vous pouvez utiliser la syntaxe des tableaux
[]
Ă la place. Il sâagit de lâapproche recommandĂ©e car elle Ă©vite des conflits potentiels avec les attributs internes de XRL et simplifie lâutilisation de noms de mĂ©thodes qui ne sont pas des identifiants PHP valides.$server['hello'] = function ($s) { return "Hello $s!"; }; $server['string.up'] = 'strtoupper';
Traitez les requĂȘtes XML-RPC qui arrivent et publiez les rĂ©sultats
$server->handle()->publish();
[1] | (1, 2) Les utilisateurs du gestionnaire de dépendances Composer doivent utiliser le chargeur automatique habituel se trouvant dans vendor/autoload.php à la place. |
HipHop Virtual Machine¶
HipHop Virtual Machine (HHVM) est une machine virtuelle basĂ©e sur la compilation Ă la volĂ©e (JIT) et servant de moteur dâexĂ©cution pour les langages de programmation PHP et Hack.
Source : http://en.wikipedia.org/wiki/HipHop_Virtual_Machine
XRL devrait ĂȘtre compatible avec HHVM. Pour nous assurer de cela, HHVM est inclus dans les tests de notre processus dâIntĂ©gration Continue.
Fonctionnalités¶
Types XML-RPC¶
Types supportés¶
XRL supporte lâensemble des types dĂ©finis dans la spĂ©cification officielle de XML-RPC, câest-Ă -dire :
int
eti4
: entier signé sur 32 bitsboolean
: le type booléen habituelstring
: une simple chaĂźne de caractĂšresdouble
: nombre flottant signé à double précisiondateTime.iso8601
: date/heure (sans milli-secondes ni fuseau horaire)base64
: données binaires encodées en base64struct
: tableau associatifarray
: tableau indexé
XRL accepte Ă©galement les types suivants, dont lâusage est plutĂŽt rĂ©pandu, bien quâils ne fassent pas partie de la spĂ©cification officielle :
nil
: valeur null (absence de valeur)i8
: entier signé sur 64 bits
Pour finir, les types suivants appartenant Ă lâespace de noms dĂ©fini par la Fondation Apache sont aussi supportĂ©s. Veuillez noter que dans ce cas particulier, les types doivent appartenir Ă lâespace de nom ayant pour URI http://ws.apache.org/xmlrpc/namespaces/extensions pour ĂȘtre correctement interprĂ©tĂ©s.
nil
: valeur null (absence de valeur); identique au type sans espace de nomsi1
: entier signé sur 8 bitsi2
: entier signé sur 16 bitsi8
: entier signé sur 64 bits; identique au type sans espace de nomsbiginteger
: entier de taille arbitrairedom
: élément du DOM, transmis sous forme de fragment XMLdateTime
: date/heure avec milli-secondes et fuseau horaire
Lorsque des types non-standards doivent ĂȘtre envoyĂ©s, XRL utilise systĂ©matiquement les types appartenant Ă des espaces de noms. Lisez le chapitre qui suit pour plus dâinformation.
Conversion des types¶
Par dĂ©faut, XRL convertit automatiquement les valeurs entre les types de PHP et ceux de XML-RPC lorsque câest nĂ©cessaire.
Le tableau qui suit montre comment XRL convertit les types PHP vers les types XML-RPC.
Type PHP | Type XML-RPC |
---|---|
null |
nil dans un espace de noms |
boolean |
boolean |
integer |
i4 si le nombre tient sur 32 bits, i8 dans un espace de noms [1] sinon |
double |
double |
string |
string sâil sâagit dâune sĂ©quence UTF-8 valide, base64 sinon |
array |
array pour les tableaux indexés, struct pour les tableaux associatifs |
ressource GMP integer (PHP < 5.6.0) |
i4 si le nombre tient sur 32 bits, i8 dans un espace de noms [1] sâil tient sur 64 bits, biginteger dans un espace de noms [1] sinon |
objet \GMP (PHP >= 5.6.0) |
i4 si le nombre tient sur 32 bits, i8 dans un espace de noms [1] sâil tient sur 64 bits, biginteger dans un espace de noms [1] sinon |
objet \fpoirotte\XRL\Types\AbstractType |
Type XML-RPC reprĂ©sentĂ© par lâobjet |
objet \DateTime |
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.
|
objet \DOMNode |
dom dans un espace de noms [1] |
objet \XMLWriter |
dom dans un espace de noms [1] |
objet \SimpleXMLElement |
dom dans un espace de noms [1] |
objet \Exception |
faute XML-RPC (dérivée de struct ) |
Le tableau qui suit montre comment XRL convertit les types XML-RPC vers les types PHP.
Type XML-RPC | Type PHP |
---|---|
boolean |
boolean |
i4 |
integer |
int |
integer |
double |
double |
string |
string |
base64 |
string |
array |
tableau indexé |
struct |
objet \Exception si la structure représente une faute [2], tableau associatif sinon |
dateTime.iso8601 |
\DateTime (en utilisant le fuseau horaire local par défaut) |
nil |
null |
nil dans un espace de noms [1] |
null |
i1 dans un espace de noms [1] |
integer |
i2 dans un espace de noms [1] |
integer |
i8 |
An exception will be thrown in this case if PHP's native
``integer`` type cannot be used and the GMP extension
is not available.
|
i8 dans un espace de noms [1] |
An exception will be thrown in this case if PHP's native
``integer`` type cannot be used and the GMP extension
is not available.
otherwise (the GMP extension is required in this case) |
biginteger dans un espace de noms [1] |
An exception will be thrown in this case if the GMP extension
is not available.
|
dom dans un espace de noms [1] |
objet \SimpleXMLElement |
datetime dans un espace de noms [1] |
\DateTime object (using local timezone information by default,
but can be configured to use another timezone as well) |
[1] | (1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15) Avec lâespace de noms portant lâURI http://ws.apache.org/xmlrpc/namespaces/extensions pour la compatibilitĂ© avec les autres implĂ©mentations. |
[2] | Un struct XML-RPC reprĂ©sentant une faute (câest-Ă -dire une erreur) est converti en une exception qui est automatiquement levĂ©e. |
Sous le capot¶
Les conversions de types sont gérées par les classes \fpoirotte\XRL\NativeEncoder
(pour les conversions depuis PHP vers XML-RPC) et \fpoirotte\XRL\NativeDecoder
(pour les conversions depuis XML-RPC vers PHP), en sâappuyant sur les classes de lâespace de noms \fpoirotte\XRL\Types\
.
Vous pouvez surcharger ou désactiver les conversions en passant un autre encodeur/décodeur au constructeur du client ou du serveur XML-RPC.
Note
Si vous changez lâencodeur/dĂ©codeur par dĂ©faut, vous devrez gĂ©rer vous-mĂȘme les conversions depuis/vers les instances de \fpoirotte\XRL\Types\AbstractType
utilisées en interne par XRL.
Avertissement
Les fautes XML-RPC sont traitées à part et sont toujours transformées en objets \fpoirotte\XRL\Exception
avant dâĂȘtre automatiquement levĂ©es. Ce comportement est indĂ©pendant du dĂ©codeur passĂ© au constructeur du client/serveur.
Extensions¶
XRL supporte plusieurs extensions par rapport Ă la spĂ©cification XML-RPC originale. Ces extensions sont connues pour ĂȘtre bien supportĂ©es par les autres implĂ©mentations et pour ne pas rentrer en conflit avec la spĂ©cification originale en gĂ©nĂ©ral.
Extensions supportées¶
getCapabilities¶
Lâextension getCapabilities a Ă©tĂ© crĂ©Ă©e pour deux raisons :
- Pour permettre aux serveurs XML-RPC dâannoncer les fonctionnalitĂ©s (non-standards) quâils supportent.
- Pour fournir un moyen simple clients XML-RPC dâadapter leur comportement en fonction des fonctionnalitĂ©s non-standards supportĂ©es par un serveur.
Les serveurs XRL implémentent les méthodes additionnelles suivantes lorsque cette extension est activée :
system.getCapabilities
introspection¶
Lâextension introspection permet Ă un client dâobtenir des informations Ă propos dâune procĂ©dure distante en interrogeant le serveur XML-RPC qui la fournit.
Les serveurs XRL implémentent les méthodes additionnelles suivantes lorsque cette extension est activée :
system.listMethods
system.methodSignature
system.methodHelp
multicall¶
Lâextension multicall a Ă©tĂ© crĂ©Ă©e afin dâattenuer la latence introduite par les allers-retours HTTP lorsque plusieurs appels de mĂ©thodes sont envoyĂ©s au mĂȘme serveur XML-RPC.
Les serveurs XRL implémentent les méthodes additionnelles suivantes lorsque cette extension est activée :
system.multicall
faults_interop¶
Lâextension faults_interop contient les spĂ©cifications de codes correspondant Ă des cas dâerreurs standards, afin dâencourager lâinteropĂ©rabilitĂ© entre les implĂ©mentations XML-RPC.
Cette extension est toujouts activĂ©e et nâajoute aucune mĂ©thode supplĂ©mentaire aux serveurs XML-RPC. Un dĂ©veloppeur dĂ©sireux dâutiliser les erreurs interopĂ©rables dĂ©finies dans cette extension peut lever lâexception associĂ©e dans lâespace de noms \fpoirotte\XRL\Faults
.
$server->error = function () {
throw new \fpoirotte\XRL\Faults\SystemErrorException();
};
Les exceptions suivantes peuvent ĂȘtre utilisĂ©es pour reprĂ©senter une erreur interopĂ©rable :
ApplicationErrorException
InternalErrorException
InvalidCharacterException
InvalidParameterException
InvalidXmlRpcException
MethodNotFoundException
NotWellFormedException
SystemErrorException
TransportErrorException
UnsupportedEncodingException
Par ailleurs, lâexception ImplementationDefinedErrorException
peut ĂȘtre utilisĂ©e pour les erreurs propres Ă lâimplĂ©mentation. Notez cependant quâun code dâerreur conforme Ă la spĂ©cification doit ĂȘtre passĂ© explicitement lors de la crĂ©ation dâune telle erreur.
$server->error = function () {
throw new \fpoirotte\XRL\Faults\ImplementationDefinedErrorException(
-32000, // Implementation-defined error code
"You're out of memory" // Implementation-defined error message
);
};
Types Apache¶
Lâextension des types Apache est un peu spĂ©ciale. Elle nâajoute pas de nouvelles mĂ©thodes. Ă la place, elle dĂ©finit de nouveaux types XML-RPC.
Cette extensions est toujours activĂ©e. Lisez Ă©galement la documentation sur les types XML-RPC supportĂ©s pour plus dâinformation sur ces types et la maniĂšre dont ils sont utilisĂ©s dans XRL.
Activer les extensions¶
Par dĂ©faut, XRL nâactive que quelques extensions (plus prĂ©cisĂ©ment, les extensions faults_interop
et Apache types
).
Pour activer le reste des extensions, vous devez appeler \fpoirotte\XRL\CapableServer::enable()
sur le serveur :
// Create a regular XML-RPC server.
$server = new \fpoirotte\XRL\Server();
// Enable additional extensions (capabilities) for that server.
\fpoirotte\XRL\CapableServer::enable($server);
Note
Il nâest pas possible actuellement dâactiver sĂ©parĂ©ment chaque extension en utilisant \fpoirotte\XRL\CapableServer::enable()
. Câest une situation de type « tout ou rien ».
Client XML-RPC en ligne de commandes¶
XRL fournit un client XML-RPC en ligne de commandes qui facilite le test dâun serveur XML-RPC distant.
Pour les installations PHAR, le client est intĂ©grĂ© Ă lâarchive elle-mĂȘme. Pour lâutiliser, appelez lâinterprĂ©teur PHP sur lâarchive PHAR :
$ php XRL.phar
Usage: XRL.phar [options] <server URL> <procedure> [args...]
Options:
-h Show this program's help.
[...]
Pour les autres formes dâinstallations, appelez lâinterprĂ©teur PHP sur bin/xrl
:
$ php ./bin/xrl
Usage: ./bin/xrl [options] <server URL> <procedure> [args...]
Options:
-h Show this program's help.
[...]
Contributions¶
Contribuer à XRL¶
Il existe plusieurs moyens pour contribuer Ă XRL.
Essayez le !¶
Plus il y a de personnes qui lâutilisent, mieux câest. Cela permet de dĂ©tecter les bugs et les rĂ©gressions plus rapidement.
Signalez les problÚmes / Suggérez des fonctionnalités¶
Si vous utilisez XRL et que vous avez identifiĂ© un problĂšme, merci de bien vouloir nous en faire part sur GitHub. Essayez de fournir autant de dĂ©tails que possible sur la maniĂšre de reproduire le problĂšme. En rĂšgle gĂ©nĂ©rale, plus le problĂšme est facile Ă reproduire, plus il a de chances dâĂȘtre corrigĂ© rapidement.
Améliorez la documentation¶
Nous essayons de documenter XRL autant possible. Cependant, comme nous sommes Ă la fois dĂ©veloppeurs et rĂ©dacteurs de la documentation, nous avons une vision un peu biaisĂ©e des Ă©lĂ©ments qui nĂ©cessitent dâĂȘtre documentĂ©s.
Si vous sentez que certains passages pourraient ĂȘtre mieux explicitĂ©s, envoyez-nous une pull request avec vos modifications et nous ferons de notre mieux pour la relire rapidement. Toute aide pour amĂ©liorer la documentation est toujours la bienvenue !
Clonez et améliorez le code !¶
Si vous trouvez un bug, que vous connaissez bien PHP et que vous avez un peu de temps libre, récupérez le code et essayez de le corriger.
Si vous possĂ©dez un compte GitHub, câest assez facile :
- Clonez le dépÎt
- Faites vos modifications
- Envoyez-nous une pull request pour relecture
- Recommencez Ă partir de lâĂ©tape 2
Conventions de codage¶
LâĂ©quipe de XRL suit attentivement les conventions de codage dĂ©finies par la PSR-2.
De plus, lors du développement, la commande suivante permet de vérifier différents aspects de la qualité du code :
$ vendor/bin/phing qa
Elle exécute les outils suivants sur le code de XRL pour détecter les éventuels problÚmes :
- PHP lint (
php -l
) : vérification de la syntaxe PHP - PHP_CodeSniffer : vérification du respect des conventions de codage
- PDepend : identification des portions de code ayant un couplage trop important
- PHPMD (PHP Mess Detector) : détection des structures de code posant un risque
- PHPCPD (PHP Copy-Paste Detector) : détection des abus de copier/coller
- PHPUnit : passage des tests unitaires
Remerciements¶
Remerciements particuliers pour :
- Thibaud Rohmer, qui a Ă©tĂ© le tout premier utilisateur de XRL et lâinstigateur de ce projet
Merci Ă :
- David Goodger pour Docutils et reStructuredText
- Georg Brandl pour Sphinx
- La personne qui a créé le thÚme
haiku
de Sphinx
grĂące auxquels lâĂ©criture et la publication de cette documentation ont Ă©tĂ© rendues possibles.
Licence¶
XRL est distribué selon les termes de la licence BSD à 3 clauses.
Autres ressources¶
- XRL sur GitHub (suivi de code source et de bugs)
- XRL sur Packagist (dépÎt Composer)
- XRL sur Travis-CI (intégration continue)
- XRL sur Read The Docs (documentation en ligne)
- Documentation dâAPI complĂšte (hĂ©bergĂ©e sur Read The Docs)