feat: Error handler for HTMX

[neznaika0]

@michalsn Is it possible to add a handler for all HTMX exceptions?

Reason

For example, we make HTMX requests from the page and replace part of the content with body > content > htmx data. Everything is working fine.

When status code 400-500, we get nothing in Response. Yes, there is a built-in debugger in the modal window, but this is not the best option. I would like the error to be configurable.

Decision

We create a new HTMXExceptionHandler, check the Request::isHtmx() and show a custom error page. Right now I don't see the full picture of what this will affect, so I'm writing here. Personally, I would like to show a small "toast" notification when an error occurs. This will make it much easier to understand that the request failed.

Alternatively, you can show the full error page from the default handler, or the full page if the response is not going to be used as a "swap-oob", "toast" notification.

Example
To get a response 400-500 in HTMX, we need to fix the configuration (or send 200 ?).

<?php

declare(strict_types=1);

namespace Neznaika0\ErrorHandlers;

use CodeIgniter\Debug\BaseExceptionHandler;
use CodeIgniter\Debug\ExceptionHandler;
use CodeIgniter\Debug\ExceptionHandlerInterface;
use CodeIgniter\HTTP\CLIRequest;
use CodeIgniter\HTTP\RequestInterface;
use CodeIgniter\HTTP\ResponseInterface;
use Michalsn\CodeIgniterHtmx\HTTP\IncomingRequest;
use Michalsn\CodeIgniterHtmx\HTTP\Response;
use Throwable;

class HTMXExceptionHandler extends BaseExceptionHandler implements ExceptionHandlerInterface
{
    /**
     * {@inheritDoc}
     *
     * @param CLIRequest|IncomingRequest $request
     * @param Response|ResponseInterface $response
     */
    public function handle(
        Throwable $exception,
        RequestInterface $request,
        ResponseInterface $response,
        int $statusCode,
        int $exitCode,
    ): void {
        // Backward compatibility with regular Requests 
        if (! $request->isHtmx()) {
            $defaultHandler = new ExceptionHandler($this->config);
            $defaultHandler->handle($exception, $request, $response, $statusCode, $exitCode);

            return;
        }

        $response->setStatusCode($statusCode);

        $viewAppFile  = APPPATH . 'Views/errors/html/error_htmx.php';
       // Default view if not exist in /app/
        $viewMainFile = __DIR__ . '../Views/errors/html/error_htmx.php';

        $viewFile = is_file($viewAppFile) ? $viewAppFile : $viewMainFile;

        // Send real status code "400-500" instead "200"
        $response->sendHeaders();
        $this->render($exception, $statusCode, $viewFile);

        // Copied from original
        if (ENVIRONMENT !== 'testing') {
            // @codeCoverageIgnoreStart
            exit($exitCode);
            // @codeCoverageIgnoreEnd
        }
    }
}

    // app/Config/Exceptions.php
    public function handler(int $statusCode, Throwable $exception): ExceptionHandlerInterface
    {
        return new HTMXExceptionHandler($this);
        // return new ExceptionHandler($this);
    }

// app/Views/errors/html/error_htmx.php
<div class="htmx-exception">
    <h1><?= $code ?></h1>
    <p>
        <?php if (ENVIRONMENT !== 'production') : ?>
            <?= nl2br(esc($message)) ?>
        <?php else: ?>
            Ooops!
        <?php endif; ?>
    </p>
</div>

// JS code
document.addEventListener('htmx:beforeSwap', function (e) {
    if (e.detail.xhr.status >= 400) {
        e.detail.shouldSwap = true;
        e.detail.isError = false;
    }
});

Others

Does such a decision make sense, will it bring benefits?

There are a few thoughts for the tests:

• HTMX request with partial replacement (in content, sidebar, toasts)
• HTMX request with an error page opening (for example, redirection after the form)
• The error page must have a full version with and a partial version with fragments to replace.
• Common exceptions should be handled by the standard handler

[neznaika0]

Heh,

If you write the problem down clearly, then the matter is half solved.

I will try to use ready-made templates. I've made it so complicated 😄 . But if it doesn't work out, then my suggestion remains

[neznaika0]

I created

// app/Views/errors/html/error_htmx.php
<?php

use Michalsn\CodeIgniterHtmx\HTTP\IncomingRequest;
use Michalsn\CodeIgniterHtmx\HTTP\Response;

/** @var IncomingRequest */
$request = service('request');

if ($request->isHtmx() && ! $request->isHistoryRestoreRequest()) {
    /** @var Response */
    $response = service('response');
    $errorMessage = (ENVIRONMENT !== 'production') ? nl2br(esc($message)) : lang('Errors.sorryBadRequest');

    $response
        ->setReplaceUrl(null)
        ->setPushUrl(null)
        ->setRetarget('#toasts')
        ->setReswap('beforeend')
        ->setBody(
            <<<"TEXT"
                <div id="htmx-exception">
                    {$code} {$message}
                </div>
            TEXT
        )
        ->send();

    exit(EXIT_ERROR);
}

// and added app/Views/errors/html/error_400.php
<?php require __DIR__ . '/error_htmx.php'; ?>
<!DOCTYPE html>
<html lang="en">
...

// now i get messages in HTML and other HTMX request work
<div id="toasts" class="toasts-container">    <div id="htmx-exception">
        400 The URI you submitted has disallowed characters: "odit-et:%$"
    </div>
   <div id="htmx-exception">
        400 The URI you submitted has disallowed characters: "odit-et:%$"
    </div></div>

[michalsn]

The package's error handling is a development helper, not a production UX layer. In production, HTMX error handling is application-specific: some apps want a toast, others want an inline fragment, a swap-oob update, or a full-page fallback for boosted requests.

That's why I don't want to add a built-in global HTMX exception handler. There's no version of it that works generally without getting too opinionated or breaking cases that need different behavior.

What I think would actually help is a documentation recipe for custom HTMX exception handling - something people can adapt rather than something the package imposes.

[neznaika0]

Thanks for the reply.
Look, as always, you can do this as a selective option: if necessary, use it; if not, work by default. Do you have an opinion on how this can be improved (without replacing the handler)?

Regarding the guide, I'm always in favor if someone explains how to work with it. As you can see, I did not immediately pay attention to the default handler. I will try to allocate this to a personal library for reuse.

And I want to warn you that HTMX 4 is already approaching, and there will be BC in it.