Skip to content

Documented ExpressionLanguage extensibility #4490

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Nov 24, 2014
Merged

Documented ExpressionLanguage extensibility #4490

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c553193
Documented expressionlanguage extensibility
wouterj Nov 18, 2014
ef4ca42
Documented new tags
wouterj Nov 19, 2014
086885b
Applied comments
wouterj Nov 23, 2014
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
72 changes: 58 additions & 14 deletions components/expression_language/extending.rst
View file
Open in desktop
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
Open in desktop
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