README

Laravel URL 路由尾部斜杠

此扩展允许强制URL路由使用或不需要尾部斜杠。

有关许可信息，请查看 LICENSE 文件。

安装

安装此扩展的首选方式是通过 composer。

运行以下命令

php composer.phar require --prefer-dist illuminatech/url-trailing-slash

或者将以下内容添加到您的 composer.json 文件的 require 部分。

"illuminatech/url-trailing-slash": "*"

一旦安装了包，您应该在应用程序中手动注册 \Illuminatech\UrlTrailingSlash\RoutingServiceProvider 实例，方法是在内核实例化之前进行，例如在应用程序引导阶段。这可以在常规 Laravel 应用程序的 'bootstrap/app.php' 文件中完成。例如

注意：由于 \Illuminatech\UrlTrailingSlash\RoutingServiceProvider 改变了路由，它绑定到构造函数级别的 HTTP 内核实例，因此不能以正常方式注册或被 Laravel 自动发现。

<?php

use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Exceptions;
use Illuminate\Foundation\Configuration\Middleware;

$app = Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        // ...
    )
    ->withMiddleware(function (Middleware $middleware) {
        // ...
    })
    // ...
    ->create();

$app->register(new Illuminatech\UrlTrailingSlash\RoutingServiceProvider($app)); // register trailing slashes routing

return $app;

为了设置具有尾部斜杠的路由的自动重定向，请将 \Illuminatech\UrlTrailingSlash\Middleware\RedirectTrailingSlash 中间件添加到您的 HTTP 内核。例如

请注意！请确保您在服务器配置级别没有尾部斜杠重定向机制，这可能与 \Illuminatech\UrlTrailingSlash\Middleware\RedirectTrailingSlash 冲突。请记住，默认情况下，Laravel 应用程序附带一个 .htaccess 文件，该文件包含强制项目 URL 不包含尾部斜杠的重定向规则。请确保您调整或禁用它，否则您的应用程序可能陷入无限重定向循环。

<?php

use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Exceptions;
use Illuminate\Foundation\Configuration\Middleware;

$app = Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        // ...
    )
    ->withMiddleware(function (Middleware $middleware) {
        $middleware->prependToGroup('web', Illuminatech\UrlTrailingSlash\Middleware\RedirectTrailingSlash::class); // enable automatic redirection on incorrect URL trailing slashes
        // probably you do not need trailing slash redirection anywhere besides public web routes,
        // thus there is no reason for addition its middleware to other groups, like API
        // ...
    })
    // ...
    ->create();

$app->register(new Illuminatech\UrlTrailingSlash\RoutingServiceProvider($app)); // register trailing slashes routing

return $app;

用法

此扩展允许强制URL路由使用或不需要尾部斜杠。您可以决定对于每个路由，其URL是否应该有尾部斜杠，只需在特定路由定义中添加或删除斜杠符号 ('/') 即可。

如果指定了具有尾部斜杠的特定路由的URL，则将强制执行此路由，并且URL末尾没有斜杠的请求将导致301重定向。如果指定了没有尾部斜杠的特定路由的URL，则将强制执行此路由的尾部斜杠的缺失，并且包含斜杠的URL末尾的请求将导致301重定向。

例如

提示：最佳 SEO 实践是在具有嵌套页面的 URL 中使用尾部斜杠，例如 "定义一个文件夹"，而在没有嵌套页面的 URL 中没有尾部斜杠，例如 "文件的路径名"。

<?php

namespace App\Http\Controllers;

use Illuminate\Support\Facades\Route;

Route::get('items/', ItemController::class.'@index')->name('items.index'); // enforce trailing slash
Route::get('items/{item}', ItemController::class.'@show')->name('items.show'); // enforce no trailing slash

// ...

echo route('items.index'); // outputs: 'http://example.com/items/'
echo route('items.show', [1]); // outputs: 'http://example.com/items/1'

如果您设置了 \Illuminatech\UrlTrailingSlash\Middleware\RedirectTrailingSlash 中间件，应用程序将自动根据路由定义重定向不正确的URL。例如，上述请求 http://example.com/items 导致重定向到 http://example.com/items/，而请求 http://example.com/items/1/ 导致重定向到 http://example.com/items/1。

请注意！安装此扩展后，您正在控制每个您定义的路由中 URL 尾部斜杠存在或不存在的要求。虽然 Laravel 通常会自动从路由 URL 中删除任何尾部斜杠，但此扩展赋予了它们意义。您应仔细检查路由定义，确保您没有为错误的路由设置尾部斜杠。

请注意！此扩展安装后，您正在控制每个您定义的路由中 URL 尾部斜杠存在或不存在的要求。虽然 Laravel 通常会自动从路由 URL 中删除任何尾部斜杠，但此扩展赋予了它们意义。您应仔细检查路由定义，确保您没有为错误的路由设置尾部斜杠。

