Skip to content

Added documentation about profiler matchers #2785

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Aug 10, 2013
Merged

Added documentation about profiler matchers #2785

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
39e8094
Added documentation about profiler matchers
wouterj Jun 29, 2013
1038fb8
Removed duplicated stuff
wouterj Jul 30, 2013
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
87 changes: 2 additions & 85 deletions book/internals.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -620,91 +620,8 @@ As the profiler adds some overhead, you might want to enable it only under
certain circumstances in the production environment. The ``only-exceptions``
settings limits profiling to 500 pages, but what if you want to get
information when the client IP comes from a specific address, or for a limited
portion of the website? You can use a request matcher:

.. configuration-block::

.. code-block:: yaml

# enables the profiler only for request coming for the 192.168.0.0 network
framework:
profiler:
matcher: { ip: 192.168.0.0/24 }

# enables the profiler only for the /admin URLs
framework:
profiler:
matcher: { path: "^/admin/" }

# combine rules
framework:
profiler:
matcher: { ip: 192.168.0.0/24, path: "^/admin/" }

# use a custom matcher instance defined in the "custom_matcher" service
framework:
profiler:
matcher: { service: custom_matcher }

.. code-block:: xml

<!-- enables the profiler only for request coming for the 192.168.0.0 network -->
<framework:config>
<framework:profiler>
<framework:matcher ip="192.168.0.0/24" />
</framework:profiler>
</framework:config>

<!-- enables the profiler only for the /admin URLs -->
<framework:config>
<framework:profiler>
<framework:matcher path="^/admin/" />
</framework:profiler>
</framework:config>

<!-- combine rules -->
<framework:config>
<framework:profiler>
<framework:matcher ip="192.168.0.0/24" path="^/admin/" />
</framework:profiler>
</framework:config>

<!-- use a custom matcher instance defined in the "custom_matcher" service -->
<framework:config>
<framework:profiler>
<framework:matcher service="custom_matcher" />
</framework:profiler>
</framework:config>

.. code-block:: php

// enables the profiler only for request coming for the 192.168.0.0 network
$container->loadFromExtension('framework', array(
'profiler' => array(
'matcher' => array('ip' => '192.168.0.0/24'),
),
));

// enables the profiler only for the /admin URLs
$container->loadFromExtension('framework', array(
'profiler' => array(
'matcher' => array('path' => '^/admin/'),
),
));

// combine rules
$container->loadFromExtension('framework', array(
'profiler' => array(
'matcher' => array('ip' => '192.168.0.0/24', 'path' => '^/admin/'),
),
));

# use a custom matcher instance defined in the "custom_matcher" service
$container->loadFromExtension('framework', array(
'profiler' => array(
'matcher' => array('service' => 'custom_matcher'),
),
));
portion of the website? You can use a Profiler Matcher, learn more about that
in ":doc:`/cookbook/profiler/matchers`".

Learn more from the Cookbook
----------------------------
Expand Down
1 change: 1 addition & 0 deletions cookbook/map.rst.inc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -100,6 +100,7 @@
* :doc:`/cookbook/profiler/index`

* :doc:`/cookbook/profiler/data_collector`
* :doc:`/cookbook/profiler/matchers`

* :doc:`/cookbook/request/index`

Expand Down
1 change: 1 addition & 0 deletions cookbook/profiler/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,3 +5,4 @@ Profiler
:maxdepth: 2

data_collector
matchers
164 changes: 164 additions & 0 deletions cookbook/profiler/matchers.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,164 @@
.. index::
single: Profiling; Matchers

How to use Matchers to enable the Profiler
==========================================

By default, the profiler is only activated in the development environment. But
it's imaginable that a developer always wants to see the profiler, even in
production. Another situation may be to show the profiler when an admin has
logged in. You can enable the profiler in these situations by using matchers.

Using the build-in Matcher
--------------------------

Symfony2 provides a
:class:`build-in matcher <Symfony\\Component\\HttpFoundation\\RequestMatcher>`
which can match paths and IPs. For instance, only show the profiler when
accessing the page with the ``168.0.0.1`` ip. Then, the profiler can be
configured to something like this:

