Request class final

Incoming HTTP request (BLUEPRINT_V2 §7.2.2).

Instances are created by the server engine from dart:io requests or by Request.fake in tests. The body is read lazily, at most once, and never beyond maxBodyBytes.

Available extensions

Constructors

Request.fake({String method = 'GET', String path = '/', Object? json, Map<String, String>? form, Map<String, Object>? files, String? body, Map<String, String>? headers, Map<String, String>? query, String ip = '127.0.0.1', String? id})
Builds a synthetic request without opening a socket.
factory
Request.fromHttpRequest(HttpRequest httpRequest, {required String id, bool secure = false, String listenerAuthority = 'localhost'})
Wraps a dart:io request.
factory

Properties

acceptsHtml → bool
Whether the client accepts HTML.
no setter
attributes → Map<String, Object?>
Arbitrary per-request data shared between middleware and handlers.
final
auth → AuthManager

Available on Request, provided by the RequestAuth extension

The auth manager of the current container.
no setter
contentLength → int?
Declared content-length, if present and valid.
no setter
cookies → Map<String, String>
The request cookies (Laravel's $request->cookies->all()), parsed like PHP's $_COOKIE: URL-decoded, first occurrence wins. Values are as sent; Laravel's EncryptCookies is not applied.
no setter
cspNonce → String
This request's Content-Security-Policy nonce: 16 bytes from a CSPRNG, base64, made on first read and the same for the rest of the request. Put it on inline scripts and styles (<script nonce="...">); a SecurityHeadersMiddleware policy that lists Csp.nonce sends it as 'nonce-...', so those run without 'unsafe-inline'. Each request has its own, so a nonce seen in one page is no use to an injected script in another.
no setter
expectsJson → bool
Whether the client expects a JSON response.
no setter
gate → AuthorizationGate

Available on Request, provided by the RequestAuth extension

The gate of the current container.
no setter
hasCspNonce → bool
Whether cspNonce has been made for this request.
no setter
hashCode → int
The hash code for this object.
no setterinherited
hasUnreadBody → bool
Whether the body is still on the socket, unread and unclaimed: nothing called bytes, body or bodyStream for it, or the call was refused before reading (a declared Content-Length above maxBodyBytes). The server takes such a body off the connection itself before it answers, so the response never waits for a client that sends it slowly. Always false for Request.fake.
no setter
headers → Headers
Request headers.
final
host → String
Host as seen by the client (X-Forwarded-Host when trusted).
no setter
htmxTarget → String?

Available on Request, provided by the HtmxRequest extension

The id of the element htmx swaps the response into (HX-Target).
no setter
htmxTrigger → String?

Available on Request, provided by the HtmxRequest extension

The id of the element that triggered the request (HX-Trigger).
no setter
id → String
Unique request id (also echoed as x-request-id).
final
ip → String
Client address. Equals remoteAddress unless a trusted proxy supplied X-Forwarded-For (see TrustProxiesMiddleware).
no setter
ips → List<String>
Full forwarding chain, client first; [remoteAddress] without proxies.
no setter
isFromTrustedProxy → bool
Whether a trusted proxy's forwarding headers were applied to this request (TrustProxiesMiddleware; Laravel's isFromTrustedProxy()). Without it scheme, host and url come from the request line, the Host header and the listener only.
no setter
isHtmx → bool

Available on Request, provided by the HtmxRequest extension

Whether htmx sent the request (HX-Request: true).
no setter
isHtmxBoosted → bool

Available on Request, provided by the HtmxRequest extension

