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.
Bien sûr, pour POST ou PUT, param() ne fonctionne que si les paramètres sont envoyés sous les types de format "multipart/form-data" ou "application/x-www-url-encoded" (ce qui est le cas dans la majorité des cas avec POST).
Cas du PUT ¶
PHP ne supporte pas correctement la méthode HTTP PUT. En effet, 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).
Jelix pallie ce défaut, en extrayant lui-même ces paramètres (via php://input), à condition que le type de contenu soit application/x-www-url-encoded ou multipart/form-data, comme pour POST. Vous appellerez donc la méthode param() comme dans n'importe quel contrôleur, en indiquant le paramètre voulu.
Par contre, les fichiers éventuellement transmis dans un contenu multipart/form-data, ne sont pas mis dans $_FILE, il vous faudra donc les traiter vous-même, en les récupérant comme les autres paramètres ($this->param('foo')).
Si les données ne sont pas de type "multipart/form-data" ou "application/x-www-url-encoded", vous pourrez quand même récupérer le contenu de la requête en indiquant le nom de paramètre __httpbody.
$data = $this->param('__httpbody');
À vous ensuite d'analyser le contenu en fonction du type des données (que vous trouverez dans $_SERVER["CONTENT_TYPE"]).
