fix(view)!: fix inconsistent fallthrough attributes and introduce apply attribute for full control

[iamdadmin]

Closes #2040.

This is likely to be a breaking change, I've taken the liberty of writing a blog post in Markdown explaining it, which you're welcome to post, adapt, or not use as suits your needs.

If changes are needed, I can adjust as well. Here's it pasted in for all to read.

Updated approach for fallthrough attributes in Tempest View

Tempest's view components provide a convenient automatic fallthrough of class, style, and id from the call site onto the root element of a component template. Pass class="mt-4" to <x-button /> and it appears on the <button> inside — no boilerplate needed.

However, a simple bug in the code meant that this didn't happen consistently, and even then there was no method to control the behaviour if it was not required. The inconsistent nature of the bug - anchored on whether or not there was a PHP preamble or other content before the 'first' HTML token in the component - means that a direct fix would be a breaking change for many applications.

The Bug

The original implementation used a single regular expression anchored to the start of the compiled template string:

$compiled->replaceRegex(
    regex: '/^<(?<tag>[\w-]+)(.*?["\s])?>/',
    ...
);

The ^ anchor means: match only if the very first character of the file is <. For a component like this, it worked fine:

<button class="rounded-md px-2.5 py-1.5 text-sm">
    <x-slot />
</button>

But the moment a PHP preamble appeared before the first tag — even a declare statement or a comment — the regex found nothing, silently produced no output, and the fallthrough was lost entirely:

<?php
$variant = $variant ?? 'primary';
?>
<button class="rounded-md px-2.5 py-1.5 text-sm">
    <x-slot />
</button>

No error. No warning. The class you passed from the parent simply never arrived.

Tempest version 3.8.0 brought changes to the way a view component was compiled, but the bug still asserted itself. The regex was removed and replaced with a proper AST walk using TempestViewParser::ast() - a big step forward - but the fallthrough check was anchored to the token index instead of the token type:

$shouldApplyFallthrough = $i === 0 && $token->type === TokenType::OPEN_TAG_START && $token->tag !== 'x-slot';

$i === 0 means: only attempt fallthrough if the first token in the parsed AST is the opening tag. However, a PHP preamble is its own token. So when one was present, the HTML element appeared at index 1 or later, $i === 0 was false, $shouldApplyFallthrough was false, and the fallthrough was silently dropped — exactly as before, just through different code. The same tests that failed before continued to fail locally.

Why wasn't it spotted before?

There are tests for this - several in fact. However, they all used minimal fixtures, and none of which had a PHP preamble.

<?php
$componentClass = 'component-class';
$componentStyle = 'display: block;';
?><x-fallthrough-test class="component-class" />
<x-fallthrough-test :class="$componentClass" />
<x-fallthrough-dynamic-test c="component-class" s="display: block;" />
<x-fallthrough-dynamic-test :c="$componentClass" :s="$componentStyle"/>

<div class="in-component"></div>

<div :class="$attributes->get('c')" :style="$attributes->get('s')"></div>

This update also brings updated tests, all of which include a PHP preamble, with simply a comment to hold it in the file, in order to ensure that the issue is tested for going forwards.

No developer control over fallthrough attributes

Beyond the bug, the original implementation was all-or-nothing. It always attempted to merge class, style, and id onto the first element, with no way to opt out, no way to target a specific element, and no way to know it had run. If your component defined its own class on the root element, the incoming value was appended on top of it regardless.

How it was resolved

Finding the first tag properly

The regex was replaced with a proper AST walk. TempestViewParser::ast() already tokenises the template, so instead of guessing with a pattern, we iterate tokens and find the first real OPEN_TAG_START or SELF_CLOSING_TAG — skipping past PHP blocks, whitespace, comments, and doctypes entirely:

foreach ($tokens as $token) {
    if (in_array($token->type, [TokenType::OPEN_TAG_START, TokenType::SELF_CLOSING_TAG], true)
        && $token->tag !== 'x-slot') {
        $firstToken = $token;
        break;
    }
}

The first valid HTML token is found regardless of what precedes it in the file. PHP preambles, declare(strict_types=1), comment blocks — none of them interfere.

Respecting what the component already declares

The previous behaviour unconditionally merged incoming values onto whatever the root element had. The new behaviour checks first: if the root element already declares class, :class, style, :style, id, or :id, the fallthrough for that attribute is now skipped entirely.

