![]()
WARNING You're browsing the documentation for an upcoming version of Laravel. The documentation and features of this release are subject to change.
HTTP Requests
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\Request; class UserController extends Controller { /** * Store a new user. * * @param \Illuminate\Http\Request $request * @return \Illuminate\Http\Response */ public function store(Request $request) { $name = $request->input('name'); // } }
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 & 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 yourid
route parameter by defining your controller method as follows:<?php namespace App\Http\Controllers; use Illuminate\Http\Request; class UserController extends Controller { /** * Update the specified user. * * @param \Illuminate\Http\Request $request * @param string $id * @return \Illuminate\Http\Response */ public function update(Request $request, $id) { // } }
Request Path & Method
The
Illuminate\Http\Request
instance provides a variety of methods for examining the incoming HTTP request and extends theSymfony\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 athttp://example.com/foo/bar
, thepath
method will returnfoo/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
orfullUrl
methods. Theurl
method will return the URL without the query string, while thefullUrl
method includes the query string:$url = $request->url(); $urlWithQueryString = $request->fullUrl();
Retrieving The Request Method
The
method
method will return the HTTP verb for the request. You may use theisMethod
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 theheader
method. If the header is not present on the request,null
will be returned. However, theheader
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
may be used to a bearer token from theAuthorization
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();
Content Negotiation
Laravel provides several methods for inspecting the incoming request's requested content types via the
Accept
header. First, thegetAcceptableContentTypes
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 returnstrue
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) { // });
{tip} 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 theall
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();
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, theinput
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), thequery
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 theContent-Type
header of the request is properly set toapplication/json
. You may even use "dot" syntax to retrieve values that are nested within JSON arrays:$name = $request->input('user.name');
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. Theboolean
method returnstrue
for 1, "1", true, "true", "on", and "yes". All other values will returnfalse
:$archived = $request->boolean('archived');
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 aname
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
andexcept
methods. Both of these methods accept a singlearray
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');
{note} The
only
method 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.Determining If Input Is Present
You may use the
has
method to determine if a value is present on the request. Thehas
method returnstrue
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
whenHas
method will execute the given closure if a value is present on the request:$request->whenHas('name', function ($input) { // });
The
hasAny
method returnstrue
if any of the specified values are present:if ($request->hasAny(['name', 'email'])) { // }
If you would like to determine if a value is present on the request and is not empty, you may use the
filled
method:if ($request->filled('name')) { // }
The
whenFilled
method will execute the given closure if a value is present on the request and is not empty:$request->whenFilled('name', function ($input) { // });
To determine if a given key is absent from the request, you may use the
missing
method:if ($request->missing('name')) { // }
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 theIlluminate\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
andflashExcept
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 ofIlluminate\Http\Request
. Theold
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 theold
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 anIlluminate\Http\Request
instance:$value = $request->cookie('name');
Input Trimming & Normalization
By default, Laravel includes the
App\Http\Middleware\TrimStrings
andApp\Http\Middleware\ConvertEmptyStringsToNull
middleware in your application's global middleware stack. These middleware are listed in the global middleware stack by theApp\Http\Kernel
class. These middleware will automatically trim all incoming string fields on the request, as well as convert any empty string fields tonull
. This allows you to not have to worry about these normalization concerns in your routes and controllers.If you would like to disable this behavior, you may remove the two middleware from your application's middleware stack by removing them from the
$middleware
property of yourApp\Http\Kernel
class.Files
Retrieving Uploaded Files
You may retrieve uploaded files from an
Illuminate\Http\Request
instance using thefile
method or using dynamic properties. Thefile
method returns an instance of theIlluminate\Http\UploadedFile
class, which extends the PHPSplFileInfo
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 & Extensions
The
UploadedFile
class also contains methods for accessing the file's fully-qualified path and its extension. Theextension
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 astore
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');
{tip} 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 Fideloper\Proxy\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; }
{tip} If you are using AWS Elastic Load Balancing, your
$headers
value should beRequest::HEADER_X_FORWARDED_AWS_ELB
. For more information on the constants that may be used in the$headers
property, 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 = '*';