README

A framework-agnostic, PSR-based server-side adapter for Inertia.js v3.

inertia-psr provides a PSR-friendly implementation of the Inertia server protocol for PHP applications. It is designed to stay closely aligned with the official Inertia.js v3 documentation:

https://inertiajs.com/docs/v3/getting-started/index

Features

PSR-oriented Inertia server implementation
HTML and JSON Inertia responses
Shared props support
Flash data support
Partial reload support
Deferred and optional props
Merge and deep merge metadata
Once-resolved props with expiration metadata
Infinite scroll metadata support
Middleware for core Inertia handling
Optional SSR integration over HTTP

Requirements

This package is designed for PSR-based PHP applications and expects integrations around:

PHP 8.5+
PSR-7 HTTP messages
PSR-15 middleware
PSR-17 factories
a session / flash implementation compatible with the package interfaces

Installation

Install the package with Composer:

composer require maskulabs/inertia-psr

What this package provides

inertia-psr focuses on the server-side Inertia protocol and response generation.

It does not provide:

a frontend application
asset bundling
framework-specific routing
framework-specific dependency injection setup
a built-in session implementation
a built-in Vite integration

Quick start

<?php
use MaskuLabs\InertiaPsr\InertiaInterface;
use Psr\Http\Message\ResponseInterface;

final readonly class DashboardAction
{
    public function __construct(
        private InertiaInterface $inertia,
    ) {}

    public function __invoke(): ResponseInterface
    {
        return $this->inertia->render('Dashboard', [
            'stats' => [
                'users' => 120,
                'sales' => 54,
            ],
        ]);
    }
}

This returns an Inertia response for the Dashboard page component.

In a real application, you will typically also:

register the package middleware in your PSR-15 middleware stack
configure a root view for HTML responses
include your frontend assets in that root view

Configuring the root view

You can configure the root view globally:

<?php
$inertia->setRootView(__DIR__ . '/views/app.php');

You can also set it per response:

<?php
return $this->inertia
    ->render('Dashboard')
    ->rootView(__DIR__ . '/views/app.php');

Root HTML template

Your root view is the HTML shell used for the initial browser visit.

It should:

render the serialized Inertia page data
provide the frontend mount element
include your frontend JavaScript assets

Example:

<?php
/** @var array $page */
?>
<!doctype html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>My App</title>
    <!-- Include frontend assets here:
         use the built JavaScript file in production,
         or @vite/client + your app entry script during development. -->
</head>
<body>
    <script type="application/json" data-page="app">
        <?php echo json_encode($page, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES); ?>
    </script>

    <div id="app"></div>
</body>
</html>

The exact asset tags depend on your frontend tooling and framework integration.

Common usage

Share data

<?php
$inertia->share('app.name', 'My App');
$inertia->share('auth.user', [
    'id' => 1,
    'name' => 'Jane Doe',
]);

Set asset version

<?php
$inertia->version('build-hash');

Flash data

<?php
$inertia->flash('success', 'Profile updated successfully.');

Redirect back

<?php
return $inertia->back();

Inertia location response

<?php
return $inertia->location('/login');

Advanced props

The package supports advanced Inertia prop behavior, including:

always()
optional()
defer()
merge()
deepMerge()
once()
shareOnce()
scroll()

Example:

<?php
use MaskuLabs\InertiaPsr\Props\ScrollProp\ScrollMetadata;

return $inertia->render('Users/Index', [
    'users' => $inertia->scroll(
        value: fn() => [
            ['id' => 1, 'name' => 'Jane'],
            ['id' => 2, 'name' => 'John'],
        ],
        metadata: new ScrollMetadata(
            pageName: 'page',
            previousPage: null,
            nextPage: 2,
            currentPage: 1,
        ),
    ),
    'stats' => $inertia->defer(
        fn() => ['active' => 42],
        'sidebar',
    ),
    'permissions' => $inertia->once(
        fn() => ['users.read', 'users.write'],
    ),
]);

Middleware and SSR

The package includes support for:

core Inertia middleware
history encryption middleware
optional SSR middleware
HTTP SSR gateway integration

To use the full Inertia request / response flow correctly, register the package middleware in your PSR-15 middleware stack.

Framework-specific wiring may differ, so see the integration examples for concrete setups.

Framework integrations

See the docs directory for complete integration examples.

Available examples:

Notes

Use a real asset version string or build hash in production.
The root view should include the frontend assets required to boot your Inertia app.
If you are using a specific framework, the package is usually best integrated through framework-specific service wiring and middleware registration.

License

MIT

maskulabs / inertia-psr

Maintainers

Package info

Statistics

Security