︙

HTTP Requests

Table of Contents

Introduction
Interacting With The Request
Input
Files
- Retrieving Uploaded Files
- Storing Uploaded Files
Configuring Trusted Proxies
Configuring Trusted Hosts

Introduction

Laravel の Illuminate\Http\Request class は、現在の HTTP request を object 指向的に操作する方法を提供し、さらに application が処理している request とともに送信された input 、cookies、ファイルを取得します。

Interacting With The Request

Request へのアクセス

依存性注入を介して現在の HTTP request のインスタンスを取得するには、route クロージャまたはコントローラ method でIlluminate\Http\Request class を types ヒントする必要があります。着信 request インスタンスは、Laravel service containerによって自動的に注入されます。

<?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');

        // Store the user...

        return redirect('/users');
    }
}

前述の通り、Illuminate\Http\Request class を route クロージャに types ヒントとしても指定することができます。クロージャが実行されるとき、 service container は自動的に入力された request をクロージャに注入します。

use Illuminate\Http\Request;

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

Dependency Injection と Route パラメータ

あなたの controller method も route パラメータからの input を期待している場合、他の依存関係の後にあなたの route パラメータをリストするべきです。例えば、あなたの route が以下のように定義されている場合：

use App\Http\Controllers\UserController;

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

次のようにコントローラー method を定義することで、Illuminate\Http\Requestに対する types ヒントを引き続き使用し、id route パラメータにアクセスすることができます。

<?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
    {
        // Update the user...

        return redirect('/users');
    }
}

Request Path 、ホスト、そして Method

Illuminate\Http\Requestインスタンスは、入力される HTTP request を調査するためのさまざまな methods を提供し、Symfony\Component\HttpFoundation\Request class を拡張します。以下で最も重要な methods のいくつかについて説明します。

Request Path の取得

pathmethod は request の path 情報を返します。したがって、着信する request がhttp://example.com/foo/barに対して行われる場合、pathmethod はfoo/barを返します。

$uri = $request->path();

Request Path / Route の調査

isの method を使用すると、受信した requestpath が指定のパターンと一致するかを確認できます。この method を使用する際には、*文字をワイルドカードとして使用することができます。

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

routeIsの method を使用すると、着信の request がnamed routeに一致したかどうかを判断することができます：

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

Request URL の取得

受信した request の完全な URL を取得するためには、url や fullUrl メソッドを使用することができます。url method は query string を除いた URL を返しますが、一方で fullUrl method は query string を含みます。

$url = $request->url();

$urlWithQueryString = $request->fullUrl();

現在の URL に append query string data data を追加したい場合は、 fullUrlWithQuery method を呼び出すことができます。この method は、与えられた query string 変数の array を現在の query string とマージします：

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

指定した query string パラメータなしで現在の URL を取得したい場合、fullUrlWithoutQuery method を利用することができます。

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

Request ホストの取得

次の host、httpHost、および schemeAndHttpHost メソッドを使用して、着信の request の "host" を取得することができます。

$request->host();
$request->httpHost();
$request->schemeAndHttpHost();

Request Method の取得

method method は、 request の HTTP 動詞を返します。あなたは、isMethod method を使って、 HTTP 動詞が指定された string と一致することを確認することができます。

$method = $request->method();

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

Request Headers

Illuminate\Http\Request インスタンスから request header を取得するには、header method を使用します。もし header が request に存在しない場合、nullが返されます。ただし、header method では、オプションの第二引数が提供され、それが header が request に存在しない場合に返されます。

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

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

hasHeader method は、 request が特定の header を含むかどうかを判断するために使用できます。

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

便宜上、bearerToken method を使用して Authorization header から bearer token を取得することができます。該当する header が存在しない場合、空の string が返されます。

$token = $request->bearerToken();

Request IP アドレス

ip method を使用して、あなたの application に request を行った client の IP アドレスを取得できます。

$ipAddress = $request->ip();

