Skip to content

Commit

Permalink
feature #4490 Documented ExpressionLanguage extensibility (WouterJ)
Browse files Browse the repository at this point in the history 
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
  • Loading branch information
@weaverryan
weaverryan committed Nov 24, 2014
2 parents ed241ab + 086885b commit 59f0374
Show file tree
Hide file tree
Showing 2 changed files with 127 additions and 87 deletions.
72 changes: 58 additions & 14 deletions components/expression_language/extending.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)) {
Expand All @@ -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);
}
}
142 changes: 69 additions & 73 deletions reference/dic_tags.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
-------------
Expand Down Expand Up @@ -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
--------------------------
Expand Down

0 comments on commit 59f0374

Please sign in to comment.