README

Yii2 Inertia

The Inertia.js v3 adapter for the Yii 2 framework.
Build React, Vue and Svelte single-page apps with classic Yii controllers — no API required.

Documentation · Installation · Upgrading from 1.x · Changelog

Features

Zero configuration — the inertia component registers and bootstraps itself
Complete Inertia v3 protocol — partial reloads, deferred, optional, once, merge and infinite scroll props, asset versioning, flash data, error bags, history encryption and fragment redirects
Made for Yii — Yii redirects, CSRF validation, JSON form bodies, model validation errors and data providers work out of the box
Vite integration — asset tags from the build manifest or the dev server with hot module replacement
Server-side rendering with automatic fallback to client-side rendering

Requirements

PHP 8.1+
Yii 2.0.55+
An Inertia.js v3 client: @inertiajs/react, @inertiajs/vue3 or @inertiajs/svelte

Installation

composer require crenspire/yii2-inertia:^2.0

Until 2.0.0 is tagged, install the development version: composer require crenspire/yii2-inertia:2.0.x-dev.

Create the root view in views/layouts/inertia.php (see stubs/inertia.php):

<?php

use Crenspire\Yii2Inertia\Inertia;
use yii\helpers\Html;

/** @var yii\web\View $this */
/** @var array $page */
/** @var Crenspire\Yii2Inertia\Ssr\SsrResponse|null $ssr */

$this->beginPage();
?>
<!DOCTYPE html>
<html lang="<?= Html::encode(Yii::$app->language) ?>">
<head>
    <meta charset="<?= Html::encode(Yii::$app->charset) ?>">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title data-inertia><?= Html::encode(Yii::$app->name) ?></title>
    <?= Inertia::vite()->tags('src/main.jsx') ?>
    <?= Inertia::ssrHead($ssr) ?>
    <?php $this->head() ?>
</head>
<body>
<?php $this->beginBody() ?>
<?= Inertia::app($page, $ssr) ?>
<?php $this->endBody() ?>
</body>
</html>
<?php $this->endPage() ?>

Then set up the client side with Vite. The installation guide walks through React, Vue and Svelte.

Usage

use Crenspire\Yii2Inertia\Inertia;
use yii\web\Controller;
use yii\web\Response;

class UserController extends Controller
{
    public function actionIndex(): Response
    {
        return Inertia::render('Users/Index', [
            'users' => fn () => User::find()->select(['id', 'name', 'email'])->asArray()->all(),
            'stats' => Inertia::defer(fn () => Stats::summary()),
        ]);
    }

    public function actionCreate(): Response
    {
        $model = new User();

        if ($this->request->isPost) {
            if ($model->load($this->request->post(), '') && $model->save()) {
                Inertia::flash('success', 'User created.');

                return $this->redirect(['user/index']);
            }

            Inertia::withErrors($model);

            return Inertia::back();
        }

        return Inertia::render('Users/Create');
    }
}

// src/pages/Users/Index.jsx
import { Deferred, Link } from '@inertiajs/react'

export default function Index({ users, stats }) {
  return (
    <>
      <Deferred data="stats" fallback={<p>Loading stats…</p>}>
        <p>{stats?.total} users</p>
      </Deferred>
      <ul>
        {users.map((user) => (
          <li key={user.id}><Link href={`/users/${user.id}`}>{user.name}</Link></li>
        ))}
      </ul>
    </>
  )
}

Documentation

The full documentation is available at https://crenspire.github.io/yii2-inertia/:

Example application

examples/basic is a complete application with React 19, Vite and Tailwind CSS, demonstrating deferred props, partial reloads, forms with validation errors, flash data and infinite scroll:

cd examples/basic
composer install
cd vite && npm install && npm run build && cd ..
php -S localhost:8080 -t web web/router.php

Contributing

Contributions are welcome. See CONTRIBUTING.md for the development setup, including how to run the tests and the documentation site locally.

License

The MIT License. See LICENSE.

crenspire / yii2-inertia

Package info

Security

Statistics