Whether it came from an hx-boosted link or form (HX-Boosted: true).
no setter
isJson → bool
Whether the body is JSON.
no setter
isSecure → bool
Whether the client connection used HTTPS.
no setter
maxBodyBytes ↔ int?
Maximum body size accepted by bytes; null means unlimited.
getter/setter pair
maxJsonDepth ↔ int?
Maximum JSON nesting depth accepted by body; null means unlimited.
getter/setter pair
method → String
Upper-cased HTTP method, after a _method override.
no setter
originalMethod → String
The method on the wire (Laravel's getRealMethod).
final
path → String
Path component of the URI.
no setter
query → Map<String, String>
Single-valued query parameters.
no setter
queryInput → Map<String, Object?>
Query parameters as Laravel reads them (PHP's parse_str): ids[]=1&ids[]=2 is a list, filter[status]=x a map, and a repeated plain key keeps its last value.
no setter
queryMulti → Map<String, List<String>>
Multi-valued query parameters.
no setter
remoteAddress → String
Address of the TCP peer (a proxy when one is in front of the app).
final
route → RouteEntry?
The matched route (set by the kernel).
no setter
routeParams → Map<String, String>
Raw route parameters (set by the kernel).
no setter
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
scheme → String
Scheme as seen by the client (X-Forwarded-Proto when trusted).
no setter
signedHost → String?
The host a signed URL of this route covers: the route's own, and none for a route that answers on any host.
no setter
uri → Uri
Full request URI as received by the server.
final
url → String
Scheme, host (with a non-default port) and path, without the query string or trailing slash (Laravel $request->url()), e.g. http://localhost/api/users.
no setter

Methods

addInputTransformer(InputTransformer transformer) → void
Registers a transformer applied to every input value returned by all and input (strings are visited recursively inside maps/lists).
all() → Future<Map<String, Object?>>
Merged input: query parameters overlaid by body fields (body wins), with input transformers applied. Computed once per request (until a transformer is added); each call returns a fresh top-level map.
applyForwarded({String? ip, List<String>? ips, String? scheme, String? host}) → void
Records forwarding information. Called by TrustProxiesMiddleware.
authorize(String ability, [List<Object?> args = const <Object?>[]]) → Future<AuthResponse>

Available on Request, provided by the RequestAuth extension

Throws 403 unless the current user may perform ability.
bearerToken() → String?
Token from an Authorization: Bearer <token> header.
bearerToken() → String?

Available on Request, provided by the RequestAuth extension

The Authorization: Bearer value, if any.
binding<T>(String param) → T
The object bound to route parameter param (see Router.bind). Throws StateError when nothing was bound.
bindRoute(RouteEntry route, Map<String, String> params) → void
Binds the matched route and its parameters. Called by the HTTP kernel.
body() → Future<Object?>
Parses the body according to its content type: JSON → decoded value, form → a map read like PHP's parse_str (see parseQueryString), otherwise the raw text (or null when empty).
bodyInput() → Future<Map<String, Object?>>
The body's fields as all sees them, without the query (Laravel's getInputSource()->all()): the transformers the fields have not been through yet applied, so a body sent by the client gets all of them and a replaced one only those registered since. A middleware that rebuilds the body with replace starts from this, so the fields the client sent keep what TrimStrings made of them.
bodyStream() → Stream<List<int>>
The raw body as it arrives, once, never above maxBodyBytes: for forwarding it (UpstreamProxy) or writing it somewhere without buffering. After bytes it replays the cached bytes.
boolean(String key, [bool fallback = false]) → Future<bool>
$request->boolean('remember'): true for true, 1, "1", "true", "on" and "yes" (PHP's FILTER_VALIDATE_BOOLEAN), false for anything else, and fallback when the key is missing.
bytes() → Future<List<int>>
Reads the raw body (once; cached). Throws PayloadTooLargeHttpException when maxBodyBytes is exceeded, checking content-length first and the actual stream second.
can(String ability, [List<Object?> args = const <Object?>[]]) → Future<bool>

Available on Request, provided by the RequestAuth extension

Whether the request's user may do ability with args.
cannot(String ability, [List<Object?> args = const <Object?>[]]) → Future<bool>

Available on Request, provided by the RequestAuth extension

Whether the request's user may not do ability.
The cookie name, or fallback (Laravel's $request->cookie()).
defer(FutureOr<void> callback()) → void
Schedules callback to run after the response has been sent (Laravel's defer() helper); errors are reported, never surfaced to the client.
deleteUploads() → Future<void>
Deletes the temporary files of the uploads; runs when the request scope ends (after the response is sent).
detachBody() → void
Lets go of the socket's body: a request upgraded to a WebSocket has none, and the stream would keep the whole HTTP request (parser, headers, response) alive as long as the connection.
file(String key) → Future<UploadedFile?>
The uploaded file at key (dot notation: photos.0), or null ($request->file('avatar')).
float(String key, [double fallback = 0]) → Future<double>
$request->float('price'): the input as a double, or fallback.
has(String key) → Future<bool>
Whether key is present in the input (even if empty).
hasCookie(String name) → bool
Whether the request carries the cookie name.
hasFile(String key) → Future<bool>
Whether key holds an uploaded file, or a list with at least one ($request->hasFile('photos')).
First value of header name.
input<T>(String key, [T? fallback]) → Future<T?>
Dot-notation input lookup across body and query (user.email).
inputSync<T>(String key, [T? fallback]) → T?
input for code that cannot wait, such as a model scope. It sees the body only once something awaited the input of this request (a validation, a filter, all); until then the query string.
integer(String key, [int fallback = 0]) → Future<int>
$request->integer('page', 1): the input as an int, or fallback when it is missing or not a number.
make<T extends Object>({String? name}) → T
Resolves T from the container of the active request scope.
merge(Map<String, Object?> input) → Future<void>
Adds input to the body's fields, overwriting those of the same name, like Laravel's $request->merge(): all, input and validation see it from now on. The body is read first when it was not.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
overrideMethod(String method) → void
Used by MethodOverrideMiddleware.
param<T>(String key, {T parse(String raw)?}) → T
Typed route parameter. Supports String, int, double, bool. Throws NotFoundHttpException when missing or unparsable, so a route like /users/{id} with id = abc yields a 404 (Laravel parity).
queryBool(String key, [bool fallback = false]) → bool
The query parameter key as a bool (like boolean), or fallback when it is missing.
queryDouble(String key, [double fallback = 0]) → double
The query parameter key as a double, or fallback.
queryInt(String key, [int fallback = 0]) → int
The query parameter key (dot notation) as an int, without await (?page=2 → 2), or fallback. Converted like integer.
queryString(String key, [String fallback = '']) → String
The query parameter key as a String, or fallback when it is missing.
replace(Map<String, Object?> input) → void
Replaces the body's fields with input, like Laravel's $request->replace(); query parameters stay. A body not read yet is discarded. input is kept as given: the input transformers registered so far do not apply to it.
replaceCookies(Map<String, String> cookies) → void
Replaces the parsed cookies: what a middleware that decrypts them (EncryptCookies) calls, as Laravel's $request->cookies->set().
setBinding(String param, Object? value) → void
Stores the object bound to route parameter param. Called by the router.
string(String key, [String fallback = '']) → Future<String>
$request->string('name'): the input as a String (numbers and booleans are converted), or fallback when it is missing.
takeDeferred() → List<FutureOr<void> Function()>
Deferred callbacks registered with defer. Consumed by the kernel.
toString() → String
A string representation of this object.
override
uploadedFiles() → Future<List<UploadedFile>>
Every file uploaded with this request.
user<T extends Authenticatable>({String? guard}) → Future<T?>

Available on Request, provided by the RequestAuth extension

The authenticated user (via guard or the active/default guard).
validate(Map<String, Object> rules, {Map<String, String> messages = const <String, String>{}, Map<String, String> attributes = const <String, String>{}}) → Future<ValidatedData>
Validates the merged input (Laravel $request->validate()): throws a 422 ValidationException on failure, otherwise returns only the validated attributes.
validated() → ValidatedData
The input validated by the route's .validates(FormRequest) or .rules({...}) (Laravel's $request->validated()); throws a StateError when the route declares neither.

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Static Properties

current → Request?
The request being handled, from anywhere in its zone (Laravel's request()): a helper, an observer, a listener run synchronously. null outside a request (a job, a command, a test without one). Prefer the handler's request parameter where there is one.
no setter

Constants

defaultMaxBodyBytes → const int
The body limit every request starts with, served or synthetic (Request.fake, the test client), so both paths behave the same: 50 MiB, the widest limit BodyLimitsMiddleware applies. The engine replaces it with ServeOptions.maxBodyBytes (HTTP_MAX_BODY), the middleware and RouteEntry.bodyLimit with theirs.
validatedAttribute → const String
Request attribute holding the result of the route's declared validation (.validates() / .rules()).