包简介

Symfony Bundle implementing the Inertia.js v3 server-side protocol

README 文档

README

Symfony bundle implementing the Inertia.js v3 server-side protocol — the Symfony equivalent of inertiajs/inertia-laravel.

What is Inertia.js?

Inertia lets you build modern React, Vue, or Svelte single-page applications without building a separate API. You keep your Symfony controllers, routing, middleware, and authentication exactly as they are - controllers just return a component name and props instead of a Twig template.

On the first visit the server returns a full HTML page. On subsequent navigations it returns a lightweight JSON response and the JavaScript adapter swaps the component client-side without a full reload.

Requirements

PHP ^8.1 · Symfony ^6.4 / ^7.4 / ^8.0 · Twig ^3.0

Installation

composer require nytodev/inertia-bundle

Without Symfony Flex, register the bundle manually in config/bundles.php:

Nytodev\InertiaBundle\InertiaBundle::class => ['all' => true],

Quick start

1. Root Twig template

{# templates/base.html.twig #}
<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    {{ inertiaHead(page) }}
    {{ encore_entry_link_tags('app') }}
</head>
<body>
    {{ inertia(page) }}
    {{ encore_entry_script_tags('app') }}
</body>
</html>

inertia(page) outputs <script data-page="app" type="application/json">...</script><div id="app"></div>.
inertiaHead(page) outputs SSR-rendered head tags (safe to include even without SSR).

2. Controller

use Nytodev\InertiaBundle\Service\Inertia;

class UserController
{
    #[Route('/users')]
    public function index(Inertia $inertia): Response
    {
        return $inertia->render('Users/Index', [
            'users' => $this->repository->findAll(),
        ]);
    }

    #[Route('/users/{id}')]
    public function show(User $user, Inertia $inertia): Response
    {
        return $inertia->render('Users/Show', [
            'user' => $user,
        ]);
    }
}

3. JavaScript entry point (React)

npm install @inertiajs/react react react-dom

// assets/app.jsx — @inertiajs/react v3 (setup is optional, Inertia calls createRoot automatically)
import { createInertiaApp } from '@inertiajs/react'

createInertiaApp({
    resolve: name => {
        const pages = import.meta.glob('./Pages/**/*.jsx', { eager: true })
        return pages[`./Pages/${name}.jsx`]
    },
})

4. A page component

// assets/Pages/Users/Index.jsx
export default function UsersIndex({ users }) {
    return (
        <ul>
            {users.map(user => (
                <li key={user.id}>{user.name}</li>
            ))}
        </ul>
    )
}

That's it. The bundle handles first-visit HTML, subsequent XHR JSON responses, asset versioning, 302→303 redirect conversion, and partial reloads automatically.

Shared props

Set props that are available on every page (e.g. authenticated user, flash messages):

// src/EventListener/InertiaShareListener.php
class InertiaShareListener
{
    public function __construct(
        private readonly Inertia $inertia,
        private readonly Security $security,
    ) {}

    public function onKernelRequest(RequestEvent $event): void
    {
        $this->inertia->share('auth', [
            'user' => $this->security->getUser()?->getUserIdentifier(),
        ]);
    }
}

# config/services.yaml
App\EventListener\InertiaShareListener:
    tags:
        - { name: kernel.event_listener, event: kernel.request }

Prop types

Method	Behaviour
`$inertia->lazy(fn)` / `optional(fn)`	Never sent on full render, only on explicit partial reload
`$inertia->always(fn)`	Always sent, even in partial reloads that filter other props
`$inertia->defer(fn)`	Fetched by the client in a separate XHR after page load
`$inertia->once(fn)`	Sent once, cached by the client
`$inertia->merge(fn)`	Merged into the existing client value (infinite scroll)

return $inertia->render('Feed/Index', [
    'posts'    => $inertia->merge(fn () => $this->postRepo->paginate($page)),
    'stats'    => $inertia->defer(fn () => $this->buildStats()),
    'comments' => $inertia->lazy(fn () => $this->commentRepo->findAll()),
]);

Configuration

# config/packages/inertia.yaml
inertia:
    root_view: base.html.twig   # Root Twig template (default: base.html.twig)
    version: null               # Asset version string — triggers full reload on change
    encrypt_history: false      # Globally encrypt browser history state
    expose_shared_prop_keys: true # Expose shared prop keys as top-level `sharedProps` in page object
    ssr_enabled: false            # Enable SSR (requires symfony/http-client)
    ssr_url: 'http://127.0.0.1:13714'
    ssr_bundle: null              # Path to SSR JS bundle, auto-detected if null

Documentation

Topic	Link
Installation & configuration	docs/installation.md
Rendering & shared props	docs/rendering.md
All prop types	docs/props.md
Asset versioning, redirects, history	docs/features.md
Flash & validation errors	docs/flash-errors.md
Server-Side Rendering	docs/ssr.md
Testing	docs/testing.md

License

MIT — see LICENSE.

nytodev/inertia-bundle 适用场景与选型建议

nytodev/inertia-bundle 是一款基于 PHP 开发的 Composer 扩展包，目前已累计 671 次下载、GitHub Stars 达 10，最近一次更新时间为 2026 年 04 月 05 日，在 PHP 生态内属于活跃度较高的组件。

它主要适用于以下技术方向：「symfony」「bundle」「react」「SPA」「vue」「inertia」等业务场景。在实际项目中，围绕这些方向常见需要落地的问题包括：接口对接、性能调优、并发安全、与既有框架（Laravel / ThinkPHP / Yii / Webman 等）的兼容适配，以及生产环境的日志埋点与稳定性保障。

我们在过去多个企业项目中使用过 nytodev/inertia-bundle 或与其功能相近的方案，如果你在选型或落地过程中遇到问题，例如 版本兼容、二次改造、私有化封装、与内部系统对接、生产 BUG 排查，欢迎联系我们协助评估。

围绕 nytodev/inertia-bundle 我们能提供哪些服务？

定制开发 / 二次开发

基于 nytodev/inertia-bundle 在你已有业务上做功能扩展、字段裁剪、UI 适配、与内部账号 / 权限 / 日志系统的深度对接。

BUG 修复 & 性能优化

线上偶发问题、内存泄漏、慢查询、并发异常等排查修复；针对高流量场景做缓存、队列、索引层面的调优。

项目外包 & 长期维护

承接完整的项目从需求 → 设计 → 开发 → 上线 → 长期运维；也可按月提供技术保姆服务。

yvsm@zunyunkeji.com QQ：316430983 微信：yvsm316 西安尊云信息科技 · 专注 PHP / Go / 分布式系统研发

与 nytodev/inertia-bundle 相关的其它包

同方向 / 同关键字的高下载量 PHP Composer 包推荐，方便对比选型：

voryx/pgasync 112

Async Reactive Postgres Driver for PHP (Non-blocking)

2lenet/easyadmin-plus-bundle 17

2lenet/EasyAdminPlusBundle

ufo-cms/json-rpc-bundle 5

The bundle for easy using json-rpc api on your project

sil/route-security-bundle 7

Provide a way to secure accesses to all routes of an symfony application.

dms/meetup-api-bundle 1

DMS Meetup API Bundle, enables Meetup API clients in services

yoanbernabeu/daplos-bundle 1

Bundle Symfony DaplosBundle

nytodev/inertia-bundle

包简介

关键字：