URL 生成

简介
基础知识
- 生成 URL
- 访问当前 URL
命名路由的 URL
- 签名 URL
控制器行为的 URL
默认值

简介

Laravel 提供了多个辅助函数来帮助你为应用程序生成 URL。这些辅助函数在模板和 API 响应中构建链接，或者在生成重定向响应到应用程序的另一部分时特别有用。

基础知识

生成 URL

可以使用 url 辅助函数为你的应用程序生成任意 URL。生成的 URL 将自动使用应用程序当前正在处理的请求的 scheme（HTTP 或 HTTPS）和 host。

1$post = App\Models\Post::find(1);
2 
3echo url("/posts/{$post->id}");
4 
5// http://example.com/posts/1

$post = App\Models\Post::find(1);

echo url("/posts/{$post->id}");

// http://example.com/posts/1

要生成带有查询字符串参数的 URL，你可以使用 query 方法。

1echo url()->query('/posts', ['search' => 'Laravel']);
2 
3// https://example.com/posts?search=Laravel
4 
5echo url()->query('/posts?sort=latest', ['search' => 'Laravel']);
6 
7// http://example.com/posts?sort=latest&search=Laravel

echo url()->query('/posts', ['search' => 'Laravel']);

// https://example.com/posts?search=Laravel

echo url()->query('/posts?sort=latest', ['search' => 'Laravel']);

// http://example.com/posts?sort=latest&search=Laravel

提供已存在于路径中的查询字符串参数将覆盖其现有值。

1echo url()->query('/posts?sort=latest', ['sort' => 'oldest']);
2 
3// http://example.com/posts?sort=oldest

echo url()->query('/posts?sort=latest', ['sort' => 'oldest']);

// http://example.com/posts?sort=oldest

值数组也可以作为查询参数传递。这些值将在生成的 URL 中被正确地键控和编码。

1echo $url = url()->query('/posts', ['columns' => ['title', 'body']]);
2 
3// http://example.com/posts?columns%5B0%5D=title&columns%5B1%5D=body
4 
5echo urldecode($url);
6 
7// http://example.com/posts?columns[0]=title&columns[1]=body

echo $url = url()->query('/posts', ['columns' => ['title', 'body']]);

// http://example.com/posts?columns%5B0%5D=title&columns%5B1%5D=body

echo urldecode($url);

// http://example.com/posts?columns[0]=title&columns[1]=body

访问当前 URL

如果没有为 url 辅助函数提供路径，则会返回一个 Illuminate\Routing\UrlGenerator 实例，允许你访问有关当前 URL 的信息。

 1// Get the current URL without the query string...
 2echo url()->current();
 3 
 4// Get the current URL including the query string...
 5echo url()->full();
 6 
 7// Get the full URL for the previous request...
 8echo url()->previous();
 9 
10// Get the path for the previous request...
11echo url()->previousPath();

// Get the current URL without the query string...
echo url()->current();

// Get the current URL including the query string...
echo url()->full();

// Get the full URL for the previous request...
echo url()->previous();

// Get the path for the previous request...
echo url()->previousPath();

这些方法中的每一个也可以通过 URL 外观模式访问。

1use Illuminate\Support\Facades\URL;
2 
3echo URL::current();

use Illuminate\Support\Facades\URL;

echo URL::current();

命名路由的 URL

可以使用 route 辅助函数生成指向命名路由的 URL。命名路由允许你生成 URL，而无需耦合到路由上定义的实际 URL。因此，如果路由的 URL 发生更改，则无需对 route 函数的调用进行任何更改。例如，假设你的应用程序包含一个像下面这样定义的路由：

1Route::get('/post/{post}', function (Post $post) {
2    // ...
3})->name('post.show');

Route::get('/post/{post}', function (Post $post) {
    // ...
})->name('post.show');

要为此路由生成 URL，你可以像这样使用 route 辅助函数：

1echo route('post.show', ['post' => 1]);
2 
3// http://example.com/post/1

echo route('post.show', ['post' => 1]);

// http://example.com/post/1

当然，route 辅助函数也可以用于为具有多个参数的路由生成 URL。

1Route::get('/post/{post}/comment/{comment}', function (Post $post, Comment $comment) {
2    // ...
3})->name('comment.show');
4 
5echo route('comment.show', ['post' => 1, 'comment' => 3]);
6 
7// http://example.com/post/1/comment/3

Route::get('/post/{post}/comment/{comment}', function (Post $post, Comment $comment) {
    // ...
})->name('comment.show');

