Download the PHP package seba1rx/exhaust without Composer

Exhaust

Minimalist PHP framework built around a commands-based response pattern for single-page applications. The primary mode of interaction is a set of typed commands that the frontend engine (engeen.js) interprets and executes. The framework also supports pure API responses for clients that consume JSON directly, without engeen.js.

Core Philosophy

SPA mode — the primary use case:

When the user interacts with the SPA, the frontend sends an asynchronous request (XHR or Fetch) to a PHP controller. The controller builds a response by calling static methods on Commands, which queue up instructions. At the end of the request cycle the framework serialises those instructions as JSON and engeen.js executes them in order (FIFO).

API mode — when the backend is consumed as a plain REST API:

The Commands::apiResponse() method sends a plain JSON object not intended for engeen.js. Use this when the controller serves a mobile app, a third-party client, or any consumer that reads JSON directly without the SPA engine.

Installation

The package does not publish any files automatically — copy the base configuration from vendor/seba1rx/exhaust/stubs/config/ into your app's config/ directory and adjust it to your needs:

Project structure

The package (seba1rx/exhaust) provides the Exhaust\ namespace. Your application code lives in the App\ namespace. Controllers, middlewares and models are app concerns — the package does not define a controller base class.

Routing

Routes are defined in config/routes.php using the Route object.

Route parameters wrapped in {braces} are captured and type-cast automatically (int, float, bool, string).

Controllers

Controllers live in App\Controllers\ and extend your app-level Controller base class (which handles middleware execution). Each action receives the request payload as an associative array and must return Commands::all().

The app-level Controller base constructor handles middlewares:

Commands reference

All methods are static on Exhaust\Response\Commands. Commands accumulate in a static array and are flushed at the end of each request by app()->run().

html — inject HTML into a DOM element

Multiple calls are applied in order. The frontend does document.getElementById(id).innerHTML = content.

script — run arbitrary JavaScript

The snippet is minified automatically before sending.

assignValue — set a JavaScript variable

dialog + dialogBuilder — SweetAlert2 modal

dialogBuilder parameters

toast — SweetAlert2 toast notification

Allowed types: success error info warning question any

Allowed positions: top top-start top-end center center-start center-end bottom bottom-start bottom-end

log — typed browser console output

Sends a colour-coded log entry to the browser console. Overrides the framework's debug_request config for this response.

Allowed types: info error debug warning

console_log — raw console.log

echo — send a full HTML page

Used for navigation requests. The content bypasses the commands engine and is rendered directly as HTML.

apiResponse — plain JSON response (API mode)

Sends a plain JSON object. The response is not processed by engeen.js — it is intended for clients that consume the backend as a REST API (mobile apps, third-party integrations, etc.). Cannot be combined with other commands in the same response.

includeScript / includeCss — inject assets dynamically

Place these before any html or script command that depends on the file.

A complete controller action

The JSON sent to the frontend:

Frontend — engeen.js

The frontend counterpart of the framework. Exposes a global Engeen object with no external dependencies (dialogs and toasts are delegated to a registered driver).

Setup

Sending requests

Request options

fetch() requests must include X-Requested-With: fetch so the backend detects RequestType::Fetch. engeen.js adds this header automatically.

How commands are processed

Engeen.executeCommands(response) iterates the JSON received from the server:

Triggering dialogs and toasts directly from JS

Utilities

Request object

Available via app()->request inside any controller.

Payload values are automatically cast to their detected type (int, float, bool, string).

PSR interoperability

The package ships three contracts in Exhaust\Contracts\ that align the framework with PSR standards without changing the existing workflow.

RequestBlueprint — typed request contract

Request now implements RequestBlueprint (which extends UrlBlueprint). Type-hint against the contract wherever you want static-analysis tools and IDEs to understand the full API of the request object.

Request::toPsr7() — PSR-7 adapter

Converts the framework request into a Psr\Http\Message\ServerRequestInterface on demand, for use with PSR-15 middleware or any library that expects a PSR-7 object.

Requires a PSR-17 ServerRequestFactoryInterface implementation — install any compliant library in your app:

The adapter maps:

MiddlewareBlueprint — PSR-15 middlewares

MiddlewareBlueprint extends PSR-15 MiddlewareInterface. Implementing it gives:

• interoperability with third-party PSR-15 libraries (CORS, rate-limiting, JWT auth, etc.)
• explicit, type-safe contract over the legacy invokable pattern
• IDE completion and static-analysis support

PSR-15 middleware (recommended for new middlewares):

Legacy invokable middleware (still fully supported):

Updating App\Controllers\Controller to support both patterns:

The app-level Controller base detects whether each middleware implements MiddlewareBlueprint and dispatches accordingly. Middlewares that don't implement the interface continue to work as invokables.

FinalHandler is a minimal pass-through that closes the middleware pipeline. Exhaust controllers handle the actual HTTP response through Commands, not through PSR-7 response objects.

ResponseBlueprint — response contract

ResponseBlueprint defines the contract for objects that wrap the Commands array and send an HTTP response. Implement it to build a custom response class — useful when you need extra headers, content negotiation, structured error envelopes, or centralised response logging.

Usage at the end of a controller action or inside app()->run():

Template engines

Configured in config/config.php → template_engine.use. All engines share the same rendering API.

Running tests