From f5d8216b5d544b3b233d7bd3b0d7a59dda5f9e40 Mon Sep 17 00:00:00 2001 From: Fabien Potencier Date: Tue, 31 Jan 2023 08:34:05 +0100 Subject: [PATCH] Consolidate profiler docs --- _build/redirection_map | 3 +- profiler.rst | 304 +++++++++++++++++++++++++++++++++++- profiler/data_collector.rst | 304 ------------------------------------ reference/dic_tags.rst | 4 +- testing/profiling.rst | 2 +- 5 files changed, 306 insertions(+), 311 deletions(-) delete mode 100644 profiler/data_collector.rst diff --git a/_build/redirection_map b/_build/redirection_map index 7a7534a765f..295311d1532 100644 --- a/_build/redirection_map +++ b/_build/redirection_map @@ -190,7 +190,8 @@ /cookbook/logging/monolog_console /logging/monolog_console /cookbook/logging/monolog_email /logging/monolog_email /cookbook/logging/monolog_regex_based_excludes /logging/monolog_regex_based_excludes -/cookbook/profiler/data_collector /profiler/data_collector +/cookbook/profiler/data_collector /profiler#profiler-data-collector +/profiler/data_collector /profiler#profiler-data-collector /cookbook/profiler/index /profiler /cookbook/profiler/matchers /profiler/matchers /cookbook/profiler/profiling_data /profiler/profiling_data diff --git a/profiler.rst b/profiler.rst index 49e804f45b2..55bc0b6bf54 100644 --- a/profiler.rst +++ b/profiler.rst @@ -211,11 +211,309 @@ event:: $response = $event->getResponse(); $response->headers->set('Symfony-Debug-Toolbar-Replace', 1); } +.. index:: + single: Profiling; Data collector -.. toctree:: - :hidden: +.. _profiler-data-collector: - profiler/data_collector +Creating a Data Collector +========================= + +The Symfony Profiler obtains its profiling and debug information using some +special classes called data collectors. Symfony comes bundled with a few of +them, but you can also create your own. + +A data collector is a PHP class that implements the +:class:`Symfony\\Component\\HttpKernel\\DataCollector\\DataCollectorInterface`. +For convenience, your data collectors can also extend from the +:class:`Symfony\\Bundle\\FrameworkBundle\\DataCollector\\AbstractDataCollector` +class, which implements the interface and provides some utilities and the +``$this->data`` property to store the collected information. + +.. versionadded:: 5.2 + + The ``AbstractDataCollector`` class was introduced in Symfony 5.2. + +The following example shows a custom collector that stores information about the +request:: + + // src/DataCollector/RequestCollector.php + namespace App\DataCollector; + + use Symfony\Bundle\FrameworkBundle\DataCollector\AbstractDataCollector; + use Symfony\Component\HttpFoundation\Request; + use Symfony\Component\HttpFoundation\Response; + + class RequestCollector extends AbstractDataCollector + { + public function collect(Request $request, Response $response, \Throwable $exception = null) + { + $this->data = [ + 'method' => $request->getMethod(), + 'acceptable_content_types' => $request->getAcceptableContentTypes(), + ]; + } + } + +These are the method that you can define in the data collector class: + +:method:`Symfony\\Component\\HttpKernel\\DataCollector\\DataCollectorInterface::collect` method: + Stores the collected data in local properties (``$this->data`` if you extend + from ``AbstractDataCollector``). If you need some services to collect the + data, inject those services in the data collector constructor. + + .. caution:: + + The ``collect()`` method is only called once. It is not used to "gather" + data but is there to "pick up" the data that has been stored by your + service. + + .. caution:: + + As the profiler serializes data collector instances, you should not + store objects that cannot be serialized (like PDO objects) or you need + to provide your own ``serialize()`` method. + +:method:`Symfony\\Component\\HttpKernel\\DataCollector\\DataCollectorInterface::reset` method: + It's called between requests to reset the state of the profiler. By default + it only empties the ``$this->data`` contents, but you can override this method + to do additional cleaning. + +:method:`Symfony\\Component\\HttpKernel\\DataCollector\\DataCollectorInterface::getName` method: + Returns the collector identifier, which must be unique in the application. + By default it returns the FQCN of the data collector class, but you can + override this method to return a custom name (e.g. ``app.request_collector``). + This value is used later to access the collector information (see + :doc:`/testing/profiling`) so you may prefer using short strings instead of FQCN strings. + +The ``collect()`` method is called during the :ref:`kernel.response ` +event. If you need to collect data that is only available later, implement +:class:`Symfony\\Component\\HttpKernel\\DataCollector\\LateDataCollectorInterface` +and define the ``lateCollect()`` method, which is invoked right before the profiler +data serialization (during :ref:`kernel.terminate ` event). + +.. note:: + + If you're using the :ref:`default services.yaml configuration ` + with ``autoconfigure``, then Symfony will start using your data collector after the + next page refresh. Otherwise, :ref:`enable the data collector by hand `. + +Adding Web Profiler Templates +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The information collected by your data collector can be displayed both in the +web debug toolbar and in the web profiler. To do so, you need to create a Twig +template that includes some specific blocks. + +First, add the ``getTemplate()`` method in your data collector class to return +the path of the Twig template to use. Then, add some *getters* to give the +template access to the collected information:: + + // src/DataCollector/RequestCollector.php + namespace App\DataCollector; + + use Symfony\Bundle\FrameworkBundle\DataCollector\AbstractDataCollector; + + class RequestCollector extends AbstractDataCollector + { + // ... + + public static function getTemplate(): ?string + { + return 'data_collector/template.html.twig'; + } + + public function getMethod() + { + return $this->data['method']; + } + + public function getAcceptableContentTypes() + { + return $this->data['acceptable_content_types']; + } + } + +In the simplest case, you want to display the information in the toolbar +without providing a profiler panel. This requires to define the ``toolbar`` +block and set the value of two variables called ``icon`` and ``text``: + +.. code-block:: html+twig + + {# templates/data_collector/template.html.twig #} + {% extends '@WebProfiler/Profiler/layout.html.twig' %} + + {% block toolbar %} + {% set icon %} + {# this is the content displayed as a panel in the toolbar #} + ... + Request + {% endset %} + + {% set text %} + {# this is the content displayed when hovering the mouse over + the toolbar panel #} +
+ Method + {{ collector.method }} +
+ +
+ Accepted content type + {{ collector.acceptableContentTypes|join(', ') }} +
+ {% endset %} + + {# the 'link' value set to 'false' means that this panel doesn't + show a section in the web profiler #} + {{ include('@WebProfiler/Profiler/toolbar_item.html.twig', { link: false }) }} + {% endblock %} + +.. tip:: + + Built-in collector templates define all their images as embedded SVG files. + This makes them work everywhere without having to mess with web assets links: + + .. code-block:: twig + + {% set icon %} + {{ include('data_collector/icon.svg') }} + {# ... #} + {% endset %} + +If the toolbar panel includes extended web profiler information, the Twig template +must also define additional blocks: + +.. code-block:: html+twig + + {# templates/data_collector/template.html.twig #} + {% extends '@WebProfiler/Profiler/layout.html.twig' %} + + {% block toolbar %} + {% set icon %} + {# ... #} + {% endset %} + + {% set text %} +
+ {# ... #} +
+ {% endset %} + + {{ include('@WebProfiler/Profiler/toolbar_item.html.twig', { 'link': true }) }} + {% endblock %} + + {% block head %} + {# Optional. Here you can link to or define your own CSS and JS contents. #} + {# Use {{ parent() }} to extend the default styles instead of overriding them. #} + {% endblock %} + + {% block menu %} + {# This left-hand menu appears when using the full-screen profiler. #} + + + Request + + {% endblock %} + + {% block panel %} + {# Optional, for showing the most details. #} +

Acceptable Content Types

+ + + + + + {% for type in collector.acceptableContentTypes %} + + + + {% endfor %} +
Content Type
{{ type }}
+ {% endblock %} + +The ``menu`` and ``panel`` blocks are the only required blocks to define the +contents displayed in the web profiler panel associated with this data collector. +All blocks have access to the ``collector`` object. + +.. note:: + + The position of each panel in the toolbar is determined by the collector + priority, which can only be defined when :ref:`configuring the data collector by hand `. + +.. note:: + + If you're using the :ref:`default services.yaml configuration ` + with ``autoconfigure``, then Symfony will start displaying your collector data + in the toolbar after the next page refresh. Otherwise, :ref:`enable the data collector by hand `. + +.. _data_collector_tag: + +Enabling Custom Data Collectors +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you don't use Symfony's default configuration with +:ref:`autowire and autoconfigure ` +you'll need to configure the data collector explicitly: + +.. configuration-block:: + + .. code-block:: yaml + + # config/services.yaml + services: + App\DataCollector\RequestCollector: + tags: + - + name: data_collector + # must match the value returned by the getName() method + id: 'App\DataCollector\RequestCollector' + # optional template (it has more priority than the value returned by getTemplate()) + template: 'data_collector/template.html.twig' + # optional priority (positive or negative integer; default = 0) + # priority: 300 + + .. code-block:: xml + + + + + + + + + + + + + + + + .. code-block:: php + + // config/services.php + namespace Symfony\Component\DependencyInjection\Loader\Configurator; + + use App\DataCollector\RequestCollector; + + return function(ContainerConfigurator $containerConfigurator) { + $services = $containerConfigurator->services(); + + $services->set(RequestCollector::class) + ->tag('data_collector', [ + 'id' => RequestCollector::class, + // optional template (it has more priority than the value returned by getTemplate()) + 'template' => 'data_collector/template.html.twig', + // optional priority (positive or negative integer; default = 0) + // 'priority' => 300, + ]); + }; .. _`Single-page applications`: https://en.wikipedia.org/wiki/Single-page_application .. _`Blackfire`: https://blackfire.io/docs/introduction?utm_source=symfony&utm_medium=symfonycom_docs&utm_campaign=profiler diff --git a/profiler/data_collector.rst b/profiler/data_collector.rst deleted file mode 100644 index 44545614da2..00000000000 --- a/profiler/data_collector.rst +++ /dev/null @@ -1,304 +0,0 @@ -.. index:: - single: Profiling; Data collector - -How to Create a custom Data Collector -===================================== - -The :doc:`Symfony Profiler ` obtains its profiling and debug -information using some special classes called data collectors. Symfony comes -bundled with a few of them, but you can also create your own. - -Creating a custom Data Collector --------------------------------- - -A data collector is a PHP class that implements the -:class:`Symfony\\Component\\HttpKernel\\DataCollector\\DataCollectorInterface`. -For convenience, your data collectors can also extend from the -:class:`Symfony\\Bundle\\FrameworkBundle\\DataCollector\\AbstractDataCollector` -class, which implements the interface and provides some utilities and the -``$this->data`` property to store the collected information. - -.. versionadded:: 5.2 - - The ``AbstractDataCollector`` class was introduced in Symfony 5.2. - -The following example shows a custom collector that stores information about the -request:: - - // src/DataCollector/RequestCollector.php - namespace App\DataCollector; - - use Symfony\Bundle\FrameworkBundle\DataCollector\AbstractDataCollector; - use Symfony\Component\HttpFoundation\Request; - use Symfony\Component\HttpFoundation\Response; - - class RequestCollector extends AbstractDataCollector - { - public function collect(Request $request, Response $response, \Throwable $exception = null) - { - $this->data = [ - 'method' => $request->getMethod(), - 'acceptable_content_types' => $request->getAcceptableContentTypes(), - ]; - } - } - -These are the method that you can define in the data collector class: - -:method:`Symfony\\Component\\HttpKernel\\DataCollector\\DataCollectorInterface::collect` method: - Stores the collected data in local properties (``$this->data`` if you extend - from ``AbstractDataCollector``). If you need some services to collect the - data, inject those services in the data collector constructor. - - .. caution:: - - The ``collect()`` method is only called once. It is not used to "gather" - data but is there to "pick up" the data that has been stored by your - service. - - .. caution:: - - As the profiler serializes data collector instances, you should not - store objects that cannot be serialized (like PDO objects) or you need - to provide your own ``serialize()`` method. - -:method:`Symfony\\Component\\HttpKernel\\DataCollector\\DataCollectorInterface::reset` method: - It's called between requests to reset the state of the profiler. By default - it only empties the ``$this->data`` contents, but you can override this method - to do additional cleaning. - -:method:`Symfony\\Component\\HttpKernel\\DataCollector\\DataCollectorInterface::getName` method: - Returns the collector identifier, which must be unique in the application. - By default it returns the FQCN of the data collector class, but you can - override this method to return a custom name (e.g. ``app.request_collector``). - This value is used later to access the collector information (see - :doc:`/testing/profiling`) so you may prefer using short strings instead of FQCN strings. - -The ``collect()`` method is called during the :ref:`kernel.response ` -event. If you need to collect data that is only available later, implement -:class:`Symfony\\Component\\HttpKernel\\DataCollector\\LateDataCollectorInterface` -and define the ``lateCollect()`` method, which is invoked right before the profiler -data serialization (during :ref:`kernel.terminate ` event). - -.. note:: - - If you're using the :ref:`default services.yaml configuration ` - with ``autoconfigure``, then Symfony will start using your data collector after the - next page refresh. Otherwise, :ref:`enable the data collector by hand `. - -Adding Web Profiler Templates ------------------------------ - -The information collected by your data collector can be displayed both in the -web debug toolbar and in the web profiler. To do so, you need to create a Twig -template that includes some specific blocks. - -First, add the ``getTemplate()`` method in your data collector class to return -the path of the Twig template to use. Then, add some *getters* to give the -template access to the collected information:: - - // src/DataCollector/RequestCollector.php - namespace App\DataCollector; - - use Symfony\Bundle\FrameworkBundle\DataCollector\AbstractDataCollector; - - class RequestCollector extends AbstractDataCollector - { - // ... - - public static function getTemplate(): ?string - { - return 'data_collector/template.html.twig'; - } - - public function getMethod() - { - return $this->data['method']; - } - - public function getAcceptableContentTypes() - { - return $this->data['acceptable_content_types']; - } - } - -In the simplest case, you want to display the information in the toolbar -without providing a profiler panel. This requires to define the ``toolbar`` -block and set the value of two variables called ``icon`` and ``text``: - -.. code-block:: html+twig - - {# templates/data_collector/template.html.twig #} - {% extends '@WebProfiler/Profiler/layout.html.twig' %} - - {% block toolbar %} - {% set icon %} - {# this is the content displayed as a panel in the toolbar #} - ... - Request - {% endset %} - - {% set text %} - {# this is the content displayed when hovering the mouse over - the toolbar panel #} -
- Method - {{ collector.method }} -
- -
- Accepted content type - {{ collector.acceptableContentTypes|join(', ') }} -
- {% endset %} - - {# the 'link' value set to 'false' means that this panel doesn't - show a section in the web profiler #} - {{ include('@WebProfiler/Profiler/toolbar_item.html.twig', { link: false }) }} - {% endblock %} - -.. tip:: - - Built-in collector templates define all their images as embedded SVG files. - This makes them work everywhere without having to mess with web assets links: - - .. code-block:: twig - - {% set icon %} - {{ include('data_collector/icon.svg') }} - {# ... #} - {% endset %} - -If the toolbar panel includes extended web profiler information, the Twig template -must also define additional blocks: - -.. code-block:: html+twig - - {# templates/data_collector/template.html.twig #} - {% extends '@WebProfiler/Profiler/layout.html.twig' %} - - {% block toolbar %} - {% set icon %} - {# ... #} - {% endset %} - - {% set text %} -
- {# ... #} -
- {% endset %} - - {{ include('@WebProfiler/Profiler/toolbar_item.html.twig', { 'link': true }) }} - {% endblock %} - - {% block head %} - {# Optional. Here you can link to or define your own CSS and JS contents. #} - {# Use {{ parent() }} to extend the default styles instead of overriding them. #} - {% endblock %} - - {% block menu %} - {# This left-hand menu appears when using the full-screen profiler. #} - - - Request - - {% endblock %} - - {% block panel %} - {# Optional, for showing the most details. #} -

Acceptable Content Types

- - - - - - {% for type in collector.acceptableContentTypes %} - - - - {% endfor %} -
Content Type
{{ type }}
- {% endblock %} - -The ``menu`` and ``panel`` blocks are the only required blocks to define the -contents displayed in the web profiler panel associated with this data collector. -All blocks have access to the ``collector`` object. - -.. note:: - - The position of each panel in the toolbar is determined by the collector - priority, which can only be defined when :ref:`configuring the data collector by hand `. - -.. note:: - - If you're using the :ref:`default services.yaml configuration ` - with ``autoconfigure``, then Symfony will start displaying your collector data - in the toolbar after the next page refresh. Otherwise, :ref:`enable the data collector by hand `. - -.. _data_collector_tag: - -Enabling Custom Data Collectors -------------------------------- - -If you don't use Symfony's default configuration with -:ref:`autowire and autoconfigure ` -you'll need to configure the data collector explicitly: - -.. configuration-block:: - - .. code-block:: yaml - - # config/services.yaml - services: - App\DataCollector\RequestCollector: - tags: - - - name: data_collector - # must match the value returned by the getName() method - id: 'App\DataCollector\RequestCollector' - # optional template (it has more priority than the value returned by getTemplate()) - template: 'data_collector/template.html.twig' - # optional priority (positive or negative integer; default = 0) - # priority: 300 - - .. code-block:: xml - - - - - - - - - - - - - - - - .. code-block:: php - - // config/services.php - namespace Symfony\Component\DependencyInjection\Loader\Configurator; - - use App\DataCollector\RequestCollector; - - return function(ContainerConfigurator $containerConfigurator) { - $services = $containerConfigurator->services(); - - $services->set(RequestCollector::class) - ->tag('data_collector', [ - 'id' => RequestCollector::class, - // optional template (it has more priority than the value returned by getTemplate()) - 'template' => 'data_collector/template.html.twig', - // optional priority (positive or negative integer; default = 0) - // 'priority' => 300, - ]); - }; diff --git a/reference/dic_tags.rst b/reference/dic_tags.rst index c1e2c902605..e6b1d44aa69 100644 --- a/reference/dic_tags.rst +++ b/reference/dic_tags.rst @@ -362,7 +362,7 @@ data_collector **Purpose**: Create a class that collects custom data for the profiler For details on creating your own custom data collection, read the -:doc:`/profiler/data_collector` article. +:ref:`profiler-data-collector` article. doctrine.event_listener ----------------------- @@ -718,7 +718,7 @@ the tag. This is mostly useful when running your projects in application servers that reuse the Symfony application between requests to improve performance. This tag -is applied for example to the built-in :doc:`data collectors ` +is applied for example to the built-in :ref:`data collectors ` of the profiler to delete all their information. .. _dic_tags-mime: diff --git a/testing/profiling.rst b/testing/profiling.rst index db7714b9d1f..0637e134a91 100644 --- a/testing/profiling.rst +++ b/testing/profiling.rst @@ -126,5 +126,5 @@ finish. It can be achieved by embedding the token in the error message:: .. tip:: - Read the API for built-in :doc:`data collectors ` + Read the API for built-in :ref:`data collectors ` to learn more about their interfaces.