Download the PHP package giantbits/yii2-htmx without Composer

yii2-htmx

HTMX-powered component framework for Yii2. Build interactive UIs with server-rendered components — no JavaScript framework, no build tools.

Each component is a self-contained class + template pair that automatically gets an HTMX endpoint. User interactions trigger server-side actions, and HTMX swaps the fresh HTML into the DOM. The developer experience is similar to React/Vue but everything runs server-side.

Installation

The package auto-bootstraps via Yii2's extension system — no manual configuration needed. It registers:

• A htmx-component/render controller route (universal endpoint for all component requests)
• HTMX loaded from CDN

For Twig template support (recommended):

And configure the renderer in your app config:

Quick Example

A component is two files side by side:

Counter.php

Counter.view.twig

Use it anywhere:

Or in Twig:

Click the buttons — the counter updates without a page reload. No JavaScript written.

How It Works

Every component instance gets a unique signed URL. The HMAC signature (using your app's cookieValidationKey) prevents tampering with class names, props, or actions.

Creating Components

The Component Class

Extend HtmxComponent and override what you need:

The Template

Templates receive the component instance as component. Use the HTMX helpers to wire up interactions:

Twig (.view.twig):

PHP (.view.php) — also supported:

The base class prefers .view.twig and falls back to .view.php.

Props

Props are passed from parent to child and serialized into the endpoint token. Use them as lightweight identifiers — not full data objects.

The component resolves the actual data in resolveState():

This keeps tokens small and data always fresh.

HTMX Helpers

These generate the full set of HTMX attributes in one call — no manual URL or target wiring:

Override or add attributes with the second argument:

In Twig, always pipe through | raw since the output is pre-escaped HTML attributes.

Cross-Component Communication

Components communicate through HTMX events — decoupled, like a pub/sub system.

Publisher — emits an event after an action:

Subscriber — listens and auto-refreshes:

When the publisher's action completes, the HX-Trigger response header fires jobListChanged, and any element with hx-trigger="jobListChanged from:body" automatically re-fetches itself.

You can also emit multiple events:

Action Utilities

Use these inside action*() methods:

Component Properties

Configuration

Set these in Yii::$app->params:

PJAX Migration

If you're migrating from Yii2's built-in Pjax, the mapping is straightforward:

Key advantages over Pjax:

• No jQuery dependency
• No custom jquery.pjax.js fixes needed
• Components are self-contained (class + template + actions in one place)
• Fine-grained updates (swap a single item, not an entire container)
• Built-in event system for cross-component communication

Security

Component endpoint URLs contain HMAC-signed tokens. The token encodes the class name, props, and action, signed with your app's cookieValidationKey. This prevents:

• Instantiating arbitrary PHP classes
• Tampering with props
• Calling unregistered actions

Only actions listed in the actions() method can be invoked. The ComponentController verifies signatures before processing any request.

Requirements

• PHP 8.1+
• Yii2 >= 2.0.45
• yiisoft/yii2-twig (optional, for .twig templates)