Skip to content

Commit b03de9d

Browse files
fabpotfabpot
committed
Merge branch '3.x' into 4.x
* 3.x: Update CHANGELOG Fix accessing arrays with stringable objects as key Update inky_to_html.rst: Updating link Update replace.rst [Doc] Tweaks in the escaping article Compile 'index' with repr (not string) in EmbedNode Introduce registerUndefinedTestCallback Fix intl test Bump minimum Commonmark requirement Support two words test guard Bump version Improve documentation examples for `enum` and `enum_cases` Avoid errors when failing to guess the template info for an error Add note to format_datetime explaining how to install required extensions Fix compatibility layer
2 parents 4ad55ff + a5487c8 commit b03de9d

File tree

25 files changed

+315
-33
lines changed

25 files changed

+315
-33
lines changed

‎doc/filters/escape.rst‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -53,8 +53,9 @@ documents:
5353
* ``url``: escapes a string for the **URI or parameter** contexts. This should
5454
not be used to escape an entire URI; only a subcomponent being inserted.
5555

56-
* ``html_attr``: escapes a string for the **HTML attribute** context,
57-
**without quotes** around HTML attribute values.
56+
* ``html_attr``: escapes a string when used as an **HTML attribute** name, and
57+
also when used as the value of an HTML attribute **without quotes**
58+
(e.g. ``data-attribute={{ some_value }}``).
5859

5960
Note that doing contextual escaping in HTML documents is hard and choosing the
6061
right escaping strategy depends on a lot of factors. Please, read related
@@ -96,23 +97,22 @@ to learn more about this topic.
9697
9798
.. tip::
9899

99-
The ``html_attr`` escaping strategy can be useful when you need to
100-
escape a **dynamic HTML attribute name**:
100+
The ``html_attr`` escaping strategy can be useful when you need to escape a
101+
**dynamic HTML attribute name**:
101102

102103
.. code-block:: html+twig
103104

104105
<p {{ your_html_attr|e('html_attr') }}="attribute value">
105106

106-
It can also be used for escaping a **dynamic HTML attribute value**
107-
if it is not quoted, but this is **less performant**.
108-
Instead, it is recommended to quote the HTML attribute value and use
109-
the ``html`` escaping strategy:
107+
It can also be used for escaping a **dynamic HTML attribute value** if it is
108+
not quoted, but this is **less performant**. Instead, it is recommended to
109+
quote the HTML attribute value and use the ``html`` escaping strategy:
110110

111111
.. code-block:: html+twig
112112

113113
<p data-content="{{ content|e('html') }}">
114114

