[TASK] Streamline expressionLanguage usage in core
[Packages/TYPO3.CMS.git] / typo3 / sysext / core / Documentation / Changelog / 9.4 / Feature-85829-ImplementSymfonyExpressionLanguageForTypoScriptConditions.rst
1 .. include:: ../../Includes.txt
2
3 =================================================================================
4 Feature: #85829 - Implement symfony expression language for TypoScript conditions
5 =================================================================================
6
7 See :issue:`85829`
8
9 Description
10 ===========
11
12 The `symfony expression language <https://symfony.com/doc/current/components/expression_language.html>`__
13 has been implemented for TypoScript conditions in both frontend and backend.
14 The existing conditions are available as variables and/or functions. Please check the following tables in detail.
15
16 General Usage
17 -------------
18
19 To learn the full power of the symfony expression language please check the `documentation for the common expression syntax <https://symfony.com/doc/current/components/expression_language/syntax.html>`__.
20 Here are some examples to understand the power of the expression language:
21
22 .. code-block:: typoscript
23
24    [page["uid"] in 18..45]
25    # This condition matches if current page uid is between 18 and 45
26    [END]
27
28    [userId in [1,5,7]]
29    # This condition matches if current logged in user has the uid 1, 5 or 7
30    [END]
31
32    [not ("foo" matches "/bar/")]
33    # This condition does match if "foo" **not** matches the regExp: `/bar/`
34    [END]
35
36    [applicationContext == "Production"] && [userId == 15]
37    # This condition match if application context is "Production" AND logged in user has the uid 15
38    # This condition could also be combined in one condition:
39    # [applicationContext == "Production" && userId == 15]
40    [END]
41
42    [request.getNormalizedParams().getHttpHost() == 'typo3.org']
43    # This condition matches if current hostname is typo3.org
44    [END]
45
46    [like(request.getNormalizedParams().getHttpHost(), "*.devbox.local")]
47    # This condition matches if current hostname is any subdomain of devbox.local
48    [END]
49
50    [request.getNormalizedParams().isHttps() == false]
51    # This condition matches if current request is **not** https
52    [END]
53
54
55 Variables
56 ---------
57
58 The following variables are available. The values are context related.
59
60 +---------------------+------------+------------------------------------------------------------------------------+
61 | Variable            | Type       | Description                                                                  |
62 +=====================+============+==============================================================================+
63 | applicationContext  | String     | current application context as string                                        |
64 +---------------------+------------+------------------------------------------------------------------------------+
65 | page                | Array      | current page record as array                                                 |
66 +---------------------+------------+------------------------------------------------------------------------------+
67 | {$foo.bar}          | Constant   | Any TypoScript constant is available like before.                            |
68 |                     |            | Depending on the type of the constant you have to use                        |
69 |                     |            | different conditions, see examples below:                                    |
70 |                     |            |                                                                              |
71 |                     |            | * if constant is an integer: `[{$foo.bar} == 4711]`                          |
72 |                     |            | * if constant is a string put constant in quotes: `["{$foo.bar}" == "4711"]` |
73 +---------------------+------------+------------------------------------------------------------------------------+
74 | tree                | Object     | object with tree information                                                 |
75 |                     |            |                                                                              |
76 | .level              | Integer    | current tree level                                                           |
77 |                     |            |                                                                              |
78 | .rootLine           | Array      | array of arrays with uid and pid                                             |
79 |                     |            |                                                                              |
80 | .rootLineIds        | Array      | an array with UIDs of the rootline                                           |
81 +---------------------+------------+------------------------------------------------------------------------------+
82 | backend             | Object     | object with backend information (available in BE only)                       |
83 |                     |            |                                                                              |
84 | .user               | Object     | object with current backend user information                                 |
85 |                     |            |                                                                              |
86 | .user.isAdmin       | Boolean    | true if current user is admin                                                |
87 |                     |            |                                                                              |
88 | .user.isLoggedIn    | Boolean    | true if current user is logged in                                            |
89 |                     |            |                                                                              |
90 | .user.userId        | Integer    | UID of current user                                                          |
91 |                     |            |                                                                              |
92 | .user.userGroupList | String     | comma list of group UIDs                                                     |
93 +---------------------+------------+------------------------------------------------------------------------------+
94 | frontend            | Object     | object with frontend information (available in FE only)                      |
95 |                     |            |                                                                              |
96 | .user               | Object     | object with current frontend user information                                |
97 |                     |            |                                                                              |
98 | .user.isLoggedIn    | Boolean    | true if current user is logged in                                            |
99 |                     |            |                                                                              |
100 | .user.userId        | Integer    | UID of current user                                                          |
101 |                     |            |                                                                              |
102 | .user.userGroupList | String     | comma list of group UIDs                                                     |
103 +---------------------+------------+------------------------------------------------------------------------------+
104 | typo3               | Object     | object with TYPO3 related information                                        |
105 |                     |            |                                                                              |
106 | .version            | String     | TYPO3_version (e.g. 9.4.0-dev)                                               |
107 |                     |            |                                                                              |
108 | .branch             | String     | TYPO3_branch (e.g. 9.4)                                                      |
109 |                     |            |                                                                              |
110 | .devIpMask          | String     | :php`$GLOBALS['TYPO3_CONF_VARS']['SYS']['devIPmask']`                        |
111 +---------------------+------------+------------------------------------------------------------------------------+
112
113
114 Functions
115 ---------
116
117 Functions take over the logic of the old conditions which do more than a simple comparison check.
118 The following functions are available in **any** context:
119
120 +------------------------+-----------------------+---------------------------------------------------------+
121 | Function               | Parameter             | Description                                             |
122 +========================+=======================+=========================================================+
123 | request                | Custom Object         | This object provides 4 methods                          |
124 |                        |                       |                                                         |
125 | .getQueryParams()      |                       | `[request.getQueryParams()['foo'] == 1]`                |
126 |                        |                       |                                                         |
127 | .getParsedBody()       |                       | `[request.getParsedBody()['foo'] == 1]`                 |
128 |                        |                       |                                                         |
129 | .getHeaders()          |                       | `[request.getHeaders()['Accept'] == 'json']`            |
130 |                        |                       |                                                         |
131 | .getCookieParams()     |                       | `[request.getCookieParams()['foo'] == 1]`               |
132 |                        |                       |                                                         |
133 | .getNormalizedParams() |                       | `[request.getNormalizedParams().isHttps()]`             |
134 +------------------------+-----------------------+---------------------------------------------------------+
135 | date                   | String                | Get current date in given format.                       |
136 |                        |                       | Examples:                                               |
137 |                        |                       |                                                         |
138 |                        |                       | * true if day of current month is 7: `[date("j") == 7]` |
139 |                        |                       | * true if day of current week is 7: `[date("w") == 7]`  |
140 |                        |                       | * true if day of current year is 7: `[date("z") == 7]`  |
141 |                        |                       | * true if current hour is 7: `[date("G") == 7]`         |
142 +------------------------+-----------------------+---------------------------------------------------------+
143 | like                   | String                | This function has two parameters:                       |
144 |                        |                       | the first parameter is the string to search in          |
145 |                        |                       | the second parameter is the search string               |
146 |                        |                       | Example: `[like("foobarbaz", "*bar*")]`                 |
147 +------------------------+-----------------------+---------------------------------------------------------+
148 | ip                     | String                | Value or Constraint, Wildcard or RegExp possible        |
149 |                        |                       | special value: devIP (match the devIPMask)              |
150 +------------------------+-----------------------+---------------------------------------------------------+
151 | compatVersion          | String                | version constraint, e.g. `9.4` or `9.4.0`               |
152 +------------------------+-----------------------+---------------------------------------------------------+
153 | loginUser              | String                | value or constraint, wildcard or RegExp possible        |
154 |                        |                       | Examples:                                               |
155 |                        |                       |                                                         |
156 |                        |                       | * `[loginUser('*')]` // any logged in user              |
157 |                        |                       | * `[loginUser(1)]` // user with uid 1                   |
158 |                        |                       | * `[loginUser('1,3,5')]` // user 1, 3 or 5              |
159 |                        |                       | * `[loginUser('*') == false]` // not logged in          |
160 +------------------------+-----------------------+---------------------------------------------------------+
161 | getTSFE                | Object                | TypoScriptFrontendController (`$GLOBALS['TSFE']`)       |
162 +------------------------+-----------------------+---------------------------------------------------------+
163 | getenv                 | String                | PHP function: :php:`getenv()`                           |
164 +------------------------+-----------------------+---------------------------------------------------------+
165 | usergroup              | String                | value or constraint, wildcard or RegExp possible        |
166 +------------------------+-----------------------+---------------------------------------------------------+
167
168
169 The following functions are only available in **frontend** context:
170
171 +--------------------+------------+-----------------------------------------------------------------+
172 | Function           | Parameter  | Description                                                     |
173 +====================+============+=================================================================+
174 | session            | String     | Get value from session                                          |
175 |                    |            |                                                                 |
176 |                    |            | Example, matches if session value = 1234567                     |
177 |                    |            | `[session("session:foo|bar") == 1234567]`                       |
178 +--------------------+------------+-----------------------------------------------------------------+
179 | site               | String     | get value from site configuration, or null if                   |
180 |                    |            | no site was found or property does not exists                   |
181 |                    |            |                                                                 |
182 |                    |            | Example, matches if site identifier = foo                       |
183 |                    |            | `[site("identifier") == "foo"]`                                 |
184 |                    |            |                                                                 |
185 |                    |            | Example, matches if site `base = http://localhost`              |
186 |                    |            | `[site("base") == "http://localhost"]`                          |
187 +--------------------+------------+-----------------------------------------------------------------+
188 | siteLanguage       | String     | get vale from siteLanguage configuration, or                    |
189 |                    |            | null if no site was found or property not exists                |
190 |                    |            |                                                                 |
191 |                    |            | Example, match if siteLanguage locale = foo                     |
192 |                    |            | `[siteLanguage("locale") == "de_CH"]`                           |
193 |                    |            |                                                                 |
194 |                    |            | Example, match if siteLanguage title = Italy                    |
195 |                    |            | `[siteLanguage("title") == "Italy"]`                            |
196 +--------------------+------------+-----------------------------------------------------------------+
197
198
199 Extending the expression language with own functions (like old userFunc)
200 ------------------------------------------------------------------------
201
202 It is possible to extend the expression language with own functions like before userFunc in the old conditions.
203 An example could be :php:`TYPO3\CMS\Core\ExpressionLanguage\FunctionsProvider\TypoScriptConditionFunctionsProvider` which implements
204 the most core functions.
205
206 Please read .. _the introduction: https://docs.typo3.org/typo3cms/extensions/core/Changelog/9.4/Feature-85828-MoveSymfonyExpressionLanguageHandlingIntoEXTcore.html first.
207
208 Add new methods by implementing own providers which implement the :php:`ExpressionFunctionProviderInterface` and
209 register the provider for the key `typoscript` in your own :file:`Configuration\ExpressionLanguage.php` file:
210
211 .. code-block:: php
212
213       return [
214          'typoscript' => [
215             \TYPO3\CMS\MyExt\ExpressionLanguage\MyCustomProvider::class,
216          ]
217       ];
218
219
220 The code above will extend the TypoScript condition configuration with your own provider, which provide your own functions.
221
222 .. index:: Backend, Frontend, TypoScript, ext:core