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

Coder un client XML-RPC¶

1. Chargez et enregistrez le chargeur automatique [1]

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

2. 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");
   

3. 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¶

1. Chargez et enregistrez le chargeur automatique [1]

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

2. Créez une nouvelle instance de serveur

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

3. 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';
     

4. Traitez les requêtes XML-RPC qui arrivent et publiez les résultats

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

Types supportés¶

XRL supporte l’ensemble des types définis dans la spécification officielle de XML-RPC, c’est-à-dire :

• int et i4 : entier signé sur 32 bits
• boolean : le type booléen habituel
• string : une simple chaîne de caractères
• double : nombre flottant signé à double précision
• dateTime.iso8601 : date/heure (sans milli-secondes ni fuseau horaire)
• base64 : données binaires encodées en base64
• struct : tableau associatif
• array: 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 noms
• i1 : entier signé sur 8 bits
• i2 : entier signé sur 16 bits
• i8 : entier signé sur 64 bits; identique au type sans espace de noms
• biginteger : entier de taille arbitraire
• dom : élément du DOM, transmis sous forme de fragment XML
• dateTime: 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.

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.

Le tableau qui suit montre comment XRL convertit les types XML-RPC vers les types PHP.

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.

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.

Extensions supportées¶

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

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

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 :

1. Clonez le dépôt
2. Faites vos modifications
3. Envoyez-nous une pull request pour relecture
4. Recommencez à partir de l’étape 2