Documentation Index
Fetch the complete documentation index at: https://kawax.biz/llms.txt
Use this file to discover all available pages before exploring further.
はじめに
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
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
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に関する情報にアクセスできます。
// クエリ文字列なしの現在のURL
echo url()->current();
// クエリ文字列を含む現在のURL
echo url()->full();
URL ファサードからもアクセスできます。
use Illuminate\Support\Facades\URL;
echo URL::current();
直前のURLの取得
ユーザーが訪問していた直前のURLを知りたい場合があります。url ヘルパーの previous メソッドや previousPath メソッドで取得できます。
// 直前のリクエストの完全なURL
echo url()->previous();
// 直前のリクエストのパス
echo url()->previousPath();
use Illuminate\Http\Request;
Route::post('/users', function (Request $request) {
$previousUri = $request->session()->previousUri();
// ...
});
$previousRoute = $request->session()->previousRoute();
名前付きルートのURL
route ヘルパーは名前付きルートへのURLを生成するために使えます。
名前付きルートを使うと、ルートに定義された実際のURLに依存せずにURLを生成できます。
そのため、ルートのURLが変更されても、route 関数の呼び出しを変更する必要がありません。
Route::get('/post/{post}', function (Post $post) {
// ...
})->name('post.show');
echo route('post.show', ['post' => 1]);
// http://example.com/post/1
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
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にはクエリ文字列に「署名」ハッシュが付加され、URLが作成後に改ざんされていないことをLaravelが検証できます。
署名付きURLは、公開アクセス可能だがURL操作に対する保護が必要なルートに特に便利です。
たとえば、顧客にメールで送信する公開「登録解除」リンクを実装するために署名付きURLを使えます。
URL ファサードの signedRoute メソッドを使って署名付きURLを作成します。
use Illuminate\Support\Facades\URL;
return URL::signedRoute('unsubscribe', ['user' => 1]);
signedRoute メソッドに absolute 引数を指定することで、署名URLハッシュからドメインを除外できます。
return URL::signedRoute('unsubscribe', ['user' => 1], absolute: false);
temporarySignedRoute メソッドを使います。
Laravelは一時的な署名付きURLを検証する際、署名付きURLにエンコードされた有効期限タイムスタンプが経過していないことを確認します。
use Illuminate\Support\Facades\URL;
return URL::temporarySignedRoute(
'unsubscribe', now()->plus(minutes: 30), ['user' => 1]
);
署名付きURLの検証フロー
署名付きルートリクエストの検証
受信リクエストに有効な署名があることを確認するには、Illuminate\Http\Request インスタンスの hasValidSignature メソッドを呼び出します。
use Illuminate\Http\Request;
Route::get('/unsubscribe/{user}', function (Request $request) {
if (! $request->hasValidSignature()) {
abort(401);
}
// ...
})->name('unsubscribe');
hasValidSignatureWhileIgnoring メソッドを使います。
if (! $request->hasValidSignatureWhileIgnoring(['page', 'order'])) {
abort(401);
}
signed（Illuminate\Routing\Middleware\ValidateSignature）ミドルウェアをルートに割り当てることもできます。
受信リクエストに有効な署名がない場合、ミドルウェアは自動的に 403 HTTPレスポンスを返します。
Route::post('/unsubscribe/{user}', function (Request $request) {
// ...
})->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」クロージャを定義することで、この動作をカスタマイズできます。
use Illuminate\Routing\Exceptions\InvalidSignatureException;
->withExceptions(function (Exceptions $exceptions): void {
$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']);
$url = action([UserController::class, 'profile'], ['id' => 1]);
フルエントURIオブジェクト
LaravelのURIクラスは、オブジェクトを通じてURIを作成・操作するための便利なフルエントインターフェースを提供します。
use App\Http\Controllers\UserController;
use Illuminate\Support\Uri;
// 文字列からURIインスタンスを生成
$uri = Uri::of('https://example.com/path');
// パス、名前付きルート、コントローラーアクションへのURIを生成
$uri = Uri::to('/dashboard');
$uri = Uri::route('users.show', ['user' => 1]);
$uri = Uri::signedRoute('users.show', ['user' => 1]);
$uri = Uri::temporarySignedRoute('user.index', now()->plus(minutes: 5));
$uri = Uri::action([UserController::class, 'index']);
// 現在のリクエストURLからURIインスタンスを生成
$uri = $request->uri();
$uri = Uri::of('https://example.com')
->withScheme('http')
->withHost('test.com')
->withPort(8000)
->withPath('/users')
->withQuery(['page' => 2])
->withFragment('section-1');
デフォルトのURLパラメータ
特定の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
{
/**
* 受信リクエストを処理する。
*
* @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デフォルト値の設定はLaravelの暗黙的なモデルバインディングの処理を妨げる場合があります。
URLデフォルト値を設定するミドルウェアをLaravel自身の SubstituteBindings ミドルウェアより前に実行されるようミドルウェアの優先度設定を行ってください。
アプリケーションの bootstrap/app.php ファイルで priority ミドルウェアメソッドを使って設定できます。->withMiddleware(function (Middleware $middleware): void {
$middleware->prependToPriorityList(
before: \Illuminate\Routing\Middleware\SubstituteBindings::class,
prepend: \App\Http\Middleware\SetDefaultLocaleForUrls::class,
);
})
