gilads-otiannoh254 / inertia-protocol

v1.0.0-rc 2026-11-09 17:34 UTC

Requires

• php: >=8.2

Requires (Dev)

• phpunit/phpunit: ^10.5 || ^11.0

MIT

• Ian Ochieng

Published on Packagist.org on 2026-11-09 17:40 UTC

README

A framework-agnostic, zero-dependency PHP 8.2+ engine implementing the complete Inertia.js Wire Protocol specification with native support for both Version 2 and Version 3 protocols.

Designed to power any PHP framework adapter (CodeIgniter 4, Symfony, Slim, RoadRunner, Swoole, Workerman, Laravel, or bespoke architectures) with 100% spec-compliant Inertia responses.

Highlights

• Zero Dependencies: Pure PHP 8.2+ with strict typing.
• Multi-Version Protocol: Seamlessly target Inertia v3 (<script data-page> tags, live props, BigInt preservation) or Inertia v2 (<div data-page> attributes).
• Advanced Prop Model: Composable props (always, optional/lazy, defer, once, live, merge, scroll).
• Decoupled Architecture: Evaluates requests into clean ResponseDecision objects without binding to specific HTTP kernels.
• SSR Ready: Built-in HttpSsrGateway for official Node SSR server rendering and health checks.

Installation

composer require gilads-otiannoh254/inertia-protocol

Quick Example

use Inertia\Protocol\InertiaProtocol;
use Inertia\Protocol\Support\NativeRequest;

// 1. Build an Inertia response with composable props
$response = InertiaProtocol::render('Users/Index', [
    'users'    => fn() => UserModel::paginate(),
    'appName'  => InertiaProtocol::always('My App'),
    'metrics'  => InertiaProtocol::defer(fn() => Analytics::getSummary(), group: 'analytics'),
    'feed'     => InertiaProtocol::defer(fn() => Feed::getLatest())->merge('id'),
]);

// 2. Evaluate against incoming request
$decision = $response->toDecision(NativeRequest::fromGlobals());

if ($decision->isJson()) {
    // XHR Navigation: Send 200 OK JSON response
    http_response_code($decision->statusCode);
    foreach ($decision->headers as $name => $value) {
        header("{$name}: {$value}");
    }
    echo json_encode($decision->content);
} else {
    // Initial Visit: Render HTML root template
    echo '<!DOCTYPE html><html><head><title>My App</title></head><body>';
    echo $decision->toHtml('app'); // Emits v3 script + root div (or v2 div)
    echo '</body></html>';
}

Documentation

Comprehensive in-depth documentation is available in the docs/ directory:

Topic	Description
Getting Started	Introduction, Installation, and Quick Start Guide
Core Concepts	The Protocol Lifecycle, Page Object Schema, Response Decisions, Request Interface
Protocol Versions	Version Overview, Version 3 Spec, Version 2 Spec, Version Switching
Props Evaluation	Evaluation Model, Always, Optional/Lazy, Deferred, Once, Live, Merging, Scroll, Shared
Advanced Features	Partial Reloads, Asset Versioning (409), Redirects (303), Reserved Props, Error Bags, History Encryption, Big Integers, SSR Gateway
Framework Adapters	Building Adapters, PSR-7 / Slim, Symfony, CodeIgniter 4, RoadRunner / Swoole

License

MIT License. See LICENSE for details.