README

Yii Framework

Inertia

Inertia.js server-side integration layer for Yii2
Server-driven pages, shared props, redirects, and asset version handling without jQuery

Features

Overview

yii2-extensions/inertia is the server-side base package for building modern Inertia-driven pages on top of Yii2. It does not ship a client adapter. Instead, it defines the server contract that future packages such as yii2-extensions/inertia-vue, yii2-extensions/inertia-react, and yii2-extensions/inertia-svelte can reuse.

Installation

composer require yii2-extensions/inertia:^0.1

return [
    'bootstrap' => [\yii\inertia\Bootstrap::class],
];

Quick start

Render a page directly from a controller action:

use yii\inertia\Inertia;
use yii\web\Controller;
use yii\web\Response;

final class SiteController extends Controller
{
    public function actionIndex(): Response
    {
        return Inertia::render(
            'Dashboard',
            ['stats' => ['visits' => 42]],
        );
    }
}

Or extend the convenience controller:

use yii\inertia\web\Controller;
use yii\web\Response;

final class SiteController extends Controller
{
    public function actionIndex(): Response
    {
        return $this->inertia(
            'Dashboard',
            [
                'stats' => ['visits' => 42],
            ]
        );
    }
}

Configuration example

use yii\inertia\Manager;

return [
    'bootstrap' => [\yii\inertia\Bootstrap::class],
    'components' => [
        'inertia' => [
            'class' => Manager::class,
            'id' => 'app',
            'rootView' => '@app/views/layouts/inertia.php',
            'version' => static function (): string {
                $path = dirname(__DIR__) . '/public/build/manifest.json';

                return is_file($path) ? (string) filemtime($path) : '';
            },
            'shared' => ['app.name' => static fn(): string => Yii::$app->name],
        ],
    ],
];

Prop types (v3)

The package supports the Inertia v3 prop types for fine-grained control over when and how props are resolved:

use yii\inertia\Inertia;

return Inertia::render(
    'Dashboard',
    [
        'stats' => $stats,                                              // regular prop
        'users' => Inertia::defer(fn () => User::find()->all()),        // loaded after render
        'activity' => Inertia::optional(fn () => $user->getActivity()), // only on partial reload
        'auth' => Inertia::always(fn () => ['user' => $identity]),      // always included
        'items' => Inertia::merge($paginated)->append('data', 'id'),    // merge instead of replace
        'countries' => Inertia::once(fn () => Country::find()->all()),  // resolved once, cached
    ],
);

See the Usage Examples for detailed documentation on each prop type.

Validation and flash messages

This package maps the session flash key errors to props.errors and exposes all remaining flashes at the top-level flash page key. A typical validation redirect looks like this:

if (!$model->validate()) {
    Yii::$app->session->setFlash('errors', $model->getErrors());

    return $this->redirect(['create']);
}

Yii::$app->session->setFlash('success', 'Record created.');

return $this->redirect(['view', 'id' => $model->id]);

CSRF protection

Drop in yii\inertia\web\Request to enable Inertia's automatic cookie-to-header CSRF flow:

'request' => [
    'class' => \yii\inertia\web\Request::class,
    'cookieValidationKey' => 'your-secret-key',
],

Inertia's HTTP client reads the XSRF-TOKEN cookie and sends it as X-XSRF-TOKEN automatically no client-side configuration required. See the Configuration Reference for details.

Package boundaries

This repository intentionally does not include Vue, React, or Svelte bootstrapping. Those concerns belong in separate client adapter packages built on top of the server contract defined here.