Merge branch '3.x' into 4.x

* 3.x:
  Rename a variable for more clarity
  Set IteratorAggregate generics for Node
  Add cross-link
  Let's no deprecate the attribute function yet
  Add more precise types for the registration of safe classes
  Clarify coding standards
  Fix markup
  Fix markup
  Clarify docs for the u filter
  Allow to use a dynamic attribute on the . operator via ()
  Remove most usage of foo/bar/baz in the docs
  Tweak docs
  Add StringCastUnary

doc/advanced.rst

@@ -271,8 +271,8 @@ A dynamic filter can define more than one dynamic parts::
 
 The filter receives all dynamic part values before the normal filter arguments,
 but after the environment and the context. For instance, a call to
-``'foo'|a_path_b()`` will result in the following arguments to be passed to the
-filter: ``('a', 'b', 'foo')``.
+``'Paris'|a_path_b()`` will result in the following arguments to be passed to the
+filter: ``('a', 'b', 'Paris')``.
 
 Deprecated Filters
 ~~~~~~~~~~~~~~~~~~
@@ -898,14 +898,14 @@ structure in your test directory::
 
     Fixtures/
         filters/
-            foo.test
-            bar.test
+            lower.test
+            upper.test
         functions/
-            foo.test
-            bar.test
+            date.test
+            format.test
         tags/
-            foo.test
-            bar.test
+            for.test
+            if.test
     IntegrationTest.php
 
 The ``IntegrationTest.php`` file should look like this::

doc/api.rst

@@ -396,32 +396,32 @@ The escaping rules are implemented as follows:
 
   .. code-block:: html+twig
 