根 URL 中的斜杠

不幸的是，这个扩展无法处理项目根URL的尾部斜杠，例如对于“主页”。换句话说，\Illuminatech\UrlTrailingSlash\Middleware\RedirectTrailingSlash 中间件无法区分 URL，例如 http://examle.com 和 http://examle.com/。这种限制是由于 PHP 本身造成的，因为在这两种情况下，$_SERVER['REQUEST_URI'] 的值都等于 '/'。

您必须在服务器设置级别单独处理根URL的尾部斜杠。

资源路由

您可以使用与常规路由相同的标记来定义资源URL的尾部斜杠存在。如果资源名称指定了尾部斜杠，则其所有URL都将包含它。例如

<?php

namespace App\Http\Controllers;

use Illuminate\Support\Facades\Route;

Route::resource('items/', ItemController::class); // enforce trailing slash
Route::resource('categories', CategoryController::class); // enforce no trailing slash

// ...

echo route('items.index'); // outputs: 'http://example.com/items/'
echo route('items.show', [1]); // outputs: 'http://example.com/items/1/'

echo route('categories.index'); // outputs: 'http://example.com/categories'
echo route('categories.show', [1]); // outputs: 'http://example.com/categories/1'

您可以使用选项 'trailingSlashOnly' 和 'trailingSlashExcept' 来控制每个资源路由的尾部斜杠存在。这些选项的行为与常规的 'only' 和 'except' 类似，指定了应该或不应该在它们的URL中包含尾部斜杠的资源控制器方法列表。例如

<?php

namespace App\Http\Controllers;

use Illuminate\Support\Facades\Route;

Route::resource('items', ItemController::class, ['trailingSlashOnly' => 'index']); // trailing slash will be present only for 'index'
Route::resource('categories', CategoryController::class, ['trailingSlashExcept' => 'show']); // trailing slash will be present for all but 'show'

// ...

echo route('items.index'); // outputs: 'http://example.com/items/'
echo route('items.show', [1]); // outputs: 'http://example.com/items/1'

echo route('categories.index'); // outputs: 'http://example.com/categories/'
echo route('categories.show', [1]); // outputs: 'http://example.com/categories/1'

注意：'trailingSlashExcept' 选项优先于 'trailingSlashOnly'。

分页中的尾部斜杠

不幸的是，尾部斜杠不会自动出现在分页URL中。问题是 Laravel 分页器在构造函数级别会从 URL 路径中移除尾部斜杠。因此，即使调整 \Illuminate\Pagination\Paginator::currentPathResolver() 也无法解决这个问题。

如果您需要在 URL 端点进行带有尾部斜杠的分页，您应该手动设置其路径，使用 \Illuminate\Pagination\AbstractPaginator::withPath()。例如

<?php

use App\Models\Item;
use Illuminate\Support\Facades\URL;

$items = Item::query()
    ->paginate()
    ->withPath(URL::current());

单元测试中的尾部斜杠

由于 Illuminatech\UrlTrailingSlash\RoutingServiceProvider 无法作为常规数据提供者注册，因此在编写单元和功能测试时，您必须在测试应用程序实例化测试内核之前手动注册它。这可以在您的 \Tests\CreatesApplication 特性中完成。

<?php

namespace Tests;

use Illuminate\Contracts\Console\Kernel;
use Illuminatech\UrlTrailingSlash\RoutingServiceProvider;

trait CreatesApplication
{
    /**
     * Creates the application.
     *
     * @return \Illuminate\Foundation\Application
     */
    public function createApplication()
    {
        $app = require __DIR__.'/../bootstrap/app.php';

        $app->register(new RoutingServiceProvider($app)); // register trailing slashes routing

        $app->make(Kernel::class)->bootstrap();

        return $app;
    }
}

然而，这不足以使测试正确运行，因为 Laravel 在开始测试 HTTP 请求之前会自动从请求 URL 中移除尾部斜杠。因此，您需要以尊重尾部斜杠的方式覆盖 \Illuminate\Foundation\Testing\Concerns\MakesHttpRequests::prepareUrlForRequest()。这可以通过使用 Illuminatech\UrlTrailingSlash\Testing\AllowsUrlTrailingSlash 特性来实现。例如

<?php

namespace Tests;

use Illuminate\Foundation\Testing\TestCase as BaseTestCase;
use Illuminatech\UrlTrailingSlash\Testing\AllowsUrlTrailingSlash;

abstract class TestCase extends BaseTestCase
{
    use CreatesApplication;
    use AllowsUrlTrailingSlash;
}

illuminatech / url-trailing-slash

维护者

详细信息