Introduction
Laravel's Illuminate\Http\Request class
provides an object-oriented way to interact with the
current HTTP request being handled by your application
as well as retrieve the input, cookies, and files that
were submitted with the request.
Interacting With The Request
Accessing the Request
To obtain an instance of the current HTTP request via
dependency injection, you should type-hint the
Illuminate\Http\Request class on your route
closure or controller method. The incoming request
instance will automatically be injected by the 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');
}
}
As mentioned, you may also type-hint the
Illuminate\Http\Request class on a route
closure. The service container will automatically inject
the incoming request into the closure when it is
executed:
use Illuminate\Http\Request;
Route::get('/', function (Request $request) {
// ...
});
Dependency Injection and Route Parameters
If your controller method is also expecting input from a route parameter you should list your route parameters after your other dependencies. For example, if your route is defined like so:
use App\Http\Controllers\UserController;
Route::put('/user/{id}', [UserController::class, 'update']);
You may still type-hint the
Illuminate\Http\Request and access your
id route parameter by defining your
controller method as follows:
<?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, Host, and Method
The Illuminate\Http\Request instance
provides a variety of methods for examining the incoming
HTTP request and extends the
Symfony\Component\HttpFoundation\Request
class. We will discuss a few of the most important
methods below.
Retrieving the Request Path
The path method returns the request's path
information. So, if the incoming request is targeted at
http://example.com/foo/bar, the
path method will return
foo/bar:
$uri = $request->path();
Inspecting the Request Path / Route
The is method allows you to verify that the
incoming request path matches a given pattern. You may
use the * character as a wildcard when
utilizing this method:
if ($request->is('admin/*')) {
// ...
}
Using the routeIs method, you may determine
if the incoming request has matched a named
route:
if ($request->routeIs('admin.*')) {
// ...
}
Retrieving the Request URL
To retrieve the full URL for the incoming request you may
use the url or fullUrl
methods. The url method will return the URL
without the query string, while the fullUrl
method includes the query string:
$url = $request->url();
$urlWithQueryString = $request->fullUrl();
If you would like to append query string data to the
current URL, you may call the
fullUrlWithQuery method. This method merges
the given array of query string variables with the
current query string:
$request->fullUrlWithQuery(['type' => 'phone']);
If you would like to get the current URL without a given
query string parameter, you may utilize the
fullUrlWithoutQuery method:
$request->fullUrlWithoutQuery(['type']);
Retrieving the Request Host
You may retrieve the "host" of the incoming
request via the host,
httpHost, and
schemeAndHttpHost methods:
$request->host();
$request->httpHost();
$request->schemeAndHttpHost();
Retrieving the Request Method
The method method will return the HTTP verb
for the request. You may use the isMethod
method to verify that the HTTP verb matches a given
string:
$method = $request->method();
if ($request->isMethod('post')) {
// ...
}
Request Headers
You may retrieve a request header from the
Illuminate\Http\Request instance using the
header method. If the header is not present
on the request, null will be returned.
However, the header method accepts an
optional second argument that will be returned if the
header is not present on the request:
$value = $request->header('X-Header-Name');
$value = $request->header('X-Header-Name', 'default');
The hasHeader method may be used to
determine if the request contains a given header:
if ($request->hasHeader('X-Header-Name')) {
// ...
}
For convenience, the bearerToken method may
be used to retrieve a bearer token from the
Authorization header. If no such header is
present, an empty string will be returned:
$token = $request->bearerToken();
Request IP Address
The ip method may be used to retrieve the IP
address of the client that made the request to your
application:
$ipAddress = $request->ip();
If you would like to retrieve an array of IP addresses,
including all of the client IP addesses that were
forwarded by proxies, you may use the ips
method. The "original" client IP address will
be at the end of the array:
$ipAddresses = $request->ips();
In general, IP addresses should be considered untrusted, user-controlled input and be used for informational purposes only.
Content Negotiation
Laravel provides several methods for inspecting the
incoming request's requested content types via the
Accept header. First, the
getAcceptableContentTypes method will
return an array containing all of the content types
accepted by the request:
$contentTypes = $request->getAcceptableContentTypes();
The accepts method accepts an array of
content types and returns true if any of
the content types are accepted by the request.
Otherwise, false will be returned:
if ($request->accepts(['text/html', 'application/json'])) {
// ...
}
You may use the prefers method to determine
which content type out of a given array of content types
is most preferred by the request. If none of the
provided content types are accepted by the request,
null will be returned:
$preferred = $request->prefers(['text/html', 'application/json']);
Since many applications only serve HTML or JSON, you may
use the expectsJson method to quickly
determine if the incoming request expects a JSON
response:
if ($request->expectsJson()) {
// ...
}
PSR-7 Requests
The PSR-7 standard specifies interfaces for HTTP messages, including requests and responses. If you would like to obtain an instance of a PSR-7 request instead of a Laravel request, you will first need to install a few libraries. Laravel uses the Symfony HTTP Message Bridge component to convert typical Laravel requests and responses into PSR-7 compatible implementations:
composer require symfony/psr-http-message-bridge
composer require nyholm/psr7
Once you have installed these libraries, you may obtain a PSR-7 request by type-hinting the request interface on your route closure or controller method:
use Psr\Http\Message\ServerRequestInterface;
Route::get('/', function (ServerRequestInterface $request) {
// ...
});
Note:
If you return a PSR-7 response instance from a route or controller, it will automatically be converted back to a Laravel response instance and be displayed by the framework.
Input
Retrieving Input
Retrieving All Input Data
You may retrieve all of the incoming request's input data
as an array using the all
method. This method may be used regardless of whether
the incoming request is from an HTML form or is an XHR
request:
$input = $request->all();
Using the collect method, you may retrieve
all of the incoming request's input data as a collection:
$input = $request->collect();
The collect method also allows you to
retrieve a subset of the incoming request's input as a
collection:
$request->collect('users')->each(function (string $user) {
// ...
});
Retrieving an Input Value
Using a few simple methods, you may access all of the
user input from your
Illuminate\Http\Request instance without
worrying about which HTTP verb was used for the request.
Regardless of the HTTP verb, the input
method may be used to retrieve user input:
$name = $request->input('name');
You may pass a default value as the second argument to
the input method. This value will be
returned if the requested input value is not present on
the request:
$name = $request->input('name', 'Sally');
When working with forms that contain array inputs, use "dot" notation to access the arrays:
$name = $request->input('products.0.name');
$names = $request->input('products.*.name');
You may call the input method without any
arguments in order to retrieve all of the input values
as an associative array:
$input = $request->input();
Retrieving Input From the Query String
While the input method retrieves values from
the entire request payload (including the query string),
the query method will only retrieve values
from the query string:
$name = $request->query('name');
If the requested query string value data is not present, the second argument to this method will be returned:
$name = $request->query('name', 'Helen');
You may call the query method without any
arguments in order to retrieve all of the query string
values as an associative array:
$query = $request->query();
Retrieving JSON Input Values
When sending JSON requests to your application, you may
access the JSON data via the input method
as long as the Content-Type header of the
request is properly set to
application/json. You may even use
"dot" syntax to retrieve values that are
nested within JSON arrays / objects:
$name = $request->input('user.name');
Retrieving Stringable Input Values
Instead of retrieving the request's input data as a
primitive string, you may use the
string method to retrieve the request data
as an instance of Illuminate\Support\Stringable:
$name = $request->string('name')->trim();
Retrieving Boolean Input Values
When dealing with HTML elements like checkboxes, your
application may receive "truthy" values that
are actually strings. For example, "true" or
"on". For convenience, you may use the
boolean method to retrieve these values as
booleans. The boolean method returns
true for 1, "1", true,
"true", "on", and "yes".
All other values will return false:
$archived = $request->boolean('archived');
Retrieving Date Input Values
For convenience, input values containing dates / times
may be retrieved as Carbon instances using the
date method. If the request does not
contain an input value with the given name,
null will be returned:
$birthday = $request->date('birthday');
The second and third arguments accepted by the
date method may be used to specify the
date's format and timezone, respectively:
$elapsed = $request->date('elapsed', '!H:i', 'Europe/Madrid');
If the input value is present but has an invalid format,
an InvalidArgumentException will be thrown;
therefore, it is recommended that you validate the input
before invoking the date method.
Retrieving Enum Input Values
Input values that correspond to PHP
enums may also be retrieved from the request. If
the request does not contain an input value with the
given name or the enum does not have a backing value
that matches the input value, null will be
returned. The enum method accepts the name
of the input value and the enum class as its first and
second arguments:
use App\Enums\Status;
$status = $request->enum('status', Status::class);
Retrieving Input via Dynamic Properties
You may also access user input using dynamic properties
on the Illuminate\Http\Request instance.
For example, if one of your application's forms contains
a name field, you may access the value of
the field like so:
$name = $request->name;
When using dynamic properties, Laravel will first look for the parameter's value in the request payload. If it is not present, Laravel will search for the field in the matched route's parameters.
Retrieving a Portion of the Input Data
If you need to retrieve a subset of the input data, you
may use the only and except
methods. Both of these methods accept a single
array or a dynamic list of arguments:
$input = $request->only(['username', 'password']);
$input = $request->only('username', 'password');
$input = $request->except(['credit_card']);
$input = $request->except('credit_card');
Warning!
Theonlymethod returns all of the key / value pairs that you request; however, it will not return key / value pairs that are not present on the request.
Input Presence
You may use the has method to determine if a
value is present on the request. The has
method returns true if the value is present
on the request:
if ($request->has('name')) {
// ...
}
When given an array, the has method will
determine if all of the specified values are
present:
if ($request->has(['name', 'email'])) {
// ...
}
The hasAny method returns true
if any of the specified values are present:
if ($request->hasAny(['name', 'email'])) {
// ...
}
The whenHas method will execute the given
closure if a value is present on the request:
$request->whenHas('name', function (string $input) {
// ...
});
A second closure may be passed to the
whenHas method that will be executed if the
specified value is not present on the request:
$request->whenHas('name', function (string $input) {
// The "name" value is present...
}, function () {
// The "name" value is not present...
});
If you would like to determine if a value is present on
the request and is not an empty string, you may use the
filled method:
if ($request->filled('name')) {
// ...
}
The anyFilled method returns
true if any of the specified values is not
an empty string:
if ($request->anyFilled(['name', 'email'])) {
// ...
}
The whenFilled method will execute the given
closure if a value is present on the request and is not
an empty string:
$request->whenFilled('name', function (string $input) {
// ...
});
A second closure may be passed to the
whenFilled method that will be executed if
the specified value is not "filled":
$request->whenFilled('name', function (string $input) {
// The "name" value is filled...
}, function () {
// The "name" value is not filled...
});
To determine if a given key is absent from the request,
you may use the missing and
whenMissing methods:
if ($request->missing('name')) {
// ...
}
$request->whenMissing('name', function (array $input) {
// The "name" value is missing...
}, function () {
// The "name" value is present...
});
Merging Additional Input
Sometimes you may need to manually merge additional input
into the request's existing input data. To accomplish
this, you may use the merge method. If a
given input key already exists on the request, it will
be overwritten by the data provided to the
merge method:
$request->merge(['votes' => 0]);
The mergeIfMissing method may be used to
merge input into the request if the corresponding keys
do not already exist within the request's input
data:
$request->mergeIfMissing(['votes' => 0]);
Old Input
Laravel allows you to keep input from one request during the next request. This feature is particularly useful for re-populating forms after detecting validation errors. However, if you are using Laravel's included validation features, it is possible that you will not need to manually use these session input flashing methods directly, as some of Laravel's built-in validation facilities will call them automatically.
Flashing Input to the Session
The flash method on the
Illuminate\Http\Request class will flash
the current input to the session so that it is
available during the user's next request to the
application:
$request->flash();
You may also use the flashOnly and
flashExcept methods to flash a subset of
the request data to the session. These methods are
useful for keeping sensitive information such as
passwords out of the session:
$request->flashOnly(['username', 'email']);
$request->flashExcept('password');
Flashing Input Then Redirecting
Since you often will want to flash input to the session
and then redirect to the previous page, you may easily
chain input flashing onto a redirect using the
withInput method:
return redirect('form')->withInput();
return redirect()->route('user.create')->withInput();
return redirect('form')->withInput(
$request->except('password')
);
Retrieving Old Input
To retrieve flashed input from the previous request,
invoke the old method on an instance of
Illuminate\Http\Request. The
old method will pull the previously flashed
input data from the session:
$username = $request->old('username');
Laravel also provides a global old helper.
If you are displaying old input within a Blade template, it is more
convenient to use the old helper to
repopulate the form. If no old input exists for the
given field, null will be returned:
<input type="text" name="username" value="{{ old('username') }}">
Cookies
Retrieving Cookies From Requests
All cookies created by the Laravel framework are
encrypted and signed with an authentication code,
meaning they will be considered invalid if they have
been changed by the client. To retrieve a cookie value
from the request, use the cookie method on
an Illuminate\Http\Request instance:
$value = $request->cookie('name');
Input Trimming and Normalization
By default, Laravel includes the
App\Http\Middleware\TrimStrings and
Illuminate\Foundation\Http\Middleware\ConvertEmptyStringsToNull
middleware in your application's global middleware
stack. These middleware are listed in the global
middleware stack by the App\Http\Kernel
class. These middleware will automatically trim all
incoming string fields on the request, as well as
convert any empty string fields to null.
This allows you to not have to worry about these
normalization concerns in your routes and
controllers.
Disabling Input Normalization
If you would like to disable this behavior for all
requests, you may remove the two middleware from your
application's middleware stack by removing them from the
$middleware property of your
App\Http\Kernel class.
If you would like to disable string trimming and empty
string conversion for a subset of requests to your
application, you may use the skipWhen
method offered by both middleware. This method accepts a
closure which should return true or
false to indicate if input normalization
should be skipped. Typically, the skipWhen
method should be invoked in the boot method
of your application's
AppServiceProvider.
use App\Http\Middleware\TrimStrings;
use Illuminate\Http\Request;
use Illuminate\Foundation\Http\Middleware\ConvertEmptyStringsToNull;
/**
* Bootstrap any application services.
*/
public function boot(): void
{
TrimStrings::skipWhen(function (Request $request) {
return $request->is('admin/*');
});
ConvertEmptyStringsToNull::skipWhen(function (Request $request) {
// ...
});
}
Files
Retrieving Uploaded Files
You may retrieve uploaded files from an
Illuminate\Http\Request instance using the
file method or using dynamic properties.
The file method returns an instance of the
Illuminate\Http\UploadedFile class, which
extends the PHP SplFileInfo class and
provides a variety of methods for interacting with the
file:
$file = $request->file('photo');
$file = $request->photo;
You may determine if a file is present on the request
using the hasFile method:
if ($request->hasFile('photo')) {
// ...
}
Validating Successful Uploads
In addition to checking if the file is present, you may
verify that there were no problems uploading the file
via the isValid method:
if ($request->file('photo')->isValid()) {
// ...
}
File Paths and Extensions
The UploadedFile class also contains methods
for accessing the file's fully-qualified path and its
extension. The extension method will
attempt to guess the file's extension based on its
contents. This extension may be different from the
extension that was supplied by the client:
$path = $request->photo->path();
$extension = $request->photo->extension();
Other File Methods
There are a variety of other methods available on
UploadedFile instances. Check out the API
documentation for the class for more information
regarding these methods.
Storing Uploaded Files
To store an uploaded file, you will typically use one of
your configured filesystems. The
UploadedFile class has a store
method that will move an uploaded file to one of your
disks, which may be a location on your local filesystem
or a cloud storage location like Amazon S3.
The store method accepts the path where the
file should be stored relative to the filesystem's
configured root directory. This path should not contain
a filename, since a unique ID will automatically be
generated to serve as the filename.
The store method also accepts an optional
second argument for the name of the disk that should be
used to store the file. The method will return the path
of the file relative to the disk's root:
$path = $request->photo->store('images');
$path = $request->photo->store('images', 's3');
If you do not want a filename to be automatically
generated, you may use the storeAs method,
which accepts the path, filename, and disk name as its
arguments:
$path = $request->photo->storeAs('images', 'filename.jpg');
$path = $request->photo->storeAs('images', 'filename.jpg', 's3');
Note:
For more information about file storage in Laravel, check out the complete file storage documentation.
Configuring Trusted Proxies
When running your applications behind a load balancer
that terminates TLS / SSL certificates, you may notice
your application sometimes does not generate HTTPS links
when using the url helper. Typically this
is because your application is being forwarded traffic
from your load balancer on port 80 and does not know it
should generate secure links.
To solve this, you may use the
App\Http\Middleware\TrustProxies middleware
that is included in your Laravel application, which
allows you to quickly customize the load balancers or
proxies that should be trusted by your application. Your
trusted proxies should be listed as an array on the
$proxies property of this middleware. In
addition to configuring the trusted proxies, you may
configure the proxy $headers that should be
trusted:
<?php
namespace App\Http\Middleware;
use Illuminate\Http\Middleware\TrustProxies as Middleware;
use Illuminate\Http\Request;
class TrustProxies extends Middleware
{
/**
* The trusted proxies for this application.
*
* @var string|array
*/
protected $proxies = [
'192.168.1.1',
'192.168.1.2',
];
/**
* The headers that should be used to detect proxies.
*
* @var int
*/
protected $headers = Request::HEADER_X_FORWARDED_FOR | Request::HEADER_X_FORWARDED_HOST | Request::HEADER_X_FORWARDED_PORT | Request::HEADER_X_FORWARDED_PROTO;
}
Note:
If you are using AWS Elastic Load Balancing, your$headersvalue should beRequest::HEADER_X_FORWARDED_AWS_ELB. For more information on the constants that may be used in the$headersproperty, check out Symfony's documentation on trusting proxies.
Trusting All Proxies
If you are using Amazon AWS or another "cloud"
load balancer provider, you may not know the IP
addresses of your actual balancers. In this case, you
may use * to trust all proxies:
/**
* The trusted proxies for this application.
*
* @var string|array
*/
protected $proxies = '*';
Configuring Trusted Hosts
By default, Laravel will respond to all requests it
receives regardless of the content of the HTTP request's
Host header. In addition, the
Host header's value will be used when
generating absolute URLs to your application during a
web request.
Typically, you should configure your web server, such as
Nginx or Apache, to only send requests to your
application that match a given host name. However, if
you do not have the ability to customize your web server
directly and need to instruct Laravel to only respond to
certain host names, you may do so by enabling the
App\Http\Middleware\TrustHosts middleware
for your application.
The TrustHosts middleware is already
included in the $middleware stack of your
application; however, you should uncomment it so that it
becomes active. Within this middleware's
hosts method, you may specify the host
names that your application should respond to. Incoming
requests with other Host value headers will
be rejected:
/**
* Get the host patterns that should be trusted.
*
* @return array<int, string>
*/
public function hosts(): array
{
return [
'laravel.test',
$this->allSubdomainsOfApplicationUrl(),
];
}
The allSubdomainsOfApplicationUrl helper
method will return a regular expression matching all
subdomains of your application's app.url
configuration value. This helper method provides a
convenient way to allow all of your application's
subdomains when building an application that utilizes
wildcard subdomains.