From c55319330d7967dd0b1fb5f504b35433629b0702 Mon Sep 17 00:00:00 2001 From: WouterJ Date: Wed, 19 Nov 2014 00:55:54 +0100 Subject: [PATCH 1/3] Documented expressionlanguage extensibility --- components/expression_language/extending.rst | 65 +++++++++++++++----- 1 file changed, 51 insertions(+), 14 deletions(-) diff --git a/components/expression_language/extending.rst b/components/expression_language/extending.rst index 5f1f743d631..9a25be53736 100644 --- a/components/expression_language/extending.rst +++ b/components/expression_language/extending.rst @@ -51,24 +51,31 @@ an ``arguments`` variable as their first argument, which is equal to the second argument to ``evaluate()`` or ``compile()`` (e.g. the "values" when evaluating or the "names" if compiling). -Creating a new ExpressionLanguage Class ---------------------------------------- +Using Expression Providers +-------------------------- -When you use the ``ExpressionLanguage`` class in your library, it's recommend -to create a new ``ExpressionLanguage`` class and register the functions there. -Override ``registerFunctions`` to add your own functions:: +.. versionadded:: 2.6 + Expression providers were introduced in Symfony 2.6. - namespace Acme\AwesomeLib\ExpressionLanguage; +When you use the ``ExpressionLanguage`` class in your library, you often want +to add custom functions. To do so, you can create a new expression provider by +creating a class that implements +:class:`Symfony\\Component\\ExpressionLanguage\\ExpressionFunctionProviderInterface`. - use Symfony\Component\ExpressionLanguage\ExpressionLanguage as BaseExpressionLanguage; +This interface requires one method: +:method:`Symfony\\Component\\ExpressionLanguage\\ExpressionFunctionProviderInterface::getFunctions`. +This method returns an array of expression functions (instances of +:class:`Symfony\\Component\\ExpressionLanguage\\ExpressionFunction`) to register. - class ExpressionLanguage extends BaseExpressionLanguage - { - protected function registerFunctions() - { - parent::registerFunctions(); // do not forget to also register core functions +.. code-block:: php - $this->register('lowercase', function ($str) { + use Symfony\Component\ExpressionLanguage\ExpressionFunction; + use Symfony\Component\ExpressionLanguage\ExpressionFunctionProviderInterface; + + class StringExpressionLanguageProvider implements ExpressionFunctionProviderInterface + { + return array( + new ExpressionFunction('lowercase', function ($str) { return sprintf('(is_string(%1$s) ? strtolower(%1$s) : %1$s)', $str); }, function ($arguments, $str) { if (!is_string($str)) { @@ -77,5 +84,35 @@ Override ``registerFunctions`` to add your own functions:: return strtolower($str); }); - } + ); } + +You can register providers using +:method:`Symfony\\Component\\ExpressionLanguage\\ExpressionLanguage::registerProvider` +or by using the second argument of the constructor:: + + use Symfony\Component\ExpressionLanguage\ExpressionLanguage; + + // using the constructor + $language = new ExpressionLanguage(null, array(...)); + + $language->registerProvider(new StringExpressionLanguageProvider()); + +.. tip:: + + It is recommended to create your own ``ExpressionLanguage`` class in your + library. Now you can add the extension by overriding the constructor:: + + use Symfony\Component\ExpressionLanguage\ExpressionLanguage as BaseExpressionLanguage; + use Symfony\Component\ExpressionLanguage\ParserCache\ParserCacheInterface; + + class ExpressionLanguage extends BaseExpressionLanguage + { + public function __construct(ParserCacheInterface $parser = null, array $providers = array()) + { + // prepend the default provider to let users override it easily + array_unshift($providers, new MyExpressionLanguageProvider()); + + parent::__construct($parser, $providers); + } + } From ef4ca4255544d7b6df0aca566c918822fd3d17e1 Mon Sep 17 00:00:00 2001 From: WouterJ Date: Wed, 19 Nov 2014 01:03:16 +0100 Subject: [PATCH 2/3] Documented new tags --- reference/dic_tags.rst | 142 ++++++++++++++++++++--------------------- 1 file changed, 69 insertions(+), 73 deletions(-) diff --git a/reference/dic_tags.rst b/reference/dic_tags.rst index 0cd97bff55e..472cb2600e7 100644 --- a/reference/dic_tags.rst +++ b/reference/dic_tags.rst @@ -12,79 +12,47 @@ section of the Service Container chapter. Below is information about all of the tags available inside Symfony. There may also be tags in other bundles you use that aren't listed here. -+-----------------------------------+---------------------------------------------------------------------------+ -| Tag Name | Usage | -+===================================+===========================================================================+ -| `assetic.asset`_ | Register an asset to the current asset manager | -+-----------------------------------+---------------------------------------------------------------------------+ -| `assetic.factory_worker`_ | Add a factory worker | -+-----------------------------------+---------------------------------------------------------------------------+ -| `assetic.filter`_ | Register a filter | -+-----------------------------------+---------------------------------------------------------------------------+ -| `assetic.formula_loader`_ | Add a formula loader to the current asset manager | -+-----------------------------------+---------------------------------------------------------------------------+ -| `assetic.formula_resource`_ | Adds a resource to the current asset manager | -+-----------------------------------+---------------------------------------------------------------------------+ -| `assetic.templating.php`_ | Remove this service if PHP templating is disabled | -+-----------------------------------+---------------------------------------------------------------------------+ -| `assetic.templating.twig`_ | Remove this service if Twig templating is disabled | -+-----------------------------------+---------------------------------------------------------------------------+ -| `console.command`_ | Add a command | -+-----------------------------------+---------------------------------------------------------------------------+ -| `data_collector`_ | Create a class that collects custom data for the profiler | -+-----------------------------------+---------------------------------------------------------------------------+ -| `doctrine.event_listener`_ | Add a Doctrine event listener | -+-----------------------------------+---------------------------------------------------------------------------+ -| `doctrine.event_subscriber`_ | Add a Doctrine event subscriber | -+-----------------------------------+---------------------------------------------------------------------------+ -| `form.type`_ | Create a custom form field type | -+-----------------------------------+---------------------------------------------------------------------------+ -| `form.type_extension`_ | Create a custom "form extension" | -+-----------------------------------+---------------------------------------------------------------------------+ -| `form.type_guesser`_ | Add your own logic for "form type guessing" | -+-----------------------------------+---------------------------------------------------------------------------+ -| `kernel.cache_clearer`_ | Register your service to be called during the cache clearing process | -+-----------------------------------+---------------------------------------------------------------------------+ -| `kernel.cache_warmer`_ | Register your service to be called during the cache warming process | -+-----------------------------------+---------------------------------------------------------------------------+ -| `kernel.event_listener`_ | Listen to different events/hooks in Symfony | -+-----------------------------------+---------------------------------------------------------------------------+ -| `kernel.event_subscriber`_ | To subscribe to a set of different events/hooks in Symfony | -+-----------------------------------+---------------------------------------------------------------------------+ -| `kernel.fragment_renderer`_ | Add new HTTP content rendering strategies | -+-----------------------------------+---------------------------------------------------------------------------+ -| `monolog.logger`_ | Logging with a custom logging channel | -+-----------------------------------+---------------------------------------------------------------------------+ -| `monolog.processor`_ | Add a custom processor for logging | -+-----------------------------------+---------------------------------------------------------------------------+ -| `routing.loader`_ | Register a custom service that loads routes | -+-----------------------------------+---------------------------------------------------------------------------+ -| `security.voter`_ | Add a custom voter to Symfony's authorization logic | -+-----------------------------------+---------------------------------------------------------------------------+ -| `security.remember_me_aware`_ | To allow remember me authentication | -+-----------------------------------+---------------------------------------------------------------------------+ -| `serializer.encoder`_ | Register a new encoder in the ``serializer`` service | -+-----------------------------------+---------------------------------------------------------------------------+ -| `serializer.normalizer`_ | Register a new normalizer in the ``serializer`` service | -+-----------------------------------+---------------------------------------------------------------------------+ -| `swiftmailer.default.plugin`_ | Register a custom SwiftMailer Plugin | -+-----------------------------------+---------------------------------------------------------------------------+ -| `templating.helper`_ | Make your service available in PHP templates | -+-----------------------------------+---------------------------------------------------------------------------+ -| `translation.loader`_ | Register a custom service that loads translations | -+-----------------------------------+---------------------------------------------------------------------------+ -| `translation.extractor`_ | Register a custom service that extracts translation messages from a file | -+-----------------------------------+---------------------------------------------------------------------------+ -| `translation.dumper`_ | Register a custom service that dumps translation messages | -+-----------------------------------+---------------------------------------------------------------------------+ -| `twig.extension`_ | Register a custom Twig Extension | -+-----------------------------------+---------------------------------------------------------------------------+ -| `twig.loader`_ | Register a custom service that loads Twig templates | -+-----------------------------------+---------------------------------------------------------------------------+ -| `validator.constraint_validator`_ | Create your own custom validation constraint | -+-----------------------------------+---------------------------------------------------------------------------+ -| `validator.initializer`_ | Register a service that initializes objects before validation | -+-----------------------------------+---------------------------------------------------------------------------+ +======================================== ======================================================================== +Tag Name Usage +======================================== ======================================================================== +`assetic.asset`_ Register an asset to the current asset manager +`assetic.factory_worker`_ Add a factory worker +`assetic.filter`_ Register a filter +`assetic.formula_loader`_ Add a formula loader to the current asset manager +`assetic.formula_resource`_ Adds a resource to the current asset manager +`assetic.templating.php`_ Remove this service if PHP templating is disabled +`assetic.templating.twig`_ Remove this service if Twig templating is disabled +`console.command`_ Add a command +`data_collector`_ Create a class that collects custom data for the profiler +`doctrine.event_listener`_ Add a Doctrine event listener +`doctrine.event_subscriber`_ Add a Doctrine event subscriber +`form.type`_ Create a custom form field type +`form.type_extension`_ Create a custom "form extension" +`form.type_guesser`_ Add your own logic for "form type guessing" +`kernel.cache_clearer`_ Register your service to be called during the cache clearing process +`kernel.cache_warmer`_ Register your service to be called during the cache warming process +`kernel.event_listener`_ Listen to different events/hooks in Symfony +`kernel.event_subscriber`_ To subscribe to a set of different events/hooks in Symfony +`kernel.fragment_renderer`_ Add new HTTP content rendering strategies +`monolog.logger`_ Logging with a custom logging channel +`monolog.processor`_ Add a custom processor for logging +`routing.loader`_ Register a custom service that loads routes +`routing.expression_language_provider`_ Register a provider for expression language functions in routing +`security.expression_language_provider`_ Register a provider for expression language functions in security +`security.voter`_ Add a custom voter to Symfony's authorization logic +`security.remember_me_aware`_ To allow remember me authentication +`serializer.encoder`_ Register a new encoder in the ``serializer`` service +`serializer.normalizer`_ Register a new normalizer in the ``serializer`` service +`swiftmailer.default.plugin`_ Register a custom SwiftMailer Plugin +`templating.helper`_ Make your service available in PHP templates +`translation.loader`_ Register a custom service that loads translations +`translation.extractor`_ Register a custom service that extracts translation messages from a file +`translation.dumper`_ Register a custom service that dumps translation messages +`twig.extension`_ Register a custom Twig Extension +`twig.loader`_ Register a custom service that loads Twig templates +`validator.constraint_validator`_ Create your own custom validation constraint +`validator.initializer`_ Register a service that initializes objects before validation +======================================== ======================================================================== assetic.asset ------------- @@ -916,6 +884,34 @@ of your configuration, and tag it with ``routing.loader``: For more information, see :doc:`/cookbook/routing/custom_route_loader`. +routing.expression_language_provider +------------------------------------ + +.. versionadded:: 2.6 + The ``routing.expression_language_provider`` tag was introduced in Symfony + 2.6. + +**Purpose**: Register a provider for expression language functions in routing + +This tag is used to automatically register :ref:`expression function providers +` for the routing expression +component. Using these providers, you can add custom functions to the routing +expression language. + +security.expression_language_provider +------------------------------------- + +.. versionadded:: 2.6 + The ``security.expression_language_provider`` tag was introduced in Symfony + 2.6. + +**Purpose**: Register a provider for expression language functions in security + +This tag is used to automatically register :ref:`expression function providers +` for the security expression +component. Using these providers, you can add custom functions to the security +expression language. + security.remember_me_aware -------------------------- From 086885b98eb9b36eea465384fe204485b1bca463 Mon Sep 17 00:00:00 2001 From: WouterJ Date: Sun, 23 Nov 2014 21:56:56 +0100 Subject: [PATCH 3/3] Applied comments --- components/expression_language/extending.rst | 17 ++++++++++++----- reference/dic_tags.rst | 8 ++++---- 2 files changed, 16 insertions(+), 9 deletions(-) diff --git a/components/expression_language/extending.rst b/components/expression_language/extending.rst index 9a25be53736..9676452219e 100644 --- a/components/expression_language/extending.rst +++ b/components/expression_language/extending.rst @@ -51,6 +51,8 @@ an ``arguments`` variable as their first argument, which is equal to the second argument to ``evaluate()`` or ``compile()`` (e.g. the "values" when evaluating or the "names" if compiling). +.. _components-expression-language-provider: + Using Expression Providers -------------------------- @@ -63,9 +65,10 @@ creating a class that implements :class:`Symfony\\Component\\ExpressionLanguage\\ExpressionFunctionProviderInterface`. This interface requires one method: -:method:`Symfony\\Component\\ExpressionLanguage\\ExpressionFunctionProviderInterface::getFunctions`. -This method returns an array of expression functions (instances of -:class:`Symfony\\Component\\ExpressionLanguage\\ExpressionFunction`) to register. +:method:`Symfony\\Component\\ExpressionLanguage\\ExpressionFunctionProviderInterface::getFunctions`, +which returns an array of expression functions (instances of +:class:`Symfony\\Component\\ExpressionLanguage\\ExpressionFunction`) to +register. .. code-block:: php @@ -94,8 +97,12 @@ or by using the second argument of the constructor:: use Symfony\Component\ExpressionLanguage\ExpressionLanguage; // using the constructor - $language = new ExpressionLanguage(null, array(...)); + $language = new ExpressionLanguage(null, array( + new StringExpressionLanguageProvider(), + // ... + )); + // using registerProvider() $language->registerProvider(new StringExpressionLanguageProvider()); .. tip:: @@ -111,7 +118,7 @@ or by using the second argument of the constructor:: public function __construct(ParserCacheInterface $parser = null, array $providers = array()) { // prepend the default provider to let users override it easily - array_unshift($providers, new MyExpressionLanguageProvider()); + array_unshift($providers, new StringExpressionLanguageProvider()); parent::__construct($parser, $providers); } diff --git a/reference/dic_tags.rst b/reference/dic_tags.rst index 472cb2600e7..87774a94f44 100644 --- a/reference/dic_tags.rst +++ b/reference/dic_tags.rst @@ -893,10 +893,10 @@ routing.expression_language_provider **Purpose**: Register a provider for expression language functions in routing -This tag is used to automatically register :ref:`expression function providers -` for the routing expression -component. Using these providers, you can add custom functions to the routing -expression language. +This tag is used to automatically register +:ref:`expression function providers ` +for the routing expression component. Using these providers, you can add custom +functions to the routing expression language. security.expression_language_provider -------------------------------------