route — 名前付きルートからURLを生成するヘルパ

カテゴリ: helper
対応バージョン: Laravel 11・12・PHP 8.2（※指定なしのため既定）
名前空間 / FQCN / コマンド: グローバル関数 route()
関連: url / action / to_route / redirect()->route() / URL::signedRoute()
変更履歴: 主要仕様に大きな変更なし（to_route() は Laravel 9 で追加）

要点（TL;DR）
概要
構文 / シグネチャ
使用例
よくある落とし穴・注意
代替・関連APIとの比較
テスト例（Pest）
トラブルシュート（エラー別）
参考リンク
関連記事

要点（TL;DR）

用途: 名前付きルートから安全にURLを生成する
最小: route('posts.show', $post)
罠:
- ルート名 or 必須パラメータの不足で UrlGenerationException
- プレースホルダ名と配列キーの不一致
- HTTP/HTTPS 混在は APP_URL や URL::forceScheme('https') で調整

概要

route() は、定義済みの名前付きルートに対して、必要なプレースホルダを埋めて完全なURL（既定は絶対URL）を返します。Eloquentモデル（UrlRoutable）を渡すと、ルートキー（通常はidやslug）で自動解決されます。余剰キーはクエリ文字列として付与されます。

構文 / シグネチャ

function route(string $name, array|\Illuminate\Contracts\Routing\UrlRoutable|int|string $parameters = [], bool $absolute = true): string

引数（表）

引数	型	必須	既定値	説明
`$name`	string	✓	—	ルート名（`Route::name()` で付与した名前）
`$parameters`	array \| UrlRoutable \| int \| string		`[]`	ルートの `{param}` に対応する値。配列キーはプレースホルダ名と一致させる。モデル可。余剰キーはクエリに。
`$absolute`	bool		`true`	`true`で絶対URL、`false`で相対パス

戻り値：string（生成されたURL）
例外/副作用：
- Illuminate\Routing\Exceptions\UrlGenerationException（ルート未定義・必須パラメータ不足・ドメイン不一致等）
- スキームやホストは APP_URL / URL::forceRootUrl() / URL::forceScheme() の影響を受ける

使用例

最小例

use Illuminate\Support\Facades\Route;

// ルート定義
Route::get('/posts/{post}', fn ($post) => '...')->name('posts.show');

// URL生成
$url = route('posts.show', ['post' => 10]); 
// 例: https://example.com/posts/10

実務例

use App\Models\Post;
use Illuminate\Support\Facades\Route;
use Illuminate\Support\Facades\URL;

// 1) モデルでプレースホルダ解決（Route Model Binding）
Route::get('/posts/{post}', fn (Post $post) => '...')->name('posts.show');

$post = Post::findOrFail(42);
$url  = route('posts.show', $post); // /posts/42

// 2) クエリを付ける（余剰キーはクエリ化）
$list = route('posts.index', ['page' => 2, 'q' => 'laravel']); // /posts?page=2&q=laravel

// 3) 相対URLが欲しい場合
$path = route('posts.show', ['post' => 42], false); // /posts/42

// 4) サブドメイン付きルート
// Route::domain('{account}.example.com')->group(...);
// route('dashboard', ['account' => 'acme']);

// 5) HTTPS を強制（本番ブートストラップ等）
URL::forceScheme('https');

よくある落とし穴・注意

プレースホルダ名不一致：/users/{user}/posts/{post} なら ['user' => 1, 'post' => 2] のキーが必要。順序で渡すよりキー指定が安全。
モデル渡しの要件：モデルは getRouteKey()（既定は主キー）で解決。RouteServiceProviderやgetRouteKeyName()を変えている場合は値が変わる。
余剰パラメータはクエリ化：プレースホルダに該当しないキーは ?key=value になる。想定外のクエリ漏れに注意。
HTTP/HTTPS/ホスト問題：プロキシ配下や異なるドメインでURLが崩れるときは APP_URL、URL::forceRootUrl()、URL::forceScheme('https') を調整。
署名付きURLではない：有効期限や改ざん検知が必要なら URL::signedRoute() / URL::temporarySignedRoute() を使う。
テストの固定化：テストでホストが環境に依存するなら URL::forceRootUrl('https://example.test') を設定。

代替・関連APIとの比較

url()：任意パスからURL生成。ルート名は使わない。既存パスに強い。
action()：コントローラの[Class@method]からURL生成。実装名で紐づけたいとき。
redirect()->route() / to_route()：リダイレクト用。route()は文字列URL、to_route()は**RedirectResponse**。
URL::signedRoute()：署名付きURL。重要リンクやメール認証等に。

テスト例（Pest）

use Illuminate\Support\Facades\Route;
use Illuminate\Support\Facades\URL;

it('generates url from named route', function () {
    URL::forceRootUrl('https://example.test');

    Route::get('/posts/{post}', fn () => 'ok')->name('posts.show');

    expect(route('posts.show', ['post' => 123]))
        ->toBe('https://example.test/posts/123');
});

it('adds extra keys as query string', function () {
    URL::forceRootUrl('https://example.test');

    Route::get('/search', fn () => 'ok')->name('posts.index');

    expect(route('posts.index', ['q' => 'laravel', 'page' => 2]))
        ->toBe('https://example.test/search?q=laravel&page=2');
});

トラブルシュート（エラー別）

症状/エラー	原因	対処
`Route [xxx] not defined.`	ルート名の綴り違い／未登録	ルート定義と名前を確認。`php artisan route:list`で一覧確認。
`UrlGenerationException`（必須パラメータ不足）	`{param}`に対応するキーが無い	配列キーをプレースホルダ名に合わせて渡す。モデル可。
生成URLがHTTPになる	スキーム未強制／`APP_URL`がhttp	`APP_URL=https://...`、本番で `URL::forceScheme('https')`。
想定外のクエリが付く	余剰キーを渡している	渡す配列から不要キーを除去。
サブドメインが反映されない	ドメイン付きルートのプレースホルダ不足	`['account' => 'acme']` など、ドメイン側のキーも提供する。

参考リンク

Laravel Docs — URLs: route() ヘルパ（公式）
https://laravel.com/docs/11.x/urls#the-route-helper
Laravel Docs — ルーティング（名前付きルート）
https://laravel.com/docs/11.x/routing#named-routes
Laravel Docs — 署名付きURL
https://laravel.com/docs/11.x/urls#signed-urls
Laravel Docs — リダイレクト
https://laravel.com/docs/11.x/redirects
Laravel API — Illuminate\Routing\UrlGenerator::route()
https://laravel.com/api/11.x/Illuminate/Routing/UrlGenerator.html#method_route

要点（TL;DR）

概要

構文 / シグネチャ

使用例

よくある落とし穴・注意

代替・関連APIとの比較

テスト例（Pest）

トラブルシュート（エラー別）

参考リンク

関連記事