@@ -51,24 +51,31 @@ an ``arguments`` variable as their first argument, which is equal to the
5151second argument to ``evaluate() `` or ``compile() `` (e.g. the "values" when
5252evaluating or the "names" if compiling).
5353
54- Creating a new ExpressionLanguage Class
55- ---------------------------------------
54+ Using Expression Providers
55+ --------------------------
5656
57- When you use the ``ExpressionLanguage `` class in your library, it's recommend
58- to create a new ``ExpressionLanguage `` class and register the functions there.
59- Override ``registerFunctions `` to add your own functions::
57+ .. versionadded :: 2.6
58+ Expression providers were introduced in Symfony 2.6.
6059
61- namespace Acme\AwesomeLib\ExpressionLanguage;
60+ When you use the ``ExpressionLanguage `` class in your library, you often want
61+ to add custom functions. To do so, you can create a new expression provider by
62+ creating a class that implements
63+ :class: `Symfony\\ Component\\ ExpressionLanguage\\ ExpressionFunctionProviderInterface `.
6264
63- use Symfony\Component\ExpressionLanguage\ExpressionLanguage as BaseExpressionLanguage;
65+ This interface requires one method:
66+ :method: `Symfony\\ Component\\ ExpressionLanguage\\ ExpressionFunctionProviderInterface::getFunctions `.
67+ This method returns an array of expression functions (instances of
68+ :class: `Symfony\\ Component\\ ExpressionLanguage\\ ExpressionFunction `) to register.
6469
65- class ExpressionLanguage extends BaseExpressionLanguage
66- {
67- protected function registerFunctions()
68- {
69- parent::registerFunctions(); // do not forget to also register core functions
70+ .. code-block :: php
7071
71- $this->register('lowercase', function ($str) {
72+ use Symfony\Component\ExpressionLanguage\ExpressionFunction;
73+ use Symfony\Component\ExpressionLanguage\ExpressionFunctionProviderInterface;
74+
75+ class StringExpressionLanguageProvider implements ExpressionFunctionProviderInterface
76+ {
77+ return array(
78+ new ExpressionFunction('lowercase', function ($str) {
7279 return sprintf('(is_string(%1$s) ? strtolower(%1$s) : %1$s)', $str);
7380 }, function ($arguments, $str) {
7481 if (!is_string($str)) {
@@ -77,5 +84,35 @@ Override ``registerFunctions`` to add your own functions::
7784
7885 return strtolower($str);
7986 });
80- }
87+ );
8188 }
89+
90+
91+ :method: `Symfony\\ Component\\ ExpressionLanguage\\ ExpressionLanguage::registerProvider `
92+ or by using the second argument of the constructor::
93+
94+ use Symfony\Component\ExpressionLanguage\ExpressionLanguage;
95+
96+ // using the constructor
97+ $language = new ExpressionLanguage(null, array(...));
98+
99+ $language->registerProvider(new StringExpressionLanguageProvider());
100+
101+ .. tip ::
102+
103+ It is recommended to create your own ``ExpressionLanguage `` class in your
104+ library. Now you can add the extension by overriding the constructor::
105+
106+ use Symfony\Component\ExpressionLanguage\ExpressionLanguage as BaseExpressionLanguage;
107+ use Symfony\Component\ExpressionLanguage\ParserCache\ParserCacheInterface;
108+
109+ class ExpressionLanguage extends BaseExpressionLanguage
110+ {
111+ public function __construct(ParserCacheInterface $parser = null, array $providers = array())
112+ {
113+ // prepend the default provider to let users override it easily
114+ array_unshift($providers, new MyExpressionLanguageProvider());
115+
116+ parent::__construct($parser, $providers);
117+ }
118+ }
0 commit comments