Folio

簡介 (Introduction)

Laravel Folio 是一個強大的基於頁面的路由器，旨在簡化 Laravel 應用程式中的路由。使用 Laravel Folio，產生路由就像在應用程式的 resources/views/pages 目錄中建立 Blade 樣板一樣輕鬆。

例如，要建立一個可透過 /greeting URL 存取的頁面，只需在應用程式的 resources/views/pages 目錄中建立一個 greeting.blade.php 檔案：

<div>
    Hello World
</div>

安裝 (Installation)

首先，使用 Composer 套件管理器將 Folio 安裝到你的專案中：

composer require laravel/folio

安裝 Folio 後，你可以執行 folio:install Artisan 指令，這將把 Folio 的服務提供者安裝到你的應用程式中。此服務提供者會註冊 Folio 搜尋路由 / 頁面的目錄：

php artisan folio:install

頁面路徑 / URI (Page Paths / URIs)

預設情況下，Folio 會從應用程式的 resources/views/pages 目錄提供頁面，但你可以在 Folio 服務提供者的 boot 方法中自訂這些目錄。

例如，有時在同一個 Laravel 應用程式中指定多個 Folio 路徑可能會很方便。你可能希望為應用程式的「管理」區域設定一個單獨的 Folio 頁面目錄，同時使用另一個目錄來存放應用程式的其餘頁面。

你可以使用 Folio::path 和 Folio::uri 方法來達成此目的。path 方法註冊一個目錄，Folio 在路由傳入的 HTTP 請求時會掃描該目錄中的頁面，而 uri 方法則指定該頁面目錄的「基礎 URI」：

use Laravel\Folio\Folio;

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

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

            // ...
        ],
    ]);

子網域路由 (Subdomain Routing)

你也可以根據傳入請求的子網域將路由導向頁面。例如，你可能希望將來自 admin.example.com 的請求路由到與其他 Folio 頁面不同的頁面目錄。你可以透過在呼叫 Folio::path 方法後呼叫 domain 方法來達成此目的：

use Laravel\Folio\Folio;

Folio::domain('admin.example.com')
    ->path(resource_path('views/pages/admin'));

`domain` 方法也允許你擷取網域或子網域的部分內容作為參數。這些參數將被注入到你的頁面樣板中：

```php
use Laravel\Folio\Folio;

Folio::domain('{account}.example.com')
    ->path(resource_path('views/pages/admin'));

建立路由 (Creating Routes)

你可以透過將 Blade 樣板放置在任何 Folio 掛載的目錄中來建立 Folio 路由。預設情況下，Folio 會掛載 resources/views/pages 目錄，但你可以在 Folio 服務提供者的 boot 方法中自訂這些目錄。

一旦 Blade 樣板被放置在 Folio 掛載的目錄中，你就可以立即透過瀏覽器存取它。例如，放置在 pages/schedule.blade.php 的頁面可以在瀏覽器中透過 http://example.com/schedule 存取。

要快速檢視所有 Folio 頁面 / 路由的列表，你可以呼叫 folio:list Artisan 指令：

php artisan folio:list

巢狀路由 (Nested Routes)

你可以透過在 Folio 的其中一個目錄中建立一個或多個目錄來建立巢狀路由。例如，要建立一個可透過 /user/profile 存取的頁面，請在 pages/user 目錄中建立一個 profile.blade.php 樣板：

php artisan folio:page user/profile

# pages/user/profile.blade.php → /user/profile

索引路由 (Index Routes)

有時，你可能希望將特定頁面設為目錄的「索引」。透過在 Folio 目錄中放置 index.blade.php 樣板，任何對該目錄根目錄的請求都將被路由到該頁面：

php artisan folio:page index
# pages/index.blade.php → /

php artisan folio:page users/index
# pages/users/index.blade.php → /users

路由參數 (Route Parameters)

通常，你需要將傳入請求 URL 的片段注入到頁面中，以便與它們互動。例如，你可能需要存取正在顯示其個人資料的使用者的「ID」。要達成此目的，你可以將頁面檔名的一部分封裝在方括號中：

php artisan folio:page "users/[id]"

# pages/users/[id].blade.php → /users/1

擷取的片段可以作為變數在你的 Blade 樣板中存取：

```html
<div>
    User {{ $id }}
</div>

要擷取多個片段，你可以在封裝的片段前加上三個點 `...`：

