リクエスト（送られてきたデータ）

リクエストは、ブラウザがサーバーへ送る「お願い」のことです。どのページがほしいか、フォームに何を入力したか、どんな種類のデータを受け取れるか、といった情報が入っています。Laravel の Illuminate\Http\Request クラスを使うと、いま処理しているリクエストから、入力・Cookie（ブラウザに保存される小さなデータ）・アップロードされたファイルなどを、メソッド（クラスの中の関数）で取り出せます。

リクエストを受け取る#

Request を手に入れる#

コントローラーのメソッドやルートのクロージャ（名前のない関数）の引数に Illuminate\Http\Request の型を書くと、サービスコンテナ（クラスを作って渡してくれる道具箱）が、いまのリクエストを自動で渡してくれます。これを依存性の注入といいます。

<?php

namespace App\Http\Controllers;

use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;

class UserController extends Controller
{
    /**
     * Store a new user.
     */
    public function store(Request $request): RedirectResponse
    {
        $name = $request->input('name');

        // ユーザーを保存する

        return redirect('/users');
    }
}

ルートのクロージャでも、同じように型を書けます。

use Illuminate\Http\Request;

Route::get('/', function (Request $request) {
    // ...
});

ルートパラメータもいっしょに受け取る#

ルートパラメータ（URL の {id} の部分）も受け取るときは、ほかの部品の後ろに並べます。たとえば、次のルートがあるとします。

use App\Http\Controllers\UserController;

Route::put('/user/{id}', [UserController::class, 'update']);

Request の型を書きながら id も受け取るには、次のようにします。

<?php

namespace App\Http\Controllers;

use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;

class UserController extends Controller
{
    /**
     * Update the specified user.
     */
    public function update(Request $request, string $id): RedirectResponse
    {
        // ユーザーを更新する

        return redirect('/users');
    }
}

パス・ホスト・メソッドを調べる#

Request は、Symfony\Component\HttpFoundation\Request クラスを引き継いで（継承して）いて、リクエストを調べるメソッドをたくさん持っています。大事なものを紹介します。

パスを取り出す#

path は、リクエストのパスを返します。http://example.com/foo/bar へのリクエストなら、foo/bar です。

$uri = $request->path();

パスやルートを調べる#

is は、パスが決めた形に合うかを調べます。* は「何でもよい」という意味です。

if ($request->is('admin/*')) {
    // ...
}

routeIs は、名前を付けたルートに当たったかを調べます。

if ($request->routeIs('admin.*')) {
    // ...
}

URL を取り出す#

URL 全体は、url か fullUrl で取れます。url はクエリ文字列（URL の ? 以降）を除き、fullUrl は含めます。

$url = $request->url();

$urlWithQueryString = $request->fullUrl();

いまの URL にクエリ文字列を足したいときは、fullUrlWithQuery です。渡した配列が、いまのクエリ文字列に合わさります。

$request->fullUrlWithQuery(['type' => 'phone']);

いまの URL から、あるクエリ文字列を除きたいときは、fullUrlWithoutQuery です。

$request->fullUrlWithoutQuery(['type']);

ホストを取り出す#

ホスト（サーバーの名前）は、host・httpHost・schemeAndHttpHost で取れます。

// http://localhost:8000
$request->host(); // localhost
$request->httpHost(); // localhost:8000
$request->schemeAndHttpHost(); // http://localhost:8000

HTTP メソッドを調べる#

method は、リクエストの HTTP メソッド（GET・POST など）を返します。isMethod は、それが指定した文字と同じかを調べます。

$method = $request->method();

if ($request->isMethod('post')) {
    // ...
}

ヘッダーを取り出す#

ヘッダーは、リクエストに付く「添え書き」です。header メソッドで取れます。なければ null が返ります。2つ目の引数を書くと、ないときにその値が返ります。

$value = $request->header('X-Header-Name');

$value = $request->header('X-Header-Name', 'default');

hasHeader は、あるヘッダーが付いているかを調べます。

if ($request->hasHeader('X-Header-Name')) {
    // ...
}

bearerToken は、Authorization ヘッダーからベアラートークンを取り出します。ヘッダーがなければ、空の文字が返ります。

$token = $request->bearerToken();

IP アドレスを取り出す#

ip は、リクエストを送ってきた相手の IP アドレス（ネットワーク上の住所のようなもの）を返します。

$ipAddress = $request->ip();

プロキシ（間に入る中継役）が転送した IP アドレスもまとめて配列で取りたいときは、ips を使います。「もとの」相手の IP アドレスは、配列の最後です。

