crenspire/yii2-inertia
Features
- Zero configuration — the
inertiacomponent 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/vue3or@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/:
- Introduction and installation
- Pages and props, shared data, redirects, forms and validation, CSRF protection
- Partial reloads, deferred props, merging props, once props, infinite scroll
- Vite, server-side rendering, testing, troubleshooting
- Configuration and API reference
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.
Related Packages
Inertia.js v3 server-side adapter for CodeIgniter 4. Build single-page apps with...