preflow / htmx

v0.63.2 2026-11-10 23:22 UTC

Requires

• php: >=8.4
• ext-sodium: *
• preflow/components: ^0.1 || @dev
• preflow/core: ^0.1 || @dev

Requires (Dev)

• phpunit/phpunit: ^11.0

MIT

Published on Packagist.org on 2026-11-11 00:52 UTC

README

Hypermedia abstraction and component endpoint for Preflow. Ships an HTMX driver out of the box; the HypermediaDriver interface allows swapping in alternatives (e.g. Datastar).

Installation

composer require preflow/htmx

Requires PHP 8.4+, ext-sodium. Twig integration requires twig/twig ^3.0.

What it does

ComponentToken issues HMAC-SHA256-signed tokens that encode a component class, props, and action name. ComponentEndpoint handles incoming hypermedia requests through five security layers: token verification → class validation → action whitelist → Guarded interface → dispatch. HtmxDriver generates hx-* attributes and sets response headers. The hd Twig global surfaces all of this as template helpers.

API

HtmxDriver

Generates HTML attributes and sets response headers.

// Attributes
$driver->actionAttrs(method: 'post', url: $url, targetId: $id, swap: SwapStrategy::OuterHTML): HtmlAttributes
$driver->listenAttrs(event: 'itemSaved', url: $url, targetId: $id): HtmlAttributes

// Response headers (call from within an action)
$driver->triggerEvent('itemSaved')    // HX-Trigger
$driver->redirect('/dashboard')      // HX-Redirect
$driver->pushUrl('/posts/1')         // HX-Push-Url

ComponentToken

$token->encode(componentClass: Post::class, props: ['id' => 1], action: 'save'): string
$token->decode(tokenString: $str, maxAge: 86400): TokenPayload

Tokens are URL-safe base64 strings. maxAge (seconds) enforces expiry.

ComponentEndpoint

Universal PSR-7 handler. Mount it at e.g. /--component/action and /--component/render.

$endpoint->handle(ServerRequestInterface $request): ResponseInterface

Security layers applied on every request:

1. Token present and base64-decodable
2. HMAC-SHA256 signature valid, optional max-age enforced
3. componentClass is a real subclass of Component
4. action is in $component->actions() (or 'render')
5. If component implements Guarded, authorize(action, request) is called

Guarded interface

Add component-level authorization without middleware.

interface Guarded
{
    public function authorize(string $action, ServerRequestInterface $request): void;
}

Throw ForbiddenHttpException to deny access.

SwapStrategy enum

OuterHTML, InnerHTML, BeforeBegin, AfterBegin, BeforeEnd, AfterEnd, Delete, None

Twig hd global (HdExtension)

Available as hd in all templates once the extension is registered.

{# POST action — renders hx-post, hx-target, hx-swap attributes #}
<button {{ hd.post('increment', 'App\\Counter', componentId, props) }}>+1</button>

{# GET action #}
<div {{ hd.get('load', 'App\\Feed', componentId, {page: 2}) }}></div>

{# Listen for a server-sent event and re-render #}
<div {{ hd.on('itemSaved', 'App\\List', componentId, props) }}></div>

{# HTMX script tag #}
{{ hd.assetTag() }}

Locale prefix

Since 0.46, HtmxExtensionProvider takes an optional pathPrefix closure (\Closure(): string) that is put before every URL it builds (actionUrl, post, get, on). Preflow's core passes the locale prefix of the current request (LocaleMiddleware::urlPrefix()), so on a /de/… page component URLs are /de/--component/… and the action runs in German; the locale middleware strips /de again before the endpoint. Pages without a prefix, and apps without the i18n URL prefix strategy, keep /--component/…. A hand-written hx-post="/--component/…" loses the locale, so use hd.actionUrl(). Only HtmxExtensionProvider (the hd.* helpers in core apps) applies the prefix; the legacy HdExtension does not. Folio's admin preview under /folio carries no locale prefix, so it renders components without it. Error pages are rendered after the pipeline (the kernel catches the exception once the locale middleware has returned), so a component on a 404 or 500 page under /de/… gets an unprefixed /--component/… URL and its action runs in the default locale.

new HtmxExtensionProvider($driver, $token, pathPrefix: fn (): string => $localeMiddleware->urlPrefix());

Usage

Component with an action:

use Preflow\Components\Component;

final class Counter extends Component
{
    public int $count = 0;

    public function resolveState(): void
    {
        $this->count = (int) ($_SESSION['count'] ?? 0);
    }

    public function actions(): array
    {
        return ['increment'];
    }

    public function actionIncrement(array $params): void
    {
        $this->count++;
        $_SESSION['count'] = $this->count;
    }
}

Template (Counter.twig):

<p>Count: {{ count }}</p>
<button {{ hd.post('increment', 'App\\Counter', componentId, props) }}>+1</button>

Guarded component:

use Preflow\Htmx\Guarded;
use Preflow\Core\Exceptions\ForbiddenHttpException;
use Psr\Http\Message\ServerRequestInterface;

final class AdminPanel extends Component implements Guarded
{
    public function actions(): array
    {
        return ['deleteItem'];
    }

    public function authorize(string $action, ServerRequestInterface $request): void
    {
        $user = $request->getAttribute('user');
        if (!$user?->isAdmin()) {
            throw new ForbiddenHttpException('Admins only.');
        }
    }

    public function actionDeleteItem(array $params): void
    {
        // ...
    }
}

Wire up the endpoint:

use Preflow\Htmx\{ComponentEndpoint, ComponentToken, HtmxDriver, ResponseHeaders};

$token    = new ComponentToken(secretKey: $_ENV['APP_KEY']);
$headers  = new ResponseHeaders();
$driver   = new HtmxDriver($headers);
$endpoint = new ComponentEndpoint(
    token: $token,
    renderer: $renderer,
    driver: $driver,
    componentFactory: fn (string $class, array $props) => new $class(),
);

// Route POST /--component/action and GET /--component/render to:
$response = $endpoint->handle($request);

Add asset tag in your base layout:

{{ hd.assetTag() }}

Asset injection in fragment responses

ComponentEndpoint automatically appends any CSS and JS collected during component rendering to HTMX fragment responses. Styles and scripts defined inside a component with {% apply css %} / {% apply js %} are included even when the response is a partial swap — no separate asset pipeline step needed.

Fragment rendering

When the HX-Target header does not match the component's own ID, ComponentEndpoint returns a fragment response via renderFragment() / renderResolvedFragment() rather than the full wrapped component. This lets a single component handle both full-page renders and targeted partial swaps.

ComponentRenderer::renderResolvedFragment() skips resolveState() and renders inner HTML only — used after an action has already mutated state.