Переопределение шаблонов ошибок по умолчанию

Вы можете использовать встроенное средство отображения ошибок 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
5

# config/routes/framework.yaml
when@dev:
    _errors:
        resource: '@FrameworkBundle/Resources/config/routing/errors.xml'
        prefix:   /_error

1
2
3
4
5
6
7
8
9
10
11

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

    <when env="dev">
        <import resource="@FrameworkBundle/Resources/config/routing/errors.xml" prefix="/_error"/>
    </when>
</routes>

1
2
3
4
5
6
7
8
9
10

// config/routes/framework.php
use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;

return function (RoutingConfigurator $routes) {
    if ('dev' === $routes->env()) {
        $routes->import('@FrameworkBundle/Resources/config/routing/errors.xml')
            ->prefix('/_error')
        ;
    }
};

Переопределение вывода ошибок для не-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 = []): array
    {
        return [
            'content' => 'This is my custom problem normalizer.',
            'exception'=> [
                'message' => $exception->getMessage(),
                'code' => $exception->getStatusCode(),
            ],
        ];
    }

    public function supportsNormalization($data, string $format = null, array $context = []): bool
    {
        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 позволяет вам ближе рассмотретьисключение и предпринять по отношению к нему разные действия. Эти действия могут включать в себя запись лога исключения, перенаправление пользователя на другую страницу или отображение специальных страниц ошибки.

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