CakeDC Blog

TIPS, INSIGHTS AND THE LATEST FROM THE EXPERTS BEHIND CAKEPHP

Building Dynamic Web Applications with CakePHP and HTMX: A Practical Guide

Written by Yevgeny on December 02, 2024
3578 VIEWS

This article is part of the CakeDC Advent Calendar 2024 (December 2th 2024)

Other Articles in the Series

This article explores how to integrate htmx with CakePHP to create more dynamic and interactive web applications while writing less JavaScript code. We'll cover the basics of htmx, its setup with CakePHP, and practical examples to demonstrate its power.

Introduction to htmx library

htmx is a modern JavaScript library that allows you to access AJAX, CSS Transitions, WebSockets, and Server Sent Events directly in HTML, using attributes. It's designed to be simple, powerful, and a natural extension of HTML's existing capabilities.

The library's main purpose is to allow you to build modern user interfaces with the simplicity of HTML, reducing the need for complex JavaScript. Instead of writing JavaScript to handle frontend interactions, you can use HTML attributes to define dynamic behaviors.

htmx works by intercepting HTML events (like clicks or form submissions), making HTTP requests in the background, and updating the DOM with the response. This approach, often called "hypermedia-driven applications," allows for rich interactivity while maintaining the simplicity of the web's original architecture.

Basic setup with CakePHP

To get started with htmx in your CakePHP application, follow these steps:

  1. Install the CakePHP htmx plugin using Composer:

    composer require zunnu/cake-htmx

  2. Load the htmx JavaScript library in your layout file (templates/layout/default.php):

    <?= $this->Html->script('https://unpkg.com/[email protected]') ?>

  3. Load the plugin in your application (Application.php):

    public function bootstrap(): void
{
// ... other plugins
$this->addPlugin('CakeHtmx');
}

Boost your CakePHP application with htmx

One of the simplest yet powerful features of htmx is the hx-boost attribute. By adding this attribute to any container element (often the <body> tag), you can automatically enhance all anchor tags and forms within that container to use AJAX instead of full page loads.

Basic Implementation

Add the hx-boost attribute to your layout file (templates/layout/default.php):

<body hx-boost="true">
    <?= $this->Flash->render() ?>
    <?= $this->fetch('content') ?>
</body>

With this single attribute, all links and forms in your application will automatically use AJAX requests instead of full page loads. The content will be smoothly updated without refreshing the page, while maintaining browser history and back/forward button functionality.

How it Works

When hx-boost is enabled:

  1. Clicks on links (<a> tags) are intercepted
  2. Form submissions are captured
  3. Instead of a full page load, htmx makes an AJAX request
  4. The response's <body> content replaces the current page's <body>
  5. The URL is updated using the History API
  6. Browser history and navigation work as expected

Practical Example

Here's a typical CakePHP navigation setup enhanced with hx-boost:

<!-- templates/layout/default.php -->
<!DOCTYPE html>
<html>
<head>
    <title><?= $this->fetch('title') ?></title>
    <?= $this->Html->script('https://unpkg.com/[email protected]') ?>
</head>
<body hx-boost="true">
    <nav>
        <?= $this->Html->link('Home', ['controller' => 'Pages', 'action' => 'display', 'home']) ?>
        <?= $this->Html->link('Posts', ['controller' => 'Posts', 'action' => 'index']) ?>
        <?= $this->Html->link('About', ['controller' => 'Pages', 'action' => 'display', 'about']) ?>
    </nav>

    <main>
        <?= $this->Flash->render() ?>
        <?= $this->fetch('content') ?>
    </main>
</body>
</html>

Selective Boosting

You can also apply hx-boost to specific sections of your page:

<!-- Only boost the post list -->
<div class="post-section" hx-boost="true">
    <?php foreach ($posts as $post): ?>
        <?= $this->Html->link(
            $post->title,
            ['action' => 'view', $post->id],
            ['class' => 'post-link']
        ) ?>
    <?php endforeach; ?>
</div>

<!-- Regular links outside won't be boosted -->
<div class="external-links">
    <a href="https://example.com">External Link</a>
</div>

Excluding Elements

You can exclude specific elements from being boosted using hx-boost="false":

<body hx-boost="true">
    <!-- This link will use AJAX -->
    <?= $this->Html->link('Profile', ['controller' => 'Users', 'action' => 'profile']) ?>

    <!-- This link will perform a full page load -->
    <a href="/logout" hx-boost="false">Logout</a>