もしプロキシによって転送されたすべての client IP アドレスを含む IP アドレスの array を取得したい場合、ips method を使用することができます。original の client IP アドレスは array の最後になります：

$ipAddresses = $request->ips();

一般的に、IP アドレスは信頼できない、ユーザーが制御する input と考えられ、情報提供のみに使用されるべきです。

Content ネゴシエーション

Laravel は、Accept header を通じて着信リクエストの要求された content タイプを検査するためのいくつかの方法を提供します。まず、getAcceptableContentTypes method は、 request によって受け入れられるすべての content タイプを含む array を返します：

$contentTypes = $request->getAcceptableContentTypes();

accepts method は、content の種類を array で受け取り、そのいずれかが request によって受け入れられるときはtrueを返します。それ以外の場合、falseを返します。

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

prefersmethod を使用して、与えられた array の contenttypes の中で、request が最も好むコンテンツ types を決定することができます。提供された contenttypes のどれもが request に受け入れられない場合は、nullが返されます：

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

多くの applications は HTML または JSON response のみを提供するため、expectsJson method を使用して、着信 request が JSON response を期待しているかどうかをすばやく判断することができます。

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

PSR-7 standard では、リクエストとレスポンスを含む HTTP メッセージのためのインターフェイスが規定されています。もし PSR-7 の request のインスタンスを、 Laravel request の代わりに取得したい場合は、まずいくつかのライブラリをインストールする必要があります。 Laravel はSymfony HTTP Message Bridge component を使用して、標準的な Laravel リクエストとレスポンスを PSR-7 互換の実装に変換します：

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

これらのライブラリをインストールしたら、 route クロージャや controller method に request インターフェースをタイプヒントとして使用することで、PSR-7 の request を取得できます。

use Psr\Http\Message\ServerRequestInterface;

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

NOTE

route や controller から PSR-7 の response インスタンスを返すと、自動的に Laravel response インスタンスに戻され、フレームワークによって表示されます。

Input

Retrieving Input

すべての Input Data を取得する

すべての受信リクエストの input data をarrayとしてall method を使用して取得することができます。この method は、受信 request が HTML フォームからであるか、XHR request であるかにかかわらず使用することができます。

$input = $request->all();

collectの method を使用すると、受信 request のすべての input data をcollectionとして取得することができます：

$input = $request->collect();

collect method は、着信リクエストの input の一部を collection として取得することも可能です：

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

Input Value の取得

いくつかのシンプルな方法を使用すると、Illuminate\Http\Requestインスタンスからすべての user 入力にアクセスでき、HTTP 動詞が request にどのように使用されたかを心配する必要はありません。 HTTP 動詞に関係なく、input method を使用して user 入力を取得することができます:

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

input method の二つ目の引数として、defaultvalue を渡すことができます。この value は、要求された入力 value が request に存在しない場合に返されます。

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

array 入力を含むフォームで作業するときは、dot 表記法を使用して配列にアクセスします。

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

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

inputの method を引数なしで呼び出して、すべての input values を連想 array として取得することができます。

$input = $request->input();

Query String からの Input の取得

input method は、全体の request ペイロード(query string を含む)から values を取得しますが、query method は、query string からのみ values を取得します：

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

要求された query string value data が存在しない場合、この method への 2 番目の引数が返されます。

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

あなたは全ての query string の values を関連付けられた array として取得するために、引数なしで querymethod を呼び出すことができます。

$query = $request->query();

JSON Input Values の取得

あなたの application に JSON request を送信する際、Content-Type header が適切にapplication/jsonに設定されていれば、input method を通じて JSON data にアクセスすることができます。 dot syntax を使用して、JSON arrays/object 内にネストされている values を取得することさえできます:

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

Stringable Input Values の取得

リクエストの input data をプリミティブなstringとして取得する代わりに、string method を使用して request data をIlluminate\Support\Stringableのインスタンスとして取得することができます：

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

Boolean Input Values の取得

