README

Yii Framework

Inertia for Yii2

Connect Yii requests, responses, views, sessions, and redirects to the Inertia protocol

Architecture

The packages have deliberately separate responsibilities:

php-forge/inertia implements the framework-agnostic protocol, page model, prop resolution, headers, redirects, and result objects.
yii2-extensions/inertia adapts Yii2 application state to that core and maps its results back to Yii responses.
php-forge/vite provides optional, framework-agnostic Vite manifest and development server support.

This adapter does not contain Vite integration or framework-specific JavaScript client packages.

Installation

composer require yii2-extensions/inertia:^0.4

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

The adapter installs php-forge/inertia as its protocol dependency.

Quick start

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]],
        );
    }
}

The convenience controller exposes the same operation as $this->inertia():

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

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,
            ],
        ],
    ],
];

Version callbacks may accept the current yii\web\Request. Prop callbacks are framework-neutral zero-argument closures and are resolved by php-forge/inertia.

Prop factories

The yii\inertia\Inertia facade delegates prop creation directly to the core:

return Inertia::render(
    'Dashboard',
    [
        'stats' => Inertia::always($stats),
        'users' => Inertia::defer(static fn(): array => User::find()->asArray()->all()),
        'activity' => Inertia::optional(static fn(): array => $activity),
        'items' => Inertia::merge($items)->append('data', 'id'),
        'countries' => Inertia::once(static fn(): array => $countries)->as('countries-v1'),
    ],
);

The facade also provides deepMerge() and scroll(). See the php-forge/inertia documentation for protocol and prop semantics.

Validation and flash messages

The adapter reads the session flash key configured by Manager::$errorFlashKey and passes it to the core as props.errors. Other flashes are emitted in the top-level flash page field. Flashes are consumed only after a page result is created, so version conflicts and failed page creation preserve them.

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

Use yii\inertia\web\Request for Inertia's cookie-to-header CSRF flow:

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

Resolved-page observation

PHPForge\Inertia\ResolvedPageObserver forwards the resolved page payload and shared-prop keys to a callback. Observer failures propagate to the caller; the observer does not mutate pages or hide callback failures.

Set Manager::$pageObserver to a portable observer. Both initial and Inertia responses notify it after page resolution; version conflicts do not. The default is null, preserving existing applications. This integration requires the core 0.3 development line.

Vite

Install and configure php-forge/vite when the application uses Vite. Asset discovery and development-server behavior are intentionally independent of this Yii2 adapter.