メインコンテンツまでスキップ

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

エロクアントモデル​

通常、エロクアントモデルのルートキー（通常はプライマリキー）を使用してURLを生成することがよくあります。そのため、パラメータ値としてエロクアントモデルを渡すことができます。routeヘルパーは自動的にモデルのルートキーを抽出します：

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

署名付きURL​

Laravelでは、名前付きルートに対して簡単に「署名付き」URLを作成することができます。これらのURLには、URLが作成された後に変更されていないことをLaravelが検証できる「署名」ハッシュがクエリ文字列に追加されます。署名付き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('error.link-expired', [], 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, // [tl! add]
        \Illuminate\Routing\Middleware\SubstituteBindings::class,
        \Illuminate\Auth\Middleware\Authorize::class,
    ]);
})