REST¶

Mise en place Simple¶

Le moyen le plus rapide pour démarrer avec REST est d’ajouter quelques lignes pour configurer resource routes dans votre fichier config/routes.php.

Une fois que le router a été configuré pour mapper les requêtes REST vers certaines actions de controller, nous pouvons continuer et créer la logique dans nos actions de controller. Un controller basique pourrait ressembler à ceci:

// src/Controller/RecipesController.php
class RecipesController extends AppController
{

    public function initialize(): void
    {
        parent::initialize();
        $this->loadComponent('RequestHandler');
    }

    public function index()
    {
        $recipes = $this->Recipes->find('all');
        $this->set('recipes', $recipes);
        $this->viewBuilder()->setOption('serialize', ['recipes']);
    }

    public function view($id)
    {
        $recipe = $this->Recipes->get($id);
        $this->set('recipe', $recipe);
        $this->viewBuilder()->setOption('serialize', ['recipe']);
    }

    public function add()
    {
        $recipe = $this->Recipes->newEntity($this->request->getData());
        if ($this->Recipes->save($recipe)) {
            $message = 'Saved';
        } else {
            $message = 'Error';
        }
        $this->set([
            'message' => $message,
            'recipe' => $recipe,
        ]);
        $this->viewBuilder()->setOption('serialize', ['recipe', 'message']);
    }

    public function edit($id)
    {
        $recipe = $this->Recipes->get($id);
        if ($this->request->is(['post', 'put'])) {
            $recipe = $this->Recipes->patchEntity($recipe, $this->request->getData());
            if ($this->Recipes->save($recipe)) {
                $message = 'Saved';
            } else {
                $message = 'Error';
            }
        }
        $this->set([
            'message' => $message,
            'recipe' => $recipe,
        ]);
        $this->viewBuilder()->setOption('serialize', ['recipe', 'message']);
    }

    public function delete($id)
    {
        $recipe = $this->Recipes->get($id);
        $message = 'Deleted';
        if (!$this->Recipes->delete($recipe)) {
            $message = 'Error';
        }
        $this->set('message', $message);
        $this->viewBuilder()->setOption('serialize', ['message']);
    }
}

Les controllers RESTful utilisent souvent les extensions parsées pour servir différentes views basées sur différents types de requête. Puisque nous gérons les requêtes REST, nous ferons des views XML. Vous pouvez aussi faire des views JSON en utilisant les Vues JSON et XML intégrées à CakePHP. En utilisant XmlView intégré, nous pouvons définir une option _serialize. Cette option est utilisée pour définir les variables de vue que XmlView doit sérialiser en XML.

Si nous voulons modifier les données avant qu’elles soient converties en XML, nous ne devons pas définir l’option _serialize, et à la place utiliser les fichiers de template. Nous plaçons les vues REST pour notre RecipesController à l’intérieur de templates/Recipes/xml. Nous pouvons aussi utiliser Xml pour une sortie XML simple à mettre en place dans ces vues. Voici à quoi notre vue index pourrait ressembler:

// templates/Recipes/xml/index.php
// Faire du formatage et de la manipulation sur le tableau
// $recipes.
$xml = Xml::fromArray(['response' => $recipes]);
echo $xml->asXML();

Quand vous servez le type de contenu spécifique en utilisant parseExtensions(), CakePHP recherche automatiquement un helper de view qui matche le type. Puisque nous utilisons le XML en type de contenu, il n’y a pas de helper intégré cependant si vous en créez un, il va être automatiquement chargé pour notre utilisation dans ces vues.

Le XML rendu va finir par ressembler à ceci:

<recipes>
    <recipe>
        <id>234</id>
        <created>2008-06-13</created>
        <modified>2008-06-14</modified>
        <author>
            <id>23423</id>
            <first_name>Billy</first_name>
            <last_name>Bob</last_name>
        </author>
        <comment>
            <id>245</id>
            <body>Yummy yummmy</body>
        </comment>
    </recipe>
    ...
</recipes>

Créer la logique pour l’action edit est un tout petit peu plus compliqué. Puisque vous fournissez une API qui sort du XML, c’est un choix naturel de recevoir le XML en input. Ne vous inquiétez pas, les classes Cake\Controller\Component\RequestHandler et Cake\Routing\Router vous facilitent les choses. Si une requête POST ou PUT a un type de contenu XML, alors l’input est lancé à travers la classe Xml de CakePHP, et la representation en tableau des données est assigné à $this->request->data. Avec cette fonctionnalité, la gestion de XML et les données POST en parallèle est seamless: aucun changement n’est nécessaire pour le code du controller ou du model. Tout ce dont vous avez besoin devrait se trouver dans $this->request->getData().

Accepter l’Input dans d’Autres Formats¶

Typiquement les applications REST ne sortent pas seulement du contenu dans des formats de données alternatifs, elles acceptent aussi des données dans des formats différents. Dans CakePHP, RequestHandlerComponent facilite ceci. Par défaut, elle va décoder toute donnée d’input JSON/XML entrante pour des requêtes POST/PUT et fournir la version du tableau de ces données dans $this->request->data. Vous pouvez aussi connecter avec des deserialisers supplémentaires dans des formats alternatifs si vous avez besoin d’eux en utilisant RequestHandler::addInputType()

RESTful Routing¶

Le Router de CakePHP fournit une interface pratique pour connecter des routes pour les ressources RESTful. Consultez la section Créer des Routes RESTful pour plus d’informations.