You are browsing the documentation for Symfony 2.7 which is not maintained anymore.

Consider upgrading your projects to Symfony 5.2.

Extending the ExpressionLanguage

2.7 version

Extending the ExpressionLanguage

The ExpressionLanguage can be extended by adding custom functions. For instance, in the Symfony Framework, the security has custom functions to check the user’s role.


If you want to learn how to use functions in an expression, read “Working with Functions”.

Registering Functions

Functions are registered on each specific ExpressionLanguage instance. That means the functions can be used in any expression executed by that instance.

To register a function, use register(). This method has 3 arguments:

  • name - The name of the function in an expression;
  • compiler - A function executed when compiling an expression using the function;
  • evaluator - A function executed when the expression is evaluated.
use Symfony\Component\ExpressionLanguage\ExpressionLanguage;

$expressionLanguage = new ExpressionLanguage();
$expressionLanguage->register('lowercase', function ($str) {
    return sprintf('(is_string(%1$s) ? strtolower(%1$s) : %1$s)', $str);
}, function ($arguments, $str) {
    if (!is_string($str)) {
        return $str;

    return strtolower($str);


This will print hello. Both the compiler and evaluator are passed 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).

Using Expression Providers

New in version 2.6: Expression providers were introduced in Symfony 2.6.

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 Symfony\Component\ExpressionLanguage\ExpressionFunctionProviderInterface.

This interface requires one method: getFunctions(), which returns an array of expression functions (instances of Symfony\Component\ExpressionLanguage\ExpressionFunction) to register:

use Symfony\Component\ExpressionLanguage\ExpressionFunction;
use Symfony\Component\ExpressionLanguage\ExpressionFunctionProviderInterface;

class StringExpressionLanguageProvider implements ExpressionFunctionProviderInterface
    public function getFunctions()
        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)) {
                    return $str;

                return strtolower($str);

You can register providers using registerProvider() or by using the second argument of the constructor:

use Symfony\Component\ExpressionLanguage\ExpressionLanguage;

// using the constructor
$expressionLanguage = new ExpressionLanguage(null, array(
    new StringExpressionLanguageProvider(),
    // ...

// using registerProvider()
$expressionLanguage->registerProvider(new StringExpressionLanguageProvider());


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())
        // prepends the default provider to let users override it easily
        array_unshift($providers, new StringExpressionLanguageProvider());

        parent::__construct($parser, $providers);

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.