👨🏽‍✈️ Contrôleurs

Introduction

Les contrôleurs sont des moyens pour simplifier l'organisation de votre projet.

Au lieu de définir toute la logique de gestion de la requête en tant que closure dans les fichiers de routage, vous pouvez organiser ce comportement à l'aide de classe de contrôleur. Les contrôleurs peuvent regrouper la logique de traitement des requêtes associée en une seule classe.

Les contrôleurs sont stockés dans le répertoire app/Controllers.

Configuration

Vous avez la possibilité de modifier le namespace des contrôleurs et des middlewares. Pour ce faire, ouvrez le fichier app\Kernel.php. La méthode namespaces permet à Bow de savoir quel est le bon namespace à ajouter sur le contrôleur lors de l'exécution de la requête ou lors de la génération de contrôleur ou de middleware par le lanceur de tâche php bow.

Imaginez que vous avez une application pour la gestion des bus d'une école et que vous voulez grouper tous vos contrôleurs dans le namespace App\Bus\Controllers. Alors comment faire ça ?

Voici le code que cela pourrait donner :

app\Kernel.php

public function namespaces()
{
  return [
    "controller" => "App\\Bus\\Controllers",
    ...
  ]
}

Ensuite, il faudra aussi changer un peu la configuration du lanceur de tâche :

Dans le fichier bow

$command = new Bow\Console\Command(__DIR__);
$command->setControllerDirectory(__DIR__.'/app/Bus/Controllers');

Visitez ce lien pour plus d'information sur la personnalisation de la structure de l'application.

Contrôleur de base

Définir un contrôleur

Voici un exemple de classe de contrôleur de base. Notez que le contrôleur hérite de la classe App\Controllers\Controller de base. Cette classe de base fournit quelques méthodes pratiques telles que la méthode du render, qui peut être utilisée pour compiler une vue.

namespace App\Controllers;

use App\Controllers\Controller;
use App\Models\User;

class UserController extends Controller
{
  /**
   * Afficher le profil pour l'utilisateur donné.
   *
   * @param int $id
   * @return mixed
   */
  public function show($id)
  {
    return $this->render('user/profile', ['user' => User::findOrFail($id)]);
  }
}

Vous pouvez définir une route dans le fichier routes/app.php vers cette méthode de contrôleur comme suit :

$app->get('user/:id', 'UserController::show');

Désormais, lorsqu'une demande correspond à l'URI de la route spécifiée, la méthode show de la classe UserController sera exécutée. Bien entendu, les paramètres de la route seront également transmis à la méthode.

Vous pouvez générer un contrôleur en utilisant la commande add:controller de php bow:

php bow add:controller UserController

Contrôleur et espaces de noms

Il est très important de noter que nous n'avons pas eu besoin de spécifier le namespace complet du contrôleur lors de la définition de la route. Étant donné que public/index.php charge vos fichiers de route dans un groupe de routage contenant le namespace, nous avons uniquement spécifié la partie du nom de classe qui vient après la partie App\Controllers du namespace.

Si vous choisissez d'imbriquer vos contrôleurs plus profondément dans le répertoire App\Controllers, utilisez le nom de classe spécifique relatif au namespace racine App\Controllers. Donc, si votre classe de contrôleur complète est App\Controllers\Photo\AdminController, vous devez enregistrer les routes sur le contrôleur comme suit :

$app->get('/foo', 'Photo\AdminController::action');

Vous pouvez générer un contrôleur en utilisant la commande add:controller de php bow:

php bow add:controller Photo/AdminController

remarque

Remarquez bien le nom du dossier : il est en camel case. Le framework créera le namespace approprié pour la classe AdminController qui sera namespace App\Controllers\Photo;. Vous trouverez le contrôleur dans le dossier app/Controllers/Photo/AdminController.php.

Plus d'information sur le routing.

Contrôleur et middleware

Les middlewares peuvent être assignés à la route du contrôleur dans vos fichiers de route. Le middleware est stocké dans le dossier app\Middlewares. Pour plus d'informations sur les middlewares, visitez ce lien.

Exemple :

$app->get('profile', 'UserController::show')->middleware('auth');

Contrôleur REST

