8000 minor #14333 [Stopwatch] Move component docs into framework guides (j… · symfony/symfony-docs@972faae · GitHub
[go: up one dir, main page]
Skip to content

Commit 972faae

Browse files
javiereguiluzjaviereguiluz
committed
minor #14333 [Stopwatch] Move component docs into framework guides (javiereguiluz)
This PR was squashed before being merged into the 4.4 branch. Discussion ---------- [Stopwatch] Move component docs into framework guides This PR continues the great work done by @javiereguiluz in #12291 . It's mostly a rebase to 4.4. Commits ------- fc847c4 [Stopwatch] Move component docs into framework guides
2 parents 064c106 + fc847c4 commit 972faae

File tree

7 files changed

+145
-168
lines changed

7 files changed

+145
-168
lines changed

‎_build/redirection_map

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -507,3 +507,4 @@
507507
/components/http_client /http_client
508508
/components/mailer /mailer
509509
/messenger/message-recorder messenger/dispatch_after_current_bus
510+
/components/stopwatch https://github.com/symfony/stopwatch

‎components/phpunit_bridge.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -477,8 +477,8 @@ If you have this kind of time-related tests::
477477
}
478478
}
479479

480-
You used the :doc:`Symfony Stopwatch Component </components/stopwatch>` to
481-
calculate the duration time of your process, here 10 seconds. However, depending
480+
You calculated the duration time of your process using the Stopwatch utilities to
481+
:ref:`profile Symfony applications <profiling-applications>`. However, depending
482482
on the load of the server or the processes running on your local machine, the
483483
``$duration`` could for example be ``10.000023s`` instead of ``10s``.
484484

‎components/stopwatch.rst

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

‎page_creation.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -176,6 +176,8 @@ the debugging routes in the next section.
176176

177177
You'll learn about many more commands as you continue!
178178

179+
.. _web-debug-toolbar:
180+
179181
The Web Debug Toolbar: Debugging Dream
180182
--------------------------------------
181183

‎performance.rst

Lines changed: 133 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -8,14 +8,24 @@ Symfony is fast, right out of the box. However, you can make it faster if you
88
optimize your servers and your applications as explained in the following
99
performance checklists.
1010

11-
Symfony Application Checklist
12-
-----------------------------
11+
Performance Checklists
12+
----------------------
1313

14-
These are the code and configuration changes that you can make in your Symfony
15-
application to improve its performance:
14+
Use these checklists to verify that your application and server are configured
15+
for maximum performance:
1616

17-
#. :ref:`Install APCu Polyfill if your server uses APC <performance-install-apcu-polyfill>`
18-
#. :ref:`Dump the service container into a single file <performance-service-container-single-file>`
17+
* **Symfony Application Checklist**:
18+
19+
#. :ref:`Install APCu Polyfill if your server uses APC <performance-install-apcu-polyfill>`
20+
21+
* **Production Server Checklist**:
22+
23+
#. :ref:`Dump the service container into a single file <performance-service-container-single-file>`
24+
#. :ref:`Use the OPcache byte code cache <performance-use-opcache>`
25+
#. :ref:`Configure OPcache for maximum performance <performance-configure-opcache>`
26+
#. :ref:`Don't check PHP files timestamps <performance-dont-check-timestamps>`
27+
#. :ref:`Configure the PHP realpath Cache <performance-configure-realpath-cache>`
28+
#. :ref:`Optimize Composer Autoloader <performance-optimize-composer-autoloader>`
1929

2030
.. _performance-install-apcu-polyfill:
2131

@@ -72,19 +82,6 @@ container into a single file, which could improve performance when using
7282
// ...
7383
$container->setParameter('container.dumper.inline_factories', true);
7484
75-
Production Server Checklist
76-
---------------------------
77-
78-
These are the changes that you can make in your production server to improve
79-
performance when running Symfony applications:
80-
81-
#. :ref:`Use the OPcache byte code cache <performance-use-opcache>`
82-
#. :ref:`Use the OPcache class preloading <performance-use-preloading>`
83-
#. :ref:`Configure OPcache for maximum performance <performance-configure-opcache>`
84-
#. :ref:`Don't check PHP files timestamps <performance-dont-check-timestamps>`
85-
#. :ref:`Configure the PHP realpath Cache <performance-configure-realpath-cache>`
86-
#. :ref:`Optimize Composer Autoloader <performance-optimize-composer-autoloader>`
87-
8885
.. _performance-use-opcache:
8986

