Documentation officielle du framework PHP Symfony 3 - Partie 5

Partie 5 : Apprendre le paramétrage des contrôleurs dans Symfony 3

Il s'agit de la traduction française de la documentation officielle du framework PHP Symfony 3. Vous allez apprendre à programmer avec ce puissant framework, de plus en plus utilisé, pour construire des applications d'envergure.

Dans cette sixième partie, vous allez apprendre à paramétrer et gérer les contrôleurs.

Si vous avez des remarques concernant ce tutoriel, un espace de dialogue vous est proposé sur le forum. N'hésitez pas à apporter vos avis sur le lien ci-dessous.

19 commentaires

Article lu fois.

Les deux auteur et traducteur

Symfony

Traducteur : Christophe LOUVET

L'article

Publié le 29 novembre 2016

Public visé : tout le monde

Version PDF Version hors-ligne

ePub, Azw et Mobi

Liens sociaux

1. Introduction▲

Un contrôleur est une fonction PHP que vous créez et qui récupère l'information depuis l'objet Request d'une requête HTTP, puis crée et retourne une réponse HTTP (un objet Response Symfony).

La réponse peut être une page HTML, un document XML un tableau JSON sérialisé, une image, une redirection, une erreur 404, ou toute autre chose que vous pouvez imaginer.

Le contrôleur exécute quelque logique arbitraire selon les besoins de votre application pour interpréter le contenu de la page.

Voyons comment simplifier ceci en regardant un contrôleur Symfony en action. Ceci interprète une page qui affiche un numéro magique (numéro choisi au hasard) :

Sélectionnez

1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.

// src/AppBundle/Controller/MagiqueControleur.php
namespace AppBundle\Controller;

use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
use Symfony\Component\HttpFoundation\Response;

class MagiqueControleur
{
    /**
     * @Route("/magique/numero")
     */
    public function numeroAction()
    {
        $numero = mt_rand(0, 100);

        return new Response(
            '<html><body>Numéro magique : '.$numero.'</body></html>'
        );
    }
}

Mais dans le vrai monde, un contrôleur sert, bien évidemment, à faire beaucoup de choses.

Le but d'un contrôleur est toujours le même : créer et retourner un objet Response. Le long de son parcours, il pourrait lire l'information depuis la requête, charger une ressource de base de données, envoyer un mail, ou placer une information sur la session utilisateur. Mais dans tous les cas, le contrôleur va éventuellement retourner l'objet Response qu'il va fournir en retour au client.

Si vous n'avez pas encore créé votre première page fonctionnelle, consulter cette partie de la documentation pour apprendre à créer des pages Web avec Symfony avant de poursuivre la lecture.

Il n'y a pas de magie et pas d'autres exigences dont il faut se soucier. Voici quelques exemples classiques de contrôleur :

Le contrôleur A prépare un objet Response représentant le contenu de la page d'accueil du site ;
le contrôleur B lit des paramètres depuis la requête pour charger une entrée du blog depuis la base de données et crée un objet Response affichant ce blog. Si les éléments indiqués dans les paramètres de l'objet Request ne peuvent être trouvés dans la base de données, il crée et retourne un objet Response avec le code de statut 404.
Le contrôleur C gère la soumission de formulaire pour celui de contact. Il lit les informations de celui-ci depuis la requête, sauve les informations de contact dans la base de données et vous envoie les informations par mail. Il crée finalement un objet Response qui redirige le navigateur client vers la page « Merci » du formulaire de contact.

2. Requêtes, contrôleur, cycle de vie des réponses▲

Chaque requête gérée par un projet Symfony passe par le même cycle de vie simple. Le Framework s'occupe de toutes les tâches répétitives : vous avez juste à écrire votre code personnalisé dans les fonctions contrôleur :

