|
| 1 | +..index:: |
| 2 | + single: Extending; ExpressionLanguage |
| 3 | + |
| 4 | +Extending the ExpressionLanguage |
| 5 | +================================ |
| 6 | + |
| 7 | +The ExpressionLanguage can be extended by adding custom functions. For |
| 8 | +instance, in the framework, the security has custom functions to check the |
| 9 | +user's role. |
| 10 | + |
| 11 | +..note:: |
| 12 | + |
| 13 | + If you want to learn how to use functions in an expression, read |
| 14 | + ":ref:`component-expression-functions`". |
| 15 | + |
| 16 | +Register Functions |
| 17 | +------------------ |
| 18 | + |
| 19 | +Functions will be registered on the current ``ExpressionLanguage`` instance. |
| 20 | +That means the functions can be used in any expression executed by that |
| 21 | +instance. |
| 22 | + |
| 23 | +To register a function, use |
| 24 | +:method:`Symfony\\Component\\ExpressionLanguage\\ExpressionLanguage::register``. |
| 25 | +This method has 3 arguments: |
| 26 | + |
| 27 | +* **name** - The name of the function in an expression; |
| 28 | +* **compiler** - A function executed when compiling an expression using the |
| 29 | + function; |
| 30 | +* **evaluator** - A function executed when the expression is evaluated. |
| 31 | + |
| 32 | +..code-block::php |
| 33 | +
|
| 34 | + use Symfony\Component\ExpressionLanguage\ExpressionLanguage; |
| 35 | +
|
| 36 | + $language = new ExpressionLanguage(); |
| 37 | + $language->register('lowercase', function ($str) { |
| 38 | + if (!is_string($str)) { |
| 39 | + return $str; |
| 40 | + } |
| 41 | +
|
| 42 | + return sprintf('strtolower(%s)', $str); |
| 43 | + }, function ($str) { |
| 44 | + if (!is_string($str)) { |
| 45 | + return $str; |
| 46 | + } |
| 47 | +
|
| 48 | + return strtolower($str); |
| 49 | + }); |
| 50 | +
|
| 51 | + echo $language->evaluate('lowercase("HELLO")'); |
| 52 | +
|
| 53 | +This will print ``hello``. |
| 54 | + |
| 55 | +Creating a new ExpressionLanguage class |
| 56 | +--------------------------------------- |
| 57 | + |
| 58 | +When you use the ``ExpressionLanguage`` class in your library, it's recommend |
| 59 | +to create a new ``ExpressionLanguage`` class and register the functions there. |
| 60 | +The class will execute ``registerFunctions`` to register the default |
| 61 | +functions, you can override this to also add your own functions:: |
| 62 | + |
| 63 | + namespace Acme\AwesomeLib\ExpressionLanguage; |
| 64 | + |
| 65 | + use Symfony\Component\ExpressionLanguage\ExpressionLanguage as BaseExpressionLanguage; |
| 66 | + |
| 67 | + class ExpressionLanguage extends BaseExpressionLanguage |
| 68 | + { |
| 69 | + protected function registerFunctions() |
| 70 | + { |
| 71 | + parent::registerFunctions(); // do not forget to also register core functions |
| 72 | + |
| 73 | + $this->register('lowercase', function ($str) { |
| 74 | + if (!is_string($str)) { |
| 75 | + return $str; |
| 76 | + } |
| 77 | + |
| 78 | + return sprintf('strtolower(%s)', $str); |
| 79 | + }, function ($str) { |
| 80 | + if (!is_string($str)) { |
| 81 | + return $str; |
| 82 | + } |
| 83 | + |
| 84 | + return strtolower($str); |
| 85 | + }); |
| 86 | + } |
| 87 | + } |