echo route('comment.show', ['post' => 1, 'comment' => 3]);

// http://example.com/post/1/comment/3

任何与路由定义参数不对应的额外数组元素都将添加到 URL 的查询字符串中。

1echo route('post.show', ['post' => 1, 'search' => 'rocket']);
2 
3// http://example.com/post/1?search=rocket

echo route('post.show', ['post' => 1, 'search' => 'rocket']);

// http://example.com/post/1?search=rocket

Eloquent 模型

你经常会使用 Eloquent 模型的路由键（通常是主键）生成 URL。因此，你可以将 Eloquent 模型作为参数值传递。route 辅助函数将自动提取模型的路由键。

1echo route('post.show', ['post' => $post]);

echo route('post.show', ['post' => $post]);

签名 URL

Laravel 允许你轻松创建指向命名路由的“签名”URL。这些 URL 在查询字符串中附加了一个“signature”哈希值，Laravel 可以使用它来验证 URL 自创建以来是否已被修改。签名 URL 对于公开访问但需要一层保护以防止 URL 篡改的路由特别有用。

例如，你可以使用签名 URL 来实现一个通过电子邮件发送给客户的公共“取消订阅”链接。要创建指向命名路由的签名 URL，请使用 URL 外观模式的 signedRoute 方法。

1use Illuminate\Support\Facades\URL;
2 
3return URL::signedRoute('unsubscribe', ['user' => 1]);

use Illuminate\Support\Facades\URL;

return URL::signedRoute('unsubscribe', ['user' => 1]);

你可以通过向 signedRoute 方法提供 absolute 参数，从签名 URL 哈希中排除域名。

1return URL::signedRoute('unsubscribe', ['user' => 1], absolute: false);

return URL::signedRoute('unsubscribe', ['user' => 1], absolute: false);

如果你想生成一个临时的签名路由 URL，该 URL 在指定时间后过期，你可以使用 temporarySignedRoute 方法。当 Laravel 验证临时签名路由 URL 时，它将确保编码到签名 URL 中的过期时间戳尚未经过。

1use Illuminate\Support\Facades\URL;
2 
3return URL::temporarySignedRoute(
4    'unsubscribe', now()->addMinutes(30), ['user' => 1]
5);

use Illuminate\Support\Facades\URL;

return URL::temporarySignedRoute(
    'unsubscribe', now()->addMinutes(30), ['user' => 1]
);

验证签名路由请求

要验证传入的请求是否具有有效签名，你应该在传入的 Illuminate\Http\Request 实例上调用 hasValidSignature 方法。

1use Illuminate\Http\Request;
2 
3Route::get('/unsubscribe/{user}', function (Request $request) {
4    if (! $request->hasValidSignature()) {
5        abort(401);
6    }
7 
8    // ...
9})->name('unsubscribe');

use Illuminate\Http\Request;

Route::get('/unsubscribe/{user}', function (Request $request) {
    if (! $request->hasValidSignature()) {
        abort(401);
    }

    // ...
})->name('unsubscribe');

有时，你可能需要允许应用程序的前端将数据附加到签名 URL，例如在执行客户端分页时。因此，你可以使用 hasValidSignatureWhileIgnoring 方法指定在验证签名 URL 时应忽略的请求查询参数。请记住，忽略参数允许任何人修改请求上的这些参数。

1if (! $request->hasValidSignatureWhileIgnoring(['page', 'order'])) {
2    abort(401);
3}

if (! $request->hasValidSignatureWhileIgnoring(['page', 'order'])) {
    abort(401);
}

除了使用传入的请求实例验证签名 URL 之外，你还可以将 signed (Illuminate\Routing\Middleware\ValidateSignature) 中间件分配给路由。如果传入的请求没有有效签名，则中间件将自动返回 403 HTTP 响应。

1Route::post('/unsubscribe/{user}', function (Request $request) {
2    // ...
3})->name('unsubscribe')->middleware('signed');

Route::post('/unsubscribe/{user}', function (Request $request) {
    // ...
})->name('unsubscribe')->middleware('signed');

如果你的签名 URL 不在 URL 哈希中包含域名，你应该向中间件提供 relative 参数。

1Route::post('/unsubscribe/{user}', function (Request $request) {
2    // ...
3})->name('unsubscribe')->middleware('signed:relative');

Route::post('/unsubscribe/{user}', function (Request $request) {
    // ...
})->name('unsubscribe')->middleware('signed:relative');