9087
Use the OPcache Byte Code Cache
@@ -212,6 +209,120 @@ deployment process too):
212209
used in your application and prevents Composer from scanning the file system for
213210
classes that are not found in the class map. (see: `Composer's autoloader optimization`_).
214211

212+
.. _profiling-applications:
213+
214+
Profiling Applications
215+
----------------------
216+
217+
`Blackfire`_ is the best tool to profile and optimize performance of Symfony
218+
applications during development, test and production. It's a commercial service,
219+
but provides free features that you can use to find bottlenecks in your projects.
220+
221+
Symfony provides a basic performance profiler in the development
222+
:ref:`config environment <configuration-environments>`. Click on the "time panel"
223+
of the :ref:`web debug toolbar <web-debug-toolbar>` to see how much time Symfony
224+
spent on tasks such as making database queries and rendering templates.
225+
226+
Custom Profiling
227+
~~~~~~~~~~~~~~~~
228+
229+
You can measure the execution time and memory consumption of your own code and
230+
display the result in the Symfony profiler thanks to the `Stopwatch component`_.
231+
232+
When using :ref:`autowiring <services-autowire>`, type-hint any controller or
233+
service argument with the :class:`Symfony\\Component\\Stopwatch\\Stopwatch` class
234+
and Symfony will inject the ``debug.stopwatch`` service::
235+
236+
use Symfony\Component\Stopwatch\Stopwatch;
237+
238+
class DataExporter
239+
{
240+
private $stopwatch;
241+
242+
public function __construct(Stopwatch $stopwatch)
243+
{
244+
$this->stopwatch = $stopwatch;
245+
}
246+
247+
public function export()
248+
{
249+
// the argument is the name of the "profiling event"
250+
$this->stopwatch->start('export-data');
251+
252+
// ...do things to export data...
253+
254+
// reset the stopwatch to delete all the data measured so far
255+
// $this->stopwatch->reset();
256+
257+
$this->stopwatch->stop('export-data');
258+
}
259+
}
260+
261+
If the request calls this service during its execution, you'll see a new
262+
event called ``export-data`` in the Symfony profiler.
263+
264+
The ``start()``, ``stop()`` and ``getEvent()`` methods return a
265+
:class:`Symfony\\Component\\Stopwatch\\StopwatchEvent` object that provides
266+
information about the current event, even while it's still running. This
267+
object can be converted to a string for a quick summary::
268+
269+
// ...
270+
dump((string) $this->stopwatch->getEvent()); // dumps e.g. '4.50 MiB - 26 ms'
271+
272+
You can also profile your template code with the :ref:`stopwatch Twig tag <reference-twig-tag-stopwatch>`:
273+
274+
.. code-block:: twig
275+
276+
{% stopwatch 'render-blog-posts' %}
277+
{% for post in blog_posts%}
278+
{# ... #}
279+
{% endfor %}
280+
{% endstopwatch %}
281+
282+
Profiling Categories
283+
....................
284+
285+
Use the second optional argument of the ``start()`` method to define the
286+
category or tag of the event. This helps keep events organized by type::
287+
288+
$this->stopwatch->start('export-data', 'export');
289+
290+
Profiling Periods
291+
.................
292+
293+
A `real-world stopwatch`_ not only includes the start/stop button but also a
294+
"lap button" to measure each partial lap. This is exactly what the ``lap()``
295+
method does, which stops an event and then restarts it immediately::
296+
297+
$this->stopwatch->start('process-data-records', 'export');
298+
299+
foreach ($records as $record) {
300+
// ... some code goes here
301+
$this->stopwatch->lap('process-data-records');
302+
}
303+
304+
$event = $this->stopwatch->stop('process-data-records');
305+
// $event->getDuration(), $event->getMemory(), etc.
306+
307+
// Lap information is stored as "periods" within the event:
308+
// $event->getPeriods();
309+
310+
Profiling Sections
311+
..................
312+
313+
Sections are a way to split the profile timeline into groups. Example::
314+
315+
$this->stopwatch->openSection();
316+
$this->stopwatch->start('validating-file', 'validation');
317+
$this->stopwatch->stopSection('parsing');
318+
319+
$events = $this->stopwatch->getSectionEvents('parsing');
320+
321+
// later you can reopen a section passing its name to the openSection() method
322+
$this->stopwatch->openSection('parsing');
323+
$this->stopwatch->start('processing-file');
324+
$this->stopwatch->stopSection('parsing');
325+
215326
Learn more
216327
----------
217328

@@ -225,3 +336,6 @@ Learn more
225336
.. _`APCu PHP functions`: https://www.php.net/manual/en/ref.apcu.php
226337
.. _`cachetool`: https://github.com/gordalina/cachetool
227338
.. _`open_basedir`: https://www.php.net/manual/ini.core.php#ini.open-basedir
339+
.. _`Blackfire`: https://blackfire.io/docs/introduction?utm_source=symfony&utm_medium=symfonycom_docs&utm_campaign=performance
340+
.. _`Stopwatch component`: https://symfony.com/components/Stopwatch
341+
.. _`real-world stopwatch`: https://en.wikipedia.org/wiki/Stopwatch

‎profiler.rst

Lines changed: 2 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -98,23 +98,8 @@ Timing the Execution of the Application
9898
---------------------------------------
9999

100100
If you want to measure the time some tasks take in your application, there's no
101-
need to create a custom data collector. Instead, use the `Stopwatch component`_
102-
which provides utilities to profile code and displays the results on the
103-
"Performance" panel of the Profiler web interface.
104-
105-
When using :ref:`autowiring <services-autowire>`, type-hint any argument with
106-
the :class:`Symfony\\Component\\Stopwatch\\Stopwatch` class and Symfony will
107-
inject the Stopwatch service. Then, use the ``start()``, ``lap()`` and
108-
``stop()`` methods to measure time::
109-
110-
// a user signs up and the timer starts...
111-
$stopwatch->start('user-sign-up');
112-
113-
// ...do things to sign up the user...
114-
$stopwatch->lap('user-sign-up');
115-
116-
// ...the sign up process is finished
117-
$stopwatch->stop('user-sign-up');
101+
need to create a custom data collector. Instead, use the built-in utilities to
102+
:ref:`profile Symfony applications <profiling-applications>`.
118103

119104
.. tip::
120105

@@ -229,5 +214,4 @@ event::
229214
profiler/data_collector
230215

231216
.. _`Single-page applications`: https://en.wikipedia.org/wiki/Single-page_application
232-
.. _`Stopwatch component`: https://symfony.com/components/Stopwatch
233217
.. _`Blackfire`: https://blackfire.io/docs/introduction?utm_source=symfony&utm_medium=symfonycom_docs&utm_campaign=profiler

‎reference/twig_reference.rst

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -601,15 +601,17 @@ trans_default_domain
601601

602602
This will set the default domain in the current template.
603603

604+
.. _reference-twig-tag-stopwatch:
605+
604606
stopwatch
605607
~~~~~~~~~
606608

607609
.. code-block:: twig
608610
609-
{% stopwatch 'name' %}...{% endstopwatch %}
611+
{% stopwatch 'event_name' %}...{% endstopwatch %}
610612
611-
This will time the run time of the code inside it and put that on the timeline
612-
of the WebProfilerBundle.
613+
This measures the time and memory used to execute some code in the template and
614+
displays it in the Symfony profiler. See :ref:`how to profile Symfony applications <profiling-applications>`.
613615

614616
.. _reference-twig-tests:
615617

0 commit comments

Comments
 (0)
0