https://github.com/yii2-extensions/inertia
Inertia.js server-side adapter for Yii2 page rendering, shared props, partial reloads, flash/error mapping, and asset version handling.
https://github.com/yii2-extensions/inertia
inertia inertiajs php server-driven-ui server-side-rendering single-page-applications spa yii2
Last synced: about 2 months ago
JSON representation
Inertia.js server-side adapter for Yii2 page rendering, shared props, partial reloads, flash/error mapping, and asset version handling.
- Host: GitHub
- URL: https://github.com/yii2-extensions/inertia
- Owner: yii2-extensions
- License: other
- Created: 2026-03-30T12:23:06.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-24T14:43:25.000Z (2 months ago)
- Last Synced: 2026-04-24T16:40:52.067Z (2 months ago)
- Topics: inertia, inertiajs, php, server-driven-ui, server-side-rendering, single-page-applications, spa, yii2
- Language: PHP
- Homepage:
- Size: 137 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
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
```bash
composer require yii2-extensions/inertia:^0.1
```
Register the bootstrap class in your application configuration:
```php
return [
'bootstrap' => [\yii\inertia\Bootstrap::class],
];
```
## Quick start
Render a page directly from a controller action:
```php
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:
```php
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],
]
);
}
}
```
Or inject the renderer contract. `Bootstrap` binds `ResponseRendererInterface` to `InertiaRenderer` in the DI container,
so the action stays decoupled from the Inertia implementation and overlays (Inertia, JSON, API) can swap the renderer
without rewriting controller code:
```php
use yii\inertia\web\ResponseRendererInterface;
use yii\web\{Controller, Response};
final class SiteController extends Controller
{
public function __construct(
$id,
$module,
private readonly ResponseRendererInterface $renderer,
$config = [],
) {
parent::__construct($id, $module, $config);
}
public function actionIndex(): Response|string
{
return $this->renderer->render('Dashboard', ['stats' => ['visits' => 42]]);
}
}
```
## Configuration example
```php
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],
],
],
];
```
## Dev server support (Vite)
The bundled `\yii\inertia\Vite` helper component renders asset tags for both development and production. When `devMode`
is `true`, it emits `@vite/client` plus each configured entrypoint from `devServerUrl`, enabling Vite's HMR WebSocket
end-to-end. When `devMode` is `false`, it reads the manifest at `manifestPath` and renders hashed asset tags for
production.
Typical development flow: run `npm run dev` to start the Vite dev server and launch Yii2 with a dev environment flag
(for example, `YII_ENV=dev ./yii serve`). `YII_ENV` does not toggle `Vite::$devMode` on its own; your application
configuration must wire the two together, for example:
```php
'components' => [
'inertiaVite' => [
'class' => \yii\inertia\Vite::class,
'devMode' => YII_ENV === 'dev',
// ...
],
],
```
For framework-specific setup, see:
- [`yii2-extensions/inertia-react`](https://github.com/yii2-extensions/inertia-react) — React Refresh preamble auto-injection.
- [`yii2-extensions/inertia-vue`](https://github.com/yii2-extensions/inertia-vue) — Vue HMR (no extra preamble).
## Prop types (v3)
The package supports the Inertia v3 prop types for fine-grained control over when and how props are resolved:
```php
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](docs/examples.md) 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:
```php
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:
```php
'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](docs/configuration.md) 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.
## Documentation
For detailed configuration options and advanced usage.
- 📚 [Installation Guide](docs/installation.md)
- ⚙️ [Configuration Reference](docs/configuration.md)
- 💡 [Usage Examples](docs/examples.md)
- 🧪 [Testing Guide](docs/testing.md)
## Package information
[](https://www.php.net/releases/8.3/en.php)
[](https://github.com/yiisoft/yii2/tree/22.0)
[](https://packagist.org/packages/yii2-extensions/inertia)
[](https://packagist.org/packages/yii2-extensions/inertia)
## Quality code
[](https://codecov.io/github/yii2-extensions/inertia)
[](https://github.com/yii2-extensions/inertia/actions/workflows/static.yml)
[](https://github.com/yii2-extensions/inertia/actions/workflows/linter.yml)
[](https://github.styleci.io/repos/1196150046?branch=main)
## License
[](LICENSE)