HTML elements"といったチェックボックスのようなものを扱うとき、"真実性"という"values"を string として受け取ることがあるかもしれません。例えば、"true"あるいは"on"のような。便宜上、これらの"values"をブール values として取得するために、boolean "method"を使用することができます。boolean "method"は、1、"1"、true、"true"、"on"、そして"yes"に対してはtrueを返します。他のすべての"values"に対してはfalseを返します。

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

日付 Input Values の取得

便宜上、日付/時間を含む input values は date method を使用して Carbon のインスタンスとして retrieved することができます。もし request が指定した名前の input value を含んでいない場合、nullが返されます。

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

date method が受け入れる第二引数と第三引数は、それぞれ日付の形式と timezone を指定するために使用できます。

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

もし input value が存在するが invalid な形式である場合、InvalidArgumentExceptionがスローされます。したがって、date method を呼び出す前に input を validate することを推奨します。

Enum Input Values の取得

Input values はPHP enums に対応するもので、また request からも retrieved することができます。もし request が指定された名前の input value を含んでいない場合や、enum が input value と一致する value を持っていない場合は、nullが返されます。enumの method は、input value の名前と、enum class を最初と二番目の引数として受け入れます：

use App\Enums\Status;

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

動的プロパティを使用して Input を取得する

また、Illuminate\Http\Requestインスタンス上の動的プロパティを使用して、 user input にアクセスすることもできます。例えば、アプリケーションのフォームの一つにnameフィールドが含まれている場合、以下のようにフィールドの value にアクセスできます。

$name = $request->name;

動的プロパティを使用する際、 Laravel はまず、 request のペイロード内のパラメータの value を探します。もし存在しない場合、 Laravel はマッチしたルートのパラメータでフィールドを search します。

Input Data の一部を取得する

もし input data の一部を取得する必要がある場合、only メソッドと except メソッドを使用することができます。これらのメソッドはどちらも single array または動的な引数リストを受け入れます：

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

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

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

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

WARNING

only method は、要求した key/ value のペアをすべて返します。しかし、 request 上に存在しない key/ value のペアは返しません。

Input の存在

has method を使用して、 request に value が存在するかどうかを判断できます。has method は、 request に value が存在する場合、trueを返します。

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

array が与えられると、has method は指定された values がすべて存在するかどうかを判断します。

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

hasAny method は、指定された values のいずれかが存在する場合にtrueを返します：

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

whenHas method は、 request に value が存在する場合、与えられたクロージャを実行します。

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

指定された value が request に存在しない場合に実行される、whenHas method に 2 つ目のクロージャを渡すことができます。

$request->whenHas('name', function (string $input) {
    // The "name" value is present...
}, function () {
    // The "name" value is not present...
});

もし request 上にある value が存在し、それが空の string でないかどうかを判断したい場合は、filled method を使用できます：

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

anyFilled method は、指定された values のいずれかが空でない string である場合、trueを返します。

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

whenFilled method は、 request に value が存在し、それが空の string でない場合、指定されたクロージャを実行します。

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

第二のクロージャは、指定された value が"filled"でない場合に実行されるように、whenFilled method に渡すことができます。

$request->whenFilled('name', function (string $input) {
    // The "name" value is filled...
}, function () {
    // The "name" value is not filled...
});

指定したキーが request から欠落しているかどうかを判断するには、missingメソッドとwhenMissingメソッドを使用できます：

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

$request->whenMissing('name', function () {
    // The "name" value is missing...
}, function () {
    // The "name" value is present...
});

追加の Input のマージ

場合によっては、リクエストの既存の input data に手動で merge した追加の input が必要になることがあります。これを実現するために、merge method を使用することができます。指定した input キーがすでに request に存在する場合、それはmerge method に提供された data によって上書きされます。

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

mergeIfMissing method は、対応する keys が request の入力 data 内に既に存在しない場合、入力を request に統合するために使用できます。

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

古い Input

