PHPackages                             trk/processwire-htmx - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. trk/processwire-htmx

ActivePw-module

trk/processwire-htmx
====================

State-Aware HTMX 2.x Module offering an elegant Request/Response API natively for ProcessWire.

v1.0.6(1mo ago)40MITJavaScriptPHP >=8.1CI passing

Since Mar 30Pushed 1mo ago1 watchersCompare

[ Source](https://github.com/trk/Htmx)[ Packagist](https://packagist.org/packages/trk/processwire-htmx)[ Docs](https://github.com/trk/Htmx)[ Patreon](https://www.patreon.com/ukyo)[ RSS](/packages/trk-processwire-htmx/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)DependenciesVersions (8)Used By (0)

ProcessWire HTMX Module
=======================

[](#processwire-htmx-module)

[![ProcessWire](https://camo.githubusercontent.com/34449e2237c61f5c40a0cbf06273d9f22ee4b9ba45442c77b6554c874927b1ea/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f50726f63657373576972652d332e782d6f72616e67652e737667)](https://camo.githubusercontent.com/34449e2237c61f5c40a0cbf06273d9f22ee4b9ba45442c77b6554c874927b1ea/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f50726f63657373576972652d332e782d6f72616e67652e737667)[![HTMX](https://camo.githubusercontent.com/4cd539801e7d76a22830071f7185169d5eadc4b3aaceeea60d5008a0ad2ee5c4/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f48544d582d322e782d626c75652e737667)](https://camo.githubusercontent.com/4cd539801e7d76a22830071f7185169d5eadc4b3aaceeea60d5008a0ad2ee5c4/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f48544d582d322e782d626c75652e737667)[![Status](https://camo.githubusercontent.com/bca963f487cdc6830ef86660ada348593e0261edbf67440c47cca0cc418d25a3/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5374617475732d50726f64756374696f6e25323052656164792d737563636573732e737667)](https://camo.githubusercontent.com/bca963f487cdc6830ef86660ada348593e0261edbf67440c47cca0cc418d25a3/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5374617475732d50726f64756374696f6e25323052656164792d737563636573732e737667)[![Security](https://camo.githubusercontent.com/5dbcd384ba719e561d966a2803ac53f60ad22aca066c456057c9f2b8c923b77d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f53656375726974792d484d41432d2d5348413235362d637269746963616c2e737667)](https://camo.githubusercontent.com/5dbcd384ba719e561d966a2803ac53f60ad22aca066c456057c9f2b8c923b77d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f53656375726974792d484d41432d2d5348413235362d637269746963616c2e737667)

A powerful HTMX integration module designed specifically for ProcessWire. It bridges the gap between client-side reactivity and server-side authority, enabling you to build SPA-like interactions without abandoning traditional PHP rendering.

By unifying **State-Aware Components**, **HMAC-SHA256 Payload Security**, and ProcessWire's native architecture, this module provides the ultimate Developer Experience (DX) inspired by frameworks like Livewire—exclusively for ProcessWire.

---

🏗 Executive Overview
--------------------

[](#-executive-overview)

- **Natively Bundled:** Supplies HTMX 2.x, WebSockets (`ws.js`), Server-Sent Events (`sse.js`), along with key extensions and `_hyperscript`, completely zero-dependency.
- **State-Aware Component Architecture:** Seamless data hydration and dehydration between requests.
- **Object Synthesis:** Magically serialize full ProcessWire objects (like `Page`) down to lightweight secure IDs, restoring them effortlessly on the next request.
- **Cryptographic Security:** End-to-end state manipulation protection with built-in HMAC-SHA256 signatures and TTL-based Replay Protection.
- **Fluent Request/Response API:** Intercept, retarget, flash messages, and trigger custom JS events directly from ProcessWire controllers.

---

⚙️ Installation
---------------

[](#️-installation)

**Via Composer (Recommended):**

```
composer require trk/processwire-htmx
```

**Via Manual Download:**

1. Clone or extract into `site/modules/Htmx/`.
2. In the ProcessWire Admin, log in and navigate to **Modules > Refresh**.
3. Install **HTMX**.

---

🧠 Core Architecture: Component Lifecycle
----------------------------------------

[](#-core-architecture-component-lifecycle)

The true power of this module lies in the `Component` class. It shifts PHP from a "fire-and-forget" mentality to a persistent, stateful application logic container.

 ```
sequenceDiagram
    participant Browser
    participant Htmx as HTMX Module
    participant Component as Component Instance
    participant DB as ProcessWire API

    Browser->>Htmx: Initial Page Load (GET)
    Htmx->>Component: mount() & fill()
    Component->>Browser: Render UI + Encrypted __state Payload

    Note over Browser, Component: User interacts (e.g. Clicks Button)

    Browser->>Htmx: HX-Request (POST) + __state
    Htmx->>Component: hydrate(__state)
    Component->>DB: Object Synthesis (Fetch Pages by ID)
    Htmx->>Component: executeAction('like')
    Component->>Browser: Re-render UI + New Encrypted __state
```

      Loading ---

🪄 Zero-Configuration Auto-Discovery
-----------------------------------

[](#-zero-configuration-auto-discovery)

To make the developer experience as seamless as possible, the HTMX module includes automatic namespace registration for your components and UI elements.

By default, if the following directories exist in your ProcessWire installation, they are automatically registered with the native `ClassLoader`:

- **`site/components/`** maps to the **`Htmx\Component`** namespace.
- **`site/ui/`** maps to the **`Htmx\Ui`** namespace.

*Note: These directory paths are fully customizable (e.g. `my-components/`) via the Module Configuration screen.*

By default, the module securely sandboxes all component rendering strictly within these explicitly defined directories and the native `templates/` folder. This is configurable via the **Allow Component Paths** module setting, balancing optimal Developer Experience (DX) with security.

This means you can place your component class files directly in `site/components/` and simply declare the `namespace Htmx\Component;`, and the module will instantly know how to load and render them during stateless POST requests without requiring custom auto-loaders or `require_once` statements.

---

🚀 Quick Start: Building a Stateful Component
--------------------------------------------

[](#-quick-start-building-a-stateful-component)

Let's build a Livewire-style "Like" button that remembers its state, seamlessly tied to a specific ProcessWire Page. We'll utilize the auto-discovery feature by placing our component in `site/components/LikeButton.php`.

### 1. Create Your Component (`site/components/LikeButton.php`)

[](#1-create-your-component-sitecomponentslikebuttonphp)

```
namespace Htmx\Component;

use Totoglu\Htmx\Component;

class LikeButton extends Component {

    // ProcessWire Objects are automatically synthesized!
    public Page $post;

    // Public properties are securely preserved across requests
    public int $likes = 0;

    /**
     * Optional: Hook executed upon initialization
     */
    public function mount() {
        if ($this->likes === 0) {
            $this->likes = $this->post->num_likes ?? 0;
        }
    }

    /**
     * Action triggered from the frontend.
     * Dependencies (like $session) are Auto-Injected!
     */
    public function like(int $step = 1, Session $session) {
        $this->likes += $step;

        // Let's also save to the DB...
        $this->post->of(false);
        $this->post->num_likes = $this->likes;
        $this->post->save('num_likes');

        $session->message("You liked {$this->post->title}!");
    }
}
```

### 2. The Component View (`components/like-button.php`)

[](#2-the-component-view-componentslike-buttonphp)

Build the markup. You have full access to `$this` (the component context).

```