115-
{# is equivalent to, but is less performant #}
115+
{# this is equivalent, but less performant #}
116116
<p data-content={{ content|e('html_attr') }}>
117117

118118
Custom Escapers

‎doc/filters/format_datetime.rst‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,29 @@ The ``format_datetime`` filter formats a date time:
88
{# Aug 7, 2019, 11:39:12 PM #}
99
{{ '2019-08-07 23:39:12'|format_datetime() }}
1010
11+
.. note::
12+
13+
The ``format_datetime`` filter is part of the ``IntlExtension`` which is not
14+
installed by default. Install it first:
15+
16+
.. code-block:: bash
17+
18+
$ composer require twig/intl-extra
19+
20+
Then, on Symfony projects, install the ``twig/extra-bundle``:
21+
22+
.. code-block:: bash
23+
24+
$ composer require twig/extra-bundle
25+
26+
Otherwise, add the extension explicitly on the Twig environment::
27+
28+
use Twig\Extra\Intl\IntlExtension;
29+
30+
$twig = new \Twig\Environment(...);
31+
$twig->addExtension(new IntlExtension());
32+
33+
1134
Format
1235
------
1336

‎doc/filters/inky_to_html.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
================
33

44
The ``inky_to_html`` filter processes an `inky email template
5-
<https://github.com/zurb/inky>`_:
5+
<https://github.com/foundation/inky>`_:
66

77
.. code-block:: html+twig
88

‎doc/filters/replace.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@ format is free-form):
66

77
.. code-block:: twig
88
9+
{% set fruit = 'apples' %}
10+
911
{{ "I like %this% and %that%."|replace({'%this%': fruit, '%that%': "oranges"}) }}
1012
{# if the "fruit" variable is set to "apples", #}
1113
{# it outputs "I like apples and oranges" #}

‎doc/functions/enum.rst‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,15 +6,21 @@
66
.. code-block:: twig
77
88
{# display one specific case of a backed enum #}
9-
{{ enum('App\\MyEnum').SomeCase.value }}
9+
{{ enum('App\\CardSuite').Clubs.value }} {# "clubs" #}
1010
1111
{# get all cases of an enum #}
12-
{% for case in enum('App\\MyEnum').cases %}
12+
{% for case in enum('App\\CardSuite').cases %}
1313
{{ case.value }}
1414
{% endfor %}
15+
{# "clubs", "spades", "hearts", "diamonds" #}
16+
17+
{# get a specific case of an enum by value #}
18+
{% set card_suite = enum('App\\CardSuite').from('hearts') %}
19+
{{ card_suite.name }} {# "Hearts" #}
20+
{{ card_suite.value }} {# "hearts" #}
1521
1622
{# call any methods of the enum class #}
17-
{{ enum('App\\MyEnum').someMethod() }}
23+
{{ enum('App\\CardSuite').someMethod() }}
1824
1925
When using a string literal for the ``enum`` argument, it will be validated
2026
during compile time to be a valid enum name.

‎doc/functions/enum_cases.rst‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,9 +5,10 @@
55

66
.. code-block:: twig
77
8-
{% for case in enum_cases('App\\MyEnum') %}
8+
{% for case in enum_cases('App\\CardSuite') %}
99
{{ case.value }}
1010
{% endfor %}
11+
{# "clubs", "spades", "hearts", "diamonds" #}
1112
1213
When using a string literal for the ``enum`` argument, it will be validated during compile time to be a valid enum name.
1314

‎doc/recipes.rst‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -226,13 +226,14 @@ thanks to the magic ``__get()`` method; you need to also implement the
226226
Defining undefined Functions, Filters, and Tags on the Fly
227227
----------------------------------------------------------
228228

229-
When a function/filter/tag is not defined, Twig defaults to throw a
229+
When a function/filter/test/tag is not defined, Twig defaults to throw a
230230
``\Twig\Error\SyntaxError`` exception. However, it can also call a `callback`_
231-
(any valid PHP callable) which should return a function/filter/tag.
231+
(any valid PHP callable) which should return a function/filter/test/tag.
232232

233233
For tags, register callbacks with ``registerUndefinedTokenParserCallback()``.
234234
For filters, register callbacks with ``registerUndefinedFilterCallback()``.
235-
For functions, use ``registerUndefinedFunctionCallback()``::
235+
For functions, use ``registerUndefinedFunctionCallback()``.
236+
For tests, use ``registerUndefinedTestCallback()``::
236237

237238
// auto-register all native PHP functions as Twig functions
238239
// NEVER do this in a project as it's NOT secure
@@ -244,15 +245,15 @@ For functions, use ``registerUndefinedFunctionCallback()``::
244245
return false;
245246
});
246247

247-
If the callable is not able to return a valid function/filter/tag, it must
248+
If the callable is not able to return a valid function/filter/test/tag, it must
248249
return ``false``.
249250

250251
If you register more than one callback, Twig will call them in turn until one
251252
does not return ``false``.
252253

253254
.. tip::
254255

255-
As the resolution of functions/filters/tags is done during compilation,
256+
As the resolution of functions/filters/tests/tags is done during compilation,
256257
there is no overhead when registering these callbacks.
257258

258259
.. warning::

‎extra/intl-extra/Tests/Fixtures/country_timezones.test‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,10 +3,10 @@
33
--TEMPLATE--
44
{{ country_timezones('UNKNOWN')|length }}
55
{{ country_timezones('FR')|join(', ') }}
6-
{{ country_timezones('US')|join(', ') }}
6+
{{ country_timezones('US')[0:2]|join(', ') }}
77
--DATA--
88
return [];
99
--EXPECT--
1010
0
1111
Europe/Paris
12-
America/Adak, America/Anchorage, America/Boise, America/Chicago, America/Denver, America/Detroit, America/Indiana/Knox, America/Indiana/Marengo, America/Indiana/Petersburg, America/Indiana/Tell_City, America/Indiana/Vevay, America/Indiana/Vincennes, America/Indiana/Winamac, America/Indianapolis, America/Juneau, America/Kentucky/Monticello, America/Los_Angeles, America/Louisville, America/Menominee, America/Metlakatla, America/New_York, America/Nome, America/North_Dakota/Beulah, America/North_Dakota/Center, America/North_Dakota/New_Salem, America/Phoenix, America/Sitka, America/Yakutat, Pacific/Honolulu
12+
America/Adak, America/Anchorage

‎extra/markdown-extra/composer.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@
2121
},
2222
"require-dev": {
2323
"erusev/parsedown": "dev-master as 1.x-dev",
24-
"league/commonmark": "^1.0|^2.0",
24+
"league/commonmark": "^2.7",
2525
"league/html-to-markdown": "^4.8|^5.0",
2626
"michelf/php-markdown": "^1.8|^2.0",
2727
"symfony/phpunit-bridge": "^6.4|^7.0"

‎extra/twig-extra-bundle/composer.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@
2121
"twig/twig": "^3.2|^4.0"
2222
},
2323
"require-dev": {
24-
"league/commonmark": "^1.0|^2.0",
24+
"league/commonmark": "^2.7",
2525
"twig/cache-extra": "^3.0",
2626
"twig/cssinliner-extra": "^3.0",
2727
"twig/html-extra": "^3.0",

0 commit comments

Comments
 (0)