$ipAddresses = $request->ips();

IP アドレスは、相手が書きかえることもできる値です。信用せず、参考の情報としてだけ使いましょう。

相手が受け取れる形を調べる（コンテントネゴシエーション）#

リクエストの Accept ヘッダーには、相手が受け取れるデータの種類が書かれています。これを調べるメソッドがあります。

getAcceptableContentTypes は、相手が受け取れる種類を、配列で返します。

$contentTypes = $request->getAcceptableContentTypes();

accepts は、種類の配列を受け取り、どれか1つでも相手が受け取れるなら true を返します。

if ($request->accepts(['text/html', 'application/json'])) {
    // ...
}

prefers は、渡した種類のうち、相手がいちばん望むものを返します。どれも受け取れないなら null です。

$preferred = $request->prefers(['text/html', 'application/json']);

HTML か JSON（データをやり取りするための文字の形式）しか返さないアプリが多いので、expectsJson で、JSON を望むリクエストかをすぐ調べられます。

if ($request->expectsJson()) {
    // ...
}

AI のエージェントなど、Markdown（見出しや箇条書きを記号で書く文字の形式）を読むクライアント（リクエストを送ってくる側のプログラム）に合わせたいときは、wantsMarkdown と acceptsMarkdown を使います。

if ($request->wantsMarkdown()) {
    // 相手がいちばん望む種類は text/markdown
}

if ($request->acceptsMarkdown()) {
    // 相手は Markdown を受け取れる
}

PSR-7 のリクエスト#

PSR-7 は、HTTP のリクエストとレスポンスの形を決めた、PHP の共通の決まりです。Laravel のリクエストではなく、PSR-7 のリクエストがほしいときは、先にライブラリを入れます。Laravel は、Symfony の HTTP Message Bridge という部品を使って、リクエストとレスポンスを PSR-7 の形に変えます。

composer require symfony/psr-http-message-bridge
composer require nyholm/psr7

入れたら、ルートのクロージャやコントローラーのメソッドに、リクエストのインターフェイス（守るべきメソッドの決まり）の型を書きます。

use Psr\Http\Message\ServerRequestInterface;

Route::get('/', function (ServerRequestInterface $request) {
    // ...
});

入力を取り出す#

入力の取り出し方#

入力を全部取り出す#

all で、リクエストの入力を全部、配列で取れます。HTML のフォームからでも、XHR（JavaScript からの送信）でも使えます。

$input = $request->all();

collect なら、コレクション（配列を便利に扱う入れ物）で取れます。

$input = $request->collect();

collect は、入力の一部だけをコレクションで取ることもできます。

$request->collect('users')->each(function (string $user) {
    // ...
});

入力の取り出しに使うメソッドを、先に一覧にします。

入力の値を1つ取り出す#

input を使うと、HTTP メソッドが何でも、入力を取れます。

$name = $request->input('name');

2つ目の引数に、ないときに返す値（初期値）を書けます。

$name = $request->input('name', 'Sally');

配列の入力があるフォームでは、ドット記法（. でつなぐ書き方）で取り出せます。

$name = $request->input('products.0.name');

$names = $request->input('products.*.name');

引数なしで呼ぶと、入力の値を全部、連想配列（名前と値の組の並び）で返します。

$input = $request->input();

クエリ文字列から取り出す#

input は、リクエスト全体（クエリ文字列を含む）から取ります。query は、クエリ文字列からだけ取ります。

$name = $request->query('name');

ないときは、2つ目の引数が返ります。

$name = $request->query('name', 'Helen');

引数なしで呼ぶと、クエリ文字列の値を、全部連想配列で返します。

$query = $request->query();

JSON の入力を取り出す#

JSON を送るときは、リクエストの Content-Type ヘッダーを application/json にしておけば、input で取れます。JSON の入れ子の中も、ドット記法で取れます。

$name = $request->input('user.name');

Stringable として取り出す#

string を使うと、入力が、ただの文字列ではなく、Illuminate\Support\Stringable の入れ物として返ります。文字をつないで加工できます。

$name = $request->string('name')->trim();

整数として取り出す#

integer は、入力を整数に変えて返します。入力がなければ、決めた初期値を返します。ページ送りなど、数の入力に便利です。

$perPage = $request->integer('per_page');

真偽として取り出す#

チェックボックスなどからは、"true" や "on" のような、文字の「真」が届くことがあります。boolean を使うと、これを true か false にして取れます。1・"1"・true・"true"・"on"・"yes" なら true で、それ以外は false です。

