Controllers (Contrôleurs)¶

Le Controller App¶

Comme indiqué dans l’introduction, la classe AppController est la classe mère de tous les controllers de votre application. AppController étend elle-même la classe Cake\Controller\Controller incluse dans la librairie du cœur de CakePHP. AppController est définie dans src/Controller/AppController.php comme ceci:

namespace App\Controller;

use Cake\Controller\Controller;

class AppController extends Controller
{
}

Les attributs et méthodes de controller créés dans AppController seront disponibles dans tous les controllers de votre application. Les Components (que vous découvrirez plus loin) sont plus appropriés pour du code utilisé dans la plupart des controllers (mais pas nécessairement tous).

Vous pouvez utiliser AppController pour charger les components qui seront utilisés dans tous les controllers de votre application. CakePHP fournit une méthode initialize() qui est appelée à la fin du constructeur du Controller pour ce type d’utilisation:

namespace App\Controller;

use Cake\Controller\Controller;

class AppController extends Controller
{

    public function initialize()
    {
        // Active toujours le component CSRF.
        $this->loadComponent('Csrf');
    }

}

En plus de la méthode initialize(), l’ancienne propriété $components vous permettra aussi de déclarer les components qui doivent être chargés. Bien que les règles d’héritage en orienté objet s’appliquent, les components et les helpers utilisés par un controller sont traités spécialement. Dans ces cas, les valeurs de la propriété de AppController sont fusionnées avec les tableaux de la classe de controller enfant. Les valeurs dans la classe enfant seront toujours surchargées par celles de AppController.

Déroulement d’une Requête¶

Quand une requête est faîte dans une application CakePHP, les classes Cake\Routing\Router et Cake\Routing\Dispatcher de CakePHP utilisent la fonctionnalité Connecter les Routes pour trouver et créer le bon controller. La requête de données est encapsulée dans un objet request. CakePHP met toutes les informations importantes de la requête dans la propriété $this->request. Consultez la section ServerRequest pour plus d’informations sur l’objet request de CakePHP.

Les Actions du Controller¶

Les actions du Controller sont responsables de la conversion des paramètres de la requête dans une réponse pour le navigateur/utilisateur faisant la requête. CakePHP utilise des conventions pour automatiser le processus et retirer quelques codes boiler-plate que vous auriez besoin d’écrire autrement.

Par convention, CakePHP rend une vue avec une version inflectée du nom de l’action. Revenons à notre boulangerie en ligne par exemple, notre RecipesController pourrait contenir les actions view(), share(), et search(). Le controller serait trouvé dans src/Controller/RecipesController.php et contiendrait:

// src/Controller/RecipesController.php

class RecipesController extends AppController
{
    public function view($id)
    {
        //la logique de l'action va ici.
    }

    public function share($customerId, $recipeId)
    {
        //la logique de l'action va ici.
    }

    public function search($query)
    {
        //la logique de l'action va ici.
    }
}

Les fichiers de template pour ces actions seraient src/Template/Recipes/view.ctp, src/Template/Recipes/share.ctp, et src/Template/Recipes/search.ctp. Le nom du fichier de vue est par convention le nom de l’action en minuscules et avec des underscores.

Les actions du Controller utilisent généralement Controller::set() pour créer un contexte que View utilise pour afficher la couche de vue. Du fait des conventions que CakePHP utilise, vous n’avez pas à créer et rendre la vue manuellement. Au lieu de ça, une fois qu’une action du controller est terminée, CakePHP va gérer le rendu et la livraison de la Vue.

Si pour certaines raisons, vous voulez éviter le comportement par défaut, vous pouvez retourner un objet de Cake\Http\Response de l’action avec la response complètement créée.

Afin que vous utilisiez efficacement le controller dans votre propre application, nous couvrons certains des attributs et méthodes du cœur fournis par les controllers de CakePHP.

Interactions avec les Vues¶

Les Controllers interagissent avec les vues de plusieurs façons. Premièrement, ils sont capables de passer des données aux vues, en utilisant Controller::set(). Vous pouvez aussi décider quelle classe de vue utiliser, et quel fichier de vue doit être rendu à partir du controller.

// Dans un premier temps vous passez les données depuis le controller:

$this->set('couleur', 'rose');

// Ensuite vous pouvez les utiliser dans la vue de cette manière:
?>

Vous avez sélectionné un glaçage <?= $couleur; ?> pour le gâteau.

$data = [
    'couleur' => 'rose',
    'type' => 'sucre',
    'prix_de_base' => 23.95
];

// donne $couleur, $type, et $prix_de_base
// disponible dans la vue:

$this->set($data);

$this->viewBuilder()
    ->helpers(['MyCustom'])
    ->theme('Modern')
    ->className('Modern.Admin');

namespace App\Controller;

class RecipesController extends AppController
{
// ...
    public function search()
    {
        // Render the view in src/Template/Recipes/search.ctp
        $this->render();
    }
// ...
}

// Rend un élément dans src/Template/Element/ajaxreturn.ctp
$this->render('/Element/ajaxreturn');

namespace App\Controller;

class PostsController extends AppController
{
    public function my_action()
    {
        $this->render('custom_file');
    }
}

namespace App\Controller;

class PostsController extends AppController
{
    public function my_action()
    {
        $this->render('Users.UserDetails/custom_file');
    }
}