</body>

The hx-boost attribute provides a simple way to enhance your CakePHP application's performance and user experience with minimal code changes. It's particularly useful for:

  • Navigation between pages
  • Form submissions
  • Search results
  • Pagination
  • Any interaction that traditionally requires a full page reload

By using hx-boost, you get the benefits of single-page application-like behavior while maintaining the simplicity and reliability of traditional server-rendered applications.

Going deeper with htmx with custom attributes

First, let's see how we can transform a traditional CakePHP index page to use htmx.

Index page example

Here's a traditional index page without htmx, showing a list of posts:

// PostsController.php
public function index()
{
    $query = $this->Posts->find();
    $posts = $this->paginate($query, ['limit' => 12]);
    $this->set(compact('posts'));
}
<!-- templates/Posts/index.php -->
<div class="posts index content">
    <div class="table-responsive">
        <table>
            <thead>
                <tr>
                    <th><?= $this->Paginator->sort('id') ?></th>
                    <?php // .... ?>
                </tr>
            </thead>
            <tbody>
                <?php foreach ($posts as $post): ?>
                    <?php // .... ?>
                <?php endforeach; ?>
            </tbody>
        </table>
    </div>
    <div class="paginator">
        <ul class="pagination">
            <?php // .... ?>
        </ul>
    </div>
</div>

Index page example with htmx

Now, let's enhance the same page with htmx to handle pagination and sorting without page reloads:

// PostsController.php
public function index()
{
    $query = $this->Posts->find();
    $posts = $this->paginate($query, ['limit' => 12]);
    $this->set(compact('posts'));
    if($this->getRequest()->is('htmx')) {
        $this->viewBuilder()->disableAutoLayout();
        $this->Htmx->setBlock('posts');
    }
}

<!-- templates/Posts/index.php -->
<div id="posts" class="posts index content">
<?php $this->start('posts'); ?>
    <div class="table-container">
        <div id="table-loading" class="htmx-indicator">
            <div class="spinner"></div>
        </div>
        <div class="table-responsive">
            <table>
                <thead
                    hx-boost="true"
                    hx-target="#posts"
                    hx-indicator="#table-loading"
                    hx-push-url="true"
                >
                    <tr>
                        <th><?= $this->Paginator->sort('id') ?></th>
                        <?php // .... ?>
                    </tr>
                </thead>
                <tbody>
                    <?php foreach ($posts as $post): ?>
                        <?php // .... ?>
                    <?php endforeach; ?>
                </tbody>
            </table>
        </div>
        <div class="paginator"
            hx-boost="true"
            hx-target="#posts"
            hx-indicator="#table-loading"
            hx-push-url="true"
        >
            <ul class="pagination">
                <?php // .... ?>
            </ul>
        </div>
    </div>
<?php $this->end(); ?>
</div>
<?= $this->fetch('posts'); ?>

Now let's look at the changes we made to the controller and the HTML structure.

Controller Changes

In the controller, we've added htmx-specific handling. When a request comes from htmx, we:

  1. Disable the layout since we only want to return the table content
  2. Use the Htmx helper to set a specific block that will be updated
  3. Maintain the same pagination logic, making it work seamlessly with both regular and htmx requests

Out-of-Band (OOB) Swaps with htmx

htmx supports Out-of-Band (OOB) Swaps, which allow you to update multiple elements on a page in a single request. This is particularly useful when you need to update content in different parts of your page simultaneously, such as updating a list of items while also refreshing a counter or status message.

How OOB Works

  1. In your response HTML, include elements with hx-swap-oob="true" attribute
  2. These elements will update their counterparts on the page based on matching IDs
  3. The main response content updates normally, while OOB content updates independently

HTML Structure Changes

The main changes to the HTML structure include:

  1. Adding an outer container with a specific ID (posts) for targeting updates
  2. Wrapping the content in a block using $this->start('posts') and $this->end() to allow for OOB swaps
  3. Adding a loading indicator element
  4. Implementing htmx attributes on the table header and paginator sections

HTMX Attributes Explained

The following htmx attributes were added to enable dynamic behavior:

  • hx-boost="true": Converts regular links into AJAX requests
  • hx-target="#posts": Specifies where to update content (the posts container)
  • hx-indicator="#table-loading": Shows/hides the loading spinner
  • hx-push-url="true": Updates the browser URL for proper history support

