Documentation officielle du framework PHP Symfony 3

Dans les applications Symfony, toutes les erreurs sont traitées comme des exceptions. Peu importe si ce sont juste des erreurs « 404 Objet non trouvé » ou une erreur fatale déclenchée par une exception dans votre code.

Dans l'environnement de programmation, Symfony détecte toutes les erreurs et affiche une page d'exception spéciale avec plusieurs informations de débogage pour vous aider à retrouver rapidement le problème racine.

Et comme ces pages contiennent plusieurs informations internes sensibles, Symfony ne les affiche pas dans un environnement de production. En lieu et place de cela, il va afficher une simple page d'erreur générique.

Les pages d'erreur en environnement de production peuvent être personnalisées de plusieurs façons selon vos besoins :

1. Si vous voulez juste modifier le contenu et le style de vos pages d'erreur pour correspondre avec le reste de votre application, il suffit de remplacer les templates d'erreur par défautRemplacement des templates d'erreur par défaut ;
2. Si vous souhaitez également modifier la logique utilisée par Symfony pour générer des pages d'erreur, remplacer le contrôleur de gestion des exceptions par défautRemplacement du ExceptionController par défaut ;
3. Si vous avez besoin d'un contrôle total de la gestion des exceptions pour exécuter votre propre logique, utiliser l'événement kernel.exceptionProgrammer avec l'événement kernel.exception.

II-A. Présentation générale▲

app/
└─ Resources/
   └─ TwigBundle/
      └─ views/
         └─ Exception/
            ├─ error404.html.twig
            ├─ error403.html.twig
            ├─ error.html.twig      # All other HTML errors (including 500)
            ├─ error404.json.twig
            ├─ error403.json.twig
            └─ error.json.twig      # All other JSON errors (including 500)

II-B. Exemple avec le template du code d'erreur 404▲

{# app/Resources/TwigBundle/views/Exception/error404.html.twig #}
{% extends 'base.html.twig' %}

{% block body %}
    <h1>Page not found</h1>

    {% if is_granted('IS_AUTHENTICATED_FULLY') %}
        {# ... #}
    {% endif %}

    <p>
        The requested page couldn't be located. Checkout for any URL
        misspelling or <a href="{{ path('homepage') }}">return to the homepage</a>.
    </p>
{% endblock %}

II-C. Tests des pages d'erreur pendant la programmation▲

# app/config/routing_dev.yml
_errors:
    resource: "@TwigBundle/Resources/config/routing/errors.xml"
    prefix:   /_error

<!-- app/config/routing_dev.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">

    <import resource="@TwigBundle/Resources/config/routing/errors.xml"
        prefix="/_error" />
</routes>

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

$collection = new RouteCollection();
$collection->addCollection(
    $loader->import('@TwigBundle/Resources/config/routing/errors.xml')
);
$collection->addPrefix("/_error");

return $collection;

http://localhost/app_dev.php/_error/{statusCode}
http://localhost/app_dev.php/_error/{statusCode}.{format}

Si vous avez besoin d'un peu plus de flexibilité, au-delà d'un simple remplacement de template, alors vous pouvez changer le contrôleur qui retourne la page d'erreur. Par exemple, vous pourriez avoir besoin de passer certaines variables à votre template.

Pour le faire, il suffit de créer simplement un nouveau contrôleur à n'importe quel emplacement de votre application, et paramétrer l'option de configuration twig.exception_controller pour pointer dessus :

# app/config/config.yml
twig:
    exception_controller:  AppBundle:Exception:showException

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

    <twig:config>
        <twig:exception-controller>AppBundle:Exception:showException</twig:exception-controller>
    </twig:config>
</container>

// app/config/config.php
$container->loadFromExtension('twig', array(
    'exception_controller' => 'AppBundle:Exception:showException',
    // ...
));

La classe ExceptionListener utilisée par le TwigBundle comme listener de l'événement kernel.exception crée la requête qui sera envoyée à votre contrôleur. En plus, deux paramètres seront passés à votre contrôleur :

1. exception : une instance FlattenException créée par l'exception gérée ;
2. logger : une instance DebugLoggerInterface qui peut être null dans certaines circonstances.

Au lieu de créer une nouvelle exception de contrôleur à partir de zéro, vous pouvez tout simplement étendre le contrôleur par défaut ExceptionController. Dans ce cas, vous pouvez remplacer l'une ou les deux méthodes suivantes : showAction() et findTemplate(). Cette dernière permet de retrouver le template qui sera utilisé.

# app/config/services.yml
services:
    app.exception_controller:
        class: AppBundle\Controller\CustomExceptionController
        arguments: ['@twig', '%kernel.debug%']

<!-- app/config/services.xml -->
<?xml version="1.0" encoding="utf-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd"
>
    <services>
        <service id="app.exception_controller"
            class="AppBundle\Controller\CustomExceptionController"
        >
            <argument type="service" id="twig"/>
            <argument>%kernel.debug%</argument>
        </service>
    </services>
</container>

// app/config/services.php
use Symfony\Component\DependencyInjection\Reference;
use Symfony\Component\DependencyInjection\Definition;

$definition = new Definition('AppBundle\Controller\CustomExceptionController', array(
    new Reference('twig'),
    '%kernel.debug%'
));
$container->setDefinition('app.exception_controller', $definition);

Et maintenant, configurez twig.exception_controller en utilisant le contrôleur comme syntaxe des services (par exemple : app.exception_controller:showAction).

Quand une exception est détectée, la classe HttpKernel la récupère et envoie un événement kernel.exception. Cela vous donne la possibilité de convertir l'exception dans un objet « Response » de peu de manières différentes.

Travailler avec cet événement est en fait beaucoup plus puissant que ce qui a été expliqué plus haut, mais requiert une connaissance plus approfondie du fonctionnement interne de Symfony. Cela peut être utile dans un cas où votre code a besoin de lancer des exceptions spécialisées ayant une signification particulière pour votre domaine d'application.

Écrire votre propre listener d'événements pour l'événement kernel.exception vous permettra d'examiner, de plus près, l'exception et exécuter plusieurs actions en dépendant. Ces actions peuvent porter sur la journalisation de l'exception, la redirection des utilisateurs vers une autre page, ou encore le rendu de pages d'erreur spécialisées.

Cette approche vous permet de créer une couche de gestion centralisée des erreurs : au lieu de capturer (et gérer) les mêmes exceptions dans divers contrôleurs à plusieurs reprises, vous pouvez juste avoir un (ou seulement très peu) de listeners pour les traiter.

Nous remercions Guillaume Sigui pour la traduction de ce tutoriel et f-leb pour la relecture orthographique.