-        {{ foo ? "Twig<br/>" : "<br/>Twig" }} {# won't be escaped #}
+        {{ any_value ? "Twig<br/>" : "<br/>Twig" }} {# won't be escaped #}
 
         {% set text = "Twig<br/>" %}
         {{ true ? text : "<br/>Twig" }} {# will be escaped #}
         {{ false ? text : "<br/>Twig" }} {# won't be escaped #}
 
         {% set text = "Twig<br/>" %}
-        {{ foo ? text|raw : "<br/>Twig" }} {# won't be escaped #}
+        {{ any_value ? text|raw : "<br/>Twig" }} {# won't be escaped #}
 
 * Objects with a ``__toString`` method are converted to strings and
   escaped. You can mark some classes and/or interfaces as being safe for some
   strategies via ``EscaperExtension::addSafeClass()``:
 
   .. code-block:: twig
 
-        // mark object of class Foo as safe for the HTML strategy
-        $escaper->addSafeClass('Foo', ['html']);
+        // mark objects of class "HtmlGenerator" as safe for the HTML strategy
+        $escaper->addSafeClass('HtmlGenerator', ['html']);
 
-        // mark object of interface Foo as safe for the HTML strategy
-        $escaper->addSafeClass('FooInterface', ['html']);
+        // mark objects of interface "HtmlGeneratorInterface" as safe for the HTML strategy
+        $escaper->addSafeClass('HtmlGeneratorInterface', ['html']);
 
-        // mark object of class Foo as safe for the HTML and JS strategies
-        $escaper->addSafeClass('Foo', ['html', 'js']);
+        // mark objects of class "HtmlGenerator" as safe for the HTML and JS strategies
+        $escaper->addSafeClass('HtmlGenerator', ['html', 'js']);
 
-        // mark object of class Foo as safe for all strategies
-        $escaper->addSafeClass('Foo', ['all']);
+        // mark objects of class "HtmlGenerator" as safe for all strategies
+        $escaper->addSafeClass('HtmlGenerator', ['all']);
 
 * Escaping is applied before printing, after any other filter is applied:
 
@@ -454,8 +454,8 @@ The escaping rules are implemented as follows:
 
     Note that autoescaping has some limitations as escaping is applied on
     expressions after evaluation. For instance, when working with
-    concatenation, ``{{ foo|raw ~ bar }}`` won't give the expected result as
-    escaping is applied on the result of the concatenation, not on the
+    concatenation, ``{{ value|raw ~ other }}`` won't give the expected result
+    as escaping is applied on the result of the concatenation, not on the
     individual variables (so, the ``raw`` filter won't have any effect here).
 
 Sandbox Extension

doc/coding_standards.rst

@@ -15,18 +15,18 @@ standards:
 
   .. code-block:: twig
 
-    {{ foo }}
+    {{ user }}
     {# comment #}
-    {% if foo %}{% endif %}
+    {% if user %}{% endif %}
 
   When using the whitespace control character, do not put any spaces between
   it and the delimiter:
 
   .. code-block:: twig
 
-    {{- foo -}}
+    {{- user -}}
     {#- comment -#}
-    {%- if foo -%}{%- endif -%}
+    {%- if user -%}{%- endif -%}
 
 * Put exactly one space before and after the following operators:
   comparison operators (``==``, ``!=``, ``<``, ``>``, ``>=``, ``<=``), math
@@ -36,17 +36,17 @@ standards:
 
   .. code-block:: twig
 
-     {{ 1 + 2 }}
-     {{ foo ~ bar }}
-     {{ true ? true : false }}
+    {{ 1 + 2 }}
+    {{ first_name ~ ' ' ~ last_name }}
+    {{ is_correct ? true : false }}
 
 * Put exactly one space after the ``:`` sign in mappings and ``,`` in sequences
   and mappings:
 
   .. code-block:: twig
 
-     {{ [1, 2, 3] }}
-     {{ {'foo': 'bar'} }}
+    [1, 2, 3]
+    {'name': 'Fabien'}
 
 * Do not put any spaces after an opening parenthesis and before a closing
   parenthesis in expressions:
@@ -59,15 +59,15 @@ standards:
 
   .. code-block:: twig
 
-    {{ 'foo' }}
-    {{ "foo" }}
+    {{ 'Twig' }}
+    {{ "Twig" }}
 
 * Do not put any spaces before and after the following operators: ``|``,
   ``.``, ``..``, ``[]``:
 
   .. code-block:: twig
 
-    {{ foo|upper|lower }}
+    {{ name|upper|lower }}
     {{ user.name }}
     {{ user[name] }}
     {% for i in 1..12 %}{% endfor %}
@@ -77,37 +77,45 @@ standards:
 
   .. code-block:: twig
 
-     {{ foo|default('foo') }}
-     {{ range(1..10) }}
+    {{ name|default('Fabien') }}
+    {{ range(1..10) }}
 
 * Do not put any spaces before and after the opening and the closing of
   sequences and mappings:
 
   .. code-block:: twig
 
-     {{ [1, 2, 3] }}
-     {{ {'foo': 'bar'} }}
+    [1, 2, 3]
+    {'name': 'Fabien'}
 
-* Use lower cased and underscored variable names:
+* Use snake case for all variable names (provided by the application and
+  created in templates):
 
   .. code-block:: twig
 
-     {% set foo = 'foo' %}
-     {% set foo_bar = 'foo' %}
+    {% set name = 'Fabien' %}
+    {% set first_name = 'Fabien' %}
+
+* Use snake case for all function/filter/test names:
+
+  .. code-block:: twig
+
+    {{ 'Fabien Potencier'|to_lower_case }}
+    {{ generate_random_number() }}
 
 * Indent your code inside tags (use the same indentation as the one used for
   the target language of the rendered template):
 
   .. code-block:: twig
 
-     {% block foo %}
-         {% if true %}
-             true
-         {% endif %}
-     {% endblock %}
+    {% block content %}
+        {% if true %}
+            true
+        {% endif %}
+    {% endblock %}
 
 * Use ``:`` instead of ``=`` to separate argument names and values:
 
   .. code-block:: twig
 
-     {{ data|convert_encoding(from: 'iso-2022-jp', to: 'UTF-8') }}
+    {{ data|convert_encoding(from: 'iso-2022-jp', to: 'UTF-8') }}

doc/filters/default.rst

@@ -8,9 +8,9 @@ undefined or empty, otherwise the value of the variable:
 
     {{ var|default('var is not defined') }}
 
-    {{ var.foo|default('foo item on var is not defined') }}
+    {{ user.name|default('name item on user is not defined') }}
 
-    {{ var['foo']|default('foo item on var is not defined') }}
+    {{ user['name']|default('name item on user is not defined') }}
 
     {{ ''|default('passed var is empty')  }}
 
@@ -20,16 +20,17 @@ undefined:
 
 .. code-block:: twig
 
-    {{ var.method(foo|default('foo'))|default('foo') }}
+    {{ user.value(name|default('username'))|default('not defined') }}
     
-Using the ``default`` filter on a boolean variable might trigger unexpected behavior, as
-``false`` is treated as an empty value. Consider using ``??`` instead:
+Using the ``default`` filter on a boolean variable might trigger unexpected
+behavior, as ``false`` is treated as an empty value. Consider using ``??``
+instead:
 
 .. code-block:: twig
 
-    {% set foo = false %}
-    {{ foo|default(true) }} {# true #}
-    {{ foo ?? true }} {# false #}
+    {% set value = false %}
+    {{ value|default(true) }} {# true #}
+    {{ value ?? true }} {# false #}
 
 .. note::
 

doc/filters/escape.rst

@@ -104,7 +104,7 @@ callable that accepts a string to escape and the charset::
     $twig->getRuntime(EscaperRuntime::class)->setEscaper('identity', $escaper);
 
     # Usage in a template:
-    # {{ 'foo'|escape('identity') }}
+    # {{ 'Twig'|escape('identity') }}
 
 .. note::
 

doc/filters/format.rst

@@ -6,10 +6,10 @@ The ``format`` filter formats a given string by replacing the placeholders
 
 .. code-block:: twig
 
-    {{ "I like %s and %s."|format(foo, "bar") }}
+    {% set fruit = 'apples' %}
+    {{ "I like %s and %s."|format(fruit, "oranges") }}
 
-    {# outputs I like foo and bar
-       if the foo parameter equals to the foo string. #}
+    {# outputs I like apples and oranges #}
 
 .. seealso::
 

doc/filters/slice.rst

@@ -21,7 +21,7 @@ You can use any valid expression for both the start and the length:
         {# ... #}
     {% endfor %}
 
-As syntactic sugar, you can also use the ``[]`` notation:
+As syntactic sugar, you can also use the ``[]`` operator:
 
 .. code-block:: twig
 

doc/filters/split.rst

@@ -6,8 +6,8 @@ of strings:
 
 .. code-block:: twig
 
-    {% set foo = "one,two,three"|split(',') %}
-    {# foo contains ['one', 'two', 'three'] #}
+    {% set items = "one,two,three"|split(',') %}
+    {# items contains ['one', 'two', 'three'] #}
 
 You can also pass a ``limit`` argument:
 
@@ -21,19 +21,19 @@ You can also pass a ``limit`` argument:
 
 .. code-block:: twig
 
-    {% set foo = "one,two,three,four,five"|split(',', 3) %}
-    {# foo contains ['one', 'two', 'three,four,five'] #}
+    {% set items = "one,two,three,four,five"|split(',', 3) %}
+    {# items contains ['one', 'two', 'three,four,five'] #}
 
 If the ``delimiter`` is an empty string, then value will be split by equal
 chunks. Length is set by the ``limit`` argument (one character by default).
 
 .. code-block:: twig
 
-    {% set foo = "123"|split('') %}
-    {# foo contains ['1', '2', '3'] #}
+    {% set items = "123"|split('') %}
+    {# items contains ['1', '2', '3'] #}
 
-    {% set bar = "aabbcc"|split('', 2) %}
-    {# bar contains ['aa', 'bb', 'cc'] #}
+    {% set items = "aabbcc"|split('', 2) %}
+    {# items contains ['aa', 'bb', 'cc'] #}
 
 .. note::
 

doc/filters/u.rst

@@ -18,6 +18,9 @@ Wrapping a text to a given number of characters:
     Twig
     = <3
 
+Here, ``u`` is the filter and ``wordwrap(5)`` is a method called on the result
+of the filter; it's equivalent to ``(text|u).wordwrap(5)``.
+
 Truncating a string:
 
 .. code-block:: twig
@@ -56,14 +59,6 @@ You can also chain methods:
     TWIG
     = <3
 
-For large strings manipulation, use the ``apply`` tag:
-
-.. code-block:: twig
-
-    {% apply u.wordwrap(5) %}
-        Some large amount of text...
-    {% endapply %}
-
 .. note::
 
     The ``u`` filter is part of the ``StringExtension`` which is not installed

doc/filters/url_encode.rst

@@ -12,8 +12,8 @@ mapping as query string:
     {{ "string with spaces"|url_encode }}
     {# outputs "string%20with%20spaces" #}
 
-    {{ {'param': 'value', 'foo': 'bar'}|url_encode }}
-    {# outputs "param=value&foo=bar" #}
+    {{ {'name': 'Fabien', 'city': 'Paris'}|url_encode }}
+    {# outputs "name=Fabien&city=Paris" #}
 
 .. note::
 

doc/functions/attribute.rst

@@ -1,6 +1,15 @@
 ``attribute``
 =============
 
+.. warning::
+
+    The ``attribute`` filter is deprecated as of Twig 3.15. Use the
+    :ref:`dot operator <dot_operator>` that now accepts any expression
+    when wrapped with parenthesis.
+
+    Note that this filter will still be available in Twig 4.0 to allow a
+    smoother upgrade path.
+
 The ``attribute`` function can be used to access a "dynamic" attribute of a
 variable:
 
@@ -20,7 +29,7 @@ attribute:
 .. note::
 
     The resolution algorithm is the same as the one used for the ``.``
-    notation, except that the item can be any valid expression.
+    operator, except that the item can be any valid expression.
 
 Arguments
 ---------

doc/functions/include.rst

@@ -19,15 +19,15 @@ additional variables:
 .. code-block:: twig
 
     {# template.html will have access to the variables from the current context and the additional ones provided #}
-    {{ include('template.html', {foo: 'bar'}) }}
+    {{ include('template.html', {name: 'Fabien'}) }}
 
 You can disable access to the context by setting ``with_context`` to
 ``false``:
 
 .. code-block:: twig
 
-    {# only the foo variable will be accessible #}
-    {{ include('template.html', {foo: 'bar'}, with_context = false) }}
+    {# only the name variable will be accessible #}
+    {{ include('template.html', {name: 'Fabien'}, with_context = false) }}
 
 .. code-block:: twig