These attributes work together to create a smooth, dynamic experience while maintaining proper browser history and navigation.

Loading Indicator Implementation

The loading indicator provides visual feedback during AJAX requests:

  1. A centered spinner appears over the table during loading
  2. The table content is dimmed using CSS opacity
  3. The indicator is hidden by default and only shows during htmx requests
  4. CSS transitions provide smooth visual feedback
.table-container {
    position: relative;
    min-height: 200px;
}

.htmx-indicator {
    display: none;
    position: absolute;
    top: 50%;
    left: 50%;
    transform: translate(-50%, -50%);
    z-index: 100;
}

.htmx-indicator.htmx-request {
    display: block;
}

.htmx-indicator.htmx-request ~ .table-responsive,
.htmx-indicator.htmx-request ~ .paginator {
    opacity: 0.3;
    pointer-events: none;
    transition: opacity 0.2s ease;
}

.spinner {
    width: 40px;
    height: 40px;
    border: 4px solid #f3f3f3;
    border-top: 4px solid #3498db;
    border-radius: 50%;
    animation: spin 1s linear infinite;
}

@keyframes spin {
    0% { transform: rotate(0deg); }
    100% { transform: rotate(360deg); }
}

Problems with current htmx implementation and boost implementation

Browser History and Back Button Issues

When using htmx with hx-boost or AJAX requests, you might encounter issues with the browser's back button showing partial content. This happens because:

  1. htmx requests only return partial HTML content
  2. The browser's history stack stores this partial content
  3. When users click the back button, the partial content is displayed instead of the full page

Preventing Cache Issues in Controllers

To disable htmx caching by browsers, you can add the following headers to your response in your controller:

    if ($this->request->is('htmx') || $this->request->is('boosted')) {
        $this->response = $this->response
            ->withHeader('Cache-Control', 'no-store, no-cache, must-revalidate')
            ->withHeader('Pragma', 'no-cache')
            ->withHeader('Expires', '0');

    }

General Solution

Prevent caching issues with htmx requests by creating a middleware:

// src/Middleware/HtmxMiddleware.php
public function process(ServerRequest $request, RequestHandler $handler): Response
{
    $response = $handler->handle($request);

    if ($request->is('htmx')) {
        return $response
            ->withHeader('Cache-Control', 'no-store, no-cache, must-revalidate, max-age=0')
            ->withHeader('Pragma', 'no-cache')
            ->withHeader('Expires', '0');
    }

    return $response;
}

Conclusion

htmx is a powerful library that can significantly enhance the interactivity and user experience of your CakePHP applications. By using htmx attributes, you can create dynamic, responsive, and efficient web applications with minimal JavaScript code.

Demo Project for Article

The examples used in this article are located at https://github.com/skie/cakephp-htmx/tree/1.0.0 and available for testing.

This article is part of the CakeDC Advent Calendar 2024 (December 2th 2024)

Latest articles

146 Views

Goodbye to 2025!

Well bakers… another advent calendar is coming to an end. I hope you enjoyed all of the topics covered each day. We are also closing the year with so much gratitude.    2025 was the 20th year of CakePHP, can you believe it? We had an amazing year with our team, the community and the CakePHP core. It was great connecting with those who attended CakeFest in Madrid, and we hope to have the opportunity to see more of you in 2026.    I cannot let the year end without getting a little sentimental. There is no better way to say it… THANK YOU. Thank you to the team who worked so hard, the core team that keeps pumping out releases, and most of all … thank you to our clients that trust us with their projects. CakeDC is successful because of the strong relationships we build with our network, and we hope to continue working with all of you for many years.    There are a lot of great things still to come in year 21! Could 2026 will be bringing us CakePHP 6?! Considering 21 is the legal drinking age in the US, maybe CakePHP 6 should be beer cake? Delicious. Stay tuned to find out.    Before I go, I am leaving you with something special. A note from Larry!   As we close out this year, I just want to say thank you from the bottom of my heart. Twenty years ago, CakePHP started as a simple idea shared by a few of us who wanted to make building on the web easier and more enjoyable. Seeing how far it has come, and more importantly, seeing how many lives and careers it has impacted, is something I never take for granted. I am deeply grateful for our team, the core contributors, the community, and our clients who continue to believe in what we do. You are the reason CakePHP and CakeDC are still here, still growing, and still relevant after two decades. Here is to what we have built together, and to what is still ahead. Thank you for being part of this journey. Larry