```shell
php artisan folio:page "users/[...ids]"

# pages/users/[...ids].blade.php → /users/1/2/3

當擷取多個片段時，擷取的片段將以陣列形式注入到頁面中：

```html
<ul>
    @foreach ($ids as $id)
        <li>User {{ $id }}</li>
    @endforeach
</ul>

路由模型綁定 (Route Model Binding)

如果頁面樣板檔名的萬用字元片段對應到應用程式的 Eloquent 模型之一，Folio 將自動利用 Laravel 的路由模型綁定功能，並嘗試將解析的模型實例注入到你的頁面中：

php artisan folio:page "users/[User]"

# pages/users/[User].blade.php → /users/1

擷取的模型可以作為變數在你的 Blade 樣板中存取。模型的變數名稱將轉換為「駝峰式大小寫」：

<div>User {{ $user->id }}</div>

自訂鍵 (Customizing the Key)

有時你可能希望使用 id 以外的欄位來解析綁定的 Eloquent 模型。為此，你可以在頁面的檔名中指定欄位。例如，檔名為 [Post:slug].blade.php 的頁面將嘗試透過 slug 欄位而不是 id 欄位來解析綁定的模型。

在 Windows 上，你應該使用 - 來分隔模型名稱和鍵：[Post-slug].blade.php。

模型位置 (Model Location)

預設情況下，Folio 會在應用程式的 app/Models 目錄中搜尋你的模型。但是，如果需要，你可以在樣板的檔名中指定完全限定的模型類別名稱：

php artisan folio:page "users/[.App.Models.User]"

# pages/users/[.App.Models.User].blade.php → /users/1

軟刪除模型 (Soft Deleted Models)

預設情況下，解析隱式模型綁定時不會檢索已軟刪除的模型。但是，如果你希望，可以在頁面的樣板中呼叫 withTrashed 函數來指示 Folio 檢索軟刪除的模型：

<?php

use function Laravel\Folio\{withTrashed};

withTrashed();

?>

<div>
    User {{ $user->id }}
</div>

渲染 Hook (Render Hooks)

預設情況下，Folio 會傳回頁面 Blade 樣板的內容作為對傳入請求的回應。但是，你可以透過在頁面樣板中呼叫 render 函數來自訂回應。

render 函數接受一個閉包，該閉包將接收 Folio 正在渲染的 View 實例，允許你向視圖新增額外資料或自訂整個回應。除了接收 View 實例之外，任何額外的路由參數或模型綁定也將提供給 render 閉包：

<?php

use App\Models\Post;
use Illuminate\Support\Facades\Auth;
use Illuminate\View\View;

use function Laravel\Folio\render;

render(function (View $view, Post $post) {
    if (! Auth::user()->can('view', $post)) {
        return response('Unauthorized', 403);
    }

    return $view->with('photos', $post->author->photos);
}); ?>

<div>
    {{ $post->content }}
</div>

<div>
    This author has also taken {{ count($photos) }} photos.
</div>

命名路由 (Named Routes)

你可以使用 name 函數為特定頁面的路由指定名稱：

<?php

use function Laravel\Folio\name;

name('users.index');

就像 Laravel 的命名路由一樣，你可以使用 route 函數產生已指派名稱的 Folio 頁面 URL：

<a href="{{ route('users.index') }}">
    All Users
</a>

如果頁面有參數，你可以簡單地將它們的值傳遞給 route 函數：

route('users.show', ['user' => $user]);

中介軟體 (Middleware)

你可以透過在頁面樣板中呼叫 middleware 函數將中介軟體套用到特定頁面：

<?php

use function Laravel\Folio\{middleware};

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

?>

<div>
    Dashboard
</div>

或者，要將中介軟體指派給一組頁面，你可以在呼叫 Folio::path 方法後串連 middleware 方法。

要指定中介軟體應套用到哪些頁面，可以使用中介軟體陣列的鍵來對應其應套用的頁面 URL 模式。可以使用 * 字元作為萬用字元：

use Laravel\Folio\Folio;

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

        // ...
    ],
]);

你可以在中介軟體陣列中包含閉包來定義內聯、匿名中介軟體：

use Closure;
use Illuminate\Http\Request;
use Laravel\Folio\Folio;

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

        function (Request $request, Closure $next) {
            // ...

            return $next($request);
        },
    ],
]);

路由快取 (Route Caching)

使用 Folio 時，你應該始終利用 Laravel 的路由快取功能。Folio 會監聽 route:cache Artisan 指令，以確保 Folio 頁面定義和路由名稱被正確快取，以獲得最佳效能。