$archived = $request->boolean('archived');

配列として取り出す#

array は、入力を必ず配列にして返します。その名前の入力がなければ、空の配列です。

$versions = $request->array('versions');

日付として取り出す#

日付や時刻の入力は、date で Carbon（日付を扱うライブラリ）の入れ物として取れます。入力がなければ null です。

$birthday = $request->date('birthday');

2つ目と3つ目の引数で、日付の形式とタイムゾーン（地域の時刻）を決められます。

$elapsed = $request->date('elapsed', '!H:i', 'Europe/Madrid');

入力はあるのに形が正しくないときは、InvalidArgumentException（引数のまちがいを知らせるエラー）が起きます。date を呼ぶ前に、入力をチェックしておくことをすすめます。

期間として取り出す#

期間（どれだけの時間か）の入力は、interval で CarbonInterval の入れ物として取れます。入力がなければ null です。

$duration = $request->interval('duration');

入力が数字のときは、2つ目の引数に単位を書けます。単位は、second・minute・day などの文字か、Carbon\Unit の Enum です。

use Carbon\Unit;

$timeout = $request->interval('timeout', 'second');

$delay = $request->interval('delay', Unit::Minute);

入力はあるのに形が正しくないときは、InvalidArgumentException のエラーが起きます。interval を呼ぶ前に、入力をチェックしておくことをすすめます。

Enum として取り出す#

入力が、PHP の Enum の値に当たるなら、Enum として取れます。入力がないか、Enum に合う値がなければ、null が返ります。enum の1つ目に入力の名前、2つ目に Enum のクラスを書きます。

use App\Enums\Status;

$status = $request->enum('status', Status::class);

入力がないか、正しくないときに返す値も、3つ目に書けます。

$status = $request->enum('status', Status::class, Status::Pending);

入力が、Enum に当たる値の配列なら、enums で、Enum の配列として取れます。

use App\Enums\Product;

$products = $request->enums('products', Product::class);

動的なプロパティで取り出す#

Request のプロパティ（クラスの中の変数）のように書いても、入力が取れます。フォームに name の欄があれば、次のとおりです。

$name = $request->name;

このとき Laravel は、まず入力の中から探します。なければ、当たったルートのパラメータの中から探します。

入力の一部だけ取り出す#

一部だけほしいときは、only と except を使います。どちらも、配列でも、並べて書いてもかまいません。

$input = $request->only(['username', 'password']);

$input = $request->only('username', 'password');

$input = $request->except(['credit_card']);

$input = $request->except('credit_card');

入力があるか調べる#

入力があるかどうかを調べるメソッドの一覧です。

has は、値があれば true を返します。

if ($request->has('name')) {
    // ...
}

配列を渡すと、挙げた値が全部あるかを調べます。

if ($request->has(['name', 'email'])) {
    // ...
}

hasAny は、挙げた値のどれかがあれば true です。

if ($request->hasAny(['name', 'email'])) {
    // ...
}

whenHas は、値があるときに、クロージャを動かします。

$request->whenHas('name', function (string $input) {
    // ...
});

2つ目のクロージャを渡すと、値がないときに、そちらが動きます。

$request->whenHas('name', function (string $input) {
    // "name" の値がある
}, function () {
    // "name" の値がない
});

値があり、しかも空の文字ではないか調べるなら、filled です。

if ($request->filled('name')) {
    // ...
}

値がないか、空の文字かを調べるなら、isNotFilled です。

if ($request->isNotFilled('name')) {
    // ...
}

配列を渡すと、挙げた値が全部、ないか空かを調べます。

if ($request->isNotFilled(['name', 'email'])) {
    // ...
}

anyFilled は、挙げた値のどれかが、空の文字でなければ true です。

if ($request->anyFilled(['name', 'email'])) {
    // ...
}

whenFilled は、値があり、空の文字ではないときに、クロージャを動かします。

$request->whenFilled('name', function (string $input) {
    // ...
});

2つ目のクロージャは、「埋まっていない」ときに動きます。

$request->whenFilled('name', function (string $input) {
    // "name" の値が入っている
}, function () {
    // "name" の値が入っていない
});

そのキーがリクエストにないことを調べるなら、missing と whenMissing です。

if ($request->missing('name')) {
    // ...
}

$request->whenMissing('name', function () {
    // "name" の値がない
}, function () {
    // "name" の値がある
});

入力を足す#

リクエストの入力に、自分で値を足したいときは、merge を使います。同じキーがすでにあると、merge で渡した値で上書きされます。

