From f1de07982fa504b18777a8c304cd203bd9b86c6a Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 3 Aug 2015 12:33:05 +0200 Subject: [PATCH 1/4] Updated the article about data collectors --- cookbook/profiler/data_collector.rst | 243 +++++++++++++++++++-------- 1 file changed, 172 insertions(+), 71 deletions(-) diff --git a/cookbook/profiler/data_collector.rst b/cookbook/profiler/data_collector.rst index 05343769443..3e090f811b8 100644 --- a/cookbook/profiler/data_collector.rst +++ b/cookbook/profiler/data_collector.rst @@ -4,9 +4,9 @@ How to Create a custom Data Collector ===================================== -:doc:`The Symfony Profiler ` delegates data collecting to -data collectors. Symfony comes bundled with a few of them, but you can easily -create your own. +:doc:`The Symfony Profiler ` delegates data collection +to some special classes called data collectors. Symfony comes bundled with a few +of them, but you can easily create your own. Creating a custom Data Collector -------------------------------- @@ -33,12 +33,12 @@ Creating a custom data collector is as simple as implementing the function getName(); } -The ``getName()`` method must return a unique name. This is used to access the -information later on (see :doc:`/cookbook/testing/profiling` for -instance). +The value returned by ``getName()`` must be unique in the application. This value +is also used to access the information later on (see :doc:`/cookbook/testing/profiling` +for instance). -The ``collect()`` method is responsible for storing the data it wants to give -access to in local properties. +The ``collect()`` method is responsible for storing the collected data in local +properties. .. caution:: @@ -51,101 +51,169 @@ Most of the time, it is convenient to extend populate the ``$this->data`` property (it takes care of serializing the ``$this->data`` property):: - class MemoryDataCollector extends DataCollector + // src/AppBundle/DataCollector/MyCollector.php + use Symfony\Component\HttpKernel\DataCollector\DataCollector; + + class MyCollector extends DataCollector { public function collect(Request $request, Response $response, \Exception $exception = null) { $this->data = array( - 'memory' => memory_get_peak_usage(true), + 'variable' => 'value', ); } - public function getMemory() + public function getVariable() { - return $this->data['memory']; + return $this->data['variable']; } public function getName() { - return 'memory'; + return 'app.my_collector'; } } .. _data_collector_tag: -Enabling custom Data Collectors +Enabling Custom Data Collectors ------------------------------- -To enable a data collector, add it as a regular service in one of your -configuration, and tag it with ``data_collector``: +To enable a data collector, define it as a regular service and tag it with +``data_collector``: .. configuration-block:: .. code-block:: yaml + # app/config/services.yml services: - data_collector.your_collector_name: - class: Fully\Qualified\Collector\Class\Name + app.my_collector: + class: AppBundle\DataCollector\MyCollector + public: false tags: - { name: data_collector } .. code-block:: xml - - - + + + + + + + + + .. code-block:: php + // app/config/services.php $container - ->register('data_collector.your_collector_name', 'Fully\Qualified\Collector\Class\Name') + ->register('app.my_collector', 'AppBundle\DataCollector\MyCollector') + ->setPublic(false) ->addTag('data_collector') ; Adding Web Profiler Templates ----------------------------- -When you want to display the data collected by your data collector in the web -debug toolbar or the web profiler, you will need to create a Twig template. The -following example can help you get started: +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. + +In the simplest case, you just 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:: jinja +.. code-block:: html+jinja {% extends 'WebProfilerBundle:Profiler:layout.html.twig' %} {% block toolbar %} - {# This toolbar item may appear along the top or bottom of the screen.#} {% set icon %} - - Example + {# this is the content displayed as a panel in the toolbar #} + + Information {% endset %} {% set text %} -
- Quick piece of data - 100 units -
-
- Another quick thing - 300 units -
+ {# this is the content displayed when hovering the mouse over + the toolbar panel #} +
+ Quick piece of data + 100 units +
+
+ Another piece of data + 300 units +
{% endset %} - {# Set the "link" value to false if you do not have a big "panel" - section that you want to direct the user to. #} - {{ include('@WebProfiler/Profiler/toolbar_item.html.twig', { 'link': true }) }} + {# 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 base64-encoded + images. This makes them work everywhere without having to mess with web assets + links: + + .. code-block:: html + + + + Another solution is to define the images as SVG files. In addition to being + resolution-independent, these images can be easily embedded in the Twig + template or included from an external file to reuse them in several templates: + .. code-block:: jinja + + {{ include('@App/data_collector/icon.svg') }} + + You are encouraged to use the latter technique for your own toolbar panels. + +If the toolbar panel includes extended web profiler information, the Twig template +must also define additional blocks: + +.. code-block:: html+jinja + + {% extends '@WebProfiler/Profiler/layout.html.twig' %} + + {% block toolbar %} + {% set icon %} + + Information + {% endset %} + + {% set text %} +
+ {# ... #} +
+ {% endset %} + + {# the 'link' value is now set to 'true', which allows the user to click + on it to access the web profiler panel. Since 'true' is the default + value, you can omit the 'link' parameter entirely #} + {{ include('@WebProfiler/Profiler/toolbar_item.html.twig', { link: true }) }} {% endblock %} {% block head %} - {# Optional, if you need your own JS or CSS files. #} - {{ parent() }} {# Use parent() to keep the default styles #} + {# Optional, you can here link to or define your own CSS and JS contents #} + {# {{ parent() }} to keep the default styles #} {% endblock %} {% block menu %} {# This left-hand menu appears when using the full-screen profiler. #} - + Example Collector {% endblock %} @@ -158,57 +226,90 @@ following example can help you get started:

{% endblock %} -Each block is optional. The ``toolbar`` block is used for the web debug -toolbar and ``menu`` and ``panel`` are used to add a panel to the web -profiler. - +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. -.. tip:: +Finally, to enable the data collector template, add a ``template`` attribute to +the ``data_collector`` tag in your service configuration: - Built-in templates use a base64 encoded image for the toolbar: +.. configuration-block:: - .. code-block:: html + .. code-block:: yaml - + # app/config/services.yml + services: + app.my_collector: + class: AppBundle\DataCollector\MyCollector + tags: + - + name: data_collector + template: 'data_collector/template.html.twig' + id: 'app.my_collector' + public: false - You can easily calculate the base64 value for an image with this - little script:: + .. code-block:: xml - #!/usr/bin/env php - + + + + + + + + -To enable the template, add a ``template`` attribute to the ``data_collector`` -tag in your configuration. For example, assuming your template is in AppBundle: + .. code-block:: php + + // app/config/services.php + $container + ->register('app.my_collector', 'AppBundle\DataCollector\MyCollector') + ->setPublic(false) + ->addTag('data_collector', array( + 'template' => 'data_collector/template.html.twig', + 'id' => 'app.my_collector', + )) + ; + +.. caution:: + + The ``id`` attribute must match the value returned by the ``getName()`` method. + +The position of each panel in the toolbar is determined by the priority defined +by each collector. Most built-in collectors use ``255`` as their priority. If you +want your collector to be displayed before them, use a higher value: .. configuration-block:: .. code-block:: yaml + # app/config/services.yml services: - data_collector.your_collector_name: - class: AppBundle\Collector\Class\Name + app.my_collector: + class: AppBundle\DataCollector\MyCollector tags: - - { name: data_collector, template: "AppBundle:Collector:templatename", id: "your_collector_name" } + - { name: data_collector, template: '...', id: '...', priority: '300' } .. code-block:: xml - - + + + .. code-block:: php + // app/config/services.php $container - ->register('data_collector.your_collector_name', 'AppBundle\Collector\Class\Name') + ->register('app.my_collector', 'AppBundle\DataCollector\MyCollector') ->addTag('data_collector', array( - 'template' => 'AppBundle:Collector:templatename', - 'id' => 'your_collector_name', + 'template' => '...', + 'id' => '...', + 'priority' => 300, )) ; - -.. caution:: - - Make sure the ``id`` attribute is the same string you used for the - ``getName()`` method. From e3a80a4e0db51b6e352b8aa32649bc51bd80cf2e Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 3 Aug 2015 13:12:33 +0200 Subject: [PATCH 2/4] Implemented all suggestions --- cookbook/profiler/data_collector.rst | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/cookbook/profiler/data_collector.rst b/cookbook/profiler/data_collector.rst index 3e090f811b8..24bc9709c09 100644 --- a/cookbook/profiler/data_collector.rst +++ b/cookbook/profiler/data_collector.rst @@ -176,7 +176,11 @@ block and set the value of two variables called ``icon`` and ``text``: .. code-block:: jinja +<<<<<<< HEAD {{ include('@App/data_collector/icon.svg') }} +======= + {{ include('@WebProfiler/Icon/my_collector.svg') }} +>>>>>>> Implemented all suggestions You are encouraged to use the latter technique for your own toolbar panels. @@ -200,14 +204,23 @@ must also define additional blocks: {% endset %} {# the 'link' value is now set to 'true', which allows the user to click +<<<<<<< HEAD on it to access the web profiler panel. Since 'true' is the default +======= + on it to access to the web profiler panel. Since 'true' is the default +>>>>>>> Implemented all suggestions value, you can omit the 'link' parameter entirely #} {{ include('@WebProfiler/Profiler/toolbar_item.html.twig', { link: true }) }} {% endblock %} {% block head %} +<<<<<<< HEAD {# Optional, you can here link to or define your own CSS and JS contents #} {# {{ parent() }} to keep the default styles #} +======= + {# Optional, here you can link to or define your own CSS and JS contents #} + {# Use {{ parent() }} to keep the default styles #} +>>>>>>> Implemented all suggestions {% endblock %} {% block menu %} From 93bd994239f4c23023045f3a74b24f02f548c95c Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 19 Aug 2015 21:57:49 +0200 Subject: [PATCH 3/4] Tweaks and fixes --- cookbook/profiler/data_collector.rst | 13 ------------- 1 file changed, 13 deletions(-) diff --git a/cookbook/profiler/data_collector.rst b/cookbook/profiler/data_collector.rst index 24bc9709c09..3e090f811b8 100644 --- a/cookbook/profiler/data_collector.rst +++ b/cookbook/profiler/data_collector.rst @@ -176,11 +176,7 @@ block and set the value of two variables called ``icon`` and ``text``: .. code-block:: jinja -<<<<<<< HEAD {{ include('@App/data_collector/icon.svg') }} -======= - {{ include('@WebProfiler/Icon/my_collector.svg') }} ->>>>>>> Implemented all suggestions You are encouraged to use the latter technique for your own toolbar panels. @@ -204,23 +200,14 @@ must also define additional blocks: {% endset %} {# the 'link' value is now set to 'true', which allows the user to click -<<<<<<< HEAD on it to access the web profiler panel. Since 'true' is the default -======= - on it to access to the web profiler panel. Since 'true' is the default ->>>>>>> Implemented all suggestions value, you can omit the 'link' parameter entirely #} {{ include('@WebProfiler/Profiler/toolbar_item.html.twig', { link: true }) }} {% endblock %} {% block head %} -<<<<<<< HEAD {# Optional, you can here link to or define your own CSS and JS contents #} {# {{ parent() }} to keep the default styles #} -======= - {# Optional, here you can link to or define your own CSS and JS contents #} - {# Use {{ parent() }} to keep the default styles #} ->>>>>>> Implemented all suggestions {% endblock %} {% block menu %} From 69bd67736939831a5b17189ee9bf8acedaadab1d Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 23 Sep 2015 17:52:51 +0200 Subject: [PATCH 4/4] Fixed some issues --- cookbook/profiler/data_collector.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/cookbook/profiler/data_collector.rst b/cookbook/profiler/data_collector.rst index 3e090f811b8..47229033063 100644 --- a/cookbook/profiler/data_collector.rst +++ b/cookbook/profiler/data_collector.rst @@ -246,7 +246,7 @@ the ``data_collector`` tag in your service configuration: name: data_collector template: 'data_collector/template.html.twig' id: 'app.my_collector' - public: false + public: false .. code-block:: xml @@ -258,8 +258,8 @@ the ``data_collector`` tag in your service configuration: http://symfony.com/schema/dic/services/services-1.0.xsd" > - - + + @@ -293,7 +293,7 @@ want your collector to be displayed before them, use a higher value: app.my_collector: class: AppBundle\DataCollector\MyCollector tags: - - { name: data_collector, template: '...', id: '...', priority: '300' } + - { name: data_collector, template: '...', id: '...', priority: 300 } .. code-block:: xml