Chaque requête est gérée par un simple fichier contrôleur frontal (ex. : app.php ou app_dev.php) qui amorce l'application ;
le routeur lit les informations depuis la requête (ex. : l'URI), trouve une route qui correspond à l'information, et lit le paramètre du contrôleur depuis la route ;
le contrôleur est exécuté depuis la route correspondante et le code interne de celui-ci crée et retourne un objet Response ;
Les entêtes HTTP et le contenu de l'objet Response sont renvoyés au client.
Le contrôleur correct de la route correspondante est exécuté et le code de celui-ci crée et retourne l'objet Response approprié ;
Les entêtes HTTP et le contenu de l'objet Response sont renvoyés au client.

Créer une page est aussi simple que de créer un contrôleur, et que de faire une route qui mappe une URL à ce contrôleur.

Image non disponible

Bien que portant le même nom, un « contrôleur frontal » est différent des contrôleurs évoqués dans ce chapitre. Un contrôleur frontal est un fichier PHP court qui réside dans votre dossier Web et par lequel toutes les requêtes sont dirigées. Une application typique va avoir un contrôleur frontal de production (ex. : app.php) et un contrôleur frontal de développement (ex. : app_dev.php). Vous n'aurez heureusement jamais besoin d'éditer, voir ou vous préoccuper des contrôleurs frontaux de votre application.

3. Un contrôleur simple▲

Tandis qu'un contrôleur peut être n'importe quelle fonction PHP appelable (une fonction, méthode d'un objet, ou une Closure), un contrôleur est habituellement une méthode dans une classe contrôleur. Les contrôleurs sont aussi appelés actions.

Sélectionnez

1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.

// src/AppBundle/Controller/MagiqueControleur.php
namespace AppBundle\Controller;

use Symfony\Component\HttpFoundation\Response;
use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;

class MagiqueControleur
{
    /**
     * @Route("/magique/numero/{max}")
     */
    public function numeroAction($max)
    {
        $numero = mt_rand(0, $max);

        return new Response(
            '<html><body>Numéro Magique: '.$numero.'</body></html>'
        );
    }
}

Notez que le contrôleur est la méthode numeroAction, laquelle réside dans une classe controller : MagiqueControleur. Ne soyez pas embrouillé par le nommage : une classe controller est simplement un moyen pratique pour grouper ensemble plusieurs contrôleurs/actions. Typiquement, la classe controller va abriter plusieurs contrôleurs/actions (ex. : miseAjourAction, supprimerAction, etc.).

Ce contrôleur est assez simple :

ligne 2 : Symfony profite de la fonctionnalité d'espace de noms de PHP pour créer un espace de noms pour toute la classe controller ;
ligne 4 : Symfony profite également de la fonctionnalité d'espace de noms de PHP : le mot clé use importe la classe Response, celle que doit retourner le contrôleur ;
ligne 7 : le nom de la classe est la concaténation du nom pour la classe controller (exemple : Magique) et du mot Controller, c'est une convention qui fournit de la consistance aux contrôleurs et leur permet d'être référencés uniquement par la première partie du nom (exemple : Magique) dans la configuration de routage. Toutefois, cette nomenclature n'est pas obligatoire pour le fonctionnement de la classe ;
ligne 12 : chaque action dans une classe controller est suffixée par Action et est référencée dans la configuration de routage par son nom d'action (exemple : numero, dans la classe précédente). Cette nomenclature n'est également pas obligatoire pour le fonctionnement de la classe. Dans la prochaine section, vous allez créer une route qui mappe une URI pour cette action. Vous allez apprendre comment les spaces réservés ({name}) de route deviennent des arguments pour la méthode de l'action ($name) ;
ligne 16 : Le contrôleur crée et retourne un objet Response.

4. Mapper une URL à un contrôleur▲

Pour visualiser cette page dans votre navigateur, il faut créer une route, qui mappe un chemin d'URL spécifique au contrôleur.

Cela se fait avec l'annotation suivante :

Sélectionnez

@Route("/lucky/number/{max}")

Pour afficher la page de votre site, saisissez l'URL suivante dans votre navigateur :

Sélectionnez

http://localhost:8000/magique/numero/100

Le nouveau contrôleur retourne une simple page HTML.

Annotations

Sélectionnez

1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.

// src/AppBundle/Controller/MagiqueControleur.php
namespace AppBundle\Controller;

use Symfony\Component\HttpFoundation\Response;
use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;

class MagiqueControleur
{
    /**
     * @Route("/magique/{numero}", numero="magique")
     */
    public function numeroAction($numero)
    {
        return new Response('<html><body>Magique '.$numero.'!</body></html>');
    }
}

Script YAML

Sélectionnez

1.
2.
3.
4.
5.

# app/config/routing.yml
numero:
    path:      /magique/{numero}
    # uses a special syntax to point to the controller - see note below
    defaults:  { _controller: AppBundle:Magique:Numero}

XML :

Sélectionnez

1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.

<!-- app/config/routing.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<routes xmlns="http://symfony.com/schema/routing"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://symfony.com/schema/routing
        http://symfony.com/schema/routing/routing-1.0.xsd">

    <route id="hello" path="/magique/{numero}">
        <!-- uses a special syntax to point to the controller - see note below -->
        <default key="_controller">AppBundle:Magique:Numero</default>
    </route>
</routes>

Script PHP

Sélectionnez

1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.

// app/config/routing.php
use Symfony\Component\Routing\Route;
use Symfony\Component\Routing\RouteCollection;

$collection = new RouteCollection();
$collection->add('Magique', new Route('/Magique/{numero}', array(
    // utilise une syntaxe spéciale pour pointer sur le contrôleur - voir note plus bas
    '_controller' => 'AppBundle:Magique:Numero',
)));

return $collection;

Maintenant, vous pouvez aller à la page /magique/70 (ex. : http://localhost:8000/magique/70 si vous utilisez le serveur Web interne) et Symfony va exécuter le contrôleur MagiqueControleur::numeroAction() puis passer 70 à la variable $numero. Créer une « page » signifie simplement créer une méthode controller et lui associer une route.

Simple non ?

La syntaxe contrôleur : AppBundle:Magique:Numero.

Si vous utilisez les formats XML ou YML, vous vous référrerez au contrôleur en utilisant une syntaxe de raccourci spéciale : AppBundle:Magique:Numero.

Vous pouvez en apprendre plus sur le système de routage dans le chapitre suivant sur le routage.

4-1. Paramètres de route comme arguments de contrôleur▲

Vous savez déjà que la route pointe vers la méthode MagiqueControleur::numeroAction() qui réside dans l'AppBundle. C'est plus intéressant si l'argument passé l'est à cette méthode :

Sélectionnez

1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.

// src/AppBundle/Controller/MagiqueControleur.php
// ...
use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;

/**
 * @Route("/magique/{numero}", numero="magique")
 */
public function numeroAction($numero)
{
    // ...
}

Le contrôleur a un seul argument, $numero, lequel correspond au paramètre {numero} de la route (70 si vous vous rendez à l'adresse magique/70). Quand vous exécutez votre contrôleur, Symfony compare chaque argument avec un paramètre de la route. La valeur de {numero} est donc passée à $numero.

Voici un exemple plus intéressant avec deux arguments : le prénom et le nom.

Annotations :

Sélectionnez

1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.

// src/AppBundle/Controller/BonjourController.php
// ...

use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;

class BonjourController
{
    /**
     * @Route("/bonjour/{prenom}/{nom}", nom="bonjour")
     */
    public function indexAction($prenom, $nom)
    {
        // ...
    }
}

YAML :

Sélectionnez

1.
2.
3.
4.

# app/config/routing.yml
hello:
    path:      /bonjour/{prenom}/{nom}
    defaults:  { _controller: AppBundle:Bonjour:index }

XML :

Sélectionnez

1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.

<!-- app/config/routing.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<routes xmlns="http://symfony.com/schema/routing"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://symfony.com/schema/routing
        http://symfony.com/schema/routing/routing-1.0.xsd">

    <route id="hello" path="/bonjour/{prenom}/{nom}">
        <default key="_controller">AppBundle:Bonjour:index</default>
    </route>
</routes>

PHP :

Sélectionnez

1.
2.
3.
4.
5.
6.
7.
8.
9.
10.

// app/config/routing.php
use Symfony\Component\Routing\Route;
use Symfony\Component\Routing\RouteCollection;

$collection = new RouteCollection();
$collection->add('hello', new Route('/bonjour/{prenom}/{nom}', array(
    '_controller' => 'AppBundle:Bonjour:index',
)));

return $collection;

Le contrôleur peut maintenant avoir deux arguments :

Sélectionnez

1.
2.
3.
4.

public function indexAction($prenom, $nom)
{
    // ...
}

Mapper les paramètres de route aux arguments du contrôleur est simple et flexible. Gardez à l'esprit les lignes directrices suivantes quand vous programmez :

L'ordre des arguments du contrôleur n'a pas d'importance.
Symfony fait correspondre les noms de paramètres de la route vers les noms de variables du contrôleur. Les arguments du contrôleur pourraient être totalement réorganisés et cela va toujours fonctionner :

Sélectionnez

1.
2.
3.
4.

public function indexAction($nom, $prenom)
{
    // ...
}

Chaque argument de contrôleur requis doit correspondre avec un paramètre de routage.
Le code suivant lèverait une RuntimeException, car il n'y a pas de paramètre foo défini dans la route :
Sélectionnez
```
public function indexAction($prenom, $nom, $foo)
{
    // ...
}
```
Par contre, rendre l'argument optionnel est parfaitement faisable. L'exemple suivant ne lèvera pas d'exception :
Sélectionnez
1.
2.
3.
4.
```
public function indexAction($prenom, $nom, $foo = 'bar')
{
    // ...
}
```
Tous les paramètres de routage n'ont pas besoin d'arguments dans votre contrôleur.
Si, par exemple, la variable nom n'est pas importante pour votre contrôleur, vous pourriez l'omettre entièrement :

Sélectionnez

1.
2.
3.
4.

public function indexAction($prenom)
{
    // ...
}

Chaque route a également un paramètre spécial _route, qui est égal au nom de la route qui correspond (ex. : Bonjour). Bien que généralement inutile, ceci est aussi disponible comme un argument de contrôleur. Vous pouvez aussi passer les autres variables depuis votre route vers vos arguments de contrôleur. Consultez Comment passer des informations supplémentaires d'une route vers un contrôleur.

Vous aurez plus d'informations sur le routage dans le prochain chapitre dédié au routage.

5. La classe de base de contrôleur et les services▲

Pour plus de commodités, Symfony est fourni avec une classe optionnelle de base Controller. Si vous l'étendez, cela ne changera rien au fonctionnement de votre contrôleur, mais vous aurez accès à un nombre de méthodes auxiliaires, et à tous les objets de votre service via le container (voir Accéder à d'autres services)Accéder à d'autres services : un objet de type tableau qui vous donne accès à tous les objets utiles du système. Ces objets nécessaires sont appelés services, et par exemple, Symfony est fourni avec un objet service qui peut retourner des templates Twig, un autre qui peut produire des logs, et d'autres qui peuvent faire bien plus.

Ajoutez la déclaration use devant la classe Controller puis modifiez le MagiqueControleur pour l'étendre :

Sélectionnez

// src/AppBundle/Controller/MagiqueControleur.php
namespace AppBundle\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\Controller;

class MagiqueControleur extends Controller
{
    // ...
}

Les méthodes auxiliaires sont juste des raccourcis pour utiliser les fonctionnalités du noyau de Symfony qui vous sont rendues disponibles avec ou sans l'utilisation de la classe Controller de base. Un excellent moyen de voir les fonctions noyau en action est de jeter un œil sur la classe Controller.

Si vous êtes curieux du fonctionnement normal d'un contrôleur n'étendant pas sa classe de base, consultez Controllers as Services. Ceci est optionnel, mais peut vous donner plus de contrôle sur les objets/dépendances injectés dans votre contrôleur.

5-1. Génération d'URL▲

La méthode generateUrl() est une méthode auxiliaire qui permet de générer une URL à la route fournie. Par exemple :

Sélectionnez

$url = $this->generateUrl('affichage_blog', array('slug' => 'slug-value'));

5-2. Redirection▲

Si vous voulez rediriger un utilisateur vers une autre page, utilisez les méthodes redirectToRoute() et redirect() :

Sélectionnez

1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.

public function indexAction()
{
    // redirect to the "homepage" route
    return $this->redirectToRoute('homepage');

    // do a permanent - 301 redirect
    return $this->redirectToRoute('homepage', array(), 301);

    // redirect to a route with parameters
    return $this->redirectToRoute('blog_show', array('slug' => 'my-page'));

    // redirect externally
    return $this->redirect('http://symfony.com/doc');
}

Le chapitre suivant sur le routage donnera plus d'informations.

La méthode redirectToRoute() est simplement un raccourci pour créer un objet Response, qui se spécialise dans la redirection de l'utilisateur. C'est équivalent à :

Sélectionnez

1.
2.
3.
4.
5.
6.

use Symfony\Component\HttpFoundation\RedirectResponse;

public function indexAction()
{
    return new RedirectResponse($this->generateUrl('homepage'));
}

La méthode redirectToRoute() a été introduite depuis Symfony 2.6. Auparavant (et encore aujourd'hui), vous pouvez utiliser redirect() et generateUrl() ensemble pour cela.

Ou, si vous voulez rediriger de façon externe, utilisez juste redirect() et passez l'URL :

Sélectionnez

1.
2.
3.
4.

public function indexAction()
{
    return $this->redirect('http://symfony.com/doc');
}

Par défaut, la méthode redirectToRoute() effectue une redirection 302 (temporaire). Pour effectuer une redirection 301 (permanente), modifiez le troisième argument :

Sélectionnez

1.
2.
3.
4.

public function indexAction()
{
 return $this->redirectToRoute('homepage', array(), 301);
}

5-3. Le rendu de templates▲

Si vous fournissez du HTML, vous voudrez interpréter un template. La méthode render() interprète un template et met son contenu dans un objet pour vous :

Sélectionnez

1.
2.

// renders app/Resources/views/magique/numero.html.twig
return $this->render('magique/numero.html.twig', array('numero' => $numero));

Les templates peuvent également se retrouver dans des sous-dossiers en profondeur, dans une arborescence. Essayez juste d'éviter de créer des structures profondes inutilement :

Sélectionnez

1.
2.
3.
4.

// renders app/Resources/views/hello/greetings/index.html.twig
return $this->render('hello/greetings/index.html.twig', array(
    'name' => $name
));

Le moteur de templating de Symfony est expliqué en détail dans le chapitre sur les templates

Référencer des templates résidant dans le Bundle :

Vous pouvez aussi mettre des templates dans le dossier Resources/views d'un bundle et les référencer avec une syntaxe NomBundle:NomDossier:NomFichier. Par exemple, AppBundle:Hello:index.html.twig devrait se référer à un template situé dans le fichier src/AppBundle/Resources/views/Hello/index.html.twig.

5-4. Accéder à d'autres services▲

Symfony est packagé avec beaucoup d'objets utiles, appelés services. Ceux-ci sont utilisés pour interpréter les templates, envoyer des mails, effectuer des requêtes dans des bases de données et d'autres « travaux » auxquels vous pourriez penser. Quand vous installez un nouveau Bundle, il apporte probablement encore plus de services.

Quand vous étendez la classe contrôleur de base, vous pouvez accéder à beaucoup de services via la méthode get(). Voici plusieurs services usuels dont vous pourriez avoir besoin :

Sélectionnez

1.
2.
3.
4.
5.

$templating = $this->get('templating');

$router = $this->get('router');

$mailer = $this->get('mailer');

Quels autres services existent ? Pour lister tous les services, utilisez la commande console debug:container :

Sélectionnez

php bin/console debug:container

Sur les versions antérieures à Symfony 2.6, cette commande est nommée container:debug.

Vous aurez plus d'informations, sur le chapitre conteneur de services.

Pour obtenir un paramètre de la configuration du container, utilisez la méthode getParameter().

Sélectionnez

$from = $this->getParameter('app.mailer.from');

6. Gérer les erreurs et les pages 404▲

Quand les objets ne sont pas trouvés, vous devriez en conformité avec le protocole HTTP retourner une réponse 404. Pour cela, vous lèverez un type spécial d'exception. Si vous étendez la classe de contrôleur de base, faites ceci :

Sélectionnez

1.
2.
3.
4.
5.
6.
7.
8.
9.
10.

public function indexAction()
{
    // récupère un objet de la base de données
    $product = ...;
    if (!$product) {
        throw $this->createNotFoundException("Le produit n'existe pas");
    }

    return $this->render(...);
}

La méthode createNotFoundException() est juste un raccourci pour créer un objet spécial NotFoundHttpException, lequel au bout du compte intercepte les réponses HTTP 404 dans Symfony.

Bien sûr, vous pouvez lever toute classe d'exception dans votre contrôleur. Symfony va automatiquement retourner un code de réponse HTTP 500.

Sélectionnez

throw new \Exception("Quelque chose s'est mal passé !");

Dans tous les cas, une page d'erreur est affichée à l'utilisateur final et une page complète de débogage est présentée au développeur (ex. : quand vous utilisez app_dev.php, voir le chapitre sur l'installation de Symfony 3).

Vous allez vouloir personnaliser la page d'erreurs vue par les utilisateurs. Pour faire ceci, consultez : comment personnaliser les pages d'erreur.

7. L'objet « Request » comme un argument du contrôleur▲

Qu'adviendra-t-il si vous voulez lire les paramètres de la requête, saisir un entête de requête ou obtenir l'accès à un fichier uploadé ? Toutes ces informations sont stockées dans l'objet « Request » de Symfony. Pour les obtenir dans votre contrôleur, il suffit de l'ajouter comme un argument et les fournir en entrée dans la classe « Request » :

Sélectionnez

1.
2.
3.
4.
5.
6.
7.
8.

use Symfony\Component\HttpFoundation\Request;

public function indexAction(Request $request, $prenom, $nom)
{
    $page = $request->query->get('page', 1);

    // ...
}

Vous aurez plus de détails sur l'objet « Request »L'objet Request dans la suite du tutoriel.

8. Gérer la session▲

8-1. Présentation générale de la gestion de session dans une application Symfony▲

Symfony fournit un super objet de session que vous pouvez utiliser pour stocker des informations à propos de l'utilisateur (que ce soit une vraie personne, un navigateur, un robot, ou un service Web) entre les requêtes. Par défaut, Symfony stocke les attributs dans un cookie en utilisant les sessions PHP natives.

Pour récupérer les données de la session, utiliser la méthode getSession() sur l'objet « Request ». Cette méthode retourne une SessionInterface avec des méthodes simples pour stocker et récupérer les informations depuis les objets de la session.

Stocker et récupérer des informations depuis la session peut être facilement fait depuis n'importe quel contrôleur :

Sélectionnez

1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.

use Symfony\Component\HttpFoundation\Request;

public function indexAction(Request $request)
{
    $session = $request->getSession();

    // stocke un attribut pour la réutilisation durant une prochaine requête utilisateur
    $session->set('foo', 'bar');

    // récupère un attribut fixé par un autre contrôleur dans une autre requête
    $foobar = $session->get('foobar');

    // utilise une valeur par défaut si l'attribut n'existe pas
    $filters = $session->get('filters', array());
}

Les attributs stockés resteront disponibles dans cette session utilisateur.

8-2. Messages Flash▲

Vous pouvez aussi stocker des messages spéciaux, nommés messages « flash », dans la session de l'utilisateur. Intentionnellement, les messages flash sont conçus pour un usage unique : ils disparaissent automatiquement de la session dès que vous les récupérez. Cette fonctionnalité fait que les messages « flash » sont particulièrement idéals pour stocker les notifications utilisateur.

Par exemple, imaginez que vous êtes en train de traiter la soumission d'un formulaire :

Sélectionnez

1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.

use Symfony\Component\HttpFoundation\Request;

public function updateAction(Request $request)
{
    //...
    $form = $this->createForm(...);
    $form->handleRequest($request);

    if ($form->isValid()) {
        // fait une sorte de prétraitement

        $this->addFlash(
            'notice',
            'Vos modifications ont été enregistrées !'
        );

        // $this->addFlash est équivalent à $this->get('session')->getFlashBag()->add

        return $this->redirectToRoute(...);
    }

    return $this->render(...);
}

Après traitement de la requête, le contrôleur affiche un message flash dans la session, puis effectue la redirection. Le message clé (« notice » dans cet exemple) peut être n'importe quoi : vous utiliserez cette clé pour récupérer le message.

Dans certains templates (comme vous le verrez dans la partie relative aux templates), il peut être nécessaire de lire tout message flash de la session. Par exemple :

Twig :

Sélectionnez

1.
2.
3.
4.
5.
6.

{# app/Resources/views/base.html.twig #}
{% pour un message flash_dans app.session.flashbag.get('notice') %}
    <div class="flash-notice">
        {{ flash_message }}
    </div>
{% endfor %}

PHP :

Sélectionnez

1.
2.
3.
4.
5.

<?php foreach ($view['session']->getFlash('notice') as $message): ?>
    <div class="flash-notice">
        <?php echo "<div class='flash-error'>$message</div>" ?>
    </div>
<?php endforeach ?>

Il est commun d'utiliser notice, warning et error comme mots clés des différents types de messages flash, mais vous pouvez utiliser d'autres mots clés comme vous le souhaitez.

Vous pouvez aussi utiliser la méthode peek() pour récupérer le message tout en la gardant dans le sac.

9. Les objets Request et Response▲

9-1. L'objet Response▲

La seule contrainte pour un contrôleur est de retourner un objet Response. Tout comme l'objet « Request », l'objet « Response » a aussi des propriétés d'entêtes publiques.

La classe Response est une abstraction autour d'une réponse HTTP : les entêtes et le contenu sont renseignés avec des messages textes qui sont renvoyés au client :

Sélectionnez

1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.

use Symfony\Component\HttpFoundation\Response;

// crée une simple réponse avec le code status 200 (code par défaut)
$response = new Response('Bonjour '.$nom, Response::HTTP_OK);


// crée une réponse CSS avec le code status 200
$response = new Response('<style> ... </style>');
$response->headers->set('Content-Type', 'text/css')

// crée une réponse JSON avec le code status 200
$response = new Response(json_encode(array('name' => $name)));
$response->headers->set('Content-Type', 'application/json');

La propriété headers de l'objet ResponseHeaderBag a des méthodes sympathiques pour obtenir et fixer les entêtes. Les noms de ces entêtes sont normalisés, et donc utiliser, par exemple, Content-Type est équivalent à content-type ou encore à content_type.

Il y a aussi des classes spéciales pour effectuer certains types de réponses plus facilement :

Pour JSON il y a JsonResponse ;
Pour les fichiers, il y a BinaryFileResponse ;
Pour les réponses en flux, il y a StreamedResponse.

Ne vous inquiétez pas, il y a beaucoup d'informations à propos des objets Response dans la documentation des composants, consultez Response.

9-2. L'objet Request▲

Comme mentionné plus hautL'objet « Request » comme un argument du contrôleur, le framework Symfony peut passer l'objet « Request » comme un argument de contrôleur, qui sera saisi en entrée de la classe « Request ».

La classe « Request » a certaines propriétés publiques et des méthodes qui peuvent vous aider à retourner n'importe quelle information relative à votre requête.

Outre les valeurs de routage des places réservées, le contrôleur a aussi accès à l'objet Request. Le Framework injecte l'objet Request dans le contrôleur si une variable est préfixée Request :

Sélectionnez

1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.

use Symfony\Component\HttpFoundation\Request;

public function indexAction(Request $request)
{
    $request->isXmlHttpRequest(); // Est ce une requête Ajax ?

    $request->getPreferredLanguage(array('en', 'fr'));


    $request->query->get('page'); // récupère un paramètre $_GET

    $request->request->get('page'); // récupère un paramètre $_POST


    // Récupérer les variables SERVER
    $request->server->get('HTTP_HOST');


    // Récupérer une instance de l'objet UploadedFile identifié par foo
    $request->files->get('foo');


    // Récupérer une valeur de COOKIE
    $request->cookies->get('PHPSESSID');


    // Récupérer un entête de requête HTTP avec de petites clés normalisées
    $request->headers->get('host');
    $request->headers->get('content_type');
}

Comme l'objet Response, la requête headers est stockée dans un objet HeaderBag et est facilement accessible.

Ne vous inquiétez pas, il y a beaucoup d'information à propos des objets Request dans la documentation composants. Consultez Request.

9-3. La méthode auxiliaire JSON▲

La méthode auxiliaire json() a été introduite depuis Symfony 3.1.

Pour retourner un contenu JSON depuis le contrôleur, il faut utiliser la méthode auxiliaire json() dans le contrôleur de base. Cela retourne un spécial objet JsonResponse qui encode les données automatiquement :

Sélectionnez

1.
2.
3.
4.
5.
6.
7.
8.
9.

// ...
public function indexAction()
{
    // returns '{"username":"jane.doe"}' and sets the proper Content-Type header
    return $this->json(array('username' => 'jane.doe'));

    // the shortcut defines three optional arguments
    // return $this->json($data, $status = 200, $headers = array(), $context = array());
}

Si le service de sérialisation est activé dans votre application, le contenu qui sera retourné de la méthode json() sera encodé par elle. Sinon la fonction json-encode sera utilisée.

Notez qu'il ne s'agit ici que des éléments de base sur les objets Request et Response. Vous aurez plus d'informations sur ces objets à la page relative au composant HttpFoundation.

10. Créer des pages statiques▲

Vous pouvez créer une page statique sans même créer de contrôleur (seulement une route et un template sont requis).

Pour cela, consultez la page comment retourner un template sans contrôleur.

11. Forwarder à un autre contrôleur▲

Bien que pas très commun, vous pouvez aussi forwarder vers un autre contrôleur en interne avec la méthode forward(). Plutôt que de rediriger le navigateur utilisateur, il effectue une sous-requête interne, et appelle le contrôleur. La méthode forward() retourne un objet Response qui est retourné depuis ce contrôleur :

Sélectionnez

public function indexAction($nom)
{
    $response = $this->forward('AppBundle:Something:fancy', array(
        'nom'  => $nom,
        'couleur' => 'vert',
    ));

    // ... modifie la réponse ou la retourne directement

    return $response;
}

Notez que la méthode forward() utilise une chaîne spéciale de représentation du contrôleur (consultez Modèle de nommage de contrôleur). Dans ce cas, la fonction cible du contrôleur sera SomethingController::fancyAction() dans l'AppBundle. Le tableau passé à la méthode devient les arguments du contrôleur résultant. Cette même idée est utilisée lors de l'intégration de contrôleurs dans les templates (voir Contrôleurs embarqués).La méthode du contrôleur cible devrait ressembler à quelque chose comme cela :

Sélectionnez

1.
2.
3.
4.

public function fancyAction($nom, $couleur)
{
    // ... créé et retourne un objet Response
}

Comme lors de la création d'un contrôleur pour une route, l'ordre des arguments de fancyAction n'a pas d'importance. Symfony fait correspondre les noms de clés d'index (ex. : nom) avec les noms d'arguments de la méthode (ex. : $nom). Si vous changez l'ordre des arguments, Symfony passera toujours les valeurs correctes à chaque variable.

12. Valider un jeton CSRF▲

Quelquefois, vous voulez utiliser la protection CSRF dans une action ou vous ne voulez pas utiliser le composant formulaire de Symfony. Si, par exemple, vous faites une action DELETE, vous pouvez utiliser la méthode isCsrfTokenValid() pour contrôler le jeton CSRF :

Sélectionnez

1.
2.
3.

if ($this->isCsrfTokenValid('token_id', $submittedToken)) {
    // ... fait quelque chose, comme détruire un objet
}

La méthode raccourcie isCsrfTokenValid() a été introduite dans Symfony 2.6. Elle est équivalente à exécuter le code suivant :

Sélectionnez

1.
2.
3.
4.

use Symfony\Component\Security\Csrf\CsrfToken;

$this->get('security.csrf.token_manager')
    ->isTokenValid(new CsrfToken('token_id', 'TOKEN'));

13. Pensées finales▲

Chaque fois que vous créez une page, vous allez au bout du compte écrire du code qui contient la logique de cette page. Dans Symfony, ceci est appelé un contrôleur, et c'est une fonction PHP ou vous pouvez faire ce qu'il faut pour retourner l'objet de réponse final qui sera retourné à l'utilisateur.

Pour vous faciliter la vie, vous pouvez choisir d'étendre une classe contrôleur de base, laquelle contient des méthodes raccourcies pour beaucoup de tâches contrôleur classiques. Par exemple, si vous ne voulez pas mettre de code HTML dans votre contrôleur, vous pouvez utiliser la méthode render() pour interpréter et retourner le contenu depuis un template. En effet, vous bénéficiez de deux avantages principaux à étendre la classe du contrôleur de base :

les méthodes raccourcies (comme render() et redirectToRoute) ;
l'accès à tous les objets utiles (services) dans votre système grâce à la méthode get()Accéder à d'autres services.

Dans les autres chapitres, vous verrez comment les contrôleurs peuvent être utilisés pour gérer des objets depuis une base de données, procéder à la soumission de formulaires, gérer le cache, et plus.

Notes de la rédaction Developpez.com▲

Nous tenons à remercier Sensiolabs pour la mise à disposition de cette documentation, Christophe Louvet pour la traduction et f-leb pour la relecture orthographique.

Vous avez aimé ce tutoriel ? Alors partagez-le en cliquant sur les boutons suivants :

En complément sur Developpez.com