Skip to content

Commit 240df84

Browse files
weaverryanweaverryan
committed
Merge pull request symfony#3241 from WouterJ/expression-furthering-component
Continuing ExpressionLanguage component docs
2 parents 4147ad4 + 6e2e583 commit 240df84

File tree

4 files changed

+132
-5
lines changed

4 files changed

+132
-5
lines changed

‎components/expression_language/extending.rst

+87
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
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+
}

‎components/expression_language/index.rst

+1
Original file line numberDiff line numberDiff line change
@@ -6,3 +6,4 @@ Expression Language
66

77
introduction
88
syntax
9+
extending

‎components/expression_language/syntax.rst

+43-5
Original file line numberDiff line numberDiff line change
@@ -81,6 +81,29 @@ JavaScript::
8181

8282
This will print ``Hi Hi Hi!``.
8383

84+
.. _component-expression-functions:
85+
86+
Working with Functions
87+
----------------------
88+
89+
You can also use registered functions in the expression by using the same
90+
syntax as PHP and JavaScript. The ExpressionLanguage component comes with one
91+
function by default: ``constant()`` Which will return the value of the PHP
92+
constant::
93+
94+
define('DB_USER', 'root');
95+
96+
echo $language->evaluate(
97+
'constant("DB_USER")'
98+
);
99+
100+
This will print ``root``.
101+
102+
.. tip::
103+
104+
To read how to register your own function to use in an expression, see
105+
":doc:`/components/expression_language/extending`".
106+
84107
.. _component-expression-arrays:
85108

86109
Working with Arrays
@@ -128,11 +151,6 @@ For example::
128151

129152
This will print out ``42``.
130153

131-
Assignment Operators
132-
~~~~~~~~~~~~~~~~~~~~
133-
134-
* ``=``
135-
136154
Bitwise Operators
137155
~~~~~~~~~~~~~~~~~
138156

@@ -249,6 +267,26 @@ Numeric Operators
249267

250268
* ``..`` (range)
251269

270+
For example::
271+
272+
class User
273+
{
274+
public $age;
275+
}
276+
277+
$user = new User();
278+
$user->age = 34;
279+
280+
$language->evaluate(
281+
'user.age in 18..45',
282+
array(
283+
'user' => $user,
284+
)
285+
);
286+
287+
This will evaluate to ``true``, because ``user.age`` is in the range from
288+
``18`` till ``45``
289+
252290
Ternary Operators
253291
~~~~~~~~~~~~~~~~~
254292

‎components/map.rst.inc

+1
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,7 @@
6161

6262
* :doc:`/components/expression_language/introduction`
6363
* :doc:`/components/expression_language/syntax`
64+
* :doc:`/components/expression_language/extending`
6465

6566
* **Filesystem**
6667

0 commit comments

Comments
 (0)