8000 Merged some profiler docs into a single main Profiler article · symfony/symfony-docs@f28fe4e · GitHub
[go: up one dir, main page]
Skip to content

Commit f28fe4e

Browse files
javiereguiluzjaviereguiluz
committed
Merged some profiler docs into a single main Profiler article
1 parent f06a0ec commit f28fe4e

File tree

6 files changed

+174
-165
lines changed

6 files changed

+174
-165
lines changed

‎_build/redirection_map

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -405,3 +405,6 @@
405405
/console/logging /console
406406
/reference/forms/twig_reference /form/form_customization
407407
/form/rendering /form/form_customization
408+
/profiler/matchers /profiler
409+
/profiler/profiling_data /profiler
410+
/profiler/wdt_follow_ajax /profiler

‎_images/profiler/web-interface.png

73.9 KB
Loading

‎profiler.rst

Lines changed: 171 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,8 @@ Profiler
22
========
33

44
The profiler is a powerful **development tool** that gives detailed information
5-
about the execution of any request.
6-
7-
**Never** enable the profiler in production environments as it will lead to
8-
major security vulnerabilities in your project.
5+
about the execution of any request. **Never** enable the profiler in production
6+
environments as it will lead to major security vulnerabilities in your project.
97

108
Installation
119
------------
@@ -17,10 +15,175 @@ install the profiler before using it:
1715
1816
$ composer require --dev symfony/profiler-pack
1917
18+
Now browse any page of your application in the development environment to let
19+
the profiler collect information. Then, click on any element of the debug
20+
toolbar injected at the bottom of your pages to open the web interface of the
21+
Symfony Profiler, which will look like this:
22+
23+
.. image:: /_images/profiler/web-interface.png
24+
:align: center
25+
26+
Accessing Profiling Data Programmatically
27+
-----------------------------------------
28+
29+
Most of the times, the profiler information is accessed and analyzed using its
30+
web-based interface. However, you can also retrieve profiling information
31+
programmatically thanks to the methods provided by the ``profiler`` service.
32+
33+
When the response object is available, use the
34+
:method:`Symfony\\Component\\HttpKernel\\Profiler\\Profiler::loadProfileFromResponse`
35+
method to access to its associated profile::
36+
37+
// ... $profiler is the 'profiler' service
38+
$profile = $profiler->loadProfileFromResponse($response);
39+
40+
When the profiler stores data about a request, it also associates a token with it;
41+
this token is available in the ``X-Debug-Token`` HTTP header of the response.
42+
Using this token, you can access the profile of any past response thanks to the
43+
:method:`Symfony\\Component\\HttpKernel\\Profiler\\Profiler::loadProfile` method::
44+
45+
$token = $response->headers->get('X-Debug-Token');
46+
$profile = $profiler->loadProfile($token);
47+
48+
.. tip::
49+
50+
When the profiler is enabled but not the web debug toolbar, inspect the page
51+
with your browser's developer tools to get the value of the ``X-Debug-Token``
52+
HTTP header.
53+
54+
The ``profiler`` service also provides the
55+
:method:`Symfony\\Component\\HttpKernel\\Profiler\\Profiler::find` method to
56+
look for tokens based on some criteria::
57+
58+
// gets the latest 10 tokens
59+
$tokens = $profiler->find('', '', 10, '', '', '');
60+
61+
// gets the latest 10 tokens for all URL containing /admin/
62+
$tokens = $profiler->find('', '/admin/', 10, '', '', '');
63+
64+
// gets the latest 10 tokens for local POST requests
65+
$tokens = $profiler->find('127.0.0.1', '', 10, 'POST', '', '');
66+
67+
// gets the latest 10 tokens for requests that happened between 2 and 4 days ago
68+
$tokens = $profiler->find('', '', 10, '', '4 days ago', '2 days ago');
69+
70+
Data Collectors
71+
---------------
72+
73+
The profiler gets its information using some services called "data collectors".
74+
Symfony comes with several collectors that get information about the request,
75+
the logger, the routing, the cache, etc.
76+
77+
Run this command to get the list of collectors actually enabled in your app:
78+
79+
.. code-block:: terminal
80+
81+
$ php bin/console debug:container --tag=data_collector
82+
83+
You can also :doc:`create your own data collector </profiler/data_collector>` to
84+
store any data generated by your app and display it in the debug toolbar and the
85+
profiler web interface.
86+
87+
Enabling the Profiler Conditionally
88+
-----------------------------------
89+
90+
.. caution::
91+
92+
The possibility to use a matcher to enable the profiler conditionally was
93+
removed in Symfony 4.0.
94+
95+
Symfony Profiler cannot be enabled/disabled conditionally using matchers, because
96+
that feature was removed in Symfony 4.0. However, you can use the ``enable()``
97+
and ``disable()`` methods of the :class:`Symfony\\Component\\HttpKernel\\Profiler\\Profiler`
98+
class in your controllers to manage the profiler programmatically::
99+
100+
use Symfony\Component\HttpKernel\Profiler\Profiler;
10 F438 1+
// ...
102+
103+
class DefaultController
104+
{
105+
// ...
106+
107+
public function someMethod(?Profiler $profiler)
108+
{
109+
// $profiler won't be set if your environment doesn't have the profiler (like prod, by default)
110+
if (null !== $profiler) {
111+
// if it exists, disable the profiler for this particular controller action
112+
$profiler->disable();
113+
}
114+
115+
// ...
116+
}
117+
}
118+
119+
In order for the profiler to be injected into your controller you need to
120+
create an alias pointing to the existing ``profiler`` service:
121+
122+
.. configuration-block::
123+
124+
.. code-block:: yaml
125+
126+
# config/services_dev.yaml
127+
services:
128+
Symfony\Component\HttpKernel\Profiler\Profiler: '@profiler'
129+
130+
.. code-block:: xml
131+
132+
<!-- config/services_dev.xml -->
133+
<?xml version="1.0" encoding="UTF-8" ?>
134+
<container xmlns="http://symfony.com/schema/dic/services"
135+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
136+
xsi:schemaLocation="http://symfony.com/schema/dic/services
137+
http://symfony.com/schema/dic/services/services-1.0.xsd">
138+
139+
<services>
140+
<service id="Symfony\Component\HttpKernel\Profiler\Profiler" alias="profiler" />
141+
</services>
142+
</container>
143+
144+
.. code-block:: php
145+
146+
// config/services_dev.php
147+
use Symfony\Component\HttpKernel\Profiler\Profiler;
148+
149+
$container->setAlias(Profiler::class, 'profiler');
150+
151+
Updating the Web Debug Toolbar After AJAX Requests
152+
--------------------------------------------------
153+
154+
`Single-page applications`_ (SPA) are web applications that interact with the
155+
user by dynamically rewriting the current page rather than loading entire new
156+
pages from a server.
157+
158+
By default, the debug toolbar displays the information of the initial page load
159+
and doesn't refresh after each AJAX request. However, you can set the
160+
``Symfony-Debug-Toolbar-Replace`` header to a value of ``1`` in the response to
161+
the AJAX request to force the refresh of the toolbar::
162+
163+
$response->headers->set('Symfony-Debug-Toolbar-Replace', 1);
164+
165+
Ideally this header should only be set during development and not for
166+
production. To do that, create an :doc:`event subscriber </event_dispatcher>`
167+
and listen to the :ref:`kernel.response<component-http-kernel-kernel-response>`
168+
event::
169+
170+
use Symfony\Component\HttpKernel\Event\FilterResponseEvent;
171+
172+
// ...
173+
174+
public function onKernelResponse(FilterResponseEvent $event)
175+
{
176+
if (!$this->getKernel()->isDebug()) {
177+
return;
178+
}
179+
180+
$response = $event->getResponse();
181+
$response->headers->set('Symfony-Debug-Toolbar-Replace', 1);
182+
}
183+
20184
.. toctree::
21-
:maxdepth: 1
185+
:hidden:
22186

23187
profiler/data_collector
24-
profiler/profiling_data
25-
profiler/matchers
26-
profiler/wdt_follow_ajax
188+
189+
.. _`Single-page applications`: https://en.wikipedia.org/wiki/Single-page_application

‎profiler/matchers.rst

Lines changed: 0 additions & 66 deletions
This file was deleted.

‎profiler/profiling_data.rst

Lines changed: 0 additions & 46 deletions
This file was deleted.

‎profiler/wdt_follow_ajax.rst

Lines changed: 0 additions & 45 deletions
This file was deleted.

0 commit comments

Comments
 (0)
0