maskulabs/inertia-yii

Yii3 integration for Inertia.js v3 with server-side rendering support, middleware, validation error handling, session and flash adapters, and Vite asset integration.

1.0.0-beta1 2026-03-17 18:52 UTC

Requires

• php: ^8.5
• maskulabs/inertia-psr: ^v3.0.0-beta3-1
• yiisoft/assets: ^5.1
• yiisoft/csrf: ^2.2
• yiisoft/data-response: ^2.2
• yiisoft/definitions: ^3.4
• yiisoft/http-middleware: ^1.2
• yiisoft/injector: ^1.2
• yiisoft/input-http: ^1.0
• yiisoft/request-provider: ^1.3
• yiisoft/session: ^3.0
• yiisoft/validator: ^2.5
• yiisoft/yii-view-renderer: ^7.4

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.94
• httpsoft/http-message: ^1.1
• phpunit/phpunit: ^12.5
• rector/rector: ^2.3
• vimeo/psalm: ^6.15
• yiisoft/code-style: ^1.0

MIT

• yii
• inertia
• yii3
• inertiajs
• inertia.js

README

Yii integration for maskulabs/inertia-psr.

inertia-yii provides the Yii-specific pieces needed to use Inertia.js v3 in Yii applications, including rendering, middleware, validation error handling, session / flash adapters, and Vite integration.

Official Inertia.js documentation:

• https://inertiajs.com/docs/v3/getting-started/index

Features

• Yii-specific Inertia implementation
• HTML and JSON Inertia responses
• Shared props middleware
• Validation exception middleware with flashed errors
• Yii session and flash adapters
• Yii response and stream factories
• Vite dev server and manifest integration

Requirements

• PHP 8.5+
• maskulabs/inertia-psr
• Yii packages required by composer.json

Installation

Install the package with Composer:

composer require maskulabs/inertia-yii

Looking for a ready application template?

If you want a ready starting point instead of wiring everything manually, see maskulabs/inertia-app.

It is an application template based on yiisoft/app with Inertia.js integration already configured.

Quick start

<?php

use MaskuLabs\InertiaPsr\InertiaInterface;
use MaskuLabs\InertiaPsr\Response\ResponseInterface;

final readonly class DashboardAction
{
    public function __construct(
        private InertiaInterface $inertia,
    ) {}

    public function __invoke(): ResponseInterface
    {
        return $this->inertia->render('Dashboard', [
            'stats' => [
                'users' => 120,
                'sales' => 54,
            ],
        ]);
    }
}

Root view

The package ships with a default root view, but you can also configure your own.

Your root view should:

• render the serialized Inertia page data
• provide the frontend mount element
• include your frontend JavaScript and CSS assets

Shared props

ShareMiddleware is intended to be configured in the Yii middleware stack.

Example:

<?php

use MaskuLabs\InertiaPsr\Middleware\InertiaMiddleware;
use MaskuLabs\InertiaYii\Middleware\ShareMiddleware as InertiaShareMiddleware;

return [
    InertiaMiddleware::class,
    [
        'class' => InertiaShareMiddleware::class,
        'withDefinitions()' => [
            Reference::to(I18n::class),
            Reference::to(Layout::class),
        ],
    ],
];

Validation errors

ValidationExceptionMiddleware catches validation exceptions and flashes formatted errors so they can be returned to the frontend after redirect.

Example:

<?php

use MaskuLabs\InertiaYii\Exception\ValidationException;

if (!$formHydrator->populateFromPostAndValidate($loginForm, $request)) {
    throw new ValidationException($loginForm->getValidationResult());
}

Vite integration

ViteAsset supports two common modes:

• development mode using the Vite dev server
• production mode using .vite/manifest.json

License

MIT