|
| 1 | +.. index:: |
| 2 | + single: Stopwatch |
| 3 | + single: Components; Stopwatch |
| 4 | + |
| 5 | +The Stopwatch Component |
| 6 | +======================= |
| 7 | + |
| 8 | + Stopwatch component provides a way to profile code. |
| 9 | + |
| 10 | +Installation |
| 11 | +------------ |
| 12 | + |
| 13 | +You can install the component in two different ways: |
| 14 | + |
| 15 | +* Use the official Git repository (https://github.com/symfony/Stopwatch); |
| 16 | +* :doc:`Install it via Composer</components/using_components>` (``symfony/stopwatch`` on `Packagist`_). |
| 17 | + |
| 18 | +Usage |
| 19 | +----- |
| 20 | + |
| 21 | +The Stopwatch component provides an easy and consistent way to measure execution time of certain parts of code, so that yo
8000
u don't constantly have to parse microtime by yourself. The basic usage is as simple as this:: |
| 22 | + |
| 23 | + use Symfony\Component\Stopwatch\Stopwatch; |
| 24 | + |
| 25 | + $stopwatch = new Stopwatch(); |
| 26 | + // Start event named 'eventName' |
| 27 | + $stopwatch->start('eventName'); |
| 28 | + // some code goes here |
| 29 | + $event = $stopwatch->stop('eventName'); |
| 30 | + |
| 31 | +You also can provide a category name to an event:: |
| 32 | + |
| 33 | + $stopwatch->start('eventName', 'categoryName'); |
| 34 | + |
| 35 | +You can consider categories as a way of tagging events. The Symfony Profiler tool uses categories to nicely colorcode different events. |
| 36 | + |
| 37 | +Periods |
| 38 | +------- |
| 39 | + |
| 40 | +As we all know from the real world, all stopwatches come with two buttons. One for starting and stopping the stopwatch, another to measure the lap time. And that's exactly what lap method does. :: |
| 41 | + |
| 42 | + $stopwatch = new Stopwatch(); |
| 43 | + // Start event named 'foo' |
| 44 | + $stopwatch->start('foo'); |
| 45 | + // some code goes here |
| 46 | + $stopwatch->lap('foo'); |
| 47 | + // some code goes here |
| 48 | + $stopwatch->lap('foo'); |
| 49 | + // some other code goes here |
| 50 | + $event = $stopwatch->stop('foo'); |
| 51 | + |
| 52 | +Lap information is stored in periods within the event. To get lap information aka periods call :: |
| 53 | + |
| 54 | + $event->getPeriods(); |
| 55 | + |
| 56 | +Besides getting periods, we can get other useful information from the event object. E.g:: |
| 57 | + |
| 58 | + $event->getCategory(); // Returns the category the evenent was started in |
| 59 | + $event->getOrigin(); // Returns the start time of the Event in milliseconds |
| 60 | + $event->ensureStopped(); // Stops all non already stopped periods |
| 61 | + $event->getStartTime(); // Returns the start of the very first period |
| 62 | + $event->getEndTime(); // Returns the end time of the very last period |
| 63 | + $event->getDuration(); // Gets the duration (including all periods) of the event |
| 64 | + $event->getMemory(); // Gets the max memory usage of all periods |
| 65 | + |
| 66 | + |
| 67 | +Sections |
| 68 | +-------- |
| 69 | + |
| 70 | +Sections are a way to logically split the timeline into groups. You can see how Symfony uses sections to nicely visualize framework lifecycle in the Symfony Profiler tool. Here is a basic usage of sections.:: |
| 71 | + |
| 72 | + $stopwatch = new Stopwatch(); |
| 73 | + |
| 74 | + $stopwatch->openSection(); |
| 75 | + $stopwatch->start('parisng_config_file', 'filesystem_operations'); |
| 76 | + $stopwatch->stopSection('routing'); |
| 77 | + |
| 78 | + $events = $stopwatch->getSectionEvents('section'); |
| 79 | + |
| 80 | + |
| 81 | +You can reopen a closed section by calling the openSection method and specifying an id of the section to be reopened. e.g.:: |
| 82 | + |
| 83 | + $stopwatch->openSection('routing'); |
| 84 | + $stopwatch->start('building_config_tree'); |
| 85 | + $stopwatch->stopSection('routing'); |
| 86 | + |
| 87 | +.. _Packagist: https://packagist.org/packages/symfony/stopwatch |
0 commit comments