Section: Un contrôleur pour REST
| « Utiliser le contrôleur CRUD | ^ Développement d'un module |
− Table des matières
La technique REST consiste à utiliser les fonctionnalités du protocole HTTP pour manipuler une ressource. En effet, il existe les méthodes POST et GET que vous connaissez, mais il existe aussi les méthodes PUT et DELETE. Ainsi, pour effectuer une création, un affichage, un effacement d'une ressource, plutôt que d'avoir plusieurs URLs spécifiques pour faire cela, il y a une seule URL, et on utilise le champ "method" de HTTP pour indiquer l'action à effectuer.
Pour en savoir plus sur les principes de REST, il existe pas mal d'explications sur le web. N'hésitez pas à googler !
Voyons maintenant comment faire du REST dans Jelix.
Le contrôleur ¶
Nous avons vu qu'il existe 4 méthodes GET, POST, DELETE, PUT dans le protocole HTTP. Il faut implémenter donc 4 méthodes pour chacune d'elles dans un contrôleur.
Vous devez réaliser un contrôleur qui va implémenter l'interface jIRestController. Ce contrôleur ne pourra être utilisé que pour faire du REST. Vous ne pourrez donc pas réaliser des méthodes pour des actions supplémentaires, autres que les quatre imposées par l'interface jIRestController :
class exempleCtrl extends jController implements jIRestController {
function get(){
}
function post(){
}
function put(){
}
function delete(){
}
}
Dans ces méthodes, vous développez vos actions comme à l'accoutumée, en respectant la signification de ces méthodes. En général, GET doit correspondre à un affichage d'une ressource, POST à sa création, PUT à sa modification, et DELETE à sa suppression.
Note : il est indispensable de déclarer que vous implémentez l'interface jIRestController. C'est en effet en analysant le contrôleur que Jelix sait si vous faites du REST ou pas, ce qui change son comportement interne.
Appel d'une action d'un contrôleur REST ¶
Comme la nature de l'action est indiquée dans la méthode HTTP, de l'extérieur vous n'avez en fait qu'une seule url, donc qu'une seule action. C'est le type de la méthode HTTP indiquée dans la requête HTTP qui indiquera à Jelix d'appeler l'une des 4 méthodes du contrôleur.
Aussi, quand vous voulez récupérer avec jUrl l'url de l'action qui correspond à votre contrôleur REST, vous ne devez indiquer que le module et le nom du contrôleur, et ne pas mettre donc le nom d'une méthode.
Ainsi, l'action qui permet d'appeler les méthodes contrôleur de l'exemple, est "leModule~exemple:" (si le module est "leModule"). Notez qu'il faut mettre un ":" pour indiquer que l'on indique bien le nom du contrôleur, et non le nom d'une méthode.
Avec l'url obtenu par jUrl::get("leModule~exemple:"), vous pouvez alors appeler dans vos scripts javascripts, via xmlHttpRequest par exemple, l'une des quatre méthodes du contrôleur, simplement en indiquant à xmlHttpRequest que vous voulez utiliser GET, POST, DELETE ou PUT.
Note ¶
Vous pouvez bien sûr faire du REST avec un contrôleur classique, en testant dans votre action, la valeur de $_SERVER['REQUEST_METHOD'] qui indique le type de la méthode HTTP. Mais c'est peut être moins "sexy" que d'utiliser le procédé indiqué dans cette page pour implémenter du REST ;-)
Récupérer les paramètres de requêtes ¶
Comme dans n'importe quel contrôleur, vous récupérez les paramètres avec la méthode param() en indiquant le nom du paramètre, en particulier pour les méthodes POST et GET, comme à l'habitude.
Pour PUT et DELETE par contre, il faut récupérer les paramètres à la main. En effet, PHP ne supporte pas correctement la méthode HTTP PUT. Il ne récupère pas les paramètres qui pourraient être éventuellement dans le corps de la requête http, comme il le fait avec la méthode POST (il n'y a pas de $_PUT).
Il vous faut alors récupérer le flux php://input et parser vous même le contenu (Dans la version suivante, Jelix le fera automatiquement).
