Перевизначення шаблонів помилок за замовчуванням

Ви можете використовувати вбудований засіб відображення помилок Twig, щоб перевизначати шаблони помилок за замовчуванням. Для цього мають бути встановлені як TwigBundle, так і TwigBridge. Виконайте цю команду, щоб переконатися, що вони встановлені:

1

$ composer require symfony/twig-pack

Коли завантажується сторінка помилки, для відображення шаблону twig та демонастрації користувачу використовується TwigErrorRenderer.

Цей відображувач використовує статус-код HTTP, формат запиту та наступну логіку, щоб визначити ім'я файлу шаблону:

1. Шукає шаблон для заданого статус-кода (на кшталт error500.html.twig);
2. Якщо попередній шаблон не існує, відкидає статус-код та шукає загальний шаблон помилок (error.html.twig).

Щоб перевизначити ці шаблони, просто покладіться на стандартний метод Symfony для перевизначення шаблонів, що живуть всередині пакету: розмістить їх в каталозі templates/bundles/TwigBundle/Exception/.

Типовий проект, який повертає сторінки HTML та JSON, може виглядати так:

1
2
3
4
5
6
7

templates/
└─ bundles/
   └─ TwigBundle/
      └─ Exception/
         ├─ error404.html.twig
         ├─ error403.html.twig
         └─ error.html.twig      # Всі інші JSON помилки (включно з 500)

Приклад шаблону помилки 404

Щоб перевизначити шаблон помилки 404 для HTML-сторінки, створіть новий шаблон error404.html.twig, який знаходиться в templates/bundles/TwigBundle/Exception/:

1
2
3
4
5
6
7
8
9
10
11

{# templates/bundles/TwigBundle/Exception/error404.html.twig #}
{% extends 'base.html.twig' %}

{% block body %}
    <h1>Сторінка не знайдена</h1>

    <p>
        Запитувана сторінка не знайдена. Перевірте помилки в URL або
        <a href="{{ path('homepage') }}">поверніться на домашню сторінку</a>.
    </p>
{% endblock %}

Якщо вони вам знадобляться, TwigErrorRenderer передає деяку інформацію в шаблон помилок через змінні status_code та status_text, які зберігають HTTP статус-код та повідомлення, відповідно.

Окрім цього у вас є доступ до Виключень за допомогою exception, який, наприклад, дозволяє вам виводити відстеження стеку, використовуючи {{ exception.traceAsString }}, або отримати доступ до будь-якого іншого методу об'єкту. Однак будьте обережні, так як це з великою вирогідністю буде оголювати конфіденційну інформацію.

Безпека та сторінки 404

У зв'язку з порядком, в якому завантажуються маршрутизація та безпека, конфіденційна інформація не буде доступною на ваших сторінках 404. Це означає, що буде здаватися, що ваш користувач не увійшов в систему на сторінці 404 (це буде працювати при тестуванні, але не у виробництві).

1
2
3
4

# config/routes/dev/twig.yaml
_errors:
    resource: '@TwigBundle/Resources/config/routing/errors.xml'
    prefix:   /_error

1
2
3
4
5
6
7
8
9
10

<!-- config/routes/dev/twig.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>

1
2
3
4
5
6
7
8
9
10

// config/routes/dev/twig.php
use Symfony\Component\Routing\RouteCollection;

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

return $collection;

Перевизначення виведення помилок для не-HTML форматів

Щоб перевизначити не-HTML виведення помилки, необхідно встановити компонент Serializer.

1

$ composer require symfony/serializer-pack

Компонент Serializer має вбудований нормалізатор FlattenException (ProblemNormalizer) та кодувальники JSON/XML/CSV/YAML. Коли ваш застосунок викличе виключення, Symfony може вивести його в один з цих форматів. Якщо ви хочете змінити зміст виведення, створіть Нормалізатор, який підтримує введення FlattenException:

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

# src/Serializer/MyCustomProblemNormalizer.php
namespace App\Serializer;

use Symfony\Component\ErrorHandler\Exception\FlattenException;
use Symfony\Component\Serializer\Normalizer\NormalizerInterface;

class MyCustomProblemNormalizer implements NormalizerInterface
{
    public function normalize($exception, string $format = null, array $context = [])
    {
        return [
            'content' => 'Це мій користувацький нормалізатор проблеми.',
            'exception'=> [
                'message' => $exception->getMessage(),
                'code' => $exception->getStatusCode(),
            ],
        ];
    }

    public function supportsNormalization($data, string $format = null)
    {
        return $data instanceof FlattenException;
    }
}

Перевизначення ExceptionController за замовчуванням

Якщо вам потрібно трошки більше гнучкості окрім простого перевизначення шаблону, то ви можете змінити контролер, що відображає сторінку помилки. Наприклад, вам може бути потрібно передати додаткові змінні в ваш шаблон.

Щоб зробити це, просто створіть новий контролер де завгодно у вашому додатку, та встановіть опцію конфігурації framework.error_controller , щоб вказати на неї:

1
2
3

# config/packages/framework.yaml
framework:
    error_controller: App\Controller\ErrorController::show

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

<!-- config/packages/framework.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
        https://symfony.com/schema/dic/services/services-1.0.xsd">

    <framework:config>
        <framework:error-controller>App\Controller\ErrorController::show</framework:error-controller>
    </framework:config>

</container>

1
2
3
4
5
6
7

// config/packages/framework.php
use Symfony\Config\FrameworkConfig;

return static function (FrameworkConfig $framework) {
    // ...
    $framework->errorController('App\Controller\ErrorController::show');
};

Клас ExceptionListener, який використовується TwigBundle в якості слухача події kernel.exception, створює запит, який буде розгорнуто у вашому контролері. На додаток, вашому контролеру будуть передані два параметри:

exception

Обробка початкового екземпляру Throwable.

logger

Екземпляр DebugLoggerInterface, який може в деяких випадках бути null.

Робота з подією kernel.exception

Коли викликається виключення, клас HttpKernel ловить його та оголошує подію kernel.exception. Це надає вам можливість конвертувати виключення в Response декількома різними способами.

Робота з цією подією насправді набагато потужніша, ніж пояснювалося раніше, але також потребує ретельного розуміння внутрішніх процесів Symfony. Уявіть, що вам код викликає спеціальні виключення з конкретним значенням у вашому домені додатку.

Написання вашого власного слухача подій для події kernel.exception дозволяє вам ближче розглянути виключення та зробити по відношенню до нього різні дії. Ці дії можуть включати в себе запис логу виключення, перенаправлення користувача на іншу сторінку або вдіображення спеціальних сторінок помилки.

Цей підхід дозволяє вам створювати централізовану та багатошарову обробку помилок: замість того, щоб ловити (та обробляти) одні й ті самі виключення в різних контролерах знову і знову, ви просто можете мати одного (або декілька) слухачів, щоб розбиратися з ними.