Problem/Motivation

None of the Twig filters have their argument names documented. As such, the names of the function arguments weren't given a lot of thought. If you were to use the undocumented arguments names in Twig with 8.x-2.3, you'd use:

{{ form|recursive_merge( array={'element': {'attributes': {'placeholder': 'Label'}}} ) }}
{{ form|set( path='element.#attributes.placeholder', value='Label' ) }}
{{ form|add( path='element.#attributes.class', value='new-class' ) }}
  1. The "array" argument in recursive_merge is kind of generic. The underlying array_replace_recursive() function uses replacements for its named argument.
  2. The "path" argument in the set and add filters isn't a well-defined term. PHP talks about array keys and nested arrays, not about paths to any specific nested element. Twig core describes this dot syntax like this:

    Use a dot (.) to access attributes of a variable (methods or properties of a PHP object, or items of a PHP array)

Proposed resolution

For the recursive_merge filter:

The underlying array_replace_recursive() function uses replacements for its named argument, but that is an implementation detail that the user doesn't need to know about. The PHP function, array_merge_recursive() breaks render arrays (which is why we don't use it), but uses "arrays" for its named argument.

So, I guess, the current "array" argument name is our best option. We just need to document it.

For the add/set filters:

The "path" argument name in the set and add filters isn't a well-defined term. PHP talks about array keys and nested arrays, not about paths to any specific nested element.

If we change this argument name to "at", we get the English-like syntax of:

{{ form|add(at="element", value="val") }}
{# OR #}
{{ form|add(value="val", at="element") }}

{# And for the set filter
{{ form|set(at="element", value="val") }}
{# OR #}
{{ form|set(value="val", at="element") }}

We could even add a plural form as a grammatical convenience for the add filter which can add an array of "values":
{{ form|add(values=["one", "two"], at="element") }}.

Issue fork components-3209575

Command icon Show commands

Start within a Git clone of the project using the version control instructions.

Or, if you do not have SSH keys set up on git.drupalcode.org:

Comments

JohnAlbin created an issue. See original summary.

johnalbin’s picture

Title: Rename the named parameter of Twig filters from "path" to "at" » Rename the named argument of Twig filters from "path" to "at"
Issue summary: View changes
Status: Active » Needs review

  • JohnAlbin committed 429cbf9 on 3.x
    Issue #3209575 by JohnAlbin: Rename the named argument of Twig filters...
johnalbin’s picture

Status: Needs review » Fixed

Fixed in 3.x. Needs backporting to 8.x-2.x.

johnalbin’s picture

Version: 3.x-dev » 8.x-2.x-dev
Status: Fixed » Active

johnalbin’s picture

Status: Active » Needs review
johnalbin’s picture

  • JohnAlbin committed 2ce7ed9 on 8.x-2.x
    Issue #3209575 by JohnAlbin: Rename the named argument of Twig filters...
johnalbin’s picture

Assigned: johnalbin » Unassigned
Status: Needs review » Fixed

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.