This PR was merged into the 3.x branch.
Discussion
----------
Document {#--#} as the replacement for the deprecated spaceless filter
Closes#4442
Commits
-------
c29877f54a Document {#--#} as the replacement for the deprecated spaceless filter
This PR was merged into the 3.x branch.
Discussion
----------
[Doc] Document loose comparison in the `in` operator
Clarifies the comparison semantics of the `in` operator in the *Containment Operators* section of `doc/templates.rst`:
- `in` uses a loose comparison (similar to `==`) for sequences, mappings, and `Traversable` objects, like PHP's `in_array()`.
- Pointer to `same as` for strict comparisons.
- Warning about boolean left operands (e.g. `true in ['foo', 'bar']` returns `true`), which surprises users.
- Note that string containment only accepts `string`, `int`, `float` on the left.
Closes#4650 (or at least the documentation half of it — the `Investigate before 4.x` label suggests the maintainers may want to revisit the actual semantics in 4.x; this PR addresses `@gorenstein`'s explicit request to "at least improve the documentation").
Commits
-------
8af8e93970 [Doc] Document loose comparison in the `in` operator
Clarifies that `in` performs a loose comparison on sequences, mappings,
and `Traversable` objects (similar to `==`), points to `same as` for
strict comparisons, and warns about boolean left operands.
Refs #4650
The previous wording ("inherited from PHP") was misleading: Twig does
not inherit anything from PHP, it deliberately implements the same
behavior, like Jinja does. The behavior was already explained earlier
in the same section, so just point back to it instead.
This PR was merged into the 3.x branch.
Discussion
----------
Reword parent-child analogy in `doc/tags/extends.rst`
Commits
-------
64a70e96a6 Replace parent-child analogy in `doc/tags/extends.rst`
- Add missing `sequence` and `mapping` to tests/index.rst toctree
- Fix alphabetical ordering of `guard`/`flush` in tags/index.rst
- Add orphaned `operators_precedence` to main index.rst toctree
This PR was squashed before being merged into the 3.x branch.
Discussion
----------
Add an `html_attr` function to make outputting HTML attributes easier
**Updated:** This description has been updated to reflect changes from the discussion up to https://github.com/twigphp/Twig/pull/3930#issuecomment-3870445987.
This PR suggests adding an `html_attr` function and two filters `html_attr_merge` and `html_attr_type`. Together, they are intended to make it easier to collect HTML attributes in arrays, in order to pass them in Twig to included templates or macros, and to ultimately print such attribute sets as.
`html_attr_merge` can be used to either merge such arrays over default values, or to override (say, inside a macro) particular values in a given attribute array. As described in #3907, it favors overwriting simple (scalar) attribute values and appending to multi-valued attributes over all the other operations one could conceive (like, for example, replacing a list of two CSS `class` names with two other ones). This is a design decision to keep the API simple and optimized for the primary use case that I see. But, since we're mostly dealing with arrays after all, users are free to do in parallel any other kind of array wrangling they see fit.
So, this PR is _not_ trying to design a full-fledged, object-oriented API with all the necessary methods to add, replace, remove attributes; to add, change or toggle elements in "list" style attributes like `class`; to provide extension points for custom (arbitrary) attributes or to provide a fluent API to do all that from within PHP code. See https://github.com/symfony/ux/issues/3269 for a Symfony UX component RFC that does that.
A little bit of special case handling is present for `aria-*`, `data-*` and inline CSS `style` attributes. But apart from that, there is no special knowledge about the attributes defined in HTML, ARIA or other standards, nor about the structure and sementic of attribute values. The approach works in a generic way, so it should be possible to use it for many custom attributes as well.
In order to support "list" style attributes like `class`, `aria-labelledby` or `srcset` that may come in different flavors, users have to be disciplined and consistently use iterables (arrays) to represent such attribute values, possibly assisted by the `html_attr_type` filter (see below).
When printing attributes, names and values are escaped. For names, the `html_attr_relaxed` strategy (#4743) is used.
#### Motivation and practical examples
I have seen repeating patterns when dealing with HTML attributes in Twig templates and macros. Typical examples can be found in Symfony's form theme, where an `attr` variable is present in various blocks.
https://github.com/symfony/symfony/blob/4a5d8cf03e1e31d1a7591921c6fa1fe7ec1c2015/src/Symfony/Bridge/Twig/Resources/views/Form/form_div_layout.html.twig#L453-L458
```twig
{%- block widget_attributes -%}
id="{{ id }}" name="{{ full_name }}"
{%- if disabled %} disabled="disabled"{% endif -%}
{%- if required %} required="required"{% endif -%}
{{ block('attributes') }}
{%- endblock widget_attributes -%}
```
Could be along the lines of:
`{{ html_attr(attr, { id, name: full_name, disabled: disabled ? true : false, required : required ? true : false }) }}`.
If `disabled` and `required` were guaranteed to be booleans (I haven't checked), even better:
`{{ html_attr(attr, { id, name: full_name, disabled, required }) }}`
https://github.com/symfony/symfony/blob/4a5d8cf03e1e31d1a7591921c6fa1fe7ec1c2015/src/Symfony/Bridge/Twig/Resources/views/Form/form_div_layout.html.twig#L347-L360
```twig
{%- set attr = {} -%}
{%- set aria_describedby = [] -%}
{%- if help -%}
{%- set aria_describedby = aria_describedby|merge([id ~ '_help']) -%}
{%- endif -%}
{%- if errors|length > 0 -%}
{%- set aria_describedby = aria_describedby|merge(errors|map((_, index) => id ~ '_error' ~ (index + 1))) -%}
{%- endif -%}
{%- if aria_describedby|length > 0 -%}
{%- set attr = attr|merge({'aria-describedby': aria_describedby|join(' ')}) -%}
{%- endif -%}
{%- if errors|length > 0 -%}
{%- set attr = attr|merge({'aria-invalid': 'true'}) -%}
{%- endif -%}
```
Could be:
```twig
{%- set attr = {}|html_attr_merge(
help ? { 'aria-describedby': [id ~ '_help'] },
errors|length ? { 'aria-invalid': true, 'aria-describedby': errors|map((_, index) => id ~ '_error' ~ (index + 1)) }
) -%}
```
https://github.com/symfony/symfony/blob/4a5d8cf03e1e31d1a7591921c6fa1fe7ec1c2015/src/Symfony/Bridge/Twig/Resources/views/Form/form_div_layout.html.twig#L470-L481
```twig
{% block attributes -%}
{%- for attrname, attrvalue in attr -%}
{{- ' ' -}}
{%- if attrname in ['placeholder', 'title'] -%}
{{- attrname }}="{{ translation_domain is same as(false) or attrvalue is null ? attrvalue : attrvalue|trans(attr_translation_parameters, translation_domain) }}"
{%- elseif attrvalue is same as(true) -%}
{{- attrname }}="{{ attrname }}"
{%- elseif attrvalue is not same as(false) -%}
{{- attrname }}="{{ attrvalue }}"
{%- endif -%}
{%- endfor -%}
{%- endblock attributes -%}
```
This should basically be the same as `{{ html_attr(attr) }}`, ignoring edge cases for `null` values. Handling of the `translation_domain` might require a preceding `html_attr_merge` step to replace values with translations.
Finally,
```twig
{% set id = 'id value' %}
{% set href = 'href value' %}
{% set disabled = true %}
<div {{ html_attr(
{ id, href },
disabled ? { 'aria-disabled': 'true' },
not disabled ? { 'aria-enabled' : true },
{ class: ['zero', 'first'] },
{ class: ['second'] },
true ? { class: 'third' },
{ style: { color: 'red' } },
{ style: { 'background-color': 'green' } },
{ style: { color: 'blue' } },
{ 'data-test': 'some value' },
{ 'data-test': 'other value', 'data-bar': 'baz' }},
{ 'dangerous=yes foo' : 'xss' },
{ style: ['text-decoration: underline'] },
) }}></div>
```
will generate HTML markup:
```
<div id="id value" href="href value" aria-disabled="true" class="zero first second third" style="color: red; background-color: green; color: blue; text-decoration: underline;" data-test="other value" data-bar="baz" dangerous=yes foo="xss"></div>
```
#### Details on `html_attr_merge`
This filter merges an `attr` style array with one or several other arrays given as arguments. All of those arrays should reasonably be mappings, i. e. use keys that denote attribute names, and not sequences or lists with numeric keys.
Empty arrays, empty strings or false values in the argument list will be ignored, which can be used to conditionally include values in the merge list like so:
```twig
{% set attr = attr|html_attr_merge(
condition ? { attrname: "attrvalue", other: "value" }
) %}
```
The merging of attribute values is similar to PHP's `array_merge` function. Latter (right) values generally override former (left) values, as follows:
When two values are to be merged and both are either scalars or objects, the latter (right) value overrides the previous (left) one.
When both values are iterables, `array_merge`/spread operator behavior is used: Numeric indices will be appended, whereas non-numeric ones will be replaced. This can be used to override designated elements in sets like CSS classes:
```twig
{% set attr = { class: ['foo', 'bar'] }|html_attr_merge(
{ class: { importance: 'normal' } },
critical ? { class: { importance: 'high' } }
) %}
```
To provide more flexibility with regards to different merging strategies, the `MergeInterface` is provided as a flex point for advanced use cases of power users.
* When an attribute value that represents a "right hand side" value has to be merged and implements `MergeInterface`, its `mergeInto()` method will be passed the previous (left hand side) value. That method will return the merge result.
* Otherwise, when the "left hand side" value implements `MergeInterface`, `appendFrom()` will be passed the new (right hand side) value. Again, that method returns the merge result.
Other combinations of values are rejected, an exception is thrown. This is a design decision to clearly and early notify users of combinations that might have unclear or unpredictable results, like merging a string like `'foo'` with an array like `['bar', 'baz']` for a `class` attribute – should this override, since one value is a scalar, or append, since the other one is an array?
#### Details on `html_attr`
The `html_attr()` function prints attribute-arrays as HTML. It will perform appropriate escaping of attribute names and values.
One or several attribute arrays can be passed to `html_attr`, and `html_attr_merge` will be used first to merge those.
In general, scalar attribute values (including the empty string `''`) will be printed as-is. For booleans and `null` values, the following extra rules apply:
* For `aria-*`, boolean `true` and `false` will be coalesced to `"true"` and `"false"`, respectively.
* For `data-*`, boolean `true` will be coalesced to `"true"`, and non-scalar values will be JSON-encoded
* Otherwise, `false` and `null` attribute values will always omit printing of the attribute.
* `true` values will print the attribute as `attributeName=""`. This is equivalent to printing `<... attributeName>`, but is X(HT)ML compliant. The user-agent will fill in the attribute's _empty default value_.
These rules derive from the comparison provided at https://github.com/symfony/ux/issues/3269#issuecomment-3708588342 that shows how React and Vue as front-end frameworks behave in the same situation.
For values that implement `AttributeValueInterface`, its `getValue(): ?string` method will be called first. The attribute will be omitted for a `null` return value, otherwise printed with the returned string.
This interface could be used to provide (outside the scope of this PR or even outside Twig itself) classes that could e. g. help building more complex attribute values, like for image `srcset`. But the primary reason for adding it was to be able to deal with attributes values that are lists or hashes and need to be printed in different ways:
* attributes like `class` or `aria-labelledby` use [space-separated tokens](https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#space-separated-tokens) as their value
* `srcset` or `sizes` for `<img>` use [comma-separated tokens](https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#comma-separated-tokens)
* other standards/extensions may have even other concepts
`html_attr` will generally print array values as a space-separated list of values.
A special case is the attribute name `style` if its value is an array. It will be converted to inline CSS. Values with numeric keys will be printed followed by a `;`. Non-numeric keys will print a pattern of `key: value;`.
#### Details on `html_attr_type`
The `html_attr_type` filter can be used to convert an array passed into it into implementations of the mentioned interfaces in a few predefined ways. It takes a single argument indicating the type to use – similar to the `escape` filter in Twig that knows about `html`, `js`, `css` and a few more.
* `sst` means `space separated tokens`
* `cst` means `comma separated tokens`
* `style` means "inline CSS", for completeness
So, the following will construct an `attr` array for an `img` tag, where `sizes` needs to be printed separated by commas.
```twig
{% set attr = {
srcset: ['small.jpg 480w']|html_attr_type('cst'),
alt: 'A cute kitten'
} %}
{# amend the srcset #}
{% set attr = attr|html_attr_merge({ srcset: ['medium.jpg 800w', 'large.jpg 1200w'] }) %}
<img {{ html_attr(attr) />
```
This works because the `SeparatedTokenList` that is used for `sst` and `cst` implements merge behavior where a given value can be extended by merging arrays.
#### Design considerations
Exposing behavior for different attribute types through these interfaces may not be the 100% perfect, nice, automagic solution. _But_ it has the big advantage that we are not committing ourselves to a particular list of attributes for which standards-specific knowledge would have to be put in the code. I would consider that a maintenance nightmare, since it would require us to decide which attribute/special case to support and which not. Every single change in that list would be BC-breaking.
The two interfaces put control over that in the hands of power users or extension authors. Arbitrary ways could be conceived to create instances of these interfaces.
The `html_attr_type` filter provides built-in access to the two types I see relevant in the HTML 5 standard, the space and comma separated token lists.
The built-in default conversion of arrays to space-separated token lists should further reduce visibility of that problem for average template authors, who can hopefully ignore the problem most of the time.
Closes#3907, which outlined the initial idea.
#### TODO:
- [x] Get initial feedback
- [x] Add tests
- [x] Concept for attributes that employ [comma-separated tokens](https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#comma-separated-tokens)
- [x] Add documentation
- [x] Add docblocks and type hints
- [x] Make a decision: [Escape attribute names or not?](https://github.com/twigphp/Twig/pull/3930#issuecomment-3743429100)
Co-authored-by: `@polarbirke`
Commits
-------
42c12fa720 Add an `html_attr` function to make outputting HTML attributes easier
This PR was merged into the 3.x branch.
Discussion
----------
Add getOperatorTokens() to ExpressionParserInterface to separate operator token registration from parser identity
Closes#4767Closes#4774
Commits
-------
e5eb95d0d7 Add getOperatorTokens() to ExpressionParserInterface to separate operator token registration from parser identity
This PR was merged into the 3.x branch.
Discussion
----------
Support short-circuiting in null-safe operator chains
This PR adds short-circuiting for null-safe operator chains, using the same rules as PHP, `PropertyAccess`, and the `ExpressionLanguage`.
Previously, only the immediate null-safe access was guarded. With this change, as soon as a `null` is encountered at a null-safe access, the rest of the chain is skipped.
My approach was to move the null check outside of the `getAttribute()` calls so the expression can immediately return `null`, eg:
```twig
foo?.bar.baz
```
Before:
```php
yield $this->env
->getRuntime('Twig\Runtime\EscaperRuntime')
->escape(
CoreExtension::getAttribute(
$this->env,
$this->source,
(
null === (
$_v0 = (
isset($context['foo']) || array_key_exists('foo', $context)
? $context['foo']
: throw new RuntimeError('Variable "foo" does not exist.', 3, $this->source)
)
)
? null
: CoreExtension::getAttribute(
$this->env,
$this->source,
$_v0,
'bar',
[],
'any',
false,
false,
false,
3
)
),
'baz',
[],
'any',
false,
false,
false,
3
),
'html',
null,
true
);
```
Now:
```php
yield $this->env
->getRuntime('Twig\Runtime\EscaperRuntime')
->escape(
(
null === (
$_v0 = (
isset($context['foo']) || array_key_exists('foo', $context)
? $context['foo']
: throw new RuntimeError('Variable "foo" does not exist.', 3, $this->source)
)
)
? null
: CoreExtension::getAttribute(
$this->env,
$this->source,
CoreExtension::getAttribute(
$this->env,
$this->source,
$_v0,
'bar',
[],
'any',
false,
false,
false,
3
),
'baz',
[],
'any',
false,
false,
false,
3
)
),
'html',
null,
true
);
```
Commits
-------
d56e8e2dba Support short-circuiting in null-safe operator chains
This PR was merged into the 3.x branch.
Discussion
----------
Add support for renaming variables in object destructuring
Closes#4747
Commits
-------
3cc1b5233c Add support for renaming variables in object destructuring
This PR was merged into the 3.x branch.
Discussion
----------
[Doc] Fix intro for operator precedence table ?
The table introductory paragraph says operator with lowest precedence are listed first ( I assume it means "listed first in the operator table" ).
However, the table starts with a precedence of 500, which seems to be the highest.
Am I completely misreading this ?
Commits
-------
26a12f73f2 Fix intro for operator precedence table ?
This PR was merged into the 3.x branch.
Discussion
----------
Update u.rst to clarify truncate method's third argument behavior
Current wording "to preserve whole words" suggests setting the argument to ``true`` preserves words. However, the parameter is ``$cut`` (defaults to ``true`` for cutting at exact length), and ``false`` is required to preserve whole words.
Commits
-------
28c2606be7 Update u.rst to clarify truncate method's third argument behavior
This PR was merged into the 3.x branch.
Discussion
----------
Fix documentation for getOperators()
Closes#4710
Commits
-------
ae51f93f70 Fix documentation for getOperators()
Current wording "to preserve whole words" suggests setting the argument to ``true`` preserves words. However, the parameter is ``$cut`` (defaults to ``true`` for cutting at exact length), and ``false`` is required to preserve whole words.
This PR was squashed before being merged into the 3.x branch.
Discussion
----------
Enhance enum.rst with dynamic case example
Added example for dynamic enum case display.
Commits
-------
bcc5ffc301 Enhance enum.rst with dynamic case example
Fabien Potencier
Pascal CESCON - Amoifr
llupa
Matthias Pigulla
Arnaud Ligny
HypeMC
Always-Victorious