From e0d304f7248f55abb13a55406799a45304e58c61 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 3 Aug 2015 15:47:51 +0200 Subject: [PATCH 1/2] Updated the profiler matchers article --- cookbook/profiler/matchers.rst | 60 +++++++++++++++++++--------------- 1 file changed, 34 insertions(+), 26 deletions(-) diff --git a/cookbook/profiler/matchers.rst b/cookbook/profiler/matchers.rst index 2a990aff333..50bcf8eab5f 100644 --- a/cookbook/profiler/matchers.rst +++ b/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 ` -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,7 +92,8 @@ 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:: @@ -97,16 +101,17 @@ Then, you need to configure the service: # 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 - + @@ -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,7 +141,7 @@ profiler to use this service as the matcher: # ... profiler: matcher: - service: app.profiler.matcher.super_admin + service: app.super_admin_matcher .. code-block:: xml @@ -141,7 +149,7 @@ profiler to use this service as the matcher: @@ -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', ), )); From 00a66879fdcac0cebfc6786e548cdf257e9c85f9 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 3 Aug 2015 17:51:00 +0200 Subject: [PATCH 2/2] Minor rewordings --- cookbook/profiler/matchers.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/cookbook/profiler/matchers.rst b/cookbook/profiler/matchers.rst index 50bcf8eab5f..0bf1ad9ef0e 100644 --- a/cookbook/profiler/matchers.rst +++ b/cookbook/profiler/matchers.rst @@ -7,14 +7,13 @@ How to Use Matchers to Enable the Profiler Conditionally 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. +issues. This behavior is implemented with the **Request Matchers**. Using the built-in Matcher -------------------------- -A Request Matcher is a class that compares a pre-defined set of checks against a -given ``Request`` instance. Symfony provides a built-in +A Request Matcher is a class that checks whether a given ``Request`` instance +matches a set of conditions. Symfony provides a :class:`built-in matcher ` 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 @@ -92,7 +91,7 @@ matcher:: } } -Then, configure the service and set it as ``private`` because the application +Then, configure a new service and set it as ``private`` because the application won't use it directly: .. configuration-block::