maskulabs/inertia-psr

PSR-based Inertia helpers and middleware integration for PHP applications
24
php middleware psr inertia inertiajs inertia.js
Install
composer require maskulabs/inertia-psr
Latest Version:v3.0.0-beta3-1
PHP:^8.5
Maintainer: maskulabs

inertia-psr

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:

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