Laravel では、次の request の間で入力を保持することができます。この特徴は特に、validationerror 検出後にフォームを再入力する際に便利です。しかし、Laravel の初めから含まれているvalidation 機能を使用している場合、Laravel の内蔵 validation 設備の一部が自動的にこれらの session 入力フラッシング機能を呼び出すため、手動でこれらの機能を使う必要がない可能性があります。

Session に Input をフラッシュする

Illuminate\Http\Requestの class 上のflash method は、現在の input をsessionにフラッシュするので、それが user の次の request 中に application で利用可能になります。

$request->flash();

また、 request data の一部を session にフラッシュするためにflashOnlyおよびflashExceptメソッドを使用することもできます。これらのメソッドは、 passwords などの機密情報を session から除外するために役立ちます。

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

$request->flashExcept('password');

Input を点滅させてからリダイレクト

あなたはしばしば input を session にフラッシュしてから前のページに redirect したいと思うでしょう、したがって、簡単に redirect に withInput method を用いて input フラッシュをチェーンできます:

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

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

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

古い Input の取得

以前の request からフラッシュされた input を取得するには、Illuminate\Http\Requestのインスタンスでold method を呼び出します。old method は、sessionから以前にフラッシュされた input data を引き出します。

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

Laravel はグローバルなoldヘルパーも提供しています。古い input をBlade テンプレートで表示している場合、フォームを再入力するためにoldヘルパーを使用する方が便利です。指定されたフィールドに対して古い input が存在しない場合、nullが返されます：

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

Cookies

リクエストからクッキーを取得する

Laravel フレームワークによって作成されたすべての cookies は、暗号化され、authentication code で署名されています。これは、もし cookies が client によって変更されていたら、それは invalid とみなされることを意味します。 request から cookie value を取得するには、 Illuminate\Http\Request インスタンス上で cookie method を使用します。

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

Input Trimming and Normalization

default で、Laravel はあなたの application のグローバルな middlewarestack にIlluminate\Foundation\Http\Middleware\TrimStringsとIlluminate\Foundation\Http\Middleware\ConvertEmptyStringsToNullの middleware を含んでいます。これらの middleware は、request の上のすべての受信ストリングフィールドを自動的にトリムし、そして任意の空のストリングフィールドをnullに変換します。これにより、あなたは routes とコントローラにおけるこれらの正規化の懸念について心配する必要がなくなります。

Input 正規化の無効化

すべてのリクエストでこの動作を無効にしたい場合は、アプリケーションの middleware stack から二つの middleware を削除できます。それには、bootstrap/app.phpファイル内のアプリケーションで$middleware->remove method を呼び出します:

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

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

もし、あなたがあなたの application へのリクエストの一部に対して、 string のトリミングを無効にし、空の string を変換したい場合、アプリケーションのbootstrap/app.phpファイル内でtrimStringsとconvertEmptyStringsToNullの middleware メソッドを使用することができます。両方のメソッドは、 input の正規化がスキップされるべきかどうかを示すためにtrueまたはfalseを返すべきクロージャの array を受け入れます。

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

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

Files

アップロードしたファイルの取得

Illuminate\Http\Request インスタンスからアップロードされたファイルを取得するには、file method を使用するか、動的なプロパティを使用します。file method は Illuminate\Http\UploadedFile class のインスタンスを返し、これは PHP の SplFileInfo class を拡張し、ファイルと対話するためのさまざまなメソッドを提供します：

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

$file = $request->photo;

ファイルが request 上に存在するかどうかは、hasFile method を使用して判断することができます：

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

Validating 成功したアップロード

ファイルが存在するかどうかを確認するだけでなく、isValid method を使用してファイルのアップロードに問題がなかったことも確認できます。

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

ファイルパスと Extensions

UploadedFile class には、ファイルの完全修飾 path とその拡張子にアクセスするためのメソッドも含まれています。extension method は、ファイルの内容に基づいてファイルの拡張子を attempt します。この拡張子は、 client が提供した拡張子とは異なる場合があります。

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

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