Written by Amanda on December 24, 2025

175 Views

Pagination of multiple queries in CakePHP

Pagination of multiple queries in CakePHP

A less typical use case for pagination in an appication is the need to paginate multiples queries. In CakePHP you can achieve this with pagination scopes.

Users list

Lest use as an example a simple users list. // src/Controller/UsersController.php class UsersController extends AppController { protected array $paginate = [ 'limit' => 25, ]; public function index() { // Default model pagination $this->set('users', $this->paginate($this->Users)); } } // templates/Users/index.php <h2><?= __('Users list') ?>/h2> <table> <thead> <tr> <th><?= $this->Paginator->sort('name', __('Name')) ?></th> <th><?= $this->Paginator->sort('email', __('Email')) ?></th> <th><?= $this->Paginator->sort('active', __('Active')) ?></th> </tr> </thead> <tbody> <?php foreach ($users as $user): ?> <tr> <td><?= h($user->name) ?></td> <td><?= h($user->email) ?></td> <td><?= $user->active ? 'Yes' : 'No' ?></td> </tr> <?php endforeach; ?> </tbody> </table> <?= $this->Paginator->counter() ?> <?= $this->Paginator->prev('« Previous') ?> <?= $this->Paginator->numbers() ?> <?= $this->Paginator->next('Next »') ?>

Pagination of multiple queries

Now, we want to display two paginated tables, one with the active users and the other with the inactive ones. // src/Controller/UsersController.php class UsersController extends AppController { protected array $paginate = [ 'Users' => [ 'scope' => 'active_users', 'limit' => 25, ], 'InactiveUsers' => [ 'scope' => 'inactive_users', 'limit' => 10, ], ]; public function index() { $activeUsers = $this->paginate( $this->Users->find()->where(['active' => true]), [scope: 'active_users'] ); // Load an additional table object with the custom alias set in the paginate property $inactiveUsersTable = $this->fetchTable('InactiveUsers', [ 'className' => \App\Model\Table\UsersTable::class, 'table' => 'users', 'entityClass' => 'App\Model\Entity\User', ]); $inactiveUsers = $this->paginate( $inactiveUsersTable->find()->where(['active' => false]), [scope: 'inactive_users'] ); $this->set(compact('users', 'inactiveUsers')); } } // templates/Users/index.php <?php // call `setPaginated` first with the results to be displayed next, so the paginator use the correct scope for the links $this->Paginator->setPaginated($users); ?> <h2><?= __('Active Users') ?>/h2> <table> <thead> <tr> <th><?= $this->Paginator->sort('name', __('Name')) ?></th> <th><?= $this->Paginator->sort('email', __('Email')) ?></th> <th><?= $this->Paginator->sort('active', __('Active')) ?></th> </tr> </thead> <tbody> <?php foreach ($users as $user): ?> <tr> <td><?= h($user->name) ?></td> <td><?= h($user->email) ?></td> <td><?= $user->active ? 'Yes' : 'No' ?></td> </tr> <?php endforeach; ?> </tbody> </table> <?= $this->Paginator->counter() ?> <?= $this->Paginator->prev('« Previous') ?> <?= $this->Paginator->numbers() ?> <?= $this->Paginator->next('Next »') ?> <?php // call `setPaginated` first with the results to be displayed next, so the paginator use the correct scope for the links $this->Paginator->setPaginated($inactiveUsers); ?> <h2><?= __('Inactive Users') ?>/h2> <table> <thead> <tr> <th><?= $this->Paginator->sort('name', __('Name')) ?></th> <th><?= $this->Paginator->sort('email', __('Email')) ?></th> <th><?= $this->Paginator->sort('active', __('Active')) ?></th> </tr> </thead> <tbody> <?php foreach ($inactiveUsers as $inactiveUser): ?> <tr> <td><?= h($inactiveUser->name) ?></td> <td><?= h($inactiveUser->email) ?></td> <td><?= $inactiveUser->active ? 'Yes' : 'No' ?></td> </tr> <?php endforeach; ?> </tbody> </table> <?= $this->Paginator->counter() ?> <?= $this->Paginator->prev('« Previous') ?> <?= $this->Paginator->numbers() ?> <?= $this->Paginator->next('Next »') ?> And with this you have two paginated tables in the same request.

Written by Rperez on December 23, 2025

302 Views

