README

Inertia

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

Features

Installation

composer require php-forge/inertia:^0.1

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',
    ],
);

$result = (new Protocol())->page(
    $request,
    new PageInput(
        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',
        sharedProps: [
            'auth' => Prop::once(fn (): array => currentUser())->as('authenticated-user'),
        ],
        errors: validationErrors(),
        flash: flashedData(),
    ),
);

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.

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.