diff --git a/components/expression_language/extending.rst b/components/expression_language/extending.rst index 5f1f743d631..9676452219e 100644 --- a/components/expression_language/extending.rst +++ b/components/expression_language/extending.rst @@ -51,24 +51,34 @@ 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 ---------------------------------------- +.. _components-expression-language-provider: -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:: +Using Expression Providers +-------------------------- - namespace Acme\AwesomeLib\ExpressionLanguage; +.. versionadded:: 2.6 + Expression providers were introduced in Symfony 2.6. - use Symfony\Component\ExpressionLanguage\ExpressionLanguage as BaseExpressionLanguage; +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`. - class ExpressionLanguage extends BaseExpressionLanguage - { - protected function registerFunctions() - { - parent::registerFunctions(); // do not forget to also register core functions +This interface requires one method: +: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 + + use Symfony\Component\ExpressionLanguage\ExpressionFunction; + use Symfony\Component\ExpressionLanguage\ExpressionFunctionProviderInterface; - $this->register('lowercase', function ($str) { + 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 +87,39 @@ 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( + new StringExpressionLanguageProvider(), + // ... + )); + + // using registerProvider() + $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 StringExpressionLanguageProvider()); + + parent::__construct($parser, $providers); + } + } diff --git a/reference/dic_tags.rst b/reference/dic_tags.rst index 0cd97bff55e..87774a94f44 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 --------------------------