Updated the profiler matchers article

cookbook/profiler/matchers.rst

@@ -4,20 +4,21 @@
 How to Use Matchers to Enable the Profiler Conditionally
 ========================================================
 
-By default, the profiler is only activated in the development environment. But
-it's imaginable that a developer may want to see the profiler even in
-production. Another situation may be that you want to show the profiler only
-when an admin has logged in. You can enable the profiler in these situations
-by using matchers.
+The Symfony profiler is only activated in the development environment to not hurt
+your application performance. However, sometimes it may be useful to conditionally
+enable the profiler in the production environment to assist you in hard to debug
+issues. This behavior is implemented with the **Request Matchers** defined by
+Symfony.
 
 Using the built-in Matcher
 --------------------------
 
-Symfony provides a
+A Request Matcher is a class that compares a pre-defined set of checks against a
+given ``Request`` instance. Symfony provides a built-in
 :class:`built-in matcher <Symfony\\Component\\HttpFoundation\\RequestMatcher>`
-which can match paths and IPs. For example, if you want to only show the
-profiler when accessing the page with the ``168.0.0.1`` IP, then you can
-use this configuration:
+which matches paths and IPs. For example, if you want to only show the profiler
+when accessing the page with the ``168.0.0.1`` IP, then you can use this
+configuration:
 
 .. configuration-block::
 
@@ -50,22 +51,24 @@ use this configuration:
 
 You can also set a ``path`` option to define the path on which the profiler
 should be enabled. For instance, setting it to ``^/admin/`` will enable the
-profiler only for the ``/admin/`` URLs.
+profiler only for the URLs which start with ``/admin/``.
 
-Creating a custom Matcher
+Creating a Custom Matcher
 -------------------------
 
-You can also create a custom matcher. This is a service that checks whether
-the profiler should be enabled or not. To create that service, create a class
+Leveraging the concept of Request Matchers you can define a custom matcher to
+enable the profiler conditionally in your application. To do so, create a class
 which implements
 :class:`Symfony\\Component\\HttpFoundation\\RequestMatcherInterface`. This
 interface requires one method:
 :method:`Symfony\\Component\\HttpFoundation\\RequestMatcherInterface::matches`.
-This method returns false to disable the profiler and true to enable the
-profiler.
+This method returns ``false`` when the request doesn't match the conditions and
+``true`` otherwise. Therefore, the custom matcher must return ``false`` to
+disable the profiler and ``true`` to enable it.
 
-To enable the profiler when a ``ROLE_SUPER_ADMIN`` is logged in, you can use
-something like::
+Suppose that the profiler must be enabled whenever a user with a
+``ROLE_SUPER_ADMIN`` is logged in. This is the only code needed for that custom
+matcher::
 
  // src/AppBundle/Profiler/SuperAdminMatcher.php
  namespace AppBundle\Profiler;
@@ -89,24 +92,26 @@ something like::
  }
  }
 
-Then, you need to configure the service:
+Then, configure the service and set it as ``private`` because the application
+won't use it directly:
 
 .. configuration-block::
 
  .. code-block:: yaml
 
  # app/config/services.yml
  services:
- app.profiler.matcher.super_admin:
+ app.super_admin_matcher:
  class: AppBundle\Profiler\SuperAdminMatcher
  arguments: ["@security.context"]
+ public: false
 
  .. code-block:: xml
 
  <!-- app/config/services.xml -->
  <services>
- <service id="app.profiler.matcher.super_admin"
- class="AppBundle\Profiler\SuperAdminMatcher">
+ <service id="app.super_admin_matcher"
+ class="AppBundle\Profiler\SuperAdminMatcher" public="false">
  <argument type="service" id="security.context" />
  </services>
 
@@ -116,12 +121,15 @@ Then, you need to configure the service:
  use Symfony\Component\DependencyInjection\Definition;
  use Symfony\Component\DependencyInjection\Reference;
 
- $container->setDefinition('app.profiler.matcher.super_admin', new Definition(
+ $definition = new Definition(
  'AppBundle\Profiler\SuperAdminMatcher',
  array(new Reference('security.context'))
  );
+ $definition->setPublic(false);
 
-Now the service is registered, the only thing left to do is configure the
+ $container->setDefinition('app.super_admin_matcher', $definition);
+
+Once the service is registered, the only thing left to do is configure the
 profiler to use this service as the matcher:
 
 .. configuration-block::
@@ -133,15 +141,15 @@ profiler to use this service as the matcher:
  # ...
  profiler:
  matcher:
- service: app.profiler.matcher.super_admin
+ service: app.super_admin_matcher
 
  .. code-block:: xml
 
  <!-- app/config/config.xml -->
  <framework:config>
  <!-- ... -->
  <framework:profiler
- service="app.profiler.matcher.super_admin"
+ service="app.super_admin_matcher"
  />
  </framework:config>
 
@@ -151,6 +159,6 @@ profiler to use this service as the matcher:
  $container->loadFromExtension('framework', array(
  // ...
  'profiler' => array(
- 'service' => 'app.profiler.matcher.super_admin',
+ 'service' => 'app.super_admin_matcher',
  ),
  ));