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:iorequest.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 -
The request cookies (Laravel's
$request->cookies->all()), parsed like PHP's$_COOKIE: URL-decoded, first occurrence wins. Values are as sent; Laravel'sEncryptCookiesis 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="...">); aSecurityHeadersMiddlewarepolicy that listsCsp.noncesends 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-Lengthabove 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-Hostwhen trusted).no setter - htmxTarget → String?
-
Available on Request, provided by the HtmxRequest extension
Theidof the element htmx swaps the response into (HX-Target).no setter - htmxTrigger → String?
-
Available on Request, provided by the HtmxRequest extension
Theidof 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(seeTrustProxiesMiddleware).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'sisFromTrustedProxy()). Without it scheme, host and url come from the request line, theHostheader 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 anhx-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;
nullmeans unlimited.getter/setter pair - maxJsonDepth ↔ int?
-
Maximum JSON nesting depth accepted by body;
nullmeans unlimited.getter/setter pair - method → String
-
Upper-cased HTTP method, after a
_methodoverride.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[]=2is a list,filter[status]=xa 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-Protowhen 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. -
Available on Request, provided by the RequestAuth extension
Throws 403 unless the current user may performability. -
bearerToken(
) → String? -
Token from an
Authorization: Bearer <token>header. -
bearerToken(
) → String? -
Available on Request, provided by the RequestAuth extension
TheAuthorization: Bearervalue, if any. -
binding<
T> (String param) → T -
The object bound to route parameter
param(seeRouter.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 (ornullwhen 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 whatTrimStringsmade 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'):truefortrue,1,"1","true","on"and"yes"(PHP'sFILTER_VALIDATE_BOOLEAN),falsefor anything else, andfallbackwhen the key is missing. -
bytes(
) → Future< List< int> > -
Reads the raw body (once; cached). Throws
PayloadTooLargeHttpException when maxBodyBytes is exceeded, checking
content-lengthfirst 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 doabilitywithargs. -
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 doability. -
The cookie
name, orfallback(Laravel's$request->cookie()). -
defer(
FutureOr< void> callback()) → void -
Schedules
callbackto run after the response has been sent (Laravel'sdefer()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), ornull($request->file('avatar')). -
float(
String key, [double fallback = 0]) → Future< double> -
$request->float('price'): the input as adouble, orfallback. -
has(
String key) → Future< bool> -
Whether
keyis present in the input (even if empty). -
hasCookie(
String name) → bool -
Whether the request carries the cookie
name. -
hasFile(
String key) → Future< bool> -
Whether
keyholds an uploaded file, or a list with at least one ($request->hasFile('photos')). -
header(
String name) → String? -
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 anint, orfallbackwhen it is missing or not a number. -
make<
T extends Object> ({String? name}) → T -
Resolves
Tfrom the container of the active request scope. -
merge(
Map< String, Object?> input) → Future<void> -
Adds
inputto the body's fields, overwriting those of the same name, like Laravel's$request->merge(): all,inputand 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}withid = abcyields a 404 (Laravel parity). -
queryBool(
String key, [bool fallback = false]) → bool -
The query parameter
keyas abool(like boolean), orfallbackwhen it is missing. -
queryDouble(
String key, [double fallback = 0]) → double -
The query parameter
keyas adouble, orfallback. -
queryInt(
String key, [int fallback = 0]) → int -
The query parameter
key(dot notation) as anint, withoutawait(?page=2→2), orfallback. Converted like integer. -
queryString(
String key, [String fallback = '']) → String -
The query parameter
keyas aString, orfallbackwhen 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.inputis 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 aString(numbers and booleans are converted), orfallbackwhen 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 (viaguardor 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
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 limitBodyLimitsMiddlewareapplies. The engine replaces it withServeOptions.maxBodyBytes(HTTP_MAX_BODY), the middleware andRouteEntry.bodyLimitwith theirs. - validatedAttribute → const String
-
Request attribute holding the result of the route's declared
validation (
.validates()/.rules()).