Inertia

A framework-agnostic PHP core for negotiating and producing current Inertia.js protocol data.

Features

Installation

composer require php-forge/inertia:^0.2

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

PHPForge\Inertia\ResolvedPageObserver forwards the resolved page payload and shared-prop keys to a callback. Observer failures propagate to the caller; the observer does not mutate pages or hide callback failures.

$observer = new \PHPForge\Inertia\ResolvedPageObserver($collector->observe(...));

$observer->observe($page);

The callback receives array<string, mixed> page data and list<string> shared-prop keys, without depending on a debugger or framework. The class is extensible so adapters can preserve their own observer interfaces without duplicating logic.

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.

Documentation

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

Package information

Code quality

Social networks

License