Skip to content

Commit 59f0374

Browse files
weaverryanweaverryan
committed
feature #4490 Documented ExpressionLanguage extensibility (WouterJ)
This PR was merged into the 2.6 branch. Discussion ---------- Documented ExpressionLanguage extensibility | Q | A | --- | --- | Doc fix? | no | New docs? | yes (symfony/symfony#12006) | Applies to | 2.6+ | Fixed tickets | #4289 Commits ------- 086885b Applied comments ef4ca42 Documented new tags c553193 Documented expressionlanguage extensibility
2 parents ed241ab + 086885b commit 59f0374

File tree

2 files changed

+127
-87
lines changed

2 files changed

+127
-87
lines changed

‎components/expression_language/extending.rst

+58-14
Original file line numberDiff line numberDiff line change
@@ -51,24 +51,34 @@ an ``arguments`` variable as their first argument, which is equal to the
5151
second argument to ``evaluate()`` or ``compile()`` (e.g. the "values" when
5252
evaluating or the "names" if compiling).
5353

54-
Creating a new ExpressionLanguage Class
55-
---------------------------------------
54+
.. _components-expression-language-provider:
5655

57-
When you use the ``ExpressionLanguage`` class in your library, it's recommend
58-
to create a new ``ExpressionLanguage`` class and register the functions there.
59-
Override ``registerFunctions`` to add your own functions::
56+
Using Expression Providers
57+
--------------------------
6058

61-
namespace Acme\AwesomeLib\ExpressionLanguage;
59+
.. versionadded:: 2.6
60+
Expression providers were introduced in Symfony 2.6.
6261

63-
use Symfony\Component\ExpressionLanguage\ExpressionLanguage as BaseExpressionLanguage;
62+
When you use the ``ExpressionLanguage`` class in your library, you often want
63+
to add custom functions. To do so, you can create a new expression provider by
64+
creating a class that implements
65+
:class:`Symfony\\Component\\ExpressionLanguage\\ExpressionFunctionProviderInterface`.
6466

65-
class ExpressionLanguage extends BaseExpressionLanguage
66-
{
67-
protected function registerFunctions()
68-
{
69-
parent::registerFunctions(); // do not forget to also register core functions
67+
This interface requires one method:
68+
:method:`Symfony\\Component\\ExpressionLanguage\\ExpressionFunctionProviderInterface::getFunctions`,
69+
which returns an array of expression functions (instances of
70+
:class:`Symfony\\Component\\ExpressionLanguage\\ExpressionFunction`) to
71+
register.
72+
73+
.. code-block:: php
74+
75+
use Symfony\Component\ExpressionLanguage\ExpressionFunction;
76+
use Symfony\Component\ExpressionLanguage\ExpressionFunctionProviderInterface;
7077
71-
$this->register('lowercase', function ($str) {
78+
class StringExpressionLanguageProvider implements ExpressionFunctionProviderInterface
79+
{
80+
return array(
81+
new ExpressionFunction('lowercase', function ($str) {
7282
return sprintf('(is_string(%1$s) ? strtolower(%1$s) : %1$s)', $str);
7383
}, function ($arguments, $str) {
7484
if (!is_string($str)) {
@@ -77,5 +87,39 @@ Override ``registerFunctions`` to add your own functions::
7787
7888
return strtolower($str);
7989
});
80-
}
90+
);
8191
}
92+
93+
You can register providers using
94+
:method:`Symfony\\Component\\ExpressionLanguage\\ExpressionLanguage::registerProvider`
95+
or by using the second argument of the constructor::
96+
97+
use Symfony\Component\ExpressionLanguage\ExpressionLanguage;
98+
99+
// using the constructor
100+
$language = new ExpressionLanguage(null, array(
101+
new StringExpressionLanguageProvider(),
102+
// ...
103+
));
104+
105+
// using registerProvider()
106+
$language->registerProvider(new StringExpressionLanguageProvider());
107+
108+
.. tip::
109+
110+
It is recommended to create your own ``ExpressionLanguage`` class in your
111+
library. Now you can add the extension by overriding the constructor::
112+
113+
use Symfony\Component\ExpressionLanguage\ExpressionLanguage as BaseExpressionLanguage;
114+
use Symfony\Component\ExpressionLanguage\ParserCache\ParserCacheInterface;
115+
116+
class ExpressionLanguage extends BaseExpressionLanguage
117+
{
118+
public function __construct(ParserCacheInterface $parser = null, array $providers = array())
119+
{
120+
// prepend the default provider to let users override it easily
121+
array_unshift($providers, new StringExpressionLanguageProvider());
122+
123+
parent::__construct($parser, $providers);
124+
}
125+
}

‎reference/dic_tags.rst

+69-73
Original file line numberDiff line numberDiff line change
@@ -12,79 +12,47 @@ section of the Service Container chapter.
1212
Below is information about all of the tags available inside Symfony. There
1313
may also be tags in other bundles you use that aren't listed here.
1414

15-
+-----------------------------------+---------------------------------------------------------------------------+
16-
| Tag Name | Usage |
17-
+===================================+===========================================================================+
18-
| `assetic.asset`_ | Register an asset to the current asset manager |
19-
+-----------------------------------+---------------------------------------------------------------------------+
20-
| `assetic.factory_worker`_ | Add a factory worker |
21-
+-----------------------------------+---------------------------------------------------------------------------+
22-
| `assetic.filter`_ | Register a filter |
23-
+-----------------------------------+---------------------------------------------------------------------------+
24-
| `assetic.formula_loader`_ | Add a formula loader to the current asset manager |
25-
+-----------------------------------+---------------------------------------------------------------------------+
26-
| `assetic.formula_resource`_ | Adds a resource to the current asset manager |
27-
+-----------------------------------+---------------------------------------------------------------------------+
28-
| `assetic.templating.php`_ | Remove this service if PHP templating is disabled |
29-
+-----------------------------------+---------------------------------------------------------------------------+
30-
| `assetic.templating.twig`_ | Remove this service if Twig templating is disabled |
31-
+-----------------------------------+---------------------------------------------------------------------------+
32-
| `console.command`_ | Add a command |
33-
+-----------------------------------+---------------------------------------------------------------------------+
34-
| `data_collector`_ | Create a class that collects custom data for the profiler |
35-
+-----------------------------------+---------------------------------------------------------------------------+
36-
| `doctrine.event_listener`_ | Add a Doctrine event listener |
37-
+-----------------------------------+---------------------------------------------------------------------------+
38-
| `doctrine.event_subscriber`_ | Add a Doctrine event subscriber |
39-
+-----------------------------------+---------------------------------------------------------------------------+
40-
| `form.type`_ | Create a custom form field type |
41-
+-----------------------------------+---------------------------------------------------------------------------+
42-
| `form.type_extension`_ | Create a custom "form extension" |
43-
+-----------------------------------+---------------------------------------------------------------------------+
44-
| `form.type_guesser`_ | Add your own logic for "form type guessing" |
45-
+-----------------------------------+---------------------------------------------------------------------------+
46-
| `kernel.cache_clearer`_ | Register your service to be called during the cache clearing process |
47-
+-----------------------------------+---------------------------------------------------------------------------+
48-
| `kernel.cache_warmer`_ | Register your service to be called during the cache warming process |
49-
+-----------------------------------+---------------------------------------------------------------------------+
50-
| `kernel.event_listener`_ | Listen to different events/hooks in Symfony |
51-
+-----------------------------------+---------------------------------------------------------------------------+
52-
| `kernel.event_subscriber`_ | To subscribe to a set of different events/hooks in Symfony |
53-
+-----------------------------------+---------------------------------------------------------------------------+
54-
| `kernel.fragment_renderer`_ | Add new HTTP content rendering strategies |
55-
+-----------------------------------+---------------------------------------------------------------------------+
56-
| `monolog.logger`_ | Logging with a custom logging channel |
57-
+-----------------------------------+---------------------------------------------------------------------------+
58-
| `monolog.processor`_ | Add a custom processor for logging |
59-
+-----------------------------------+---------------------------------------------------------------------------+
60-
| `routing.loader`_ | Register a custom service that loads routes |
61-
+-----------------------------------+---------------------------------------------------------------------------+
62-
| `security.voter`_ | Add a custom voter to Symfony's authorization logic |
63-
+-----------------------------------+---------------------------------------------------------------------------+
64-
| `security.remember_me_aware`_ | To allow remember me authentication |
65-
+-----------------------------------+---------------------------------------------------------------------------+
66-
| `serializer.encoder`_ | Register a new encoder in the ``serializer`` service |
67-
+-----------------------------------+---------------------------------------------------------------------------+
68-
| `serializer.normalizer`_ | Register a new normalizer in the ``serializer`` service |
69-
+-----------------------------------+---------------------------------------------------------------------------+
70-
| `swiftmailer.default.plugin`_ | Register a custom SwiftMailer Plugin |
71-
+-----------------------------------+---------------------------------------------------------------------------+
72-
| `templating.helper`_ | Make your service available in PHP templates |
73-
+-----------------------------------+---------------------------------------------------------------------------+
74-
| `translation.loader`_ | Register a custom service that loads translations |
75-
+-----------------------------------+---------------------------------------------------------------------------+
76-
| `translation.extractor`_ | Register a custom service that extracts translation messages from a file |
77-
+-----------------------------------+---------------------------------------------------------------------------+
78-
| `translation.dumper`_ | Register a custom service that dumps translation messages |
79-
+-----------------------------------+---------------------------------------------------------------------------+
80-
| `twig.extension`_ | Register a custom Twig Extension |
81-
+-----------------------------------+---------------------------------------------------------------------------+
82-
| `twig.loader`_ | Register a custom service that loads Twig templates |
83-
+-----------------------------------+---------------------------------------------------------------------------+
84-
| `validator.constraint_validator`_ | Create your own custom validation constraint |
85-
+-----------------------------------+---------------------------------------------------------------------------+
86-
| `validator.initializer`_ | Register a service that initializes objects before validation |
87-
+-----------------------------------+---------------------------------------------------------------------------+
15+
======================================== ========================================================================
16+
Tag Name Usage
17+
======================================== ========================================================================
18+
`assetic.asset`_ Register an asset to the current asset manager
19+
`assetic.factory_worker`_ Add a factory worker
20+
`assetic.filter`_ Register a filter
21+
`assetic.formula_loader`_ Add a formula loader to the current asset manager
22+
`assetic.formula_resource`_ Adds a resource to the current asset manager
23+
`assetic.templating.php`_ Remove this service if PHP templating is disabled
24+
`assetic.templating.twig`_ Remove this service if Twig templating is disabled
25+
`console.command`_ Add a command
26+
`data_collector`_ Create a class that collects custom data for the profiler
27+
`doctrine.event_listener`_ Add a Doctrine event listener
28+
`doctrine.event_subscriber`_ Add a Doctrine event subscriber
29+
`form.type`_ Create a custom form field type
30+
`form.type_extension`_ Create a custom "form extension"
31+
`form.type_guesser`_ Add your own logic for "form type guessing"
32+
`kernel.cache_clearer`_ Register your service to be called during the cache clearing process
33+
`kernel.cache_warmer`_ Register your service to be called during the cache warming process
34+
`kernel.event_listener`_ Listen to different events/hooks in Symfony
35+
`kernel.event_subscriber`_ To subscribe to a set of different events/hooks in Symfony
36+
`kernel.fragment_renderer`_ Add new HTTP content rendering strategies
37+
`monolog.logger`_ Logging with a custom logging channel
38+
`monolog.processor`_ Add a custom processor for logging
39+
`routing.loader`_ Register a custom service that loads routes
40+
`routing.expression_language_provider`_ Register a provider for expression language functions in routing
41+
`security.expression_language_provider`_ Register a provider for expression language functions in security
42+
`security.voter`_ Add a custom voter to Symfony's authorization logic
43+
`security.remember_me_aware`_ To allow remember me authentication
44+
`serializer.encoder`_ Register a new encoder in the ``serializer`` service
45+
`serializer.normalizer`_ Register a new normalizer in the ``serializer`` service
46+
`swiftmailer.default.plugin`_ Register a custom SwiftMailer Plugin
47+
`templating.helper`_ Make your service available in PHP templates
48+
`translation.loader`_ Register a custom service that loads translations
49+
`translation.extractor`_ Register a custom service that extracts translation messages from a file
50+
`translation.dumper`_ Register a custom service that dumps translation messages
51+
`twig.extension`_ Register a custom Twig Extension
52+
`twig.loader`_ Register a custom service that loads Twig templates
53+
`validator.constraint_validator`_ Create your own custom validation constraint
54+
`validator.initializer`_ Register a service that initializes objects before validation
55+
======================================== ========================================================================
8856

8957
assetic.asset
9058
-------------
@@ -916,6 +884,34 @@ of your configuration, and tag it with ``routing.loader``:
916884
917885
For more information, see :doc:`/cookbook/routing/custom_route_loader`.
918886
887+
routing.expression_language_provider
888+
------------------------------------
889+
890+
.. versionadded:: 2.6
891+
The ``routing.expression_language_provider`` tag was introduced in Symfony
892+
2.6.
893+
894+
**Purpose**: Register a provider for expression language functions in routing
895+
896+
This tag is used to automatically register
897+
:ref:`expression function providers <components-expression-language-provider>`
898+
for the routing expression component. Using these providers, you can add custom
899+
functions to the routing expression language.
900+
901+
security.expression_language_provider
902+
-------------------------------------
903+
904+
.. versionadded:: 2.6
905+
The ``security.expression_language_provider`` tag was introduced in Symfony
906+
2.6.
907+
908+
**Purpose**: Register a provider for expression language functions in security
909+
910+
This tag is used to automatically register :ref:`expression function providers
911+
<components-expression-language-provider>` for the security expression
912+
component. Using these providers, you can add custom functions to the security
913+
expression language.
914+
919915
security.remember_me_aware
920916
--------------------------
921917

0 commit comments

Comments
 (0)