.. configuration-block::

.. code-block:: yaml

# app/config/config.yml
framework:
# ...
profiler:
matcher:
ip: 168.0.0.1

.. code-block:: xml

<!-- app/config/config.xml -->
<framework:config>
<framework:profiler
ip="168.0.0.1"
/>
</framework:config>

.. code-block:: php

// app/config/config.php
$container->loadFromExtension('framework', array(
'profiler' => array(
'ip' => '168.0.0.1',
),
));

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.

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
which implements
:class:`Symfony\\Component\\HttpFoundation\\RequestMatcherInterface`. This
interface requires one method:
:method:`Symfony\\Component\\HttpFoundation\\RequestMatcherInterface::matches`.
This method returns a falsey value to disable the profiler, any other value
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

false

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

no falsey value, so 0, array(), null and false.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I changed it to false at sha: 826197b. The reason is that even though the implementation (i.e. the class in Symfony that calls matches and uses its value) allows for a "falsey" value, the RequestMatcherInterface::matches states that this method returns a boolean.

Obviously, small detail - but I wanted to explain why I chose to change it :).

Thanks!

enables the profiler.

To enable the profiler when a ``ROLE_SUPER_ADMIN`` is logged in, you can use
something like::

// src/Acme/DemoBundle/Profiler/SuperAdminMatcher.php
namespace Acme\DemoBundle\Profiler;

use Symfony\Component\Security\Core\SecurityContext;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\RequestMatcherInterface;

class SuperAdminMatcher implements RequestMatcherInterface
{
protected $securityContext;

public function __construct(SecurityContext $securityContext)
{
$this->securityContext = $securityContext;
}

public function matches(Request $request)
{
return $this->securityContext->isGranted('ROLE_SUPER_ADMIN');
}
}

Then, you need to configure the service:

.. configuration-block::

.. code-block:: yaml

parameters:
acme_demo.profiler.matcher.super_admin.class: Acme\DemoBundle\Profiler\SuperAdminMatcher

services:
acme_demo.profiler.matcher.super_admin:
class: "%acme_demo.profiler.matcher.super_admin.class%"
arguments: [@security.context]

.. code-block:: xml

<parameters>
<parameter
key="acme_demo.profiler.matcher.super_admin.class"
>Acme\DemoBundle\Profiler\SuperAdminMatcher</parameter>
</parameters>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For me this looks pretty ugly.

<parameters>
    <parameter key="acme_demo.profiler.matcher.super_admin.class">
        Acme\DemoBundle\Profiler\SuperAdminMatcher
    </parameter>
</parameters>

Is what I prefer.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it looks really ugly, but your solution won't work AFAIK. Whitespaces aren't removed from parameter values,


<services>
<service id="acme_demo.profiler.matcher.super_admin"
class="%acme_demo.profiler.matcher.super_admin.class%">
<argument type="service" id="security.context" />
</services>

.. code-block:: php

use Symfony\Component\DependencyInjection\Definition;
use Symfony\Component\DependencyInjection\Reference;

$container->setParameter(
'acme_demo.profiler.matcher.super_admin.class',
'Acme\DemoBundle\Profiler\SuperAdminMatcher'
);

$container->setDefinition('acme_demo.profiler.matcher.super_admin', new Definition(
'%acme_demo.profiler.matcher.super_admin.class%',
array(new Reference('security.context'))
);

Now the service is registered, the only thing left to do is configure the
profiler to use this service as the matcher:

.. configuration-block::

.. code-block:: yaml

# app/config/config.yml
framework:
# ...
profiler:
matcher:
service: acme_demo.profiler.matcher.super_admin

.. code-block:: xml

<!-- app/config/config.xml -->
<framework:config>
<framework:profiler
service="acme_demo.profiler.matcher.super_admin"
/>
</framework:config>

.. code-block:: php

// app/config/config.php
$container->loadFromExtension('framework', array(
'profiler' => array(
'service' => 'acme_demo.profiler.matcher.super_admin',
),
));