Les contrôleurs REST sont un moyen simple pour mettre en place une API Rest. Cette approche vous permet de vous concentrer sur votre logique et de laisser le framework gérer le routage pour vous.

Définir un contrôleur REST

Pour définir un nouveau contrôleur REST, vous devez utiliser le lanceur de tâche php bow avec la commande generate:resource dans votre console :

php bow generate:resource PetController

Un contrôleur nommé PetController sera donc créé. Ce qui fait sa particularité, c'est qu'il y a déjà des méthodes prédéfinies et ces méthodes doivent rester telles quelles.

namespace App\Controllers;

use App\Controllers\Controller;
use App\Models\Pet;

class PetController extends Controller
{
  /**
   * Point d'entrée
   *
   * @return void
   */
  public function index()
  {
    // Codez Ici
  }

  /**
   * Permet d'afficher la vue permettant de créer une résource.
   *
   * @return void
   */
  public function create()
  {
    // Codez Ici
  }

  /**
   * Permet d'ajouter une nouvelle ressource dans la base de données
   *
   * @return void
   */
  public function store()
  {
    // Codez Ici
  }

  /**
   * Permet de récupérer une information précise avec un identifiant
   *
   * @param mixed $id
   * @return void
   */
  public function show($id)
  {
    // Codez Ici
  }

  /**
   * Mise à jour d'une ressource en utilisant les paramètres GET
   *
   * @param mixed $id
   * @return void
   */
  public function edit($id)
  {
    // Codez Ici
  }

  /**
   * Mise à jour d'une résource
   *
   * @param mixed $id
   * @return void
   */
  public function update($id)
  {
    // Codez Ici
  }

  /**
   * Permet de supprimer une ressource
   *
   * @param mixed $id
   * @return void
   */
  public function destroy($id)
  {
    // Codez Ici
  }
}

Utiliser le contrôleur REST

Pour utiliser le contrôleur REST, vous devez utiliser la méthode rest sur la variable globale $app dans vos fichiers de routing.

Prototype de la méthode rest

$app->rest(url, action, where = []);

Paramètre	Type
url	String, Array - Le nom de la route
action	String - Le nom du contrôleur
where	Array - Contrainte sur la variable id

Utilisation simple

Et ça donne ceci :

$app->rest('pets', 'PetController');

Utilisation avec les contraintes

Avec une contrainte ça donne ceci:

$app->rest('pets', 'PetController', ['id' => '\d+']);

Ici la contrainte s'applique sur toutes les méthodes. Mais, vous avez aussi la possibilité de restreindre les contraintes sur des méthodes comme ceci :

$app->rest('pets', 'PetController', [
  'show' => ['id' => '\d+'],
  'edit' => ['id' => '[a-z]+'],
]);

Utilisation via un tableau comme action

Dans le cas ou action est un array voici les clés/valeurs possibles.

$action = [
  'controller' => 'PetController',
  'ignores' => ['index', 'create'],
];

$app->rest('pets', $action, ['id' => '\d+']);

Ignorer des méthodes

La valeur de ignores sera une liste de méthodes/URLs qui seront ignorées par le routeur. Ainsi, dans l'exemple précédent, les méthodes index et create seront indisponibles.

URL et action

En considérant la définition REST suivante :

$action = [
  'controller' => 'PetController',
  'ignores' => ['index', 'create'],
];

$app->rest('pets', $action, ['id' => '\d+']);

URL	Méthode HTTP	Nom de la route	Description
/pets	GET	pets.index	Retourne la liste des pets
/pets	POST	pets.store	Permet d'ajouter un autre pet
/pets/:id	GET	pets.show	Afficher un seul pet
/pets/:id	PUT/PATCH	pets.update	Permet de mettre à jour les informations d'un pet
/pets/:id	DELETE	pets.delete	Ceci va supprimer un pet
/pets/create	GET	pets.create	Permet d'afficher le formulaire d'ajout

Il manque quelque chose ?

Si vous rencontrez des problèmes avec la documentation ou si vous avez des suggestions pour améliorer la documentation ou le projet en général, veuillez déposer une issue pour nous, ou envoyer un tweet mentionnant le compte Twitter @bowframework ou sur directement sur le github.