Merged some profiler docs into a single main Profiler article

_build/redirection_map

@@ -405,3 +405,6 @@
 /console/logging /console
 /reference/forms/twig_reference /form/form_customization
 /form/rendering /form/form_customization
+/profiler/matchers /profiler
+/profiler/profiling_data /profiler
+/profiler/wdt_follow_ajax /profiler

components/stopwatch.rst

@@ -63,9 +63,8 @@ Symfony Profiler tool uses categories to nicely color-code different events.
 
 .. tip::
 
-    When you want to show events in the Symfony profiler, autowire
-    ``Symfony\Component\Stopwatch\Stopwatch`` into your service. Each category
-    is shown on a separate line.
+    Read :ref:`this article <profiler-timing-execution>` to learn more about
+    integrating the Stopwatch component into the Symfony profiler.
 
 Periods
 -------

profiler.rst

@@ -2,10 +2,8 @@ Profiler
 ========
 
 The profiler is a powerful **development tool** that gives detailed information
-about the execution of any request.
-
-**Never** enable the profiler in production environments as it will lead to
-major security vulnerabilities in your project.
+about the execution of any request. **Never** enable the profiler in production
+environments as it will lead to major security vulnerabilities in your project.
 
 Installation
 ------------
@@ -17,10 +15,207 @@ install the profiler before using it:
 
     $ composer require --dev symfony/profiler-pack
 
