> ## 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。

尤其適合以內容為中心的網站，或想快速新增頁面的後台。
若需要如 API 般細緻的 HTTP 控管，實務上仍建議與一般路由並用。

## 安裝

先透過 Composer 加入 Folio。

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

`folio:install` 會註冊 Folio 的服務提供者。
預設頁面目錄為 `resources/views/pages/`。
若要同時處理多個頁面目錄或不同 base 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 路由

`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 segment。

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

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

若要接收多個 segment，可使用 `...`。

```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'],
]);
```

## 命名路由

Folio 頁面也能透過 `name()` 命名。

```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-TW/advanced/app-structure.md)
- [Laravel Boost](/zh-TW/boost.md)
- [Laravel Telescope](/zh-TW/telescope.md)
- [Laravel Bluesky](/zh-TW/packages/laravel-bluesky/index.md)
- [Laravel Octane](/zh-TW/octane.md)