$request->merge(['votes' => 0]);

mergeIfMissing は、そのキーがまだないときだけ、足します。

$request->mergeIfMissing(['votes' => 0]);

前の入力を残す（old input）#

Laravel は、1つ前のリクエストの入力を、次のリクエストまで残せます。入力チェックでエラーになったとき、フォームに前の入力を入れ直すのに便利です。ただ、Laravel のバリデーション（入力のチェック）を使うなら、入力を残す処理をバリデーションが自動でしてくれることがあります。そのため、自分で書かなくて済むこともあります。

入力をセッションに残す#

flash は、いまの入力をセッション（同じ人のアクセスをまたいで情報を覚えておくしくみ）に残し、その人の次のリクエストで使えるようにします。

$request->flash();

一部だけ残すには、flashOnly と flashExcept を使います。パスワードのような大事な情報を、セッションに残さずに済みます。

$request->flashOnly(['username', 'email']);

$request->flashExcept('password');

入力を残して転送する#

入力を残して、前のページへ転送することが多いので、転送に withInput をつなげられます。

return redirect('/form')->withInput();

return redirect()->route('user.create')->withInput();

return redirect('/form')->withInput(
    $request->except('password')
);

前の入力を取り出す#

前のリクエストで残した入力は、Request の old で取り出します。セッションから取り出されます。

$username = $request->old('username');

どこからでも呼べる old のヘルパー関数もあります。Blade テンプレートでフォームに入れ直すなら、こちらが便利です。その欄の前の入力がなければ、null が返ります。

<input type="text" name="username" value="{{ old('username') }}">

Cookie#

リクエストから Cookie を取り出す#

Laravel が作った Cookie は、すべて暗号化され、書きかえを見破るための印（署名）が付いています。ブラウザ側で書きかえられると、無効になります。Cookie の値は、Request の cookie で取り出します。

$value = $request->cookie('name');

入力の整え方（トリミングと正規化）#

Laravel には、全体にかかるミドルウェアとして、Illuminate\Foundation\Http\Middleware\TrimStrings と Illuminate\Foundation\Http\Middleware\ConvertEmptyStringsToNull が最初から入っています。前者は、送られてきた文字の前後の空白を取り除きます。後者は、空の文字を null に変えます。そのため、ルートやコントローラーで、こうした整えを気にしなくて済みます。

整えないようにする#

すべてのリクエストでやめたいときは、bootstrap/app.php で $middleware->remove を呼び、2つのミドルウェアを外します。

use Illuminate\Foundation\Http\Middleware\ConvertEmptyStringsToNull;
use Illuminate\Foundation\Http\Middleware\TrimStrings;

->withMiddleware(function (Middleware $middleware): void {
    $middleware->remove([
        ConvertEmptyStringsToNull::class,
        TrimStrings::class,
    ]);
})

一部のリクエストだけやめたいときは、bootstrap/app.php で、trimStrings と convertEmptyStringsToNull を使います。どちらも、クロージャの配列を受け取ります。クロージャが true を返したリクエストでは、整えません。

->withMiddleware(function (Middleware $middleware): void {
    $middleware->convertEmptyStringsToNull(except: [
        fn (Request $request) => $request->is('admin/*'),
    ]);

    $middleware->trimStrings(except: [
        fn (Request $request) => $request->is('admin/*'),
    ]);
})

ファイル#

アップロードされたファイルを取り出す#

アップロードされたファイルは、file か、動的なプロパティで取り出します。file は、Illuminate\Http\UploadedFile クラスの実体を返します。このクラスは PHP の SplFileInfo を引き継いで（継承して）いて、ファイルを扱うメソッドがたくさんあります。

$file = $request->file('photo');

$file = $request->photo;

ファイルがあるかは、hasFile で調べます。

if ($request->hasFile('photo')) {
    // ...
}

アップロードされたのが画像で、保存の前に加工したいときは、image で、Illuminate\Image\Image の入れ物として取り出せます。ファイルがなければ null です。

$image = $request->image('photo');

画像の加工について、くわしくは画像の加工を見てください。

アップロードが成功したか調べる#

ファイルがあるかだけでなく、アップロードに問題がなかったかも、isValid で調べられます。

if ($request->file('photo')->isValid()) {
    // ...
}

ファイルの場所と拡張子#

UploadedFile は、ファイルの場所（パス）と拡張子（.jpg など）も取れます。extension は、ファイルの中身から拡張子を推測します。相手が付けた拡張子とは、ちがうこともあります。

$path = $request->photo->path();

