> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Laravel Folio

> 介绍如何使用 Laravel Folio 实现基于文件的路由，从安装到路由模型绑定一应俱全。

## 简介

Laravel Folio 是一个基于页面的路由器，只需放置 Blade 文件即可定义路由。
与传统的以 `routes/web.php` 为中心的定义方式不同，它能够将文件系统的结构直接映射到 URL。

对于以内容为中心的网站，或希望按页面快速添加页面的后台管理系统尤其有效。
在需要精细 HTTP 控制的场景（如 API）中，建议与常规路由搭配使用。

## 安装

首先通过 Composer 安装 Folio。

```bash theme={null}
composer require laravel/folio
php artisan folio:install
```

`folio:install` 会注册 Folio 的服务提供者。
默认情况下，`resources/views/pages/` 为页面目录。
如果需要区分多个页面目录或基础 URI，请在服务提供者的 `boot` 中设置 `Folio::path()` 和 `uri()`。

```php theme={null}
use Laravel\Folio\Folio;

Folio::path(resource_path('views/pages/guest'))->uri('/');

Folio::path(resource_path('views/pages/admin'))
    ->uri('/admin');
```

## 创建路由

Folio 会从挂载目录下 Blade 文件的文件名自动生成 URL。

```text theme={null}
resources/views/pages/schedule.blade.php -> /schedule
```

```bash theme={null}
php artisan folio:list
```

### 嵌套路由

嵌套目录时，URL 也会以同样的结构嵌套。

```bash theme={null}
php artisan folio:page user/profile
# pages/user/profile.blade.php -> /user/profile
```

### 索引路由

`index.blade.php` 会映射到该目录的根路径。

```bash theme={null}
php artisan folio:page index
# pages/index.blade.php -> /

php artisan folio:page users/index
# pages/users/index.blade.php -> /users
```

## 路由参数

在文件名中使用 `[]` 即可接收 URL 段。

```bash theme={null}
php artisan folio:page "users/[id]"
# pages/users/[id].blade.php -> /users/1
```

```blade theme={null}
<div>User {{ $id }}</div>
```

要接收多个段，请使用 `...`。

```bash theme={null}
php artisan folio:page "users/[...ids]"
# pages/users/[...ids].blade.php -> /users/1/2/3
```

```blade theme={null}
@foreach ($ids as $id)
    <li>User {{ $id }}</li>
@endforeach
```

## 路由模型绑定

像 `[User].blade.php` 这样使用模型名，即可自动解析出模型实例。

```bash theme={null}
php artisan folio:page "users/[User]"
# pages/users/[User].blade.php -> /users/1
```

```blade theme={null}
<div>User {{ $user->id }}</div>
```

如果要包含软删除的模型，请在页面中调用 `withTrashed()`。

```php theme={null}
<?php

use function Laravel\Folio\withTrashed;

withTrashed();
```

<Info>
  写作 `[Post:slug].blade.php` 时，可以使用 `id` 之外的键（例如 `slug`）来解析模型。
</Info>

## 中间件

如果只对特定页面应用中间件，请在页面模板内使用 `middleware()`。

```php theme={null}
<?php

use function Laravel\Folio\middleware;

middleware(['auth', 'verified']);
```

要一次性对多个页面应用中间件，请使用 `Folio::path(...)->middleware()`。

```php theme={null}
<?php

use Laravel\Folio\Folio;

Folio::path(resource_path('views/pages'))->middleware([
    'admin/*' => ['auth', 'verified'],
]);
```

## 命名路由

也可以通过 `name()` 为 Folio 页面命名。

```php theme={null}
<?php

use function Laravel\Folio\name;

name('users.index');
```

<Info>
  在诸如 `users/[User].blade.php` 这样的单个页面中定义 `name('users.show')` 后，就可以通过 `route('users.show', ['user' => $user])` 生成带参数的 URL。
</Info>

设置好路由名之后，可用 `route()` 辅助函数生成 URL。

```php theme={null}
route('users.index');
route('users.show', ['user' => $user]);
```

## 文件与 URL 的对应关系

```mermaid theme={null}
graph LR
  A["pages/index.blade.php"] --> B["/"]
  C["pages/about.blade.php"] --> D["/about"]
  E["pages/users/[User].blade.php"] --> F["/users/1"]
```

## 与传统路由的对比

| 特性   | 常规路由                | Folio              |
| ---- | ------------------- | ------------------ |
| 路由定义 | `routes/web.php`    | 通过文件名自动生成          |
| 控制器  | 需要（或使用闭包）           | 不需要（直接在 Blade 中处理） |
| 适用场景 | API、SPA、复杂的 HTTP 控制 | 内容网站、后台管理          |

<Tip>
  即便使用 Folio，也可以通过 `php artisan route:cache` 启用路由缓存，从而在生产环境中优化性能。
</Tip>


## Related topics

- [Laravel 11 之后的应用结构](/zh/advanced/app-structure.md)
- [Laravel Boost](/zh/boost.md)
- [Laravel Telescope](/zh/telescope.md)
- [Laravel Bluesky](/zh/packages/laravel-bluesky/index.md)
- [Laravel Octane](/zh/octane.md)