Clean DI in CakePHP 5.3: Say Goodbye to fetchTable()

This article is part of the CakeDC Advent Calendar 2025 (December 23rd, 2025)

Introduction: The Death of the "Hidden" Dependency

For years, accessing data in CakePHP meant "grabbing" it from the global state. Whether using TableRegistry::getTableLocator()->get() or the LocatorAwareTrait’s $this->fetchTable(), your classes reached out to a locator to find what they needed. While convenient, this created hidden dependencies. A class constructor might look empty, despite the class being secretly reliant on multiple database tables. This made unit testing cumbersome, forcing you to stub the global TableLocator just to inject a mock. CakePHP 5.3 changes the game with Inversion of Control. With the framework currently in its Release Candidate (RC) stage and a stable release expected soon, now is the perfect time to explore these architectural improvements. By using the new TableContainer as a delegate for your PSR-11 container, tables can now be automatically injected directly into your constructors. This shift to explicit dependencies makes your code cleaner, fully type-hinted, and ready for modern testing standards. The Old Way (Hidden Dependency): public function execute() { $users = $this->fetchTable('Users'); // Where did this come from? } The 5.3 Way (Explicit Dependency): public function __construct(protected UsersTable $users) {} public function execute() { $this->users->find(); // Explicit and testable. }

Enabling the Delegate

Open src/Application.php and update the services() method by delegating table resolution to the TableContainer. // src/Application.php use Cake\ORM\TableContainer; public function services(ContainerInterface $container): void { // Register the TableContainer as a delegate $container->delegate(new TableContainer()); }

How it works under the hood

When you type-hint a class ending in Table (e.g., UsersTable), the main PSR-11 container doesn't initially know how to instantiate it. Because you've registered a delegate, it passes the request to the TableContainer, which then:
  1. Validates: It verifies the class name and ensures it is a subclass of \Cake\ORM\Table.
  2. Locates: It uses the TableLocator to fetch the correct instance (handling all the usual CakePHP ORM configuration behind the scenes).
  3. Resolves: It returns the fully configured Table object back to the main container to be injected.
Note: The naming convention is strict. The TableContainer specifically looks for the Table suffix. If you have a custom class that extends the base Table class but is named UsersRepository, the delegate will skip it, and the container will fail to resolve the dependency.

Practical Example: Cleaner Services

Now, your domain services no longer need to know about the LocatorAwareTrait. They simply ask for what they need. namespace App\Service; use App\Model\Table\UsersTable; class UserManagerService { // No more TableRegistry::get() or $this->fetchTable() public function __construct( protected UsersTable $users ) {} public function activateUser(int $id): void { $user = $this->users->get($id); // ... logic } } Next, open src/Application.php and update the services() method by delegating table resolution to the TableContainer. // src/Application.php use App\Model\Table\UsersTable; use App\Service\UserManagerService; use Cake\ORM\TableContainer; public function services(ContainerInterface $container): void { // Register the TableContainer as a delegate $container->delegate(new TableContainer()); // Register your service with the table as constructor argument $container ->add(UserManagerService::class) ->addArgument(UsersTable::class); }

Why this is a game changer for Testing

Because the table is injected via the constructor, you can now swap it for a mock effortlessly in your test suite without touching the global state of the application. $mockUsers = $this->createMock(UsersTable::class); $service = new UserManagerService($mockUsers); // Pure injection!

Conclusion: Small Change, Big Impact

At first glance, adding a single line to your Application::services() method might seem like a minor update. However, TableContainer represents a significant shift in how we approach CakePHP architecture. By delegating table resolution to the container, we gain:
  • True Type-Safety: Your IDE and static analysis tools now recognize the exact Table class being used. This is a massive win for PHPStan users—no more "Call to an undefined method" errors or messy @var docblock workarounds just to prove to your CI that a method exists.
  • Zero-Effort Mocking: Testing a service no longer requires manipulating the global TableRegistry state. Simply pass a mock object into the constructor and move on.
  • Standardization: Your CakePHP code now aligns with modern PHP practices found in any PSR-compliant ecosystem, making your application more maintainable and easier for new developers to understand.
If you plan to upgrade to CakePHP 5.3 upon its release, this is one of the easiest wins for your codebase. It’s time to stop fetching your tables and start receiving them. This article is part of the CakeDC Advent Calendar 2025 (December 23rd, 2025)

Written by Arusinowski on December 23, 2025

We Bake with CakePHP