+Now browse any page of your application in the development environment to let
+the profiler collect information. Then, click on any element of the debug
+toolbar injected at the bottom of your pages to open the web interface of the
+Symfony Profiler, which will look like this:
+
+.. image:: /_images/profiler/web-interface.png
+   :align: center
+   :class: with-browser
+
+Accessing Profiling Data Programmatically
+-----------------------------------------
+
+Most of the times, the profiler information is accessed and analyzed using its
+web-based interface. However, you can also retrieve profiling information
+programmatically thanks to the methods provided by the ``profiler`` service.
+
+When the response object is available, use the
+:method:`Symfony\\Component\\HttpKernel\\Profiler\\Profiler::loadProfileFromResponse`
+method to access to its associated profile::
+
+    // ... $profiler is the 'profiler' service
+    $profile = $profiler->loadProfileFromResponse($response);
+
+When the profiler stores data about a request, it also associates a token with it;
+this token is available in the ``X-Debug-Token`` HTTP header of the response.
+Using this token, you can access the profile of any past response thanks to the
+:method:`Symfony\\Component\\HttpKernel\\Profiler\\Profiler::loadProfile` method::
+
+    $token = $response->headers->get('X-Debug-Token');
+    $profile = $profiler->loadProfile($token);
+
+.. tip::
+
+    When the profiler is enabled but not the web debug toolbar, inspect the page
+    with your browser's developer tools to get the value of the ``X-Debug-Token``
+    HTTP header.
+
+The ``profiler`` service also provides the
+:method:`Symfony\\Component\\HttpKernel\\Profiler\\Profiler::find` method to
+look for tokens based on some criteria::
+
+    // gets the latest 10 tokens
+    $tokens = $profiler->find('', '', 10, '', '', '');
+
+    // gets the latest 10 tokens for all URL containing /admin/
+    $tokens = $profiler->find('', '/admin/', 10, '', '', '');
+
+    // gets the latest 10 tokens for local POST requests
+    $tokens = $profiler->find('127.0.0.1', '', 10, 'POST', '', '');
+
+    // gets the latest 10 tokens for requests that happened between 2 and 4 days ago
+    $tokens = $profiler->find('', '', 10, '', '4 days ago', '2 days ago');
+
+Data Collectors
+---------------
+
+The profiler gets its information using some services called "data collectors".
+Symfony comes with several collectors that get information about the request,
+the logger, the routing, the cache, etc.
+
+Run this command to get the list of collectors actually enabled in your app:
+
+.. code-block:: terminal
+
+    $ php bin/console debug:container --tag=data_collector
+
+You can also :doc:`create your own data collector </profiler/data_collector>` to
+store any data generated by your app and display it in the debug toolbar and the
+profiler web interface.
+
+.. _profiler-timing-execution:
+
+Timing the Execution of the Application
+---------------------------------------
+
+If you want to measure the time some tasks take in your application, there's no
+need to create a custom data collector. Instead, use the `Stopwatch component`_
+which provides utilities to profile code and displayes the results on the
+"Performance" panel of the Profiler web interface.
+
+When using :ref:`autowiring <services-autowire>`, type-hint any argument with
+the :class:`Symfony\\Component\\Stopwatch\\Stopwatch` class and Symfony will
+inject the Stopwatch service. Then, use the ``start()``, ``lapse()`` and
+``stop()`` methods to measure time::
+
+    // a user signs up and the timer starts...
+    $stopwatch->start('user-sign-up');
+
+    // ...do things to sign up the user...
+    $stopwatch->lapse('user-sign-up');
+
+    // ...the sign up process is finished
+    $stopwatch->stop('user-sign-up');
+
+.. tip::
+
+    Consider using a professional profiler such as `Blackfire`_ to measure and
+    analyze the execution of your application in detail.
+
+Enabling the Profiler Conditionally
+-----------------------------------
+
+.. caution::
+
+    The possibility to use a matcher to enable the profiler conditionally was
+    removed in Symfony 4.0.
+
+Symfony Profiler cannot be enabled/disabled conditionally using matchers, because
+that feature was removed in Symfony 4.0. However, you can use the ``enable()``
+and ``disable()`` methods of the :class:`Symfony\\Component\\HttpKernel\\Profiler\\Profiler`
+class in your controllers to manage the profiler programmatically::
+
+    use Symfony\Component\HttpKernel\Profiler\Profiler;
+    // ...
+
+    class DefaultController
+    {
+        // ...
+
+        public function someMethod(?Profiler $profiler)
+        {
+            // $profiler won't be set if your environment doesn't have the profiler (like prod, by default)
+            if (null !== $profiler) {
+                // if it exists, disable the profiler for this particular controller action
+                $profiler->disable();
+            }
+
+            // ...
+        }
+    }
+
+In order for the profiler to be injected into your controller you need to
+create an alias pointing to the existing ``profiler`` service:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/services_dev.yaml
+        services:
+            Symfony\Component\HttpKernel\Profiler\Profiler: '@profiler'
+
+    .. code-block:: xml
+
+        <!-- config/services_dev.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                http://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <services>
+                <service id="Symfony\Component\HttpKernel\Profiler\Profiler" alias="profiler" />
+            </services>
+        </container>
+
+    .. code-block:: php
+
+        // config/services_dev.php
+        use Symfony\Component\HttpKernel\Profiler\Profiler;
+
+        $container->setAlias(Profiler::class, 'profiler');
+
+Updating the Web Debug Toolbar After AJAX Requests
+--------------------------------------------------
+
+`Single-page applications`_ (SPA) are web applications that interact with the
+user by dynamically rewriting the current page rather than loading entire new
+pages from a server.
+
+By default, the debug toolbar displays the information of the initial page load
+and doesn't refresh after each AJAX request. However, you can set the
+``Symfony-Debug-Toolbar-Replace`` header to a value of ``1`` in the response to
+the AJAX request to force the refresh of the toolbar::
+
+    $response->headers->set('Symfony-Debug-Toolbar-Replace', 1);
+
+Ideally this header should only be set during development and not for
+production. To do that, create an :doc:`event subscriber </event_dispatcher>`
+and listen to the :ref:`kernel.response<component-http-kernel-kernel-response>`
+event::
+
+    use Symfony\Component\HttpKernel\Event\FilterResponseEvent;
+
+    // ...
+
+    public function onKernelResponse(FilterResponseEvent $event)
+    {
+        if (!$this->getKernel()->isDebug()) {
+            return;
+        }
+
+        $response = $event->getResponse();
+        $response->headers->set('Symfony-Debug-Toolbar-Replace', 1);
+    }
+
 .. toctree::
-    :maxdepth: 1
+    :hidden:
 
     profiler/data_collector
-    profiler/profiling_data
-    profiler/matchers
-    profiler/wdt_follow_ajax
+
+.. _`Single-page applications`: https://en.wikipedia.org/wiki/Single-page_application
+.. _`Stopwatch component`: https://symfony.com/components/Stopwatch
+.. _`Blackfire`: https://blackfire.io/