{$this->title}
;
+ }
+}
+// ` and `$component = Card::class` behaves like ` an element).
+$tag = 'date';
+echo <$tag/>, "\n";
+
+// A capitalized value can never reach an internal function like Date().
+$tag = 'Date';
+try {
+ echo <$tag/>;
+} catch (Error $e) {
+ echo $e->getMessage(), "\n";
+}
+
+// A capitalized value with no symbol behind it.
+$tag = 'NoSuchComponent';
+try {
+ echo <$tag/>;
+} catch (Error $e) {
+ echo $e->getMessage(), "\n";
+}
+
+// A "Class::method" value dispatches as a static-method component; a missing
+// class is the same hard error the static tag form gives.
+$tag = 'NoSuchRegistry::make';
+try {
+ echo <$tag/>;
+} catch (Error $e) {
+ echo $e->getMessage(), "\n";
+}
+?>
+--EXPECT--
+bool(true)
+
+Text 2
+
; }
+}
+
+// Static component spanning lines: the render_component call site is the
+// opening ...` is
+- An expression tag with a brace closes **anonymously** with ``
+ - A closing tag cannot restate the expression - re-evaluating it would run its side effects twice, and matching it textually is meaningless for a computed value; the expression is evaluated exactly once.
+- A self-closing `<$tag/>` / `<{expr}/>` needs no closer at all.
+
+#### Userland integration: dispatch hooks
+
+By default the engine constructs a class component with `new` and calls a static-method component directly. In userland, particularly within frameworks, they will often want to intervene - to resolve components through a dependency-injection container (autowiring the constructor dependencies the props do not supply), or to apply a cross-cutting transform to every component's output. Two request-scoped hook lists make this possible without touching any component's code. Each behaves like `spl_autoload_register` - handlers are kept in registration order, with a matching `unregister_*` that reports whether a handler matched:
+
+| Hook | Fires for | Signature | Purpose |
+|---|---|---|---|
+| `Html\register_component_factory` | class components | `(string $class, array $args): ?object` | replace `new` (e.g. container construction) |
+| `Html\register_component_decorator` | **every** component kind | `(Html\Htmlable $rendered, string $component): Html\Htmlable` | transform / wrap / log / cache the output |
+
+The engine always does the part only it can: resolve the name, confirm the target, and route props + `#[Html\Slot]` content into `$args`. A **factory** only changes *how a class component's instance is produced* - it returns an instance of the requested class, or `null` to defer to the next handler (and finally to the engine's own `new`). A **decorator** is the cross-cutting seam: it runs on the `Html\Htmlable` every component produces - class and static-method alike - composing in registration order. (Plain HTML elements such as `{new Card('nested')} , "\n";
+var_dump((new ReflectionMethod(FancyCard::class, '__toString'))->isInternal());
+?>
+--EXPECT--
+Hello {track()} , "\n";
+var_dump($evaluated); // 0 - never evaluated
+
+// Logged in: the body evaluates exactly once, even though a component could
+// in principle render its slot twice (LazyFragment memoizes).
+class Twice implements Html\Htmlable {
+ public function __construct(#[Html\Slot] public Html\Htmlable $slot) {}
+ public function toHtml(): Html\Htmlable {
+ return new Html\Fragment([$this->slot, $this->slot]);
+ }
+}
+$evaluated = 0;
+echo x{track()} , "\n";
+var_dump($evaluated); // 1 - memoized across both renders
+
+// Without `:lazy` the body is eager: track() runs before Auth even sees it.
+$evaluated = 0;
+echo Hello {track()} , "\n";
+var_dump($evaluated); // 1 - evaluated eagerly
+
+// The lowered value is an Html\LazyFragment that is itself an Html\Htmlable.
+$lazy = new Html\LazyFragment(fn() => new E('span', [], ['built']));
+var_dump($lazy instanceof Html\Htmlable);
+var_dump($lazy->toHtml() instanceof Html\Element);
+echo $lazy, "\n";
+
+// The thunk must return an Html\Htmlable.
+try {
+ (new Html\LazyFragment(fn() => 'nope'))->toHtml();
+} catch (\Error $e) {
+ echo $e->getMessage(), "\n";
+}
+?>
+--EXPECT--
+
+int(0)
+xsecretxsecret
+int(1)
+
+int(1)
+bool(true)
+bool(true)
+built
+Html\LazyFragment thunk must return an Html\Htmlable
diff --git a/features/22-native-markup/tests/markup_operand_position_bc.phpt b/features/22-native-markup/tests/markup_operand_position_bc.phpt
new file mode 100644
index 0000000..1f42c28
--- /dev/null
+++ b/features/22-native-markup/tests/markup_operand_position_bc.phpt
@@ -0,0 +1,131 @@
+--TEST--
+Native markup: bare "<" after operand-ending tokens stays a comparison (no-space BC)
+--FILE--
+ 1 }check(new Base));
+
+// Bare `exit` is an expression operand; "<" after it is a comparison.
+// (Only reached when the left side is falsy-compared, so guard it.)
+function never_exit(): bool { return false && exit` operator is untouched in infix (operator) position.
+var_dump($a[0]<>2);
+
+// Plain variables, literals, and `)` end an operand too, with or without spaces.
+$lhs = 1; $rhs = 2;
+var_dump($lhs < $rhs);
+var_dump($lhs<$rhs);
+var_dump(3 < 4);
+var_dump(($lhs) < $rhs);
+
+// Other "<"-led operators are unchanged: spaceship, less-or-equal, shifts.
+var_dump($lhs <=> $rhs);
+var_dump($lhs <= $rhs);
+var_dump(1 << 4);
+var_dump(64 >> 2);
+
+// A heredoc body containing "<" stays literal text, not markup.
+echo << text
+EOT, "\n";
+
+// Error suppression with "@" still works before an expression.
+$sup = []; var_dump(@$sup['missing']);
+
+// Bare `yield` is a complete operand: `<` and `<>` after it stay comparisons
+// ((yield) != 5, (yield) < FOO), with or without spaces. Yielding markup
+// therefore needs parentheses: `yield ()`.
+function gen_ne() { var_dump(yield <> 5); }
+$g = gen_ne(); $g->current(); $g->send(7);
+function gen_lt() { var_dump(yield < FOO); }
+$g = gen_lt(); $g->current(); $g->send("aaa");
+function gen_lt_nospace() { $r = yieldcurrent(); $g->send("aaa");
+
+// Inverse direction: in operand position (after `=`, `(`, `,`, `=>`, `return`,
+// and parenthesized after `yield`) a ";
+ take(
); + $f = fn() => a; + yield (item );
+ return done;
+}
+
+// Dynamic tags: "<$tag" and "<{expr}" in operand position are markup
+// ("$i--<$n" above is the operator-position inverse, still a comparison).
+function never_runs_dynamic() {
+ $tag = 'div';
+ $x = <$tag class="a">hi;
+ $y = <{$tag . 'x'}>hi;
+ take(<{pick()}/>);
+ return <$tag/>;
+}
+echo "parsed\n";
+?>
+--EXPECT--
+bool(true)
+bool(true)
+int(4)
+bool(true)
+bool(true)
+bool(true)
+bool(true)
+bool(true)
+bool(true)
+bool(true)
+bool(true)
+bool(false)
+bool(false)
+bool(true)
+bool(true)
+bool(true)
+bool(true)
+bool(true)
+int(-1)
+bool(true)
+int(16)
+int(16)
+literal text
+NULL
+bool(true)
+bool(true)
+bool(true)
+parsed
diff --git a/features/22-native-markup/tests/syntax_attributes.phpt b/features/22-native-markup/tests/syntax_attributes.phpt
new file mode 100644
index 0000000..be19f64
--- /dev/null
+++ b/features/22-native-markup/tests/syntax_attributes.phpt
@@ -0,0 +1,131 @@
+--TEST--
+Markup syntax: attributes - literal/{expr}/bare-boolean with coercion, {...spread}, ":"/"@" prefixed names
+--EXTENSIONS--
+html
+--FILE--
+link)->__toString(), "\n";
+
+// attribute value is escaped
+echo (
)->__toString(), "\n";
+
+// --- {...$attrs} spread: elements (array merge) ---
+// Element: spread merges into the attribute map; values are still escaped.
+$extra = ['data-id' => 7, 'class' => 'from-spread', 'title' => 'T & T'];
+echo (link)->__toString(), "\n";
+
+// Conflict resolution follows array-merge order (last wins).
+echo ( 'override']}>x)->__toString(), "\n";
+echo ( 'base']} class="explicit">x)->__toString(), "\n";
+
+// --- {...$attrs} spread: components (named args) ---
+// Component: spread becomes named arguments (props).
+class Card implements Html\Htmlable {
+ public function __construct(public string $title, public string $tone = 'plain') {}
+ public function toHtml(): Html\Htmlable {
+ return new E('div', ['class' => 'card-' . $this->tone], [$this->title]);
+ }
+}
+$props = ['title' => 'Hi & bye', 'tone' => 'loud'];
+echo ( 'soft']}/>)->__toString(), "\n";
+
+// A component variadic collects unknown (e.g. hyphenated) spread keys.
+class Box implements Html\Htmlable {
+ private array $attrs;
+ public function __construct(public string $kind, ...$attrs) { $this->attrs = $attrs; }
+ public function toHtml(): Html\Htmlable {
+ return new E('div', ['class' => $this->kind, ...$this->attrs], ['box']);
+ }
+}
+echo ( '1', 'role' => 'note']}/>)->__toString(), "\n";
+
+// --- ":" / "@" as an optional leading character of attribute names ---
+// Vue/Alpine shorthand attribute names: literal value, {expr} value, bare boolean.
+$open = 'open';
+echo 
+link
+x
+x
+
, "\n"; +echo
, "\n"; + +// --- self-closing source; serializer expands non-void elements --- +// Void elements serialize without a closing tag... +echo (![]()
)->__toString(), "\n";
+echo (
)->__toString(), "\n";
+// ...non-void self-closed source expands to open+close output.
+echo ()->__toString(), "\n";
+echo ()->__toString(), "\n";
+
+// Empty components and fragments are allowed (only HTML elements must self-close).
+class C implements Html\Htmlable {
+ public function toHtml(): Html\Htmlable { return Html\raw('C'); }
+}
+echo (t : f, "\n"; // after "?" and ":"
+echo null ?? coal, "\n"; // after "??"
+echo (string) print
; echo "\n"; // after `print` +echo [a, b][1], "\n"; // after "[" and "," +echo (fn() =>arrow )(), "\n"; // after "=>"
+echo match(true) { true => match }, "\n"; // match arm "=>"
+function gen() { yield from [yf]; } // after `yield from`
+echo iterator_to_array(gen())[0], "\n";
+?>
+--EXPECT--
+bool(true)
+
+
+![]()
+
+
+
+C
+string(0) ""
+
+t
+coal
+print
+b +arrow
+match
+yf
diff --git a/features/22-native-markup/tests/syntax_component_resolution.phpt b/features/22-native-markup/tests/syntax_component_resolution.phpt
new file mode 100644
index 0000000..7a1ad32
--- /dev/null
+++ b/features/22-native-markup/tests/syntax_component_resolution.phpt
@@ -0,0 +1,100 @@
+--TEST--
+Markup syntax: compile-time component-name resolution (use aliases, qualified/fully-qualified tags, static methods)
+--EXTENSIONS--
+html
+--FILE--
+ 'card'], [$this->title]);
+ }
+ }
+}
+
+namespace App {
+ class Greeting implements \Html\Htmlable {
+ public function __construct(#[\Html\Slot] public ?\Html\Htmlable $slot = null) {}
+ public function toHtml(): \Html\Htmlable {
+ return resolves to App\Components\Card via the `use` alias, not a global Card.
+ echo (hi )->__toString(), "\n";
+ echo (
;', '$x = <{"div"}>a;'] as $code) {
+ try {
+ eval($code);
+ } catch (ParseError $e) {
+ echo $e->getMessage(), "\n";
+ }
+}
+
+// An empty tag value is rejected up front.
+try {
+ Html\render_dynamic('');
+} catch (ValueError $e) {
+ echo $e->getMessage(), "\n";
+}
+
+// A value that is no valid tag name fails at serialization (the existing
+// Element guard) - a dynamic name can never break out of the markup.
+$tag = 'di v';
+try {
+ echo (string) <$tag/>;
+} catch (Error $e) {
+ echo $e->getMessage(), "\n";
+}
+
+// A lowercase value is always an element, even if a function of that name
+// exists (the same rule that makes static ` are not components; no hook fires for them. A static-method component's *call* has no production hook; a component that needs container construction is a class component.)
+
+Every `register_*`/`unregister_*` function also takes an optional second argument, `?string $component = null`, that scopes the hook to a single component: the hook only fires when the resolved name it would receive - the class FQCN, or `"Class::method"` - matches (case-insensitively, with or without a leading backslash). Scoped and unscoped hooks share one chain in registration order, and the dispatch skips out-of-scope hooks inside the engine, before any userland call, so a hook registered for one component costs the others nothing. Unregistering matches on both the callable and the scope it was registered with.
+
+Registration is scoped to the current runtime, so a framework registers hooks during bootstrap; when nothing is registered the hooks add no cost - the default `new`/call path is unchanged.
+
+```php
+$container = ...;
+
+// A framework's bootstrap: wire components to the service container...
+Html\register_component_factory(
+ fn(string $class, array $args) => $container->make($class, $args)
+);
+
+// ...and a cross-cutting decorator (profiling, caching, wrapping, ...).
+Html\register_component_decorator(function (Html\Htmlable $rendered, string $component) {
+ return $rendered;
+});
+```
+
+A component can then simply declare its dependencies; the container supplies them while markup attributes still fill the remaining parameters as named arguments:
+
+```php
+final class UserCard implements Html\Htmlable {
+ public function __construct(private Clock $clock, public string $name) {}
+ public function toHtml(): Html\Htmlable { /* ...uses $this->clock... */ }
+}
+
+)
+```
+
+The slot value is always a single `Html\Fragment` (an `Html\Htmlable` whose children are each normalized to `Html\Htmlable`); `{$slot}` renders the whole body, correctly escaped. The fragment's children are introspectable as an opt-in (`$slot->children`).
+
+Rules for the slot parameter:
+
+* **At most one** parameter may carry `#[Html\Slot]`; more than one is an **error**.
+* Body content given to a component with no `#[Html\Slot]` parameter, or a parameter filled both by an attribute and by body content, is an **error**.
+* `#[Html\Slot]` on a variadic parameter → **error** (a slot is a single value).
+* The slot is an ordinary parameter, so a **required** slot (no default) left unfilled fails at runtime like any missing argument (`ArgumentCountError`). Declare a default (`?Html\Htmlable $slot = null`) to make it optional.
+
+#### Further content areas are markup-valued props
+
+A component has exactly one body slot; any *additional* content regions are passed as ordinary props typed `Html\Htmlable`. Because an attribute value is an arbitrary expression and markup is a value, a chunk of markup passes straight through with no extra syntax:
+
+```php
+class Layout implements Html\Htmlable {
+ public function __construct(
+ #[Html\Slot] public Html\Htmlable $body,
+ public ?Html\Htmlable $header = null,
+ public ?Html\Htmlable $footer = null,
+ ) {}
+ public function toHtml(): Html\Htmlable { /* ... */ }
+}
+
+Title}
+ footer={<>© 2026}
+>
+
+```
+
+A "named slot" is therefore just a prop, checked against the component's real signature exactly like any other - a misspelled `heaer=` is the same `TypeError` a misspelled prop is, not a silent no-op. This keeps the whole surface consistent with the RFC's headline property that props are type-checkable named arguments.
+
+This is also the proposal's answer to **template inheritance**: what Twig, Latte and Blade's older syntax call a base template with overridable *blocks* is here a `Layout` component whose regions are markup-valued props (and the body slot) filled by composition, rather than a template that is extended; layouts nest the same way. (A dedicated `` block form for large named regions is a possible future ergonomic addition - see Future Scope - but expresses nothing a prop cannot.)
+
+#### Eager evaluation, and opting into laziness with `:lazy`
+
+Because a component invocation is an ordinary call, **the body is fully evaluated before the component runs** (PHP evaluates arguments before the call). A component therefore cannot, by default, conditionally skip or defer rendering its body - the body has already been built by the time the component decides what to do with it.
+
+The `:lazy` directive on a component tag opts its body out of that rule:
+
+```php
+class Auth implements Html\Htmlable
+{
+ public function __construct(
+ public bool $check,
+ #[Html\Slot] public ?Html\Htmlable $slot = null,
+ ) {}
+ public function toHtml(): Html\Htmlable
+ {
+ // When logged out we never reference $slot, so with :lazy the body's
+ // expressions never run.
+ return $this->check ? check()}>Hello, {auth()->user()->name}
+
+// Lazy: the body is built, and its interpolations run, only if Auth renders it.
+check()}>Hello, {auth()->user()->name}
+```
+
+With `:lazy` the body lowers to an `Html\LazyFragment` wrapping a closure, instead of an eager `Html\Fragment`:
+
+```php
+// Hello, {$name}
+// → \Html\render_component(Auth::class, [],
+// new \Html\LazyFragment(fn() => new \Html\Fragment(['Hello, ', $name])), 'Auth')
+```
+
+`Html\LazyFragment` is *itself* an `Html\Htmlable`, so **the component's slot parameter type is unchanged** (`?Html\Htmlable`) and a component need not be written any differently to accept a lazy body - laziness is transparent to it. It evaluates its closure on first render and **memoizes** the result, so a body rendered more than once still runs its expressions once. Variables the body references are captured by value at the point of the tag (ordinary arrow-function semantics); only the *expressions* - method calls, property reads - are deferred to render time. A body that is never rendered is never evaluated.
+
+`:lazy` is deliberately the single point where markup departs from "an ordinary call with eager arguments," which is why it is explicit and opt-in; eager remains the default. (For a body that should be evaluated *repeatedly* rather than merely deferred, pass a closure as an ordinary prop and call it - e.g. `each={fn($x) => {$x} }`.)
+
+#### Child coercion
+
+| Child value | Renders as |
+|---|---|
+| `Html\Htmlable` | itself, **not** escaped (resolved through `toHtml()` and serialized natively) |
+| `string` / `int` / `float` / `bool` / `null` | cast to string and escaped - so `false`/`null` → `""`, `true` → `"1"` |
+| `array` / `Traversable` | flattened, each element coerced recursively |
+| non-`Stringable` object / resource | `TypeError` |
+
+This makes control flow ride entirely on `{...}` with no new directives, exactly what JSX has landed on:
+
+```php
+
` (no closing tag, no slash) for known void elements, so output is clean HTML5 whichever source form was used. Giving a void element children (possible when constructing `Html\Element` by hand) is an error rather than silent data loss. +* **Fragments** `<>...` produce an `Html\Fragment` with no wrapper element. +* **Whitespace** follows the JSX/Babel algorithm: split each text run into lines, trim leading whitespace on every line but the first and trailing whitespace on every line but the last, drop blank lines, and join the surviving lines with a single space. The net effect is that indentation/newlines between block elements vanish while a meaningful single space between inline content is preserved. +* **Character references**: markup text and literal attribute values decode HTML character references at compile time - the full WHATWG named set (semicolon-terminated forms only) plus numeric `—` / `—`. The named list is *frozen by the HTML standard*, so it is baked into the scanner as a generated table. Decoding is lenient like HTML and JSX: a bare `&`, an unknown name, or an invalid numeric form stays literal - `{$card} , "\n";
+
+// And as a component tag.
+echo
;
+ }
+}
+
+// Inheritance pushes the linked class (with its injected internal method)
+// through opcache's inheritance cache / persistence paths.
+class FancyCard extends Card {}
+
+echo new Card('a & b'), "\n";
+echo new FancyCard('c'), "\n";
+echo Body content flows to the slot.
+{$this->slot}
: <>;
+ }
+}
+
+// Eager: auth()->user()->name is evaluated before Auth runs - and would error
+// when logged out - even though Auth discards the body in that case.
+- {array_map(fn($i) =>
- {$i->name} , $items)}
{$user !== null ? {$user->name} : null}
// conditional (null → "")
+{$loggedIn ? Log out : null}
// optional (null → "")
+```
+
+Conditionals use a ternary, not the JSX `{condition && ` (no closing tag, no slash) for known void elements, so output is clean HTML5 whichever source form was used. Giving a void element children (possible when constructing `Html\Element` by hand) is an error rather than silent data loss. +* **Fragments** `<>...` produce an `Html\Fragment` with no wrapper element. +* **Whitespace** follows the JSX/Babel algorithm: split each text run into lines, trim leading whitespace on every line but the first and trailing whitespace on every line but the last, drop blank lines, and join the surviving lines with a single space. The net effect is that indentation/newlines between block elements vanish while a meaningful single space between inline content is preserved. +* **Character references**: markup text and literal attribute values decode HTML character references at compile time - the full WHATWG named set (semicolon-terminated forms only) plus numeric `—` / `—`. The named list is *frozen by the HTML standard*, so it is baked into the scanner as a generated table. Decoding is lenient like HTML and JSX: a bare `&`, an unknown name, or an invalid numeric form stays literal - `
fish & chips
` needs no escaping. The decoded value is an ordinary string escaped at render time, so `&` round-trips and `<script>` can never smuggle real markup structure. Text decodes *after* whitespace normalization; comment contents and interpolated PHP strings are never decoded, and `token_get_all()` still sees the raw source. +* **Literal braces**: `{` begins interpolation, so a literal `{` in text is written as in HTML or JSX - a character reference (`{` / `{`) or an interpolated string (`{'{'}`). A lone `}` is already literal. No additional escape syntax (eg. Blade-style `@{{`) is introduced. A block of literal JSON/JS inside `; + +echo ; + +echo{'{'}example{'}'}
;
+```
+
+### Components are testable values
+
+A component is an ordinary object and its `toHtml()` result an ordinary value object, so a component is unit-tested directly: construct it, assert against the tree - no rendering, no string matching, no DOM parsing:
+
+```php
+public function testSaleBadgeShownWhenOnSale(): void
+{
+ $el = (new ProductBadge(product: $this->saleProduct()))->toHtml();
+
+ $this->assertInstanceOf(Html\Element::class, $el);
+ $this->assertSame('span', $el->tag);
+ $this->assertSame('badge sale', $el->attributes['class']);
+}
+```
+
+Views decompose the way any other code does: small component classes, each testable in isolation, composed by a top-level component returning the final page.
+
+### Framework components - a Livewire-style clock
+
+In frameworks whose components are PHP classes that render themselves - Livewire is the clearest example - the class and its markup are forced apart today: the component holds the state and behaviour, while the HTML lives in a separate Blade file the class points to by name.
+
+With markup expressions the same component could collapse into one self-contained class - `render()` returns the view instead of naming a file that contains it:
+
+```php
+class Clock extends Component
+{
+ public string $timezone = 'UTC';
+
+ public function render(): Html\Htmlable
+ {
+ return
+ {now($this->timezone)->format('H:i:s')}
+
;
+ }
+}
+```
+
+## Backward Incompatible Changes
+
+`<` is heavily overloaded in PHP (`<`, `<=`, `<=>`, `<<`, `<>`, `<<<`), so this was the main design risk. It is resolved by the same technique JavaScript uses to tell regex from division: the scanner tracks whether it is in **operand position** (a value is expected) or **operator position** (a value just ended), from the last significant token. Markup begins only when `<` is in operand position *and* is immediately followed by `[A-Za-z>]`, by `\` then a letter (a fully-qualified component tag such as `<\App\Card/>`), by `$` then a variable name, or by `{` (the dynamic tags `<$tag>` / `<{expr}>`):
+
+* In `$a < $b` (or the no-space `$a <$b`), `<` follows an operand → comparison, unchanged.
+* In `$a < \Foo::BAR`, `<` is in operator position → comparison, unchanged.
+* In `return `, `<` is in operand position followed by a letter → markup.
+
+The operand-position decision is an explicit allowlist that **fails closed**: markup begins only after a token that *expects* an operand - `return`, `echo`, `=`, `(`, `,`, `=>`, binary and assignment operators, casts, and the other expression-introducing contexts - which are exactly the positions where an infix `<` cannot legally appear today, and where `<` followed by a letter, `$`, `{`, or `>` is *always a syntax error*. After every other token, `<` keeps its existing meaning. Two properties follow:
+
+* **No valid program changes meaning, by construction.** Reclaiming `<` only ever applies where the source could not previously compile.
+* **The design is future-proof in the safe direction.** If a token is missing from the allowlist (or a future PHP version adds a new operator and forgets to include it), the only consequence is that markup cannot directly follow that token - a loud, feature-side parse error worked around with parentheses and fixed by a one-line addition. A gap can never silently change what existing code means.
+
+`<>` is the legacy alias of `!=` and is preserved in infix position (`$a <> $b` is still not-equal). `<>` is only reinterpreted as a fragment opener in **operand position**, where it is currently a syntax error - so no valid program needs changes. Two positions are deliberately excluded from the allowlist because an infix `<` after them is (or may be) valid PHP: after a bare `yield` (`yield < LIM` is valid, so yielding markup is written `yield ()`) and after a closing `}` (which ends `match` and interpolation values), so markup as a bare expression statement immediately following a block is assigned or echoed instead.
+
+This leaves just one backwards compatibility concern:
+
+1. **New `Html\` namespace** - introduces `Html\Htmlable`, `Html\Element`, `Html\Fragment`, `Html\Raw`, `Html\Slot`, `Html\raw()`, `Html\escape()`. Top-level `Html\` follows the established precedent for bundled extensions (`Random\`, `Dom\`, `Uri\`), and real-world top-level `Html\` packages are rare. No existing keywords are reserved and no new global reserved words are introduced (the syntax uses bare `<`, and the `:lazy` directive is only meaningful inside a markup tag).
+
+### Impact on tooling
+
+The scanner emits new `T_MARKUP_*` tokens (exposed as constants and through `token_get_all()`/`PhpToken`); ordinary code continues to tokenize identically. Tools that parse PHP source (nikic/php-parser, PHPStan, Psalm, php-cs-fixer, IDEs) will need grammar updates to understand markup expressions, as with any new syntax.
+
+A working syntax-highlighting/IDE extension for VS Code was built alongside the reference implementation to validate that the syntax is toolable.
+
+Because markup lowers to ordinary AST at compile time, everything downstream of the parser is unaffected: opcache caches and restores markup-containing files normally (verified, including the file cache), and reflection, serialization, `var_export()`, `clone` and `json_encode()` on the value objects behave as for any other class.
+
+A related question is what this means for **template engines** (Blade, Twig, Latte). This RFC does not replace them, and does not aim to: a full engine is much more than syntax plus escaping - layout inheritance, a designer-facing dialect that is deliberately *not* PHP, sandboxed rendering of untrusted templates, context-aware escaping, fragment caching, and years of ecosystem conventions. Nothing here removes any of that; markup is opt-in syntax, and code that never uses it is untouched.
+
+What this RFC offers the engines is a first-class substrate to build on. Today each engine maintains its own parser, its own escaping, and its own component model, because the language provides none. With markup native, an engine can adopt the shared foundation where it fits: `Html\Htmlable` is a common currency (a Blade view and a markup expression can accept and return the same interface and compose within one page); the dispatch hooks exist precisely so a framework can route component tags through its existing container and resolution logic; and an engine's component layer could compile *to* markup expressions, inheriting escape-by-default and end-to-end static analysis for free. The likely long-term shape is convergence rather than replacement: engines keep their higher-level features and progressively delegate parsing, escaping, and the value model to the language - much as database layers did not disappear when PDO shipped, but re-based onto it.
+
+## Future Scope
+
+Some natural extensions are deliberately left out of this RFC to keep its scope tight and expandable in the future; none is required for the feature to be useful:
+
+* **Context-aware escaping** (URL/JS/CSS contexts), as in Go's `html/template` or Latte's escaping, - so that e.g. a `javascript:` URL in `href` is caught. This RFC escapes HTML context only; the value-tree model is designed so this can be layered on later without a syntax change. Some examples include:
+ * A JavaScript escaping context inside `` breakout is inexpressible.
++
++### 3. Tags: HTML elements vs components
++
++Dispatch is purely **syntactic** (the compiler cannot know runtime types):
++
++| Tag form | Meaning |
++|---|---|
++| `"; echo
" \ + "$("$PHP" -r 'echo
;')" + +check "self-close and open/close are equivalent" "bool(true)" \ + "$("$PHP" -r 'var_dump((string) === (string));')" + +check "arrays in interpolation flatten" 'x ' \
+ "$("$PHP" -r '$tag="section"; echo <$tag>x;')"
+
+check "bare < still parses as less-than" "bool(true)" \
+ "$("$PHP" -r 'var_dump(1 < 2);')"
+
+echo "----"
+echo "passed: $pass, failed: $fail"
+[ "$fail" -eq 0 ]
diff --git a/features/22-native-markup/tests/children.phpt b/features/22-native-markup/tests/children.phpt
new file mode 100644
index 0000000..161f596
--- /dev/null
+++ b/features/22-native-markup/tests/children.phpt
@@ -0,0 +1,94 @@
+--TEST--
+Html\Element children: scalar coercion, recursive array flattening, Traversables, and the nesting-depth bound
+--EXTENSIONS--
+html
+--FILE--
+ "1", false/null -> "".
+echo (new Element('p', [], [1, ' ', 2.5, ' ', true, false, null]))->__toString(), "\n";
+
+// Arrays flatten recursively (the array_map loop idiom).
+$items = ['Ada', 'Linus', 'Grace'];
+echo (new Element('ul', [], [
+ array_map(fn($n) => new Element('li', [], [$n]), $items),
+]))->__toString(), "\n";
+
+// A nested Htmlable passes through un-escaped.
+echo (new Element('div', [], [raw('bold')]))->__toString(), "\n";
+
+// Nested elements are Htmlable too.
+echo (new Element('div', [], [new Element('em', [], ['hi & bye'])]))->__toString(), "\n";
+
+// Non-Stringable object is a hard error.
+try {
+ (new Element('div', [], [new stdClass]))->__toString();
+} catch (\Throwable $e) {
+ echo get_class($e), ': ', $e->getMessage(), "\n";
+}
+
+// --- Traversable children: generators, Iterator, IteratorAggregate ---
+
+// Generator
+function rows(): Generator {
+ yield new Element('li', [], ['one']);
+ yield new Element('li', [], ['two']);
+}
+echo (new Element('ul', [], [rows()]))->__toString(), "\n";
+
+// ArrayIterator (Iterator), mixing scalars and Htmlable, with keys ignored
+$it = new ArrayIterator(['a' => 'x & y', 'b' => new Element('b', [], ['z'])]);
+echo (new Element('p', [], [$it]))->__toString(), "\n";
+
+// IteratorAggregate, nested inside an array (recursive flattening)
+$agg = new class implements IteratorAggregate {
+ public function getIterator(): Iterator {
+ return new ArrayIterator([new Element('span', [], ['nested'])]);
+ }
+};
+echo (new Element('div', [], [['before ', $agg, ' after']]))->__toString(), "\n";
+
+// An exception thrown mid-iteration propagates.
+function boom(): Generator {
+ yield new Element('i', [], ['ok']);
+ throw new RuntimeException('stop');
+}
+try {
+ (new Element('div', [], [boom()]))->__toString();
+} catch (\Throwable $e) {
+ echo get_class($e), ': ', $e->getMessage(), "\n";
+}
+
+// --- nesting-depth bound ---
+
+// A cheap-to-build, deeply nested array must throw, not crash the process.
+$kids = ['x'];
+for ($i = 0; $i < 100000; $i++) {
+ $kids = [$kids];
+}
+try {
+ echo (new E('div', [], $kids))->__toString(), "\n";
+} catch (\Throwable $e) {
+ echo get_class($e), ': ', $e->getMessage(), "\n";
+}
+
+// Normal (shallow) nesting still renders.
+echo (new E('ul', [], [[[new E('li', [], ['ok'])]]]))->__toString(), "\n";
+?>
+--EXPECTF--
+
cannot have children +Error: Component props must use string keys +Error: Component class "PrivateCtor" has a non-public constructor +Error: Component class "NoCtor" has no constructor, so it cannot accept attributes or slots +no-ctor +Error: Component method Methods::hidden() must be a public static user-defined method +Error: Component method Methods::nonStatic() must be a public static user-defined method +Too few arguments to function NeedsDep::__construct()%A +Too few arguments to function NeedsDep::__construct()%A +Too few arguments to function NeedsDep::__construct()%A +RuntimeException: boom +clean diff --git a/features/22-native-markup/tests/component_hooks.phpt b/features/22-native-markup/tests/component_hooks.phpt new file mode 100644 index 0000000..ffa564d --- /dev/null +++ b/features/22-native-markup/tests/component_hooks.phpt @@ -0,0 +1,188 @@ +--TEST-- +Html components: factory hooks (DI), decorators, and per-component hook scoping +--EXTENSIONS-- +html +--FILE-- +title]); + } +} +class Badge implements Html\Htmlable { + public function __construct(public string $label = "?") {} + public function toHtml(): Html\Htmlable { + return new Html\Element('b', [], [$this->label]); + } +} +class Note implements Html\Htmlable { + public function __construct(public string $t) {} + public function toHtml(): Html\Htmlable { + return new Html\Element('p', [], [$this->t]); + } +} +class Author { + public static function byline(string $t): Html\Htmlable { + return new Html\Element('span', [], [$t]); + } +} + +// --- factory hooks: chain, defer, bad return, unregister identity --- + +// A dependency the props never supply; the "container" injects it. +class Clock { public function now(): string { return "T"; } } + +// Class component: a DI dependency ($clock) plus a prop ($label). +class TimeBadge implements Html\Htmlable { + public function __construct(private Clock $clock, public string $label) {} + public function toHtml(): Html\Htmlable { + return new Html\Element('span', [], ["{$this->label}:{$this->clock->now()}"]); + } +} + +// A tiny autowiring container: fill non-builtin params the $args don't provide. +function autowire(ReflectionFunctionAbstract $r, array $args): array { + $extra = []; + foreach ($r->getParameters() as $p) { + $t = $p->getType(); + if ($t instanceof ReflectionNamedType && !$t->isBuiltin() + && !array_key_exists($p->getName(), $args)) { + $extra[$p->getName()] = new ($t->getName())(); + } + } + return [...$extra, ...$args]; +} +$defer = fn(string $class, array $args) => null; // always defers to the next factory +$make = fn(string $class, array $args) + => (new ReflectionClass($class))->newInstanceArgs( + autowire(new ReflectionMethod($class, '__construct'), $args)); + +// (1) Without hooks, the engine's own `new` runs and fails for the missing Clock. +try { echo did not return an instance of it or null
+bool(false)
+bool(true)
+bool(true)
+restored: TimeBadge::__construct(): Argument #1 ($clock) not passed
+[Card] did not return an Html\Htmlable
+factory(Card)
+hi
+Error: Parameter $body is filled by both an attribute and body content
+Error: Component received body content but has no #[Html\Slot] parameter
+Error: Component has more than one #[Html\Slot] parameter
+Error: #[Html\Slot] cannot be applied to a variadic parameter
+body -> Html\Slot
+bool(true)
diff --git a/features/22-native-markup/tests/components.phpt b/features/22-native-markup/tests/components.phpt
new file mode 100644
index 0000000..a25424d
--- /dev/null
+++ b/features/22-native-markup/tests/components.phpt
@@ -0,0 +1,133 @@
+--TEST--
+Html components: tag lowering, class/static-method dispatch, resolution errors, hyphenated attrs
+--EXTENSIONS--
+html
+--FILE--
+getMessage(); }
+}
+
+// --- component tag lowering: class + static-method dispatch ---
+
+// Class component implementing Htmlable, with a prop and an anonymous slot.
+class Card implements Html\Htmlable {
+ public function __construct(
+ public string $title,
+ #[Slot] public ?Html\Htmlable $body = null,
+ ) {}
+ public function toHtml(): Html\Htmlable {
+ return new E('section', ['class' => 'card'], [new E('h2', [], [$this->title]), $this->body]);
+ }
+}
+
+// A second, minimal component for nesting cases.
+class Badge implements Html\Htmlable {
+ public function __construct(public string $label) {}
+ public function toHtml(): Html\Htmlable {
+ return new E('span', ['class' => 'badge'], [$this->label]);
+ }
+}
+
+// Static-method component - multiple components can live together on one class.
+// (broken() returns a non-Htmlable, for the error section below.)
+class Author {
+ public static function byline(string $name): Html\Htmlable {
+ return new E('p', ['class' => 'by'], ['By ', $name]);
+ }
+ public static function broken(): string {
+ return 'plain';
+ }
+}
+
+$who = 'Ada & co';
+
+// class component: attribute prop + body routed to the anonymous slot
+echo ()->__toString(), "\n";
+
+// the same dispatch, called directly by name
+echo render_component(Badge::class, ['label' => 'New &'])->__toString(), "\n";
+
+// a component used as a child of an HTML element, and inside interpolation
+echo ('], []))->__toString(), "\n";
+
+// A classic XSS attempt is neutralised.
+$evil = '';
+echo (new Element('span', [], [$evil]))->__toString(), "\n";
+
+// --- attribute value coercion ---
+
+// null and false omit the attribute; true is a bare boolean attribute.
+echo (new Element('input', [
+ 'type' => 'checkbox',
+ 'checked' => true,
+ 'disabled' => false,
+ 'value' => null,
+ 'tabindex' => 3,
+ 'data-ratio' => 1.5,
+]))->__toString(), "\n";
+
+// Stringable attribute value.
+$s = new class implements Stringable {
+ public function __toString(): string { return 'x&y'; }
+};
+echo (new Element('a', ['data-x' => $s]))->__toString(), "\n";
+
+// Arrays are reserved -> TypeError.
+try {
+ (new Element('div', ['class' => ['a', 'b']]))->__toString();
+} catch (\Throwable $e) {
+ echo get_class($e), ': ', $e->getMessage(), "\n";
+}
+
+// --- Htmlable attribute values (no double-escaping) ---
+
+// Html\raw(): trusted content, emitted verbatim (the entity survives).
+echo x, "\n";
+
+// Html\escape(): escaped exactly once, not re-escaped at render time.
+echo x, "\n";
+
+// Plain strings still escape by default.
+echo x, "\n";
+
+// A generic Stringable (not Htmlable) still escapes.
+class S { public function __toString(): string { return 'x & y'; } }
+echo x, "\n";
+
+// --- Fragment, void elements, raw()/escape() helpers ---
+
+// Fragment: no wrapper element, children concatenated.
+$frag = new Fragment([
+ new Element('h1', [], ['Title']),
+ new Element('p', [], ['Body']),
+]);
+echo $frag->__toString(), "\n";
+
+// Void elements emit clean HTML5 (no slash, no closing tag).
+echo (new Element('br'))->__toString(), "\n";
+echo (new Element('img', ['src' => '/a.png', 'alt' => 'A & B']))->__toString(), "\n";
+
+// raw(): trusted passthrough, not escaped.
+echo raw('x')->__toString(), "\n";
+
+// escape(): escaped once, then safe to embed without double-escaping.
+$safe = escape('x');
+echo $safe->__toString(), "\n";
+echo (new Element('p', [], [$safe]))->__toString(), "\n"; // not escaped again
+
+var_dump(raw('y') instanceof Html\Htmlable);
+
+// --- tag/attribute-name validation (security) ---
+
+function err(callable $fn): string {
+ try { return $fn()->__toString(); }
+ catch (\Throwable $e) { return get_class($e) . ': ' . $e->getMessage(); }
+}
+
+// Attribute name from an attacker-controlled spread key - must be rejected.
+echo err(fn() => new E('a', ['x" onmouseover="alert(1)' => 'y'], ['hi'])), "\n";
+
+// Tag name from a dynamic source - must be rejected.
+echo err(fn() => new E('a>', [], [])), "\n";
+
+// Empty names rejected.
+echo err(fn() => new E('', [], [])), "\n";
+echo err(fn() => new E('div', ['' => 'x'], [])), "\n";
+
+// Legitimate dynamic names still work (custom elements, data-/aria-, namespaces).
+echo (new E('my-widget', ['data-x' => '1', 'aria-label' => 'ok', 'xml:lang' => 'en'], ['x']))->__toString(), "\n";
+echo ( 5]}>ok), "\n";
+?>
+--EXPECTF--
+Click me
+Click me
+bool(true)
+bool(true)
+string(1) "a"
+array(2) {
+ ["href"]=>
+ string(15) "https://php.net"
+ ["class"]=>
+ string(3) "btn"
+}
+array(1) {
+ [0]=>
+ string(8) "Click me"
+}
+
+
+x
+<b>x</b>
+x
+ok
diff --git a/features/22-native-markup/tests/htmlable.phpt b/features/22-native-markup/tests/htmlable.phpt
new file mode 100644
index 0000000..88c32c3
--- /dev/null
+++ b/features/22-native-markup/tests/htmlable.phpt
@@ -0,0 +1,171 @@
+--TEST--
+Html\Htmlable: toHtml() contract and recursive resolution, injected default __toString vs declared __toString, cycles and throwing implementations
+--EXTENSIONS--
+html
+--FILE--
+{$this->title}
;
+ }
+}
+
+$card = new Card('Hi & bye');
+var_dump($card->toHtml() instanceof Html\Element);
+var_dump($card->toHtml()->tag);
+
+// The injected default __toString renders via toHtml(), so echo, (string),
+// and interpolation all work without the class declaring __toString.
+echo $card, "\n";
+echo (string) $card, "\n";
+echo "wrapped: {$card}\n";
+var_dump($card instanceof Stringable);
+
+// In markup child position the component renders through toHtml() natively.
+echo `, `` (lowercase / hyphenated) | literal HTML element → `Html\Element` |
++| `` (bare, capitalized) | a **component** - resolved as a class name honoring `use` / namespace |
++| ``, `<\App\Card>` (namespace-qualified) | a **component** - a namespace-qualified or fully-qualified class name |
++| `` | a **component** - a public static method on a class |
++| `<$tag>`, `<{expr}>` (a variable / any expression) | a **dynamic tag** - the runtime string value is classified by the same rule, at runtime |
++
++Any tag whose name is capitalized, contains a namespace separator (`\`), or names a static method (`::`) is a component; everything else is a literal HTML element.
++
++A **component produces `Html\Htmlable`**, and every component tag resolves through the *class* name rules alone. There are two forms:
++
++```php
++// Class implementing Html\Htmlable - the instance IS the renderable
++class Card implements Html\Htmlable {
++ public function __construct(public string $title) {}
++ public function toHtml(): Html\Htmlable {
++ return line.
++try {
++ echo
++ ;
++} catch (TypeError $e) {
++ /* trace: [0] the internal ctor frame (no line), [1] the render_component
++ * call site - which must be the opening-tag line. */
++ echo "component call site: line ", $e->getTrace()[1]['line'], "\n";
++}
++
++// Dynamic tag spanning lines: same rule.
++$var = new stdClass;
++try {
++ echo <$var>
++ body
++ ;
++} catch (TypeError $e) {
++ echo "dynamic tag: line ", $e->getLine(), "\n";
++}
++?>
++--EXPECT--
++component call site: line 10
++dynamic tag: line 23
+diff --git a/ext/html/tests/syntax_lowering.phpt b/ext/html/tests/syntax_lowering.phpt
+new file mode 100644
+index 00000000..a338ead7
+--- /dev/null
++++ b/ext/html/tests/syntax_lowering.phpt
+@@ -0,0 +1,49 @@
++--TEST--
++Markup syntax: the exact plain-PHP lowering, pinned via zend_ast_export (assert)
++--EXTENSIONS--
++html
++--INI--
++zend.assertions=1
++assert.exception=1
++--FILE--
++getMessage(), strlen("assert(false && "), -1);
++ }
++ return "NO EXPORT";
++}
++
++// A plain element with a literal and an interpolated attribute.
++echo desugar('fbody '), "\n";
++
++// A static-method tag resolves its class part like any class name.
++echo desugar('Hello {$name} '), "\n";
++
++// Dynamic tags lower to Html\render_dynamic.
++echo desugar('<$tag class="x">{$content}'), "\n";
++
++// Character references are decoded at compile time, so the exported string
++// literal contains the decoded text.
++echo desugar('
, found in %s on line %d
diff --git a/features/22-native-markup/smoke.sh b/features/22-native-markup/smoke.sh
new file mode 100755
index 0000000..a21c8ec
--- /dev/null
+++ b/features/22-native-markup/smoke.sh
@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+# Smoke tests for native markup expressions (JSX-style syntax).
+# Run after scripts/build.sh.
+set -uo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+PHP="$REPO_ROOT/php-src/sapi/cli/php"
+
+pass=0; fail=0
+check() { # name | expected | actual
+ if [ "$2" = "$3" ]; then echo "ok - $1"; pass=$((pass+1));
+ else echo "FAIL - $1 (expected [$2], got [$3])"; fail=$((fail+1)); fi
+}
+
+check "element lowers to Html\\Element" "bool(true)" \
+ "$("$PHP" -r 'var_dump(() instanceof Html\Element);')"
+
+check "fragment lowers to Html\\Fragment" "bool(true)" \
+ "$("$PHP" -r 'var_dump((<>) instanceof Html\Fragment);')"
+
+check "attributes + escaped interpolation" '{$this->title}
;
++ }
++}
++// ` and `$component = Card::class` behaves like ` an element).
++$tag = 'date';
++echo <$tag/>, "\n";
++
++// A capitalized value can never reach an internal function like Date().
++$tag = 'Date';
++try {
++ echo <$tag/>;
++} catch (Error $e) {
++ echo $e->getMessage(), "\n";
++}
++
++// A capitalized value with no symbol behind it.
++$tag = 'NoSuchComponent';
++try {
++ echo <$tag/>;
++} catch (Error $e) {
++ echo $e->getMessage(), "\n";
++}
++
++// A "Class::method" value dispatches as a static-method component; a missing
++// class is the same hard error the static tag form gives.
++$tag = 'NoSuchRegistry::make';
++try {
++ echo <$tag/>;
++} catch (Error $e) {
++ echo $e->getMessage(), "\n";
++}
++?>
++--EXPECT--
++bool(true)
++
++Text 2
++
; }
++}
++
++// Static component spanning lines: the render_component call site is the
++// opening ...` is
++- An expression tag with a brace closes **anonymously** with ``
++ - A closing tag cannot restate the expression - re-evaluating it would run its side effects twice, and matching it textually is meaningless for a computed value; the expression is evaluated exactly once.
++- A self-closing `<$tag/>` / `<{expr}/>` needs no closer at all.
++
++#### Userland integration: dispatch hooks
++
++By default the engine constructs a class component with `new` and calls a static-method component directly. In userland, particularly within frameworks, they will often want to intervene - to resolve components through a dependency-injection container (autowiring the constructor dependencies the props do not supply), or to apply a cross-cutting transform to every component's output. Two request-scoped hook lists make this possible without touching any component's code. Each behaves like `spl_autoload_register` - handlers are kept in registration order, with a matching `unregister_*` that reports whether a handler matched:
++
++| Hook | Fires for | Signature | Purpose |
++|---|---|---|---|
++| `Html\register_component_factory` | class components | `(string $class, array $args): ?object` | replace `new` (e.g. container construction) |
++| `Html\register_component_decorator` | **every** component kind | `(Html\Htmlable $rendered, string $component): Html\Htmlable` | transform / wrap / log / cache the output |
++
++The engine always does the part only it can: resolve the name, confirm the target, and route props + `#[Html\Slot]` content into `$args`. A **factory** only changes *how a class component's instance is produced* - it returns an instance of the requested class, or `null` to defer to the next handler (and finally to the engine's own `new`). A **decorator** is the cross-cutting seam: it runs on the `Html\Htmlable` every component produces - class and static-method alike - composing in registration order. (Plain HTML elements such as `{new Card('nested')} , "\n";
++var_dump((new ReflectionMethod(FancyCard::class, '__toString'))->isInternal());
++?>
++--EXPECT--
++Hello {track()} , "\n";
++var_dump($evaluated); // 0 - never evaluated
++
++// Logged in: the body evaluates exactly once, even though a component could
++// in principle render its slot twice (LazyFragment memoizes).
++class Twice implements Html\Htmlable {
++ public function __construct(#[Html\Slot] public Html\Htmlable $slot) {}
++ public function toHtml(): Html\Htmlable {
++ return new Html\Fragment([$this->slot, $this->slot]);
++ }
++}
++$evaluated = 0;
++echo x{track()} , "\n";
++var_dump($evaluated); // 1 - memoized across both renders
++
++// Without `:lazy` the body is eager: track() runs before Auth even sees it.
++$evaluated = 0;
++echo Hello {track()} , "\n";
++var_dump($evaluated); // 1 - evaluated eagerly
++
++// The lowered value is an Html\LazyFragment that is itself an Html\Htmlable.
++$lazy = new Html\LazyFragment(fn() => new E('span', [], ['built']));
++var_dump($lazy instanceof Html\Htmlable);
++var_dump($lazy->toHtml() instanceof Html\Element);
++echo $lazy, "\n";
++
++// The thunk must return an Html\Htmlable.
++try {
++ (new Html\LazyFragment(fn() => 'nope'))->toHtml();
++} catch (\Error $e) {
++ echo $e->getMessage(), "\n";
++}
++?>
++--EXPECT--
++
++int(0)
++xsecretxsecret
++int(1)
++
++int(1)
++bool(true)
++bool(true)
++built
++Html\LazyFragment thunk must return an Html\Htmlable
+diff --git a/ext/html/tests/syntax_attributes.phpt b/ext/html/tests/syntax_attributes.phpt
+new file mode 100644
+index 00000000..be19f645
+--- /dev/null
++++ b/ext/html/tests/syntax_attributes.phpt
+@@ -0,0 +1,131 @@
++--TEST--
++Markup syntax: attributes - literal/{expr}/bare-boolean with coercion, {...spread}, ":"/"@" prefixed names
++--EXTENSIONS--
++html
++--FILE--
++link)->__toString(), "\n";
++
++// attribute value is escaped
++echo ()->__toString(), "\n";
++
++// --- {...$attrs} spread: elements (array merge) ---
++// Element: spread merges into the attribute map; values are still escaped.
++$extra = ['data-id' => 7, 'class' => 'from-spread', 'title' => 'T & T'];
++echo (link)->__toString(), "\n";
++
++// Conflict resolution follows array-merge order (last wins).
++echo ( 'override']}>x)->__toString(), "\n";
++echo ( 'base']} class="explicit">x)->__toString(), "\n";
++
++// --- {...$attrs} spread: components (named args) ---
++// Component: spread becomes named arguments (props).
++class Card implements Html\Htmlable {
++ public function __construct(public string $title, public string $tone = 'plain') {}
++ public function toHtml(): Html\Htmlable {
++ return new E('div', ['class' => 'card-' . $this->tone], [$this->title]);
++ }
++}
++$props = ['title' => 'Hi & bye', 'tone' => 'loud'];
++echo ( 'soft']}/>)->__toString(), "\n";
++
++// A component variadic collects unknown (e.g. hyphenated) spread keys.
++class Box implements Html\Htmlable {
++ private array $attrs;
++ public function __construct(public string $kind, ...$attrs) { $this->attrs = $attrs; }
++ public function toHtml(): Html\Htmlable {
++ return new E('div', ['class' => $this->kind, ...$this->attrs], ['box']);
++ }
++}
++echo ( '1', 'role' => 'note']}/>)->__toString(), "\n";
++
++// --- ":" / "@" as an optional leading character of attribute names ---
++// Vue/Alpine shorthand attribute names: literal value, {expr} value, bare boolean.
++$open = 'open';
++echo
, "\n"; ++echo
, "\n"; ++ ++// --- self-closing source; serializer expands non-void elements --- ++// Void elements serialize without a closing tag... ++echo (![]()
)->__toString(), "\n";
++echo ()->__toString(), "\n";
++// ...non-void self-closed source expands to open+close output.
++echo ()->__toString(), "\n";
++echo ()->__toString(), "\n";
++
++// Empty components and fragments are allowed (only HTML elements must self-close).
++class C implements Html\Htmlable {
++ public function toHtml(): Html\Htmlable { return Html\raw('C'); }
++}
++echo (t : f, "\n"; // after "?" and ":"
++echo null ?? coal, "\n"; // after "??"
++echo (string) print
; echo "\n"; // after `print` ++echo [a, b][1], "\n"; // after "[" and "," ++echo (fn() =>arrow )(), "\n"; // after "=>"
++echo match(true) { true => match }, "\n"; // match arm "=>"
++function gen() { yield from [yf]; } // after `yield from`
++echo iterator_to_array(gen())[0], "\n";
++?>
++--EXPECT--
++bool(true)
++
++
++![]()
++
++
++
++C
++string(0) ""
++
++t
++coal
++print
++b ++arrow
++match
++yf
+diff --git a/ext/html/tests/syntax_component_resolution.phpt b/ext/html/tests/syntax_component_resolution.phpt
+new file mode 100644
+index 00000000..7a1ad325
+--- /dev/null
++++ b/ext/html/tests/syntax_component_resolution.phpt
+@@ -0,0 +1,100 @@
++--TEST--
++Markup syntax: compile-time component-name resolution (use aliases, qualified/fully-qualified tags, static methods)
++--EXTENSIONS--
++html
++--FILE--
++ 'card'], [$this->title]);
++ }
++ }
++}
++
++namespace App {
++ class Greeting implements \Html\Htmlable {
++ public function __construct(#[\Html\Slot] public ?\Html\Htmlable $slot = null) {}
++ public function toHtml(): \Html\Htmlable {
++ return resolves to App\Components\Card via the `use` alias, not a global Card.
++ echo (hi )->__toString(), "\n";
++ echo (
;', '$x = <{"div"}>a;'] as $code) {
++ try {
++ eval($code);
++ } catch (ParseError $e) {
++ echo $e->getMessage(), "\n";
++ }
++}
++
++// An empty tag value is rejected up front.
++try {
++ Html\render_dynamic('');
++} catch (ValueError $e) {
++ echo $e->getMessage(), "\n";
++}
++
++// A value that is no valid tag name fails at serialization (the existing
++// Element guard) - a dynamic name can never break out of the markup.
++$tag = 'di v';
++try {
++ echo (string) <$tag/>;
++} catch (Error $e) {
++ echo $e->getMessage(), "\n";
++}
++
++// A lowercase value is always an element, even if a function of that name
++// exists (the same rule that makes static ` are not components; no hook fires for them. A static-method component's *call* has no production hook; a component that needs container construction is a class component.)
++
++Every `register_*`/`unregister_*` function also takes an optional second argument, `?string $component = null`, that scopes the hook to a single component: the hook only fires when the resolved name it would receive - the class FQCN, or `"Class::method"` - matches (case-insensitively, with or without a leading backslash). Scoped and unscoped hooks share one chain in registration order, and the dispatch skips out-of-scope hooks inside the engine, before any userland call, so a hook registered for one component costs the others nothing. Unregistering matches on both the callable and the scope it was registered with.
++
++Registration is scoped to the current runtime, so a framework registers hooks during bootstrap; when nothing is registered the hooks add no cost - the default `new`/call path is unchanged.
++
++```php
++$container = ...;
++
++// A framework's bootstrap: wire components to the service container...
++Html\register_component_factory(
++ fn(string $class, array $args) => $container->make($class, $args)
++);
++
++// ...and a cross-cutting decorator (profiling, caching, wrapping, ...).
++Html\register_component_decorator(function (Html\Htmlable $rendered, string $component) {
++ return $rendered;
++});
++```
++
++A component can then simply declare its dependencies; the container supplies them while markup attributes still fill the remaining parameters as named arguments:
++
++```php
++final class UserCard implements Html\Htmlable {
++ public function __construct(private Clock $clock, public string $name) {}
++ public function toHtml(): Html\Htmlable { /* ...uses $this->clock... */ }
++}
++
++)
++```
++
++The slot value is always a single `Html\Fragment` (an `Html\Htmlable` whose children are each normalized to `Html\Htmlable`); `{$slot}` renders the whole body, correctly escaped. The fragment's children are introspectable as an opt-in (`$slot->children`).
++
++Rules for the slot parameter:
++
++* **At most one** parameter may carry `#[Html\Slot]`; more than one is an **error**.
++* Body content given to a component with no `#[Html\Slot]` parameter, or a parameter filled both by an attribute and by body content, is an **error**.
++* `#[Html\Slot]` on a variadic parameter → **error** (a slot is a single value).
++* The slot is an ordinary parameter, so a **required** slot (no default) left unfilled fails at runtime like any missing argument (`ArgumentCountError`). Declare a default (`?Html\Htmlable $slot = null`) to make it optional.
++
++#### Further content areas are markup-valued props
++
++A component has exactly one body slot; any *additional* content regions are passed as ordinary props typed `Html\Htmlable`. Because an attribute value is an arbitrary expression and markup is a value, a chunk of markup passes straight through with no extra syntax:
++
++```php
++class Layout implements Html\Htmlable {
++ public function __construct(
++ #[Html\Slot] public Html\Htmlable $body,
++ public ?Html\Htmlable $header = null,
++ public ?Html\Htmlable $footer = null,
++ ) {}
++ public function toHtml(): Html\Htmlable { /* ... */ }
++}
++
++Title}
++ footer={<>© 2026}
++>
++
++```
++
++A "named slot" is therefore just a prop, checked against the component's real signature exactly like any other - a misspelled `heaer=` is the same `TypeError` a misspelled prop is, not a silent no-op. This keeps the whole surface consistent with the RFC's headline property that props are type-checkable named arguments.
++
++This is also the proposal's answer to **template inheritance**: what Twig, Latte and Blade's older syntax call a base template with overridable *blocks* is here a `Layout` component whose regions are markup-valued props (and the body slot) filled by composition, rather than a template that is extended; layouts nest the same way. (A dedicated `` block form for large named regions is a possible future ergonomic addition - see Future Scope - but expresses nothing a prop cannot.)
++
++#### Eager evaluation, and opting into laziness with `:lazy`
++
++Because a component invocation is an ordinary call, **the body is fully evaluated before the component runs** (PHP evaluates arguments before the call). A component therefore cannot, by default, conditionally skip or defer rendering its body - the body has already been built by the time the component decides what to do with it.
++
++The `:lazy` directive on a component tag opts its body out of that rule:
++
++```php
++class Auth implements Html\Htmlable
++{
++ public function __construct(
++ public bool $check,
++ #[Html\Slot] public ?Html\Htmlable $slot = null,
++ ) {}
++ public function toHtml(): Html\Htmlable
++ {
++ // When logged out we never reference $slot, so with :lazy the body's
++ // expressions never run.
++ return $this->check ? check()}>Hello, {auth()->user()->name}
++
++// Lazy: the body is built, and its interpolations run, only if Auth renders it.
++check()}>Hello, {auth()->user()->name}
++```
++
++With `:lazy` the body lowers to an `Html\LazyFragment` wrapping a closure, instead of an eager `Html\Fragment`:
++
++```php
++// Hello, {$name}
++// → \Html\render_component(Auth::class, [],
++// new \Html\LazyFragment(fn() => new \Html\Fragment(['Hello, ', $name])), 'Auth')
++```
++
++`Html\LazyFragment` is *itself* an `Html\Htmlable`, so **the component's slot parameter type is unchanged** (`?Html\Htmlable`) and a component need not be written any differently to accept a lazy body - laziness is transparent to it. It evaluates its closure on first render and **memoizes** the result, so a body rendered more than once still runs its expressions once. Variables the body references are captured by value at the point of the tag (ordinary arrow-function semantics); only the *expressions* - method calls, property reads - are deferred to render time. A body that is never rendered is never evaluated.
++
++`:lazy` is deliberately the single point where markup departs from "an ordinary call with eager arguments," which is why it is explicit and opt-in; eager remains the default. (For a body that should be evaluated *repeatedly* rather than merely deferred, pass a closure as an ordinary prop and call it - e.g. `each={fn($x) => {$x} }`.)
++
++#### Child coercion
++
++| Child value | Renders as |
++|---|---|
++| `Html\Htmlable` | itself, **not** escaped (resolved through `toHtml()` and serialized natively) |
++| `string` / `int` / `float` / `bool` / `null` | cast to string and escaped - so `false`/`null` → `""`, `true` → `"1"` |
++| `array` / `Traversable` | flattened, each element coerced recursively |
++| non-`Stringable` object / resource | `TypeError` |
++
++This makes control flow ride entirely on `{...}` with no new directives, exactly what JSX has landed on:
++
++```php
++
` (no closing tag, no slash) for known void elements, so output is clean HTML5 whichever source form was used. Giving a void element children (possible when constructing `Html\Element` by hand) is an error rather than silent data loss. ++* **Fragments** `<>...` produce an `Html\Fragment` with no wrapper element. ++* **Whitespace** follows the JSX/Babel algorithm: split each text run into lines, trim leading whitespace on every line but the first and trailing whitespace on every line but the last, drop blank lines, and join the surviving lines with a single space. The net effect is that indentation/newlines between block elements vanish while a meaningful single space between inline content is preserved. ++* **Character references**: markup text and literal attribute values decode HTML character references at compile time - the full WHATWG named set (semicolon-terminated forms only) plus numeric `—` / `—`. The named list is *frozen by the HTML standard*, so it is baked into the scanner as a generated table. Decoding is lenient like HTML and JSX: a bare `&`, an unknown name, or an invalid numeric form stays literal - `{$card} , "\n";
++
++// And as a component tag.
++echo
;
++ }
++}
++
++// Inheritance pushes the linked class (with its injected internal method)
++// through opcache's inheritance cache / persistence paths.
++class FancyCard extends Card {}
++
++echo new Card('a & b'), "\n";
++echo new FancyCard('c'), "\n";
++echo Body content flows to the slot.
++{$this->slot}
: <>;
++ }
++}
++
++// Eager: auth()->user()->name is evaluated before Auth runs - and would error
++// when logged out - even though Auth discards the body in that case.
++- {array_map(fn($i) =>
- {$i->name} , $items)}
{$user !== null ? {$user->name} : null}
// conditional (null → "")
++{$loggedIn ? Log out : null}
// optional (null → "")
++```
++
++Conditionals use a ternary, not the JSX `{condition && ` (no closing tag, no slash) for known void elements, so output is clean HTML5 whichever source form was used. Giving a void element children (possible when constructing `Html\Element` by hand) is an error rather than silent data loss. ++* **Fragments** `<>...` produce an `Html\Fragment` with no wrapper element. ++* **Whitespace** follows the JSX/Babel algorithm: split each text run into lines, trim leading whitespace on every line but the first and trailing whitespace on every line but the last, drop blank lines, and join the surviving lines with a single space. The net effect is that indentation/newlines between block elements vanish while a meaningful single space between inline content is preserved. ++* **Character references**: markup text and literal attribute values decode HTML character references at compile time - the full WHATWG named set (semicolon-terminated forms only) plus numeric `—` / `—`. The named list is *frozen by the HTML standard*, so it is baked into the scanner as a generated table. Decoding is lenient like HTML and JSX: a bare `&`, an unknown name, or an invalid numeric form stays literal - `
fish & chips
` needs no escaping. The decoded value is an ordinary string escaped at render time, so `&` round-trips and `<script>` can never smuggle real markup structure. Text decodes *after* whitespace normalization; comment contents and interpolated PHP strings are never decoded, and `token_get_all()` still sees the raw source. ++* **Literal braces**: `{` begins interpolation, so a literal `{` in text is written as in HTML or JSX - a character reference (`{` / `{`) or an interpolated string (`{'{'}`). A lone `}` is already literal. No additional escape syntax (eg. Blade-style `@{{`) is introduced. A block of literal JSON/JS inside `; ++ ++echo ; ++ ++echo{'{'}example{'}'}
;
++```
++
++### Components are testable values
++
++A component is an ordinary object and its `toHtml()` result an ordinary value object, so a component is unit-tested directly: construct it, assert against the tree - no rendering, no string matching, no DOM parsing:
++
++```php
++public function testSaleBadgeShownWhenOnSale(): void
++{
++ $el = (new ProductBadge(product: $this->saleProduct()))->toHtml();
++
++ $this->assertInstanceOf(Html\Element::class, $el);
++ $this->assertSame('span', $el->tag);
++ $this->assertSame('badge sale', $el->attributes['class']);
++}
++```
++
++Views decompose the way any other code does: small component classes, each testable in isolation, composed by a top-level component returning the final page.
++
++### Framework components - a Livewire-style clock
++
++In frameworks whose components are PHP classes that render themselves - Livewire is the clearest example - the class and its markup are forced apart today: the component holds the state and behaviour, while the HTML lives in a separate Blade file the class points to by name.
++
++With markup expressions the same component could collapse into one self-contained class - `render()` returns the view instead of naming a file that contains it:
++
++```php
++class Clock extends Component
++{
++ public string $timezone = 'UTC';
++
++ public function render(): Html\Htmlable
++ {
++ return
++ {now($this->timezone)->format('H:i:s')}
++
;
++ }
++}
++```
++
++## Backward Incompatible Changes
++
++`<` is heavily overloaded in PHP (`<`, `<=`, `<=>`, `<<`, `<>`, `<<<`), so this was the main design risk. It is resolved by the same technique JavaScript uses to tell regex from division: the scanner tracks whether it is in **operand position** (a value is expected) or **operator position** (a value just ended), from the last significant token. Markup begins only when `<` is in operand position *and* is immediately followed by `[A-Za-z>]`, by `\` then a letter (a fully-qualified component tag such as `<\App\Card/>`), by `$` then a variable name, or by `{` (the dynamic tags `<$tag>` / `<{expr}>`):
++
++* In `$a < $b` (or the no-space `$a <$b`), `<` follows an operand → comparison, unchanged.
++* In `$a < \Foo::BAR`, `<` is in operator position → comparison, unchanged.
++* In `return `, `<` is in operand position followed by a letter → markup.
++
++The operand-position decision is an explicit allowlist that **fails closed**: markup begins only after a token that *expects* an operand - `return`, `echo`, `=`, `(`, `,`, `=>`, binary and assignment operators, casts, and the other expression-introducing contexts - which are exactly the positions where an infix `<` cannot legally appear today, and where `<` followed by a letter, `$`, `{`, or `>` is *always a syntax error*. After every other token, `<` keeps its existing meaning. Two properties follow:
++
++* **No valid program changes meaning, by construction.** Reclaiming `<` only ever applies where the source could not previously compile.
++* **The design is future-proof in the safe direction.** If a token is missing from the allowlist (or a future PHP version adds a new operator and forgets to include it), the only consequence is that markup cannot directly follow that token - a loud, feature-side parse error worked around with parentheses and fixed by a one-line addition. A gap can never silently change what existing code means.
++
++`<>` is the legacy alias of `!=` and is preserved in infix position (`$a <> $b` is still not-equal). `<>` is only reinterpreted as a fragment opener in **operand position**, where it is currently a syntax error - so no valid program needs changes. Two positions are deliberately excluded from the allowlist because an infix `<` after them is (or may be) valid PHP: after a bare `yield` (`yield < LIM` is valid, so yielding markup is written `yield ()`) and after a closing `}` (which ends `match` and interpolation values), so markup as a bare expression statement immediately following a block is assigned or echoed instead.
++
++This leaves just one backwards compatibility concern:
++
++1. **New `Html\` namespace** - introduces `Html\Htmlable`, `Html\Element`, `Html\Fragment`, `Html\Raw`, `Html\Slot`, `Html\raw()`, `Html\escape()`. Top-level `Html\` follows the established precedent for bundled extensions (`Random\`, `Dom\`, `Uri\`), and real-world top-level `Html\` packages are rare. No existing keywords are reserved and no new global reserved words are introduced (the syntax uses bare `<`, and the `:lazy` directive is only meaningful inside a markup tag).
++
++### Impact on tooling
++
++The scanner emits new `T_MARKUP_*` tokens (exposed as constants and through `token_get_all()`/`PhpToken`); ordinary code continues to tokenize identically. Tools that parse PHP source (nikic/php-parser, PHPStan, Psalm, php-cs-fixer, IDEs) will need grammar updates to understand markup expressions, as with any new syntax.
++
++A working syntax-highlighting/IDE extension for VS Code was built alongside the reference implementation to validate that the syntax is toolable.
++
++Because markup lowers to ordinary AST at compile time, everything downstream of the parser is unaffected: opcache caches and restores markup-containing files normally (verified, including the file cache), and reflection, serialization, `var_export()`, `clone` and `json_encode()` on the value objects behave as for any other class.
++
++A related question is what this means for **template engines** (Blade, Twig, Latte). This RFC does not replace them, and does not aim to: a full engine is much more than syntax plus escaping - layout inheritance, a designer-facing dialect that is deliberately *not* PHP, sandboxed rendering of untrusted templates, context-aware escaping, fragment caching, and years of ecosystem conventions. Nothing here removes any of that; markup is opt-in syntax, and code that never uses it is untouched.
++
++What this RFC offers the engines is a first-class substrate to build on. Today each engine maintains its own parser, its own escaping, and its own component model, because the language provides none. With markup native, an engine can adopt the shared foundation where it fits: `Html\Htmlable` is a common currency (a Blade view and a markup expression can accept and return the same interface and compose within one page); the dispatch hooks exist precisely so a framework can route component tags through its existing container and resolution logic; and an engine's component layer could compile *to* markup expressions, inheriting escape-by-default and end-to-end static analysis for free. The likely long-term shape is convergence rather than replacement: engines keep their higher-level features and progressively delegate parsing, escaping, and the value model to the language - much as database layers did not disappear when PDO shipped, but re-based onto it.
++
++## Future Scope
++
++Some natural extensions are deliberately left out of this RFC to keep its scope tight and expandable in the future; none is required for the feature to be useful:
++
++* **Context-aware escaping** (URL/JS/CSS contexts), as in Go's `html/template` or Latte's escaping, - so that e.g. a `javascript:` URL in `href` is caught. This RFC escapes HTML context only; the value-tree model is designed so this can be layered on later without a syntax change. Some examples include:
++ * A JavaScript escaping context inside `';
++echo (new Element('span', [], [$evil]))->__toString(), "\n";
++
++// --- attribute value coercion ---
++
++// null and false omit the attribute; true is a bare boolean attribute.
++echo (new Element('input', [
++ 'type' => 'checkbox',
++ 'checked' => true,
++ 'disabled' => false,
++ 'value' => null,
++ 'tabindex' => 3,
++ 'data-ratio' => 1.5,
++]))->__toString(), "\n";
++
++// Stringable attribute value.
++$s = new class implements Stringable {
++ public function __toString(): string { return 'x&y'; }
++};
++echo (new Element('a', ['data-x' => $s]))->__toString(), "\n";
++
++// Arrays are reserved -> TypeError.
++try {
++ (new Element('div', ['class' => ['a', 'b']]))->__toString();
++} catch (\Throwable $e) {
++ echo get_class($e), ': ', $e->getMessage(), "\n";
++}
++
++// --- Htmlable attribute values (no double-escaping) ---
++
++// Html\raw(): trusted content, emitted verbatim (the entity survives).
++echo x, "\n";
++
++// Html\escape(): escaped exactly once, not re-escaped at render time.
++echo x, "\n";
++
++// Plain strings still escape by default.
++echo x, "\n";
++
++// A generic Stringable (not Htmlable) still escapes.
++class S { public function __toString(): string { return 'x & y'; } }
++echo x, "\n";
++
++// --- Fragment, void elements, raw()/escape() helpers ---
++
++// Fragment: no wrapper element, children concatenated.
++$frag = new Fragment([
++ new Element('h1', [], ['Title']),
++ new Element('p', [], ['Body']),
++]);
++echo $frag->__toString(), "\n";
++
++// Void elements emit clean HTML5 (no slash, no closing tag).
++echo (new Element('br'))->__toString(), "\n";
++echo (new Element('img', ['src' => '/a.png', 'alt' => 'A & B']))->__toString(), "\n";
++
++// raw(): trusted passthrough, not escaped.
++echo raw('x')->__toString(), "\n";
++
++// escape(): escaped once, then safe to embed without double-escaping.
++$safe = escape('x');
++echo $safe->__toString(), "\n";
++echo (new Element('p', [], [$safe]))->__toString(), "\n"; // not escaped again
++
++var_dump(raw('y') instanceof Html\Htmlable);
++
++// --- tag/attribute-name validation (security) ---
++
++function err(callable $fn): string {
++ try { return $fn()->__toString(); }
++ catch (\Throwable $e) { return get_class($e) . ': ' . $e->getMessage(); }
++}
++
++// Attribute name from an attacker-controlled spread key - must be rejected.
++echo err(fn() => new E('a', ['x" onmouseover="alert(1)' => 'y'], ['hi'])), "\n";
++
++// Tag name from a dynamic source - must be rejected.
++echo err(fn() => new E('a>', [], [])), "\n";
++
++// Empty names rejected.
++echo err(fn() => new E('', [], [])), "\n";
++echo err(fn() => new E('div', ['' => 'x'], [])), "\n";
++
++// Legitimate dynamic names still work (custom elements, data-/aria-, namespaces).
++echo (new E('my-widget', ['data-x' => '1', 'aria-label' => 'ok', 'xml:lang' => 'en'], ['x']))->__toString(), "\n";
++echo ( 5]}>ok), "\n";
++?>
++--EXPECTF--
++Click me
++Click me
++bool(true)
++bool(true)
++string(1) "a"
++array(2) {
++ ["href"]=>
++ string(15) "https://php.net"
++ ["class"]=>
++ string(3) "btn"
++}
++array(1) {
++ [0]=>
++ string(8) "Click me"
++}
++
++
++x
++<b>x</b>
++x
++ok
+diff --git a/ext/html/tests/htmlable.phpt b/ext/html/tests/htmlable.phpt
+new file mode 100644
+index 00000000..88c32c30
+--- /dev/null
++++ b/ext/html/tests/htmlable.phpt
+@@ -0,0 +1,171 @@
++--TEST--
++Html\Htmlable: toHtml() contract and recursive resolution, injected default __toString vs declared __toString, cycles and throwing implementations
++--EXTENSIONS--
++html
++--FILE--
++{$this->title}
;
++ }
++}
++
++$card = new Card('Hi & bye');
++var_dump($card->toHtml() instanceof Html\Element);
++var_dump($card->toHtml()->tag);
++
++// The injected default __toString renders via toHtml(), so echo, (string),
++// and interpolation all work without the class declaring __toString.
++echo $card, "\n";
++echo (string) $card, "\n";
++echo "wrapped: {$card}\n";
++var_dump($card instanceof Stringable);
++
++// In markup child position the component renders through toHtml() natively.
++echo Tom & Jerry <3 "quotes" 'apostrophe'
++ ++<script>alert(1)</script> ++ ++ ++TypeError: Attribute "class" value must be of type string|int|float|bool|null|Stringable, array given ++x ++x ++x ++x ++Title
Body
++++
++x
++<b>x</b>
++<b>x</b>
++bool(true) ++ValueError: Invalid attribute name "x" onmouseover="alert(1)" ++ValueError: Invalid tag name "a>" ++ValueError: Invalid tag name "" ++ValueError: Invalid attribute name "" ++{new Selfish()}
; }
++catch (Error $e) { echo get_class($e), ": ", $e->getMessage(), "\n"; }
++
++// A two-class cycle is caught by the same bound.
++class Ping implements Html\Htmlable {
++ public function toHtml(): Html\Htmlable { return new Pong(); }
++}
++class Pong implements Html\Htmlable {
++ public function toHtml(): Html\Htmlable { return new Ping(); }
++}
++try { echo new Ping(); }
++catch (Error $e) { echo get_class($e), ": ", $e->getMessage(), "\n"; }
++
++// An exception thrown inside toHtml() propagates cleanly through the injected
++// __toString (both directly and from child position).
++class Boom implements Html\Htmlable {
++ public function toHtml(): Html\Htmlable { throw new RuntimeException('boom'); }
++}
++try { echo new Boom(); }
++catch (RuntimeException $e) { echo get_class($e), ": ", $e->getMessage(), "\n"; }
++try { echo {new Boom()}
; }
++catch (RuntimeException $e) { echo get_class($e), ": ", $e->getMessage(), "\n"; }
++
++echo "clean\n";
++?>
++--EXPECT--
++bool(true)
++string(3) "div"
++Hi & bye
++Hi & bye
++wrapped: Hi & bye
++bool(true)
++Hi & bye
Tagged
++delegated
++bool(true)
++bool(true)
++bool(true)
++CUSTOM
++markup
++LOUD / quiet
++BASE / child
++
++
++bool(true)
++string(6) "string"
++string(9) "SidePanel"
++bool(true)
++bool(true)
++
++Error: Maximum toHtml() resolution depth of 64 exceeded (Selfish::toHtml() never produced an Html\Element, Html\Fragment, or Html\Raw)
++Error: Maximum toHtml() resolution depth of 64 exceeded (Selfish::toHtml() never produced an Html\Element, Html\Fragment, or Html\Raw)
++Error: Maximum toHtml() resolution depth of 64 exceeded (Ping::toHtml() never produced an Html\Element, Html\Fragment, or Html\Raw)
++RuntimeException: boom
++RuntimeException: boom
++clean
+diff --git a/ext/html/tests/htmlable_missing_tohtml.phpt b/ext/html/tests/htmlable_missing_tohtml.phpt
+new file mode 100644
+index 00000000..efb3c746
+--- /dev/null
++++ b/ext/html/tests/htmlable_missing_tohtml.phpt
+@@ -0,0 +1,12 @@
++--TEST--
++Html\Htmlable: a class implementing neither toHtml() nor __toString() only owes toHtml()
++--EXTENSIONS--
++html
++--FILE--
++
++--EXPECTF--
++Fatal error: Class Nope contains 1 abstract method and must therefore be declared abstract or implement the remaining method (Html\Htmlable::toHtml) in %s on line %d
+diff --git a/ext/html/tests/htmlable_tohtml_opcache.phpt b/ext/html/tests/htmlable_tohtml_opcache.phpt
+new file mode 100644
+index 00000000..decb3206
+--- /dev/null
++++ b/ext/html/tests/htmlable_tohtml_opcache.phpt
+@@ -0,0 +1,34 @@
++--TEST--
++Html\Htmlable: the injected default __toString() survives opcache (arena-allocated internal method)
++--EXTENSIONS--
++html
++--SKIPIF--
++
++--INI--
++opcache.enable=1
++opcache.enable_cli=1
++--FILE--
++{$this->title}a & b
++c
++nested
x
)->__toString(), "\n";
++
++// self-closing element with attributes
++echo (t
, "\n";
++echo , "\n";
++
++// The prefix composes with the rest of the name charset (Alpine long forms,
++// modifiers) - only the *leading* character is new.
++echo , "\n";
++
++// Prefixed keys also pass the runtime name validation: spread and new Element.
++$attrs = ['@click' => 'save()', ':class' => 'cls'];
++echo s, "\n";
++echo new Html\Element('i', ['@x' => '1'], []), "\n";
++
++// On a component the names were never valid named-argument labels, so - like
++// data-* - they are collected by a variadic.
++class Btn implements Html\Htmlable {
++ private array $attrs;
++ public function __construct(public string $label, ...$attrs) { $this->attrs = $attrs; }
++ public function toHtml(): Html\Htmlable {
++ return ;
++ }
++}
++echo x
, "\n";
++
++// Attribute position only: a prefixed name can never begin a tag. At top
++// level "<:" / "<@" do not start markup at all; nested in markup content a
++// stray "<" gives the dedicated error.
++try {
++ eval('$x = <:foo/>
;');
++} catch (ParseError $e) {
++ echo $e->getMessage(), "\n";
++}
++try {
++ eval('$x = <@click/>
;');
++} catch (ParseError $e) {
++ echo $e->getMessage(), "\n";
++}
++
++// The prefix must be followed by a letter, and closing tags take no attributes.
++try {
++ eval('$x = t
;');
++} catch (ParseError $e) {
++ echo $e->getMessage(), "\n";
++}
++try {
++ eval('$x = t
;');
++} catch (ParseError $e) {
++ echo $e->getMessage(), "\n";
++}
++?>
++--EXPECT--
++link
++x
++Hi & bye
++Explicit
++box
++t
++
++
++s
++
++
++x
++Unescaped "<" in markup text; write {'<'} for a literal less-than sign
++Unescaped "<" in markup text; write {'<'} for a literal less-than sign
++syntax error, unexpected T_ERROR "@", expecting markup tag name or markup tag end or markup self-close or markup interpolation start
++syntax error, unexpected T_ERROR "@", expecting markup tag end
+diff --git a/ext/html/tests/syntax_basic.phpt b/ext/html/tests/syntax_basic.phpt
+new file mode 100644
+index 00000000..ca63a971
+--- /dev/null
++++ b/ext/html/tests/syntax_basic.phpt
+@@ -0,0 +1,176 @@
++--TEST--
++Markup syntax: elements, fragments, interpolation, whitespace, childless/self-close, literal braces, comments
++--EXTENSIONS--
++html
++--FILE--
++";
++
++// Element with interpolation and a nested element.
++$el = Hello {$name} world
;
++var_dump($el instanceof Html\Element);
++echo $el->__toString(), "\n";
++
++// Fragment (no wrapper).
++$frag = <>Title
Body {$name}
; ++var_dump($frag instanceof Html\Fragment); ++echo $frag->__toString(), "\n"; ++ ++// Interpolation can hold any expression; arrays flatten, null renders "". ++$items = ['x', 'y']; ++echo (- {array_map(fn($i) =>
- {$i} , $items)}
{true ? 'yes' : null}
)->__toString(), "\n"; ++ ++// --- JSX-style whitespace normalization --- ++// Newlines + indentation between block elements are dropped. ++echo (-
++
- one ++
- two ++
Hello {$who}, welcome back
)->__toString(), "\n"; ++ ++// Leading/trailing blank lines and indentation around text collapse away. ++echo (++ Just some text. ++
)->__toString(), "\n"; ++ ++// Words on separate lines join with a single space. ++echo (++ one ++ two ++ three ++
)->__toString(), "\n"; ++ ++// Inline trailing space with no newline is kept (so adjacent elements don't fuse). ++echo (a b c
)->__toString(), "\n"; ++ ++// --- childless elements: empty or self-closed are equivalent --- ++// and are equivalent - both allowed, so real HTML can be ++// pasted into markup unchanged. ++var_dump((string) === (string) ); ++echo , "\n"; ++echo , "\n"; ++ ++// A whitespace-only multi-line body normalizes away to the same empty element. ++echo
++
, "\n";
++
++// Void elements still serialize with no closing tag, from either source form.
++echo , "\n"; ++echo
, "\n"; ++ ++// --- self-closing source; serializer expands non-void elements --- ++// Void elements serialize without a closing tag... ++echo (
)->__toString(), "\n";
++// ...non-void self-closed source expands to open+close output.
++echo ()->__toString(), "\n";
++echo ()->__toString(), "\n";
++
++// Empty components and fragments are allowed (only HTML elements must self-close).
++class C implements Html\Htmlable {
++ public function toHtml(): Html\Htmlable { return Html\raw('C'); }
++}
++echo ({x}
)->__toString(), "\n"; ++echo ({x}
)->__toString(), "\n"; ++ ++// The JSX form: an interpolated string literal. ++echo ({'{'}x{'}'}
)->__toString(), "\n"; ++ ++// A lone } in text is already literal. ++echo (a } b
)->__toString(), "\n"; ++ ++// Literal JSON in a )->__toString(), "\n"; ++ ++// --- comments: is literal output; {/* */} renders nothing --- ++$x = 'ignored'; ++ ++// is emitted verbatim; its content is literal (no interpolation). ++echo (body
a{/* dropped */}b
)->__toString(), "\n"; ++ ++// an empty interpolation renders nothing too ++echo (x{}y
)->__toString(), "\n"; ++ ++// comment between block elements survives (it is real output, not whitespace) ++echo (-
++
++
- one ++
cast
, "\n"; // after a cast ++echopipe
|> strtoupper(...), "\n"; // after "|>"
++echo clone cl, "\n"; // after `clone`
++print Hello Ada & <friends> world
++bool(true)
++Title
Body Ada & <friends>
++- x
- y
yes
++- one
- two
Hello Ada, welcome back
++Just some text.
++one two three
++a b c
++bool(true) ++ ++ ++ ++++
++
++
++
++C
++string(0) ""
++{x}
++{x}
++{x}
++a } b
++ ++body
ab
++xy
++- one
cast
++PIPE
++cl
++{$this->slot}
; ++ } ++ } ++ class Card implements \Html\Htmlable { ++ public function __construct(public string $title) {} ++ public function toHtml(): \Html\Htmlable { ++ return new \Html\Element('b', [], [$this->title]); ++ } ++ } ++ class Author { ++ public static function byline(string $name): \Html\Htmlable { ++ return new \Html\Element('i', [], ['By ', $name]); ++ } ++ } ++} ++ ++// --- use-alias resolution from another namespace --- ++namespace App\Views { ++ use App\Components\Card; ++ //Hi & ok
++Nested
hi
++G ++fq
++C ++By Ada ++By Grace ++local ++"Wrong\Card" is not a component: no such class implementing Html\Htmlable +diff --git a/ext/html/tests/syntax_doctype.phpt b/ext/html/tests/syntax_doctype.phpt +new file mode 100644 +index 00000000..3de7054b +--- /dev/null ++++ b/ext/html/tests/syntax_doctype.phpt +@@ -0,0 +1,50 @@ ++--TEST-- ++Markup syntax: emission rules and non-doctype ++ ++hi
++)->__toString(), "\n"; ++ ++// Case-insensitive, and content is literal (no interpolation). ++echo (<>)->__toString(), "\n"; ++ ++// Legacy doctypes with public/system identifiers pass through too. ++echo (<>x
)->__toString(), "\n"; ++ ++// Position is not validated: emitted where written, like a comment. ++echo (s
)->__toString(), "\n";
++
++// --- non-doctype ;');
++} catch (ParseError $e) {
++ echo $e->getMessage(), "\n";
++}
++try {
++ eval('$v = ;');
++} catch (ParseError $e) {
++ echo $e->getMessage(), "\n";
++}
++// An unterminated doctype must not scan past the end of the file.
++try {
++ eval('$v = getMessage(), "\n";
++}
++?>
++--EXPECTF--
++
for .
++try {
++ eval('$x = <$a>hi;');
++} catch (CompileError $e) {
++ echo $e->getMessage(), "\n";
++}
++
++// A brace tag closes anonymously; a named or variable close is a parse error
++// (the expression cannot be restated without re-evaluating it).
++foreach (['$x = <{"div"}>ahi
++ ++x
++s
++Unsupported markup declaration; only comments and are supported
++Unsupported markup declaration; only comments and are supported
++%s
+diff --git a/ext/html/tests/syntax_dynamic.phpt b/ext/html/tests/syntax_dynamic.phpt
+new file mode 100644
+index 00000000..8ff87fb0
+--- /dev/null
++++ b/ext/html/tests/syntax_dynamic.phpt
+@@ -0,0 +1,177 @@
++--TEST--
++Markup syntax: dynamic tags <$tag>/<{expr}> - classification, escaping, single evaluation, BC, error cases
++--EXTENSIONS--
++html
++--FILE--
++ variable elements ---
++// An element name: behaves exactly like the static tag.
++$tag = 'div';
++$el = <$tag class="box">Hello;
++var_dump($el instanceof Html\Element);
++echo $el, "\n";
++
++// Self-close; void elements serialize as voids.
++$tag = 'br';
++echo <$tag/>, "\n";
++$tag = 'section';
++echo <$tag id="main" hidden>Text {1 + 1}, "\n";
++
++// Nested inside static markup, with spread attributes.
++$tag = 'em';
++$attrs = ['class' => 'x'];
++echo <$tag {...$attrs}>hi
, "\n";
++
++// --- runtime classification: components ---
++// A class-component name (::class gives the FQCN): full component dispatch.
++class Card implements Html\Htmlable {
++ public function __construct(
++ private string $title,
++ #[Html\Slot] private ?Html\Htmlable $body = null,
++ ) {}
++ public function toHtml(): Html\Htmlable {
++ return <{'em'}>in here
, "\n";
++
++// --- operator-position "<$" keeps its comparison meaning (BC) ---
++$a = 5;
++$b = 9;
++var_dump($a <$b, $b <$a);
++
++// --- render_dynamic() direct calls ---
++// The runtime target is a public function, same as render_component().
++echo Html\render_dynamic('p', ['class' => 'y'], ['direct']), "\n";
++echo Html\render_dynamic(Card::class, ['title' => 'Direct']), "\n";
++
++// --- error cases ---
++// Mismatched closing variable is a compile error, like Hello
++++
hi
++Hi
Hi
BodyHello
++note
++Braced
once
++int(1) ++in here
++bool(true)
++bool(false)
++direct
++Direct
Á vs á
, "\n"; ++ ++// Numeric references: decimal, hex (either x/X case), multi-codepoint named. ++echoABC 😀 ≫⃒
, "\n"; ++ ++// is a real U+00A0, not the entity text (htmlspecialchars leaves it alone). ++var_dump((string) === "\u{00A0}"); ++ ++// --- lenient handling of invalid references --- ++// Lenient like HTML/JSX: unknown names, bare "&", missing semicolons, ++// and invalid numerics (zero, surrogate, out of range, empty) stay literal ++// and are escaped on output. ++echoa & b &nosuchentity; & c
, "\n"; ++echo� � � &#; &#x; &#xG;
, "\n"; ++ ++// --- attribute values --- ++// Attribute values decode too; the "&" re-escapes when serialized. ++echo x, "\n"; ++ ++// --- entities cannot smuggle markup structure --- ++// lt/gt decode to real angle brackets in the value, escaped on output -- ++// so entities cannot smuggle markup structure. ++echo<script>alert(1)</script>
, "\n"; ++ ++// --- interaction with whitespace normalization, comments, interpolation --- ++// Entities decode after whitespace normalization, so survives where a ++// literal trailing space would be trimmed (the entity spelling of JSX {' '}). ++echoa ++
, "\n"; ++ ++// Entities inside stay verbatim (comments are raw output). ++echo , "\n"; ++ ++// Interpolated strings are never entity-decoded; they are plain PHP values. ++echo{"&"}
, "\n"; ++ ++// --- tokenizer round-trip --- ++// Entity decoding happens only for the compiler; the tokenizer must see the ++// raw source text so token streams concatenate back to the original file. ++$code = 'Fish & chips ❤; ?>'; ++ ++$joined = ''; ++foreach (token_get_all($code) as $token) { ++ $joined .= is_array($token) ? $token[1] : $token; ++} ++var_dump($joined === $code); ++?> ++--EXPECT-- ++Fish & chips — £5
++Á vs á
++ABC 😀 ≫⃒
++bool(true) ++a & b &nosuchentity; & c
++� � � &#; &#x; &#xG;
++x ++<script>alert(1)</script>
++a
++ ++&
++bool(true) +diff --git a/ext/html/tests/syntax_lineno.phpt b/ext/html/tests/syntax_lineno.phpt +new file mode 100644 +index 00000000..8f6da867 +--- /dev/null ++++ b/ext/html/tests/syntax_lineno.phpt +@@ -0,0 +1,37 @@ ++--TEST-- ++Markup syntax: multi-line elements report errors on the opening-tag line, like any multi-line call ++--EXTENSIONS-- ++html ++--FILE-- ++{$this->title}Hello {$name}
'), "\n";
++
++// Fragment, component with props + spread, nested element body.
++echo desugar('<>Fish & chips — £5
'), "\n"; ++?> ++--EXPECT-- ++new \Html\Element('div', ['class' => 'box', 'id' => $id], ['Hello ', $name]) ++new \Html\Fragment([\Html\render_component(Card::class, ['title' => 'Hi', ...$attrs], new \Html\Fragment([new \Html\Element('b', [], ['f']), 'body']))]) ++\Html\render_component(Author::class . '::byline', ['name' => 'Ada'], null) ++\Html\render_component(Auth::class, [], new \Html\LazyFragment(fn() => new \Html\Fragment(['Hello ', $name]))) ++\Html\render_dynamic($tag, ['class' => 'x'], [$content]) ++new \Html\Element('p', [], ['Fish & chips — £5']) +diff --git a/ext/html/tests/syntax_mismatch.phpt b/ext/html/tests/syntax_mismatch.phpt +new file mode 100644 +index 00000000..a11b3e3b +--- /dev/null ++++ b/ext/html/tests/syntax_mismatch.phpt +@@ -0,0 +1,10 @@ ++--TEST-- ++Markup syntax: a mismatched closing tag is a compile error ++--EXTENSIONS-- ++html ++--FILE-- ++oops; ++?> ++--EXPECTF-- ++Fatal error: Mismatched markup closing tag: expectedHello Ada & <friends> world
' \
+ "$("$PHP" -r '$name="Ada & Hello {$name} world
;')"
+
+check "attribute values are escaped" 'x' \
+ "$("$PHP" -r '$u="?a=1&b=2"; echo x;')"
+
+check "void element serializes with no closing tag" "" \ + "$("$PHP" -r 'echo
;')" + +check "self-close and open/close are equivalent" "bool(true)" \ + "$("$PHP" -r 'var_dump((string) === (string));')" + +check "arrays in interpolation flatten" '
- x
- y
- {array_map(fn($v)=>
- {$v} , $i)}
bold
' \ + "$("$PHP" -r 'echo{Html\raw("bold")}
;')" + +check "component tag dispatches to render_component" 'hi' \ + "$("$PHP" -r 'class Badge implements Html\Htmlable { public function __construct(public string $label){} + public function toHtml(): Html\Htmlable { return new Html\Element("span",["class"=>"badge"],[$this->label]); } } + echohi
' \
+ "$("$PHP" -r 'class Badge implements Html\Htmlable { public function __construct(public string $label){}
+ public function toHtml(): Html\Htmlable { return new Html\Element("span",["class"=>"badge"],[$this->label]); } }
+ echo 1 2.5 1
+- Ada
- Linus
- Grace
bold
+hi & bye
+TypeError: Object of class stdClass cannot be rendered as a markup child: it implements none of Html\Htmlable, Stringable, or Traversable
+- one
- two
x & yz
+before nested after
+RuntimeException: stop
+Error: Maximum markup nesting depth of 1024 exceeded
+- ok
cannot have children +Error: Component props must use string keys +Error: Component class "PrivateCtor" has a non-public constructor +Error: Component class "NoCtor" has no constructor, so it cannot accept attributes or slots +no-ctor +Error: Component method Methods::hidden() must be a public static user-defined method +Error: Component method Methods::nonStatic() must be a public static user-defined method +Too few arguments to function NeedsDep::__construct()%A +Too few arguments to function NeedsDep::__construct()%A +Too few arguments to function NeedsDep::__construct()%A +RuntimeException: boom +clean diff --git a/features/22-native-markup/tests/component_hooks.phpt b/features/22-native-markup/tests/component_hooks.phpt new file mode 100644 index 0000000..ffa564d --- /dev/null +++ b/features/22-native-markup/tests/component_hooks.phpt @@ -0,0 +1,188 @@ +--TEST-- +Html components: factory hooks (DI), decorators, and per-component hook scoping +--EXTENSIONS-- +html +--FILE-- +title]); + } +} +class Badge implements Html\Htmlable { + public function __construct(public string $label = "?") {} + public function toHtml(): Html\Htmlable { + return new Html\Element('b', [], [$this->label]); + } +} +class Note implements Html\Htmlable { + public function __construct(public string $t) {} + public function toHtml(): Html\Htmlable { + return new Html\Element('p', [], [$this->t]); + } +} +class Author { + public static function byline(string $t): Html\Htmlable { + return new Html\Element('span', [], [$t]); + } +} + +// --- factory hooks: chain, defer, bad return, unregister identity --- + +// A dependency the props never supply; the "container" injects it. +class Clock { public function now(): string { return "T"; } } + +// Class component: a DI dependency ($clock) plus a prop ($label). +class TimeBadge implements Html\Htmlable { + public function __construct(private Clock $clock, public string $label) {} + public function toHtml(): Html\Htmlable { + return new Html\Element('span', [], ["{$this->label}:{$this->clock->now()}"]); + } +} + +// A tiny autowiring container: fill non-builtin params the $args don't provide. +function autowire(ReflectionFunctionAbstract $r, array $args): array { + $extra = []; + foreach ($r->getParameters() as $p) { + $t = $p->getType(); + if ($t instanceof ReflectionNamedType && !$t->isBuiltin() + && !array_key_exists($p->getName(), $args)) { + $extra[$p->getName()] = new ($t->getName())(); + } + } + return [...$extra, ...$args]; +} +$defer = fn(string $class, array $args) => null; // always defers to the next factory +$make = fn(string $class, array $args) + => (new ReflectionClass($class))->newInstanceArgs( + autowire(new ReflectionMethod($class, '__construct'), $args)); + +// (1) Without hooks, the engine's own `new` runs and fails for the missing Clock. +try { echo
a
[/Card]
+[Note]b
[/Note] +[Author::byline]c[/Author::byline] +<<[Note]d
[/Note]>> +Component decorator formade
+?
+factory(Card)
+made
+any(Badge)
+?
+bool(false)
+bool(false)
+bool(true)
+bool(true)
+?
+<<B>>
+C
+bool(true)
+B
diff --git a/features/22-native-markup/tests/component_slots.phpt b/features/22-native-markup/tests/component_slots.phpt
new file mode 100644
index 0000000..745b72d
--- /dev/null
+++ b/features/22-native-markup/tests/component_slots.phpt
@@ -0,0 +1,116 @@
+--TEST--
+Html components: #[Html\Slot] body routing, slot validation errors, Slot attribute reflection
+--EXTENSIONS--
+html
+--FILE--
+getMessage(); }
+}
+
+// --- body content routes to the #[Html\Slot] parameter ---
+
+// The body slot routes to the #[Slot] parameter; other content areas are
+// ordinary props typed Html\Htmlable (what named slots used to be).
+class Layout implements Html\Htmlable {
+ public function __construct(
+ public string $lang,
+ #[Slot] public ?Html\Htmlable $body = null,
+ public ?Html\Htmlable $header = null,
+ public ?Html\Htmlable $footer = null,
+ ) {}
+ public function toHtml(): Html\Htmlable {
+ return new E('main', ['lang' => $this->lang], [$this->header, $this->body, $this->footer]);
+ }
+}
+
+$out = render_component(
+ Layout::class,
+ [
+ 'lang' => 'en',
+ 'header' => new E('h1', [], ['Title']),
+ 'footer' => new Fragment([new E('small', [], ['(c) 2026'])]),
+ ],
+ new Fragment([new E('p', [], ['loose body'])]), // body slot
+);
+echo $out, "\n";
+
+// Body slot only.
+class Panel implements Html\Htmlable {
+ public function __construct(
+ public string $kind,
+ #[Slot] public ?Html\Htmlable $content = null,
+ ) {}
+ public function toHtml(): Html\Htmlable {
+ return new E('section', ['class' => $this->kind], [$this->content]);
+ }
+}
+echo render_component(Panel::class, ['kind' => 'note'], new Fragment([Html\raw('hi')]))->__toString(), "\n";
+
+// --- slot-routing validation errors ---
+
+// Body content given, but a parameter+attribute would collide.
+class Solo implements Html\Htmlable {
+ public function __construct(#[Slot] public Html\Htmlable $body) {}
+ public function toHtml(): Html\Htmlable { return new E('p', [], [$this->body]); }
+}
+echo err(fn() => render_component(Solo::class, ['body' => 'x'], new Fragment([Html\raw('y')]))), "\n";
+
+// Body content given to a component that has no slot parameter.
+class NoSlot implements Html\Htmlable {
+ public function __construct(public string $x) {}
+ public function toHtml(): Html\Htmlable { return new E('i', [], [$this->x]); }
+}
+echo err(fn() => render_component(NoSlot::class, ['x' => 'hi'], new Fragment([Html\raw('body')]))), "\n";
+
+// More than one slot parameter is a definition error.
+class TwoSlots implements Html\Htmlable {
+ public function __construct(#[Slot] public ?Html\Htmlable $a = null, #[Slot] public ?Html\Htmlable $b = null) {}
+ public function toHtml(): Html\Htmlable { return new Fragment([$this->a, $this->b]); }
+}
+echo err(fn() => render_component(TwoSlots::class, [], new Fragment([]))), "\n";
+
+// #[Slot] on a variadic parameter is a definition error.
+class Variadic implements Html\Htmlable {
+ private array $parts;
+ public function __construct(#[Slot] Html\Htmlable ...$parts) { $this->parts = $parts; }
+ public function toHtml(): Html\Htmlable { return new Fragment($this->parts); }
+}
+echo err(fn() => render_component(Variadic::class, [], new Fragment([]))), "\n";
+
+// --- Html\Slot is a bare parameter-target marker attribute ---
+
+function LayoutFn(
+ #[Slot] Html\Htmlable $body,
+ ?Html\Htmlable $footer = null,
+): Html\Htmlable {
+ return new Html\Fragment([$body, $footer]);
+}
+
+$ref = new ReflectionFunction('LayoutFn');
+foreach ($ref->getParameters() as $param) {
+ foreach ($param->getAttributes(Slot::class) as $attr) {
+ $slot = $attr->newInstance();
+ printf("%s -> %s\n", $param->getName(), get_class($slot));
+ }
+}
+
+// Slot takes no arguments and only targets parameters.
+$attr = (new ReflectionClass(Slot::class))->getAttributes(Attribute::class)[0]->newInstance();
+var_dump($attr->flags === Attribute::TARGET_PARAMETER);
+?>
+--EXPECTF--
+Title
loose body
(c) 2026Hi {$who}
- {array_map(fn($t) =>
Ada & co
Hi Ada & co
Solo
By Ada & co
+New & +x
+- ab
By Ada
+Error: Component "Author::broken" did not return an Html\Htmlable +Error: Component class "NoSuchClass" not found +FROM CLASS +box
+Error: Unknown named parameter $data-x
diff --git a/features/22-native-markup/tests/element.phpt b/features/22-native-markup/tests/element.phpt
new file mode 100644
index 0000000..a03eb50
--- /dev/null
+++ b/features/22-native-markup/tests/element.phpt
@@ -0,0 +1,159 @@
+--TEST--
+Html\Element/Fragment/Raw construction API: rendering, escaping, attribute coercion, Htmlable attributes, void elements, raw()/escape(), name validation
+--EXTENSIONS--
+html
+--FILE--
+ 'https://php.net', 'class' => 'btn'], ['Click me']);
+echo $el->__toString(), "\n";
+echo $el, "\n"; // echo casts via __toString
+
+var_dump($el instanceof Html\Htmlable);
+var_dump($el instanceof Stringable);
+var_dump($el->tag);
+var_dump($el->attributes);
+var_dump($el->children);
+
+// --- escaping ---
+
+// Child text is escaped.
+echo (new Element('p', [], ['Tom & Jerry <3 "quotes" \'apostrophe\'']))->__toString(), "\n";
+
+// Attribute values are escaped.
+echo (new Element('div', ['title' => 'a "b" & Tom & Jerry <3 "quotes" 'apostrophe'
+ +<script>alert(1)</script> + + +TypeError: Attribute "class" value must be of type string|int|float|bool|null|Stringable, array given +x +x +x +x +Title
Body
++
+x
+<b>x</b>
+<b>x</b>
+bool(true) +ValueError: Invalid attribute name "x" onmouseover="alert(1)" +ValueError: Invalid tag name "a>" +ValueError: Invalid tag name "" +ValueError: Invalid attribute name "" +{new Selfish()}
; }
+catch (Error $e) { echo get_class($e), ": ", $e->getMessage(), "\n"; }
+
+// A two-class cycle is caught by the same bound.
+class Ping implements Html\Htmlable {
+ public function toHtml(): Html\Htmlable { return new Pong(); }
+}
+class Pong implements Html\Htmlable {
+ public function toHtml(): Html\Htmlable { return new Ping(); }
+}
+try { echo new Ping(); }
+catch (Error $e) { echo get_class($e), ": ", $e->getMessage(), "\n"; }
+
+// An exception thrown inside toHtml() propagates cleanly through the injected
+// __toString (both directly and from child position).
+class Boom implements Html\Htmlable {
+ public function toHtml(): Html\Htmlable { throw new RuntimeException('boom'); }
+}
+try { echo new Boom(); }
+catch (RuntimeException $e) { echo get_class($e), ": ", $e->getMessage(), "\n"; }
+try { echo {new Boom()}
; }
+catch (RuntimeException $e) { echo get_class($e), ": ", $e->getMessage(), "\n"; }
+
+echo "clean\n";
+?>
+--EXPECT--
+bool(true)
+string(3) "div"
+Hi & bye
+Hi & bye
+wrapped: Hi & bye
+bool(true)
+Hi & bye
Tagged
+delegated
+bool(true)
+bool(true)
+bool(true)
+CUSTOM
+markup
+LOUD / quiet
+BASE / child
+
+
+bool(true)
+string(6) "string"
+string(9) "SidePanel"
+bool(true)
+bool(true)
+
+Error: Maximum toHtml() resolution depth of 64 exceeded (Selfish::toHtml() never produced an Html\Element, Html\Fragment, or Html\Raw)
+Error: Maximum toHtml() resolution depth of 64 exceeded (Selfish::toHtml() never produced an Html\Element, Html\Fragment, or Html\Raw)
+Error: Maximum toHtml() resolution depth of 64 exceeded (Ping::toHtml() never produced an Html\Element, Html\Fragment, or Html\Raw)
+RuntimeException: boom
+RuntimeException: boom
+clean
diff --git a/features/22-native-markup/tests/htmlable_missing_tohtml.phpt b/features/22-native-markup/tests/htmlable_missing_tohtml.phpt
new file mode 100644
index 0000000..efb3c74
--- /dev/null
+++ b/features/22-native-markup/tests/htmlable_missing_tohtml.phpt
@@ -0,0 +1,12 @@
+--TEST--
+Html\Htmlable: a class implementing neither toHtml() nor __toString() only owes toHtml()
+--EXTENSIONS--
+html
+--FILE--
+
+--EXPECTF--
+Fatal error: Class Nope contains 1 abstract method and must therefore be declared abstract or implement the remaining method (Html\Htmlable::toHtml) in %s on line %d
diff --git a/features/22-native-markup/tests/htmlable_tohtml_opcache.phpt b/features/22-native-markup/tests/htmlable_tohtml_opcache.phpt
new file mode 100644
index 0000000..decb320
--- /dev/null
+++ b/features/22-native-markup/tests/htmlable_tohtml_opcache.phpt
@@ -0,0 +1,34 @@
+--TEST--
+Html\Htmlable: the injected default __toString() survives opcache (arena-allocated internal method)
+--EXTENSIONS--
+html
+--SKIPIF--
+
+--INI--
+opcache.enable=1
+opcache.enable_cli=1
+--FILE--
+{$this->title}a & b
+c
+nested
hi
,); + $f = fn() => a; + yield (
x
)->__toString(), "\n";
+
+// self-closing element with attributes
+echo (t
, "\n";
+echo , "\n";
+
+// The prefix composes with the rest of the name charset (Alpine long forms,
+// modifiers) - only the *leading* character is new.
+echo , "\n";
+
+// Prefixed keys also pass the runtime name validation: spread and new Element.
+$attrs = ['@click' => 'save()', ':class' => 'cls'];
+echo s, "\n";
+echo new Html\Element('i', ['@x' => '1'], []), "\n";
+
+// On a component the names were never valid named-argument labels, so - like
+// data-* - they are collected by a variadic.
+class Btn implements Html\Htmlable {
+ private array $attrs;
+ public function __construct(public string $label, ...$attrs) { $this->attrs = $attrs; }
+ public function toHtml(): Html\Htmlable {
+ return ;
+ }
+}
+echo x
, "\n";
+
+// Attribute position only: a prefixed name can never begin a tag. At top
+// level "<:" / "<@" do not start markup at all; nested in markup content a
+// stray "<" gives the dedicated error.
+try {
+ eval('$x = <:foo/>
;');
+} catch (ParseError $e) {
+ echo $e->getMessage(), "\n";
+}
+try {
+ eval('$x = <@click/>
;');
+} catch (ParseError $e) {
+ echo $e->getMessage(), "\n";
+}
+
+// The prefix must be followed by a letter, and closing tags take no attributes.
+try {
+ eval('$x = t
;');
+} catch (ParseError $e) {
+ echo $e->getMessage(), "\n";
+}
+try {
+ eval('$x = t
;');
+} catch (ParseError $e) {
+ echo $e->getMessage(), "\n";
+}
+?>
+--EXPECT--
+link
+x
+Hi & bye
+Explicit
+box
+t
+
+
+s
+
+
+x
+Unescaped "<" in markup text; write {'<'} for a literal less-than sign
+Unescaped "<" in markup text; write {'<'} for a literal less-than sign
+syntax error, unexpected T_ERROR "@", expecting markup tag name or markup tag end or markup self-close or markup interpolation start
+syntax error, unexpected T_ERROR "@", expecting markup tag end
diff --git a/features/22-native-markup/tests/syntax_basic.phpt b/features/22-native-markup/tests/syntax_basic.phpt
new file mode 100644
index 0000000..ca63a97
--- /dev/null
+++ b/features/22-native-markup/tests/syntax_basic.phpt
@@ -0,0 +1,176 @@
+--TEST--
+Markup syntax: elements, fragments, interpolation, whitespace, childless/self-close, literal braces, comments
+--EXTENSIONS--
+html
+--FILE--
+";
+
+// Element with interpolation and a nested element.
+$el = Hello {$name} world
;
+var_dump($el instanceof Html\Element);
+echo $el->__toString(), "\n";
+
+// Fragment (no wrapper).
+$frag = <>Title
Body {$name}
; +var_dump($frag instanceof Html\Fragment); +echo $frag->__toString(), "\n"; + +// Interpolation can hold any expression; arrays flatten, null renders "". +$items = ['x', 'y']; +echo (- {array_map(fn($i) =>
- {$i} , $items)}
{true ? 'yes' : null}
)->__toString(), "\n"; + +// --- JSX-style whitespace normalization --- +// Newlines + indentation between block elements are dropped. +echo (-
+
- one +
- two +
Hello {$who}, welcome back
)->__toString(), "\n"; + +// Leading/trailing blank lines and indentation around text collapse away. +echo (+ Just some text. +
)->__toString(), "\n"; + +// Words on separate lines join with a single space. +echo (+ one + two + three +
)->__toString(), "\n"; + +// Inline trailing space with no newline is kept (so adjacent elements don't fuse). +echo (a b c
)->__toString(), "\n"; + +// --- childless elements: empty or self-closed are equivalent --- +// and are equivalent - both allowed, so real HTML can be +// pasted into markup unchanged. +var_dump((string) === (string) ); +echo , "\n"; +echo , "\n"; + +// A whitespace-only multi-line body normalizes away to the same empty element. +echo
+
, "\n";
+
+// Void elements still serialize with no closing tag, from either source form.
+echo , "\n"; +echo
, "\n"; + +// --- self-closing source; serializer expands non-void elements --- +// Void elements serialize without a closing tag... +echo (
)->__toString(), "\n";
+// ...non-void self-closed source expands to open+close output.
+echo ()->__toString(), "\n";
+echo ()->__toString(), "\n";
+
+// Empty components and fragments are allowed (only HTML elements must self-close).
+class C implements Html\Htmlable {
+ public function toHtml(): Html\Htmlable { return Html\raw('C'); }
+}
+echo ({x}
)->__toString(), "\n"; +echo ({x}
)->__toString(), "\n"; + +// The JSX form: an interpolated string literal. +echo ({'{'}x{'}'}
)->__toString(), "\n"; + +// A lone } in text is already literal. +echo (a } b
)->__toString(), "\n"; + +// Literal JSON in a )->__toString(), "\n"; + +// --- comments: is literal output; {/* */} renders nothing --- +$x = 'ignored'; + +// is emitted verbatim; its content is literal (no interpolation). +echo (body
a{/* dropped */}b
)->__toString(), "\n"; + +// an empty interpolation renders nothing too +echo (x{}y
)->__toString(), "\n"; + +// comment between block elements survives (it is real output, not whitespace) +echo (-
+
+
- one +
cast
, "\n"; // after a cast +echopipe
|> strtoupper(...), "\n"; // after "|>"
+echo clone cl, "\n"; // after `clone`
+print Hello Ada & <friends> world
+bool(true)
+Title
Body Ada & <friends>
+- x
- y
yes
+- one
- two
Hello Ada, welcome back
+Just some text.
+one two three
+a b c
+bool(true) + + + ++
+
+
+
+C
+string(0) ""
+{x}
+{x}
+{x}
+a } b
+ +body
ab
+xy
+- one
cast
+PIPE
+cl
+{$this->slot}
; + } + } + class Card implements \Html\Htmlable { + public function __construct(public string $title) {} + public function toHtml(): \Html\Htmlable { + return new \Html\Element('b', [], [$this->title]); + } + } + class Author { + public static function byline(string $name): \Html\Htmlable { + return new \Html\Element('i', [], ['By ', $name]); + } + } +} + +// --- use-alias resolution from another namespace --- +namespace App\Views { + use App\Components\Card; + //Hi & ok
+Nested
hi
+G +fq
+C +By Ada +By Grace +local +"Wrong\Card" is not a component: no such class implementing Html\Htmlable diff --git a/features/22-native-markup/tests/syntax_doctype.phpt b/features/22-native-markup/tests/syntax_doctype.phpt new file mode 100644 index 0000000..3de7054 --- /dev/null +++ b/features/22-native-markup/tests/syntax_doctype.phpt @@ -0,0 +1,50 @@ +--TEST-- +Markup syntax: emission rules and non-doctype + +hi
+)->__toString(), "\n"; + +// Case-insensitive, and content is literal (no interpolation). +echo (<>)->__toString(), "\n"; + +// Legacy doctypes with public/system identifiers pass through too. +echo (<>x
)->__toString(), "\n"; + +// Position is not validated: emitted where written, like a comment. +echo (s
)->__toString(), "\n";
+
+// --- non-doctype ;');
+} catch (ParseError $e) {
+ echo $e->getMessage(), "\n";
+}
+try {
+ eval('$v = ;');
+} catch (ParseError $e) {
+ echo $e->getMessage(), "\n";
+}
+// An unterminated doctype must not scan past the end of the file.
+try {
+ eval('$v = getMessage(), "\n";
+}
+?>
+--EXPECTF--
+
for .
+try {
+ eval('$x = <$a>hi;');
+} catch (CompileError $e) {
+ echo $e->getMessage(), "\n";
+}
+
+// A brace tag closes anonymously; a named or variable close is a parse error
+// (the expression cannot be restated without re-evaluating it).
+foreach (['$x = <{"div"}>ahi
+ +x
+s
+Unsupported markup declaration; only comments and are supported
+Unsupported markup declaration; only comments and are supported
+%s
diff --git a/features/22-native-markup/tests/syntax_dynamic.phpt b/features/22-native-markup/tests/syntax_dynamic.phpt
new file mode 100644
index 0000000..8ff87fb
--- /dev/null
+++ b/features/22-native-markup/tests/syntax_dynamic.phpt
@@ -0,0 +1,177 @@
+--TEST--
+Markup syntax: dynamic tags <$tag>/<{expr}> - classification, escaping, single evaluation, BC, error cases
+--EXTENSIONS--
+html
+--FILE--
+ variable elements ---
+// An element name: behaves exactly like the static tag.
+$tag = 'div';
+$el = <$tag class="box">Hello;
+var_dump($el instanceof Html\Element);
+echo $el, "\n";
+
+// Self-close; void elements serialize as voids.
+$tag = 'br';
+echo <$tag/>, "\n";
+$tag = 'section';
+echo <$tag id="main" hidden>Text {1 + 1}, "\n";
+
+// Nested inside static markup, with spread attributes.
+$tag = 'em';
+$attrs = ['class' => 'x'];
+echo <$tag {...$attrs}>hi
, "\n";
+
+// --- runtime classification: components ---
+// A class-component name (::class gives the FQCN): full component dispatch.
+class Card implements Html\Htmlable {
+ public function __construct(
+ private string $title,
+ #[Html\Slot] private ?Html\Htmlable $body = null,
+ ) {}
+ public function toHtml(): Html\Htmlable {
+ return {$this->title}
{$this->body}<{'em'}>in here
, "\n";
+
+// --- operator-position "<$" keeps its comparison meaning (BC) ---
+$a = 5;
+$b = 9;
+var_dump($a <$b, $b <$a);
+
+// --- render_dynamic() direct calls ---
+// The runtime target is a public function, same as render_component().
+echo Html\render_dynamic('p', ['class' => 'y'], ['direct']), "\n";
+echo Html\render_dynamic(Card::class, ['title' => 'Direct']), "\n";
+
+// --- error cases ---
+// Mismatched closing variable is a compile error, like Hello
++
hi
+Hi
Hi
BodyHello
+note
+Braced
once
+int(1) +in here
+bool(true)
+bool(false)
+direct
+Direct
Á vs á
, "\n"; + +// Numeric references: decimal, hex (either x/X case), multi-codepoint named. +echoABC 😀 ≫⃒
, "\n"; + +// is a real U+00A0, not the entity text (htmlspecialchars leaves it alone). +var_dump((string) === "\u{00A0}"); + +// --- lenient handling of invalid references --- +// Lenient like HTML/JSX: unknown names, bare "&", missing semicolons, +// and invalid numerics (zero, surrogate, out of range, empty) stay literal +// and are escaped on output. +echoa & b &nosuchentity; & c
, "\n"; +echo� � � &#; &#x; &#xG;
, "\n"; + +// --- attribute values --- +// Attribute values decode too; the "&" re-escapes when serialized. +echo x, "\n"; + +// --- entities cannot smuggle markup structure --- +// lt/gt decode to real angle brackets in the value, escaped on output -- +// so entities cannot smuggle markup structure. +echo<script>alert(1)</script>
, "\n"; + +// --- interaction with whitespace normalization, comments, interpolation --- +// Entities decode after whitespace normalization, so survives where a +// literal trailing space would be trimmed (the entity spelling of JSX {' '}). +echoa +
, "\n"; + +// Entities inside stay verbatim (comments are raw output). +echo , "\n"; + +// Interpolated strings are never entity-decoded; they are plain PHP values. +echo{"&"}
, "\n"; + +// --- tokenizer round-trip --- +// Entity decoding happens only for the compiler; the tokenizer must see the +// raw source text so token streams concatenate back to the original file. +$code = 'Fish & chips ❤; ?>'; + +$joined = ''; +foreach (token_get_all($code) as $token) { + $joined .= is_array($token) ? $token[1] : $token; +} +var_dump($joined === $code); +?> +--EXPECT-- +Fish & chips — £5
+Á vs á
+ABC 😀 ≫⃒
+bool(true) +a & b &nosuchentity; & c
+� � � &#; &#x; &#xG;
+x +<script>alert(1)</script>
+a
+ +&
+bool(true) diff --git a/features/22-native-markup/tests/syntax_lineno.phpt b/features/22-native-markup/tests/syntax_lineno.phpt new file mode 100644 index 0000000..8f6da86 --- /dev/null +++ b/features/22-native-markup/tests/syntax_lineno.phpt @@ -0,0 +1,37 @@ +--TEST-- +Markup syntax: multi-line elements report errors on the opening-tag line, like any multi-line call +--EXTENSIONS-- +html +--FILE-- +{$this->title}Hello {$name}
'), "\n";
+
+// Fragment, component with props + spread, nested element body.
+echo desugar('<>Fish & chips — £5
'), "\n"; +?> +--EXPECT-- +new \Html\Element('div', ['class' => 'box', 'id' => $id], ['Hello ', $name]) +new \Html\Fragment([\Html\render_component(Card::class, ['title' => 'Hi', ...$attrs], new \Html\Fragment([new \Html\Element('b', [], ['f']), 'body']))]) +\Html\render_component(Author::class . '::byline', ['name' => 'Ada'], null) +\Html\render_component(Auth::class, [], new \Html\LazyFragment(fn() => new \Html\Fragment(['Hello ', $name]))) +\Html\render_dynamic($tag, ['class' => 'x'], [$content]) +new \Html\Element('p', [], ['Fish & chips — £5']) diff --git a/features/22-native-markup/tests/syntax_mismatch.phpt b/features/22-native-markup/tests/syntax_mismatch.phpt new file mode 100644 index 0000000..a11b3e3 --- /dev/null +++ b/features/22-native-markup/tests/syntax_mismatch.phpt @@ -0,0 +1,10 @@ +--TEST-- +Markup syntax: a mismatched closing tag is a compile error +--EXTENSIONS-- +html +--FILE-- +oops; +?> +--EXPECTF-- +Fatal error: Mismatched markup closing tag: expected