$extension = $request->photo->extension();

そのほかのメソッド#

UploadedFile には、ほかにもたくさんのメソッドがあります。くわしくは、Symfony の UploadedFile クラスの API ドキュメントを見てください。

アップロードされたファイルを保存する#

保存には、ふつう、設定したファイルの保存先（ファイルの保存）の1つを使います。UploadedFile の store メソッドは、アップロードされたファイルを、ディスク（保存先の名前）の1つに移します。ディスクは、自分のパソコンの中でも、Amazon S3 のようなクラウドの保存先でもかまいません。

store には、保存先の、ルート（出発点）からのフォルダのパスを渡します。ファイル名は入れません。ファイル名には、重ならない ID が自動で付くからです。

2つ目の引数で、使うディスクの名前を決められます。返るのは、ディスクのルートからのファイルのパスです。

$path = $request->photo->store('images');

$path = $request->photo->store('images', 's3');

ファイル名を自動で付けたくないときは、storeAs です。パス・ファイル名・ディスク名を渡します。

$path = $request->photo->storeAs('images', 'filename.jpg');

$path = $request->photo->storeAs('images', 'filename.jpg', 's3');

信頼するプロキシを決める#

TLS / SSL の証明書（HTTPS にするための証明）を、ロードバランサー（アクセスを分けてサーバーに送る装置）で処理していると、url ヘルパー関数（どこからでも呼べる便利な関数）が、HTTPS のリンクを作らないことがあります。これは、ロードバランサーが 80 番のポート（サーバーの受付の番号）でアプリへ転送しているため、アプリが「安全なリンクを作るべきだ」と分からないからです。

直すには、Laravel に最初から入っている Illuminate\Http\Middleware\TrustProxies ミドルウェアを使います。信頼するロードバランサーやプロキシを決められます。bootstrap/app.php の trustProxies メソッドの at に書きます。

->withMiddleware(function (Middleware $middleware): void {
    $middleware->trustProxies(at: [
        '192.168.1.1',
        '10.0.0.0/8',
    ]);
})

信頼するプロキシだけでなく、信頼するヘッダーも決められます。

->withMiddleware(function (Middleware $middleware): void {
    $middleware->trustProxies(headers: Request::HEADER_X_FORWARDED_FOR |
        Request::HEADER_X_FORWARDED_HOST |
        Request::HEADER_X_FORWARDED_PORT |
        Request::HEADER_X_FORWARDED_PROTO |
        Request::HEADER_X_FORWARDED_AWS_ELB
    );
})

すべてのプロキシを信頼する#

Amazon AWS などのクラウドのロードバランサーでは、実際の装置の IP アドレスが分からないことがあります。そのときは、* で、すべてのプロキシを信頼できます。

->withMiddleware(function (Middleware $middleware): void {
    $middleware->trustProxies(at: '*');
})

信頼するホストを決める#

Laravel は、ふつう、リクエストの Host ヘッダーが何であっても、届いたリクエストすべてに答えます。また、Web のリクエストの中で、アプリの絶対 URL（https:// から始まる完全な URL）を作るときに、Host ヘッダーの値が使われます。

ふつうは、Nginx や Apache などの Web サーバーで、決めたホスト名のリクエストだけをアプリに送るようにします。でも、Web サーバーを自分で変えられず、Laravel に特定のホスト名にだけ答えさせたいときは、Illuminate\Http\Middleware\TrustHosts ミドルウェアを有効にします。

有効にするには、bootstrap/app.php で trustHosts メソッドを呼びます。at に、答えるホスト名を書きます。ホスト名の文字は、正規表現（文字の並びのパターン）として扱われます。ほかの Host ヘッダーのリクエストは、断られます。

->withMiddleware(function (Middleware $middleware): void {
    $middleware->trustHosts(at: ['^laravel\.test$']);
})

最初から、アプリの URL のサブドメイン（example.com に対する shop.example.com のような別の名前）からのリクエストも、自動で信頼されます。やめるには、subdomains を使います。

->withMiddleware(function (Middleware $middleware): void {
    $middleware->trustHosts(at: ['^laravel\.test$'], subdomains: false);
})

信頼するホストを決めるのに、設定ファイルやデータベースを使いたいときは、at にクロージャを渡せます。

->withMiddleware(function (Middleware $middleware): void {
    $middleware->trustHosts(at: fn () => config('app.trusted_hosts'));
})

関連するページ#

• ルーティング
• コントローラー
• バリデーション（入力のチェック）
• ファイルの保存（ストレージ）
• セッション