exceptions.rst

.. index::
    single: Configuration
    single: Exception
    single: Filter
    single: Renderer

Exception strategy

Any exception thrown by a block service is handled by an exception strategy manager that determines how the exception should be handled. A default strategy can be defined for all block types but a specific strategy can also be defined on a per block type basis.

The exception strategy uses an exception filter and an exception renderer.

Filters

The role of an exception filter is to define which exceptions should be handled and which should be ignored silently. There are currently 4 filters available:

• debug_only: only handle exceptions when in debug mode (default),
• ignore_block_exception: only handle exceptions that don't implement BlockExceptionInterface,
• keep_all: handle all exceptions,
• keep__none: ignore all exceptions.

Warning

Use the keep__none filter with care!

These filters may be modified or combined with other filters in the configuration file:

.. configuration-block::

    .. code-block:: yaml

        # config/packages/sonata_block.yaml

        sonata_block:
            exception:
                default:
                    filter: debug_only
                filters:
                    debug_only:             sonata.block.exception.filter.debug_only
                    ignore_block_exception: sonata.block.exception.filter.ignore_block_exception
                    keep_all:               sonata.block.exception.filter.keep_all
                    keep_none:              sonata.block.exception.filter.keep_none

A default filter may be configured to be applied to all block types. If you wish to customize a filter on a particular block type, you may also add the following option in the configuration file:

.. configuration-block::

    .. code-block:: yaml

        # config/packages/sonata_block.yaml

        sonata_block:
            blocks:
                sonata.block.service.text:
                    exception: { filter: keep_all }

Renderers

The role of an exception renderer is to define what to do with the exceptions that have passed the filter. There are currently 3 kind of renderer available:

• inline: renders a Twig template within the rendering workflow with minimal information regarding the exception,
• inline_debug: renders a twig template with the full debug exception information from Symfony,
• throw: throws the exception to let the framework handle the exception.

These filters may be modified or completed with other filters in the configuration file:

.. configuration-block::

    .. code-block:: yaml

        # config/packages/sonata_block.yaml

        sonata_block:
            exception:
                default:
                    renderer: throw
                renderers:
                    inline:       sonata.block.exception.renderer.inline
                    inline_debug: sonata.block.exception.renderer.inline_debug
                    throw:        sonata.block.exception.renderer.throw

A default renderer will be applied to all block types. If you wish to use a different renderer on a particular block type, you should add the following option in the configuration file:

.. configuration-block::

    .. code-block:: yaml

        # config/packages/sonata_block.yaml

        sonata_block:
            blocks:
                sonata.block.service.text:
                    exception: { renderer: inline }