他のファイルメソッド

UploadedFile インスタンスには、さまざまな他のメソッドが利用可能です。これらのメソッドに関する詳細な情報は、API ドキュメンテーションの class をご覧ください。

アップロードされたファイルの保存

アップロードされたファイルを保存するには、通常、設定したfilesystemsのうちの一つを使用します。UploadedFile class には、アップロードされたファイルをローカルファイルシステム上の場所や、Amazon S3 のようなクラウド storage の位置に移動させるstore method があります。

storeの method は、ファイルが保存されるべき path をファイルシステムの設定された root ディレクトリに対して受け入れます。この path にはファイル名を含めないでください。なぜなら、 unique な ID が自動的に生成され、ファイル名として機能するからです。

storeの method は、ファイルを保存するために使用するディスクの名前のための任意の二番目の引数も受け付けます。 method は、ディスクの root に対するファイルの path を返します。

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

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

ファイル名を自動的に生成させたくない場合は、storeAs method を使用することができます。これは path 、ファイル名、ディスク名をその引数として受け取ります：

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

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

NOTE

Laravel のファイル storage についての詳しい情報は、完全なファイル storage のドキュメンテーションをご覧ください。

Configuring Trusted Proxies

TLS / SSL 証明書を終了させるロードバランサーの背後でアプリケーションを実行すると、ご使用のurlhelper を使う際に、 application が HTTPS links を生成しないときがあることに気付くかもしれません。通常、これは、ロードバランサーからのトラフィックがポート 80 で転送され、安全な links を生成するべきであることを application が認識していないためです。

これを解決するには、Illuminate\Http\Middleware\TrustProxies middleware を有効にし、これはあなたの Laravel application に含まれており、ロードバランサーやプロキシをすばやくカスタマイズすることを可能にします。これらはあなたの application から信頼するべきです。信頼すべきプロキシは、アプリケーションのbootstrap/app.phpファイルのtrustProxies middleware method を使って指定するべきです：

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

信頼できるプロキシを設定するだけでなく、信頼すべきプロキシの headers も設定することができます：

->withMiddleware(function (Middleware $middleware) {
    $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
    );
})

NOTE

AWS Elastic Load Balancing を使用している場合、headersの value はRequest::HEADER_X_FORWARDED_AWS_ELBであるべきです。ロードバランサがRFC 7239 からの標準的なForwarded header を使用している場合、headersの value はRequest::HEADER_FORWARDEDであるべきです。headersの value で使用できる定数についての詳細は、Symfony のtrusting proxies のドキュメンテーションをご覧ください。

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

Amazon AWS や他の"クラウド"ロードバランサーの provider を使用している場合、実際のバランサーの IP アドレスがわからないかもしれません。この場合、全てのプロキシを信頼するために*を使用することができます：

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

Configuring Trusted Hosts

default では、Laravel は、Hostheader の HTTP requests の content に関係なく、受信したすべての requests に response します。さらに、Host header の value は、web request 中にあなたの application への絶対 URL を生成する際に使用されます。

通常は、Nginx や Apache などの webserver を設定して、特定のホスト名と一致する application への requests のみを送信するようにします。しかし、直接 webserver をカスタマイズする能力がなく、Illuminate\Http\Middleware\TrustHosts middleware を有効にして Laravel に特定のホスト名に対してのみ response するよう指示する必要がある場合もあります。

TrustHostsの middleware を有効にするには、アプリケーションのbootstrap/app.phpファイルで、trustHostsの middleware method を呼び出す必要があります。この method のat引数を使用して、 application が response する必要があるホスト名を指定できます。その他のHostの headers を持つ着信 requests は拒否されます：

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

default で、アプリケーションの URL のサブドメインからのリクエストも自動的に信頼されます。この挙動を無効にしたい場合は、subdomains引数を使用することができます：

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