Laravel Folio

简介
安装
- 页面路径/URI
- 子域路由
创建路由
- 嵌套路由
- 索引路由
路由参数
路由模型绑定
- 软删除模型
渲染钩子
命名路由
中间件
路由缓存

简介

Laravel Folio 是一个强大的基于页面的路由器，旨在简化 Laravel 应用程序中的路由。使用 Laravel Folio，生成路由就像在应用程序的 resources/views/pages 目录中创建 Blade 模板一样简单。

例如，要创建一个可在 /greeting URL 访问的页面，只需在应用程序的 resources/views/pages 目录中创建一个 greeting.blade.php 文件。

<div>
    Hello World
</div>

安装

要开始使用，请使用 Composer 包管理器将 Folio 安装到您的项目中。

composer require laravel/folio

安装 Folio 后，您可以执行 folio:install Artisan 命令，该命令会将 Folio 的服务提供者安装到您的应用程序中。此服务提供者注册 Folio 将在其中搜索路由/页面的目录。

php artisan folio:install

页面路径/URI

默认情况下，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',
 
            // ...
        ],
    ]);

子域路由

您还可以根据传入请求的子域对页面进行路由。例如，您可能希望将来自 admin.example.com 的请求路由到与其他 Folio 页面不同的页面目录。您可以通过在调用 Folio::path 方法后调用 domain 方法来实现这一点。

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

domain 方法还允许您捕获域或子域的部分内容作为参数。这些参数将被注入到您的页面模板中。

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

创建路由

您可以通过将 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

嵌套路由

您可以通过在一个或多个 Folio 目录中创建目录来创建嵌套路由。例如，要创建一个可以通过 /user/profile 访问的页面，请在 pages/user 目录中创建一个 profile.blade.php 模板。

php artisan folio:page user/profile
 
# pages/user/profile.blade.php → /user/profile

索引路由

有时，您可能希望将某个页面设置为目录的“索引”。通过将 index.blade.php 模板放在 Folio 目录中，对该目录根目录的任何请求都将被路由到该页面。

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

路由参数

通常，您需要将传入请求 URL 的部分段注入到您的页面中，以便您可以与它们进行交互。例如，您可能需要访问正在显示的用户的“ID”。要实现这一点，您可以在页面文件名中用方括号将部分段封装起来。

php artisan folio:page "users/[id]"
 
# pages/users/[id].blade.php → /users/1

捕获的段可以在您的 Blade 模板中作为变量访问。

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

要捕获多个段，可以在封装的段前面加上三个点 ...。

php artisan folio:page "users/[...ids]"
 
# pages/users/[...ids].blade.php → /users/1/2/3

捕获多个段时，捕获的段将作为数组注入到页面中。

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

路由模型绑定

如果页面模板文件名的通配符段与应用程序的 Eloquent 模型之一相对应，Folio 将自动利用 Laravel 的路由模型绑定功能，并尝试将解析的模型实例注入到您的页面中。

php artisan folio:page "users/[User]"
 
# pages/users/[User].blade.php → /users/1

捕获的模型可以在您的 Blade 模板中作为变量访问。模型的变量名将转换为“骆驼大小写”。

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

自定义键

有时您可能希望使用除 id 之外的其他列来解析绑定的 Eloquent 模型。为此，您可以在页面的文件名中指定该列。例如，文件名 [Post:slug].blade.php 的页面将尝试通过 slug 列而不是 id 列来解析绑定的模型。

在 Windows 上，您应该使用 - 来分隔模型名称和键：[Post-slug].blade.php。

模型位置

默认情况下，Folio 将在应用程序的 app/Models 目录中搜索您的模型。但是，如果需要，您可以在模板的文件名中指定完全限定的模型类名。

php artisan folio:page "users/[.App.Models.User]"
 
# pages/users/[.App.Models.User].blade.php → /users/1

软删除模型

默认情况下，软删除的模型在解析隐式模型绑定时不会被检索。但是，如果您希望检索软删除的模型，可以在页面的模板中调用 withTrashed 函数。

<?php
 
use function Laravel\Folio\{withTrashed};
 
withTrashed();
 
?>
 
<div>
    User {{ $user->id }}
</div>

渲染钩子

默认情况下，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>

命名路由

您可以使用 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 函数将中间件应用于特定页面。

<?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);
        },
    ],
]);

路由缓存

使用 Folio 时，您应该始终利用 Laravel 的路由缓存功能。Folio 监听 route:cache Artisan 命令以确保 Folio 页面定义和路由名称被正确缓存以实现最佳性能。