php-forge/inertia

Features

Installation

composer require php-forge/inertia:^0.3

PHP 8.3 or later and the JSON extension are required.

Quick start

use PHPForge\Inertia\{PageInput, Protocol, RequestContext};
use PHPForge\Inertia\Prop\Prop;

$request = new RequestContext(
    method: 'GET',
    url: '/users?page=1',
    absoluteUrl: 'https://example.com/users?page=1',
    headers: [
        'X-Inertia' => 'true',
        'X-Inertia-Version' => 'assets-v1',
    ],
);

$input = PageInput::create(
    component: 'Users/Index',
    props: [
        'users' => Prop::merge(fn (): array => loadUsers())->append('data', 'id'),
        'analytics' => Prop::defer(fn (): array => loadAnalytics(), group: 'analytics'),
        'filters' => Prop::optional(fn (): array => availableFilters()),
    ],
    version: 'assets-v1',
)
->withSharedProps(
    [
        'auth' => Prop::once(fn (): array => currentUser())->as('authenticated-user'),
    ],
)
->withErrors(validationErrors())
->withFlash(flashedData());

$result = Protocol::create()->page($request, $input);

Protocol does not return a framework response. An adapter inspects the result, applies statusCode() and headers(), serializes page() for an Inertia visit, or embeds the page JSON in the root HTML document for an initial visit.

Resolved-page observation

The existing ResolvedPageObserver callback remains available to older adapters. New diagnostic integrations use Event/ProtocolResultCreated through the optional PSR-14 dispatcher instead; see debugging. Do not wire both paths to the same diagnostic collector.

Adapter boundary

The core owns protocol decisions and page shaping. A framework adapter remains responsible for:

• extracting the method, relative URL, absolute URL, and supported request headers;
• resolving shared props, validation errors, flash data, and the asset version;
• rendering the root HTML document and embedding the initial page JSON;
• translating neutral results into its HTTP response implementation;
• managing sessions, flash persistence or reflashing, redirects, routes, CSRF, and asset tooling;
• JSON encoding the final page with the framework application's selected flags.

See the configuration reference for the complete result mapping.

Debugger integration

Protocol emits ProtocolResultCreated through an optional PSR-14 dispatcher. The protocol core never imports a debug contract or calls a collector, so installing the package does not activate a debugger and a call without a dispatcher emits no events. The collector and panel that do implement those contracts live apart, in PHPForge\Inertia\Debug, owned by this package.

See Debugger integration for the Yii2 and Yii3 wiring. It remains an unreleased prototype.

Documentation

• 📚 Installation guide
• ⚙️ Configuration and adapter reference
• 💡 Usage examples
• 🐞 Debugger integration
• 📖 Inertia.js protocol documentation
• 🧪 Testing guide

Package information

Code quality

Social networks

License