响应无效签名路由

当有人访问过期的签名 URL 时，他们将收到 403 HTTP 状态代码的通用错误页面。但是，你可以通过在应用程序的 bootstrap/app.php 文件中为 InvalidSignatureException 异常定义自定义“render”闭包来自定义此行为。

1use Illuminate\Routing\Exceptions\InvalidSignatureException;
2 
3->withExceptions(function (Exceptions $exceptions) {
4    $exceptions->render(function (InvalidSignatureException $e) {
5        return response()->view('errors.link-expired', status: 403);
6    });
7})

use Illuminate\Routing\Exceptions\InvalidSignatureException;

->withExceptions(function (Exceptions $exceptions) {
    $exceptions->render(function (InvalidSignatureException $e) {
        return response()->view('errors.link-expired', status: 403);
    });
})

控制器行为的 URL

action 函数为给定的控制器行为生成 URL。

1use App\Http\Controllers\HomeController;
2 
3$url = action([HomeController::class, 'index']);

use App\Http\Controllers\HomeController;

$url = action([HomeController::class, 'index']);

如果控制器方法接受路由参数，你可以将路由参数的关联数组作为函数的第二个参数传递。

1$url = action([UserController::class, 'profile'], ['id' => 1]);

$url = action([UserController::class, 'profile'], ['id' => 1]);

默认值

对于某些应用程序，你可能希望为某些 URL 参数指定请求范围的默认值。例如，假设你的许多路由定义了一个 {locale} 参数。

1Route::get('/{locale}/posts', function () {
2    // ...
3})->name('post.index');

Route::get('/{locale}/posts', function () {
    // ...
})->name('post.index');

每次调用 route 辅助函数时都传递 locale 参数是很麻烦的。因此，你可以使用 URL::defaults 方法为此参数定义一个默认值，该默认值将始终在当前请求期间应用。你可能希望从路由中间件调用此方法，以便你可以访问当前请求。

 1<?php
 2 
 3namespace App\Http\Middleware;
 4 
 5use Closure;
 6use Illuminate\Http\Request;
 7use Illuminate\Support\Facades\URL;
 8use Symfony\Component\HttpFoundation\Response;
 9 
10class SetDefaultLocaleForUrls
11{
12    /**
13     * Handle an incoming request.
14     *
15     * @param  \Closure(\Illuminate\Http\Request): (\Symfony\Component\HttpFoundation\Response)  $next
16     */
17    public function handle(Request $request, Closure $next): Response
18    {
19        URL::defaults(['locale' => $request->user()->locale]);
20 
21        return $next($request);
22    }
23}

<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\URL;
use Symfony\Component\HttpFoundation\Response;

class SetDefaultLocaleForUrls
{
    /**
     * Handle an incoming request.
     *
     * @param  \Closure(\Illuminate\Http\Request): (\Symfony\Component\HttpFoundation\Response)  $next
     */
    public function handle(Request $request, Closure $next): Response
    {
        URL::defaults(['locale' => $request->user()->locale]);

        return $next($request);
    }
}

一旦设置了 locale 参数的默认值，你在通过 route 辅助函数生成 URL 时不再需要传递其值。

URL 默认值和中间件优先级

设置 URL 默认值可能会干扰 Laravel 对隐式模型绑定的处理。因此，你应该优先处理你的中间件，将设置 URL 默认值的中间件优先于 Laravel 自己的 SubstituteBindings 中间件执行。你可以使用应用程序的 bootstrap/app.php 文件中的 priority 中间件方法来实现这一点。

1->withMiddleware(function (Middleware $middleware) {
2    $middleware->prependToPriorityList(
3        before: \Illuminate\Routing\Middleware\SubstituteBindings::class,
4        prepend: \App\Http\Middleware\SetDefaultLocaleForUrls::class,
5    );
6})

->withMiddleware(function (Middleware $middleware) {
    $middleware->prependToPriorityList(
        before: \Illuminate\Routing\Middleware\SubstituteBindings::class,
        prepend: \App\Http\Middleware\SetDefaultLocaleForUrls::class,
    );
})

序言

快速入门

架构概念

基础知识

深入

安全

数据库

Eloquent ORM

测试

软件包

URL 生成

简介

基础知识

生成 URL

访问当前 URL

命名路由的 URL

Eloquent 模型

签名 URL

验证签名路由请求

响应无效签名路由

控制器行为的 URL

默认值

URL 默认值和中间件优先级

产品

软件包

资源