Documented ExpressionLanguage extensibility

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);
+            }
+        }

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
+<components-expression-language-provider>` 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
+<components-expression-language-provider>` for the security expression
+component. Using these providers, you can add custom functions to the security
+expression language.
+
 security.remember_me_aware
 --------------------------