URL生成

• はじめに
• 基本
  • URLの生成
  • 現在のURLへのアクセス
• 名前付きルートのURL
  • 署名付きURL
• コントローラアクションのURL
• デフォルト値

はじめに

Laravelには、アプリケーションのURL生成を支援するためのいくつかのヘルパーが用意されています。これらのヘルパーは、主にテンプレートやAPIレスポンスでリンクを構築したり、アプリケーションの別の部分へのリダイレクトレスポンスを生成したりする場合に役立ちます。

基本

URLの生成

urlヘルパーを使用して、アプリケーションの任意のURLを生成できます。生成されたURLは、アプリケーションによって処理されている現在のリクエストから、スキーム（HTTPまたはHTTPS）とホストを自動的に使用します。

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

クエリ文字列パラメータ付きのURLを生成するには、queryメソッドを使用できます。

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

パスにすでに存在するクエリ文字列パラメータを提供すると、既存の値が上書きされます。

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

値の配列をクエリパラメータとして渡すこともできます。これらの値は適切にキー設定され、生成されたURLでエンコードされます。

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に関する情報にアクセスできます。

// 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();

これらの各メソッドには、URLファサードを介してアクセスすることもできます。

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

名前付きルートのURL

routeヘルパーを使用して、名前付きルートへのURLを生成できます。名前付きルートを使用すると、ルートで定義された実際のURLに結合せずにURLを生成できます。したがって、ルートのURLが変更されても、route関数への呼び出しを変更する必要はありません。たとえば、アプリケーションに次のように定義されたルートが含まれているとします。

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

このルートへのURLを生成するには、次のようにrouteヘルパーを使用できます。

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

もちろん、routeヘルパーは、複数のパラメータを持つルートのURLを生成するためにも使用できます。

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のクエリ文字列に追加されます。

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

Eloquentモデル

多くの場合、Eloquentモデルのルートキー（通常は主キー）を使用してURLを生成します。このため、Eloquentモデルをパラメータ値として渡すことができます。routeヘルパーは、モデルのルートキーを自動的に抽出します。

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

署名付きURL

Laravelを使用すると、名前付きルートへの「署名付き」URLを簡単に作成できます。これらのURLには、クエリ文字列に「署名」ハッシュが付加されており、これによりLaravelはURLが作成されてから変更されていないことを確認できます。署名付きURLは、一般にアクセス可能でありながら、URL操作に対する保護レイヤーが必要なルートに特に役立ちます。

たとえば、署名付きURLを使用して、顧客にメールで送信されるパブリックな「購読解除」リンクを実装できます。名前付きルートへの署名付きURLを作成するには、URLファサードのsignedRouteメソッドを使用します。

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

signedRouteメソッドにabsolute引数を指定することで、署名付きURLハッシュからドメインを除外できます。

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

指定された時間後に期限切れになる一時的な署名付きルートURLを生成する場合は、temporarySignedRouteメソッドを使用できます。Laravelが一時的な署名付きルートURLを検証するとき、署名付きURLにエンコードされている有効期限タイムスタンプが経過していないことを確認します。

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

署名付きルートリクエストの検証

受信リクエストに有効な署名があることを確認するには、受信したIlluminate\Http\RequestインスタンスでhasValidSignatureメソッドを呼び出す必要があります。

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

場合によっては、クライアント側のページネーションを実行する場合など、アプリケーションのフロントエンドで署名付きURLにデータを追加できるようにする必要があります。したがって、hasValidSignatureWhileIgnoringメソッドを使用して、署名付きURLを検証するときに無視する必要があるリクエストクエリパラメータを指定できます。パラメータを無視すると、誰でもリクエストでそれらのパラメータを変更できることに注意してください。

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

受信リクエストインスタンスを使用して署名付きURLを検証する代わりに、ルートにsigned (Illuminate\Routing\Middleware\ValidateSignature) ミドルウェアを割り当てることができます。受信リクエストに有効な署名がない場合、ミドルウェアは自動的に403 HTTPレスポンスを返します。

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

署名付きURLにURLハッシュにドメインが含まれていない場合は、ミドルウェアにrelative引数を指定する必要があります。

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

無効な署名付きルートへの対応

期限切れになった署名付きURLにアクセスすると、403 HTTPステータスコードの一般的なエラーページが表示されます。ただし、アプリケーションのbootstrap/app.phpファイルでInvalidSignatureException例外のカスタム「render」クロージャを定義することにより、この動作をカスタマイズできます。

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を生成します。

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

コントローラメソッドがルートパラメータを受け入れる場合は、関数の2番目の引数としてルートパラメータの連想配列を渡すことができます。

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

デフォルト値

一部のアプリケーションでは、特定のURLパラメータに対してリクエスト全体でのデフォルト値を指定する必要がある場合があります。たとえば、多くのルートが{locale}パラメータを定義しているとします。

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

routeヘルパーを呼び出すたびに常にlocaleを渡すのは面倒です。そのため、URL::defaultsメソッドを使用して、現在のリクエスト中に常に適用されるこのパラメータのデフォルト値を定義できます。現在のリクエストにアクセスできるように、ルートミドルウェアからこのメソッドを呼び出すことをお勧めします。

<?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ミドルウェアメソッドを使用することで実現できます。

->withMiddleware(function (Middleware $middleware) {
    $middleware->priority([
        \Illuminate\Foundation\Http\Middleware\HandlePrecognitiveRequests::class,
        \Illuminate\Cookie\Middleware\EncryptCookies::class,
        \Illuminate\Cookie\Middleware\AddQueuedCookiesToResponse::class,
        \Illuminate\Session\Middleware\StartSession::class,
        \Illuminate\View\Middleware\ShareErrorsFromSession::class,
        \Illuminate\Foundation\Http\Middleware\ValidateCsrfToken::class,
        \Illuminate\Contracts\Auth\Middleware\AuthenticatesRequests::class,
        \Illuminate\Routing\Middleware\ThrottleRequests::class,
        \Illuminate\Routing\Middleware\ThrottleRequestsWithRedis::class,
        \Illuminate\Session\Middleware\AuthenticateSession::class,
        \App\Http\Middleware\SetDefaultLocaleForUrls::class, 
        \Illuminate\Routing\Middleware\SubstituteBindings::class,
        \Illuminate\Auth\Middleware\Authorize::class,
    ]);
})