if (array_key_exists($name, $firstToken->htmlAttributes)
    || array_key_exists(':' . $name, $firstToken->htmlAttributes)) {
    continue;
}

For applications previously relying on the mandatory merge of these attributes, this is a breaking change, meaning you'll need to adjust your views to manually implement the merge. This was a necessary change however, in order to add control.

This now means a component can take ownership of any of these attributes simply by declaring them. Pass whatever you like from the call site — if the component has already configured it, the component wins:

<button :class="$class ?? 'rounded-md px-2.5 py-1.5 text-sm'">
    <x-slot />
</button>

With the above, class is owned by the component. Pass class="something-else" from the call site and the component's expression takes precedence. id and style, having no declaration on the root, still fall through as before.

The new :apply attribute

For cases where you want full manual control — spreading additional attributes, filtering specific ones, or building the attribute set dynamically — the new :apply attribute hands you that control explicitly.

Placing :apply anywhere in a component template disables automatic fallthrough for that component entirely. The $attributes variable, an ImmutableArray of everything passed at the call site, is always available:

<button :apply="$attributes">
    <x-slot />
</button>

Because $attributes is an ImmutableArray, you can filter it before spreading. To exclude specific attributes:

<button :apply="$attributes->removeKeys['id', 'style'])">
    <x-slot />
</button>

To include only specific attributes:

<button :apply="$attributes->removeKeysExcept(['class'])">
    <x-slot />
</button>

You can also build the array entirely yourself in a PHP preamble and pass it in, which pairs naturally with the :as attribute for components that conditionally render as different elements:

<?php
$apply = [
    'class' => $class ?? null,
    'href'  => $href ?? '',
    'target' => (isset($href) && str_contains($href, 'http')) ? '_blank' : null,
];
?>
<button :as="$apply['href'] !== '' ? 'a' : 'button'" :apply="$apply">
    {{ $label ?? '' }}
</button>

:apply stringifies attribute values according to the following rules: true emits a bare attribute name; false, null, and empty string are omitted; everything else is rendered as name="value".

[github-actions]

Benchmark Results

Comparison of 3.x-applyFallthroughAttributes against 3.x (cf812ebdaaf884fe0d39f79ece927e9b20db144c).

Open to see the benchmark results

No benchmark changes above ±5%.

_{Generated by phpbench against commit b7f4f09}

[iamdadmin]

Weird, I can't replicate the run style check's unused view import. Locally mago on the same version doesn't find any unused view imports, and the logs don't show where. I'll do some digging.

Edit to clarify: I did find this, it was in one of the tests.

[iamdadmin]

Blocked by #2094

[iamdadmin]

Will update for #2094 changes and ready it up again after.

[brendt]

As discussed in #2097, we'll need a dedicated attributes value object with dedicated methods (I prefer with and without)

[iamdadmin]

As discussed in #2097, we'll need a dedicated attributes value object with dedicated methods (I prefer with and without)

There's several instances of $attributes spread across tempest/view, some of them are array[] and some are ImmutableArray via arr(), each in different spaces and generally contained within itself or between a couple of classes.

Anyone that's already typing $attributes out in their views is going to find this to be a breaking change to their typing at a minimum; in order to maintain compatibility and prevent it breaking anything else people could already be doing to it, and with usage of methods already within tempest/views, $attributes effectively needs to just be a copy of ImmutableArray with with and without declared in the final class, because it needs to expose the same methods.

Does this really add value? It seems like we're layering an abstraction just to have aliases for with -> removeKeys and without -> removeKeysExcept.

[brendt]

Ok the breaking change is a good point…

I guess we can then just use removeKeys and removeKeysExcept for now.

I want the record to state I don't like it, but I also get why this is the best approach…

[iamdadmin]

Ok the breaking change is a good point…

I guess we can then just use removeKeys and removeKeysExcept for now.

I want the record to state I don't like it, but I also get why this is the best approach…

I'll raise a separate FR to handle the conversion for $attributes as it's own piece of work. Perhaps it can go into 4.0 as it'd potentially be possible to use the major bump rector to re-type it anywhere it's found in developer applications?

In the meantime this PR should be ready to go again, and I will edit this with the ref to the FR in a few.

Edit: #2103 for the $attributes value object class.