Rediriger vers d’Autres Pages¶

Cake\Controller\Controller::redirect(string|array $url, integer $status)¶

La méthode de contrôle de flux que vous utiliserez le plus souvent est Controller::redirect(). Cette méthode prend son premier paramètre sous la forme d’une URL relative à votre application CakePHP. Quand un utilisateur a réalisé un paiement avec succès, vous aimeriez le rediriger vers un écran affichant le reçu:

public function place_order()
{
    // Logique pour finaliser la commande
    if ($success) {
        return $this->redirect(
            ['controller' => 'Orders', 'action' => 'thanks']
        );
    }
    return $this->redirect(
        ['controller' => 'Orders', 'action' => 'confirm']
    );
}

La méthode va retourner l’instance de réponse avec les bons headers définis. Vous devrez retourner l’instance de réponse à partir de votre action pour éviter les rendus de view et laisser le dispatcher gérer la bonne redirection.

Vous pouvez aussi utiliser une URL relative ou absolue avec $url:

return $this->redirect('/orders/thanks');
return $this->redirect('http://www.example.com');

Vous pouvez aussi passer des données à l’action:

return $this->redirect(['action' => 'edit', $id]);

Le second paramètre de la fonction Controller::redirect() vous permet de définir un code de statut HTTP accompagnant la redirection. Vous aurez peut-être besoin d’utiliser le code 301 (document déplacé de façon permanente) ou 303 (voir ailleurs), en fonction de la nature de la redirection.

Si vous avez besoin de rediriger à la page appelante, vous pouvez utiliser:

return $this->redirect($this->referer());

Un exemple d’utilisation des requêtes en chaînes et hashés ressemblerait à ceci:

return $this->redirect([
    'controller' => 'Orders',
    'action' => 'confirm',
    '?' => [
        'product' => 'pizza',
        'quantity' => 5
    ],
    '#' => 'top'
]);

L’URL générée serait:

http://www.example.com/orders/confirm?product=pizza&quantity=5#top

// Depuis l'action delete, vous pouvez rendre
// la liste mise à jour.
$this->setAction('index');

Chargement des Models Supplémentaires¶

Cake\Controller\Controller::loadModel(string $modelClass, string $type)¶

La fonction loadModel() devient pratique quand vous avez besoin d’utiliser une table de model/collection qui n’est pas le model du controller par défaut ou un de ses models associés:

// Dans une méthode de controller.
$this->loadModel('Articles');
$recentArticles = $this->Articles->find('all', [
    'limit' => 5,
    'order' => 'Articles.created DESC'
]);

Si vous utilisez un provider de table différent de l’ORM intégré, vous pouvez lier ce système de table dans les controllers de CakePHP en connectant sa méthode factory:

// Dans une méthode de controller.
$this->modelFactory(
    'ElasticIndex',
    ['ElasticIndexes', 'factory']
);

Après avoir enregistré la table factory, vous pouvez utiliser loadModel() pour charger les instances:

// Dans une méthode de controller.
$this->loadModel('Locations', 'ElasticIndex');

Paginer un Model¶

Cake\Controller\Controller::paginate()¶

Cette méthode est utilisée pour paginer les résultats retournés par vos models. Vous pouvez définir les tailles de la page, les conditions à utiliser pour la recherche de ces données et bien plus encore. Consultez la section pagination pour plus de détails sur l’utilisation de la pagination.

L’attribut paginate vous donne une façon facile de personnaliser la façon dont paginate() se comporte:

class ArticlesController extends AppController
{
    public $paginate = [
        'Articles' => [
            'conditions' => ['published' => 1]
        ]
    ];
}

Configurer les Components à Charger¶

Cake\Controller\Controller::loadComponent($name, $config = [])¶

Dans la méthode initialize() de votre Controller, vous pouvez définir tout component que vous voulez charger et toute donnée de configuration pour eux:

public function initialize()
{
    parent::initialize();
    $this->loadComponent('Csrf');
    $this->loadComponent('Comments', Configure::read('Comments'));
}

property Cake\Controller\Controller::$components¶

La propriété $components de vos controllers vous permet de configurer les components. Les components configurés et leurs dépendances vont être créés par CakePHP pour vous. Lisez la section Configuration des Components pour plus d’informations. Comme mentionné plus tôt, la propriété $components sera fusionnée avec la propriété définie dans chacune des classes parentes de votre controller.

Configurer les Helpers à Charger¶

property Cake\Controller\Controller::$helpers¶

Voyons comment dire à un controller de CakePHP que vous avez prévu d’utiliser les classes MVC supplémentaires:

class RecipesController extends AppController
{
    public $helpers = ['Form'];
}

Chacune de ces variables sont fusionnées avec leurs valeurs héritées, ainsi il n’est pas nécessaire (par exemple) de redéclarer FormHelper, ou bien tout ce qui est déclaré dans votre AppController.

Cycle de Vie des Callbacks de la Requête¶

Les controllers de CakePHP lancent plusieurs events/callbacks (méthodes de rappel) que vous pouvez utiliser pour insérer de la logique durant tout le cycle de vie de la requête:

//use Cake\Event\Event;
public function beforeFilter(Event $event)
{
    parent::beforeFilter($event);
}

Plus sur les Controllers¶