crenspire/yii3-inertia

A server-side Inertia.js adapter for Yii3 and any other PSR-7/PSR-15 application. Build single-page apps with React, Vue or Svelte while keeping routing, controllers and validation in PHP.

Features

• Inertia.js 3 protocol, with support for Inertia.js 1 and 2 clients
• Partial reloads, and deferred, optional, always, merge, once and infinite scroll props
• Validation errors with error bags, flash data and history encryption
• CSRF protection for yiisoft/csrf
• Vite tags for the dev server and production builds, with automatic asset versioning
• Server-side rendering through a PSR-18 HTTP client
• Zero-config setup in Yii3 through yiisoft/config
• Stateless services, safe for RoadRunner, Swoole and FrankenPHP workers

Requirements

• PHP 8.2 – 8.5
• A PSR-17 HTTP factory implementation

Installation

composer require crenspire/yii3-inertia:^2.0

In a Yii3 application, the services are registered automatically. Add the middleware before the router in config/web/di/application.php:

SessionMiddleware::class,
\Crenspire\Inertia\Middleware\XsrfTokenMiddleware::class, // when using yiisoft/csrf
CsrfTokenMiddleware::class,
\Crenspire\Inertia\Middleware\InertiaMiddleware::class,
Router::class,

Create the root view at resources/views/inertia.php:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title data-inertia>My App</title>
    <?= $vite->reactRefresh() ?>
    <?= $vite->tags('resources/js/app.jsx') ?>
    <?= $inertia->head() ?>
</head>
<body>
    <?= $inertia->body() ?>
</body>
</html>

Then set up the frontend as described in Client-side setup.

Usage

use Crenspire\Inertia\Inertia;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;

final readonly class IndexAction
{
    public function __construct(
        private Inertia $inertia,
        private UserRepository $users,
    ) {}

    public function __invoke(ServerRequestInterface $request): ResponseInterface
    {
        return $this->inertia->render($request, 'Users/Index', [
            'users' => fn () => $this->users->findAll(),
            'stats' => Inertia::defer(fn () => $this->users->statistics()),
        ]);
    }
}

import { Deferred } from '@inertiajs/react'

export default function Index({ users, stats }) {
  return (
    <>
      <UserTable users={users} />
      <Deferred data="stats" fallback={<p>Loading…</p>}>
        <Stats stats={stats} />
      </Deferred>
    </>
  )
}

Read the documentation for forms and validation, shared data, all prop types, Vite, server-side rendering, usage without Yii3, and more.

Examples

• examples/psr15: a runnable application built only from PSR components
• examples/yii3: files for an application created from yiisoft/app

Upgrading from 1.x

Version 2.0 is a rewrite with a new API. See the upgrade guide.

Contributing

See CONTRIBUTING.md. The documentation lives in docs and is published with GitHub Pages.

License

MIT. See LICENSE.