Skip to content

Requests

David Ciulla edited this page Nov 7, 2026 · 2 revisions

HTTP Requests

Every route handler and controller action receives a Laravex.Http.Request struct as its first argument. The struct carries the method, path, parsed parameters, headers, cookies, session, authenticated user, uploaded files, flash data, and validation state for the current request.

The Request Struct

%Laravex.Http.Request{
  method:       "GET",        # uppercased HTTP verb
  path:         "/posts/1",   # request path (no query string)
  query:        %{},          # parsed query string
  headers:      %{},          # lowercased header map
  body:         "",           # raw body
  params:       %{},          # merged query + body + route params
  files:        %{},          # uploaded files (%UploadedFile{})
  cookies:      %{},          # parsed cookie map
  session:      %{},          # session data for this request
  session_id:   nil,          # session ID string
  user:         nil,          # authenticated user (or nil)
  expects_json: false,        # true when Accept prefers JSON
  route_params: %{},          # params extracted from the URI pattern
  errors:       %{},          # validation errors from the previous request
  old:          %{},          # old input flashed from the previous request
  flash:        %{},          # flash messages for this request
  peer:         nil,          # raw peer IP (before TrustProxies)
  validated:    %{}           # params that passed FormRequest validation
}

Retrieving Input

input/3

Retrieve a single input value. Returns default (defaults to nil) when the key is absent:

Request.input(request, "title")
Request.input(request, "page", 1)

all/1

Return all merged input as a map:

Request.all(request)   # => %{"title" => "Hello", "page" => "1"}

only/2 and except/2

Return a subset of the input:

Request.only(request, ["title", "body"])
Request.except(request, ["_token"])

has?/2, has_any?/2, has_all?/2, and missing?/2

Check whether keys are present in the input (regardless of their value):

Request.has?(request, "search")
Request.missing?(request, "search")

# True when ANY of the given keys is present
Request.has_any?(request, ["name", "email", "username"])

# True when ALL of the given keys are present
Request.has_all?(request, ["email", "password"])

filled?/2

Returns true when the key is present and not blank (nil, "", [], or empty map):

Request.filled?(request, "email")

boolean/2

Coerce a checkbox or flag value to a boolean. Treats true, 1, "1", "true", "on", and "yes" as true:

Request.boolean(request, "subscribe")

Typed Getters

# Integer (returns default on parse failure, default: 0)
Request.integer(request, "page", 1)

# Float (returns default on parse failure, default: 0.0)
Request.float(request, "price")

# String (always returns a string, default: "")
Request.string(request, "name")

# Date (%Date{}, default: nil)
Request.date(request, "published_at")

# Enum — return value only when it is in allowed list
Request.enum(request, "status", ["published", "draft"], "draft")

# value/3 — same as input/3 (alias)
Request.value(request, "search", "")

Conditional Callbacks

Call a function when a key is present / filled / missing:

# when_has — call fun when the key is present
Request.when_has(request, "search", fn req ->
  IO.inspect(Request.input(req, "search"))
  req
end)

# when_filled — call fun when the key is filled (non-blank)
Request.when_filled(request, "email", fn req -> ... end)

# when_missing — call fun when the key is absent
Request.when_missing(request, "token", fn req -> ... end)

# when_not_has — call fun when the key is absent
Request.when_not_has(request, "debug", fn req -> ... end)

# when_not_filled — call fun when the key is blank/missing
Request.when_not_filled(request, "coupon", fn req -> ... end)

merge/2, replace/2, and merge_if_missing/2

# Merge new values into the existing params
request = Request.merge(request, %{"user_id" => 42})

# Replace all params
request = Request.replace(request, %{"new_key" => "new_value"})

# Merge only keys that are not already present
request = Request.merge_if_missing(request, %{"page" => 1, "per_page" => 15})

Headers

Request.header(request, "content-type")
Request.header(request, "x-api-key", "default")

# Bearer token from Authorization header:
Request.bearer_token(request)   # => "some.jwt.token" or nil

Content Negotiation

# Accept includes application/json or +json
Request.wants_json?(request)

# X-Requested-With: XMLHttpRequest
Request.ajax?(request)

# Accept includes any of the given types
Request.accepts?(request, ["text/html", "application/json"])

# Combined: wants_json? OR expects_json field is true
Request.expects_json?(request)

URL and Path

# Full URL including query string (uses app.url config)
Request.full_url(request)   # => "https://example.com/posts?page=2"

# Pattern match against the path (supports * wildcard)
Request.is?(request, "api/*")
Request.is?(request, "posts/*/edit")

Client Information

# Real IP, respecting X-Forwarded-For via TrustProxies
Request.ip(request)       # => "1.2.3.4"

# Is the connection HTTPS (after TrustProxies / X-Forwarded-Proto)?
Request.secure?(request)  # => true | false

# Is this a safe (read-only) HTTP method?
Request.safe?(request)    # GET, HEAD, OPTIONS => true

Uploaded Files

Multipart files are parsed into Laravex.Http.UploadedFile structs and stored in request.files. Retrieve them with Request.file/2:

file = Request.file(request, "avatar")
# => %Laravex.Http.UploadedFile{filename: "photo.jpg", content_type: "image/jpeg", ...}

file.filename       # original filename
file.content_type   # MIME type from the multipart header
file.size           # byte size (integer)
file.contents       # raw binary content

# Helpers on the struct:
Laravex.Http.UploadedFile.extension(file)   # => "jpg"
Laravex.Http.UploadedFile.image?(file)      # => true
Laravex.Http.UploadedFile.mime_type(file)   # => "image/jpeg"
Laravex.Http.UploadedFile.size_kb(file)     # => 42

# Store to disk:
Laravex.Http.UploadedFile.store(file, "avatars", "public")

In-Request Validation

You may call Request.validate/2 for ad-hoc validation without a Validation#Form Requests:

{:ok, validated} = Request.validate(request, %{
  "email" => "required|email",
  "name"  => "required|min:2"
})

Returns {:ok, validated_map} or {:error, errors_map}. For web requests that should redirect on failure, prefer Laravex.Validation.validate_request/3 or a FormRequest (which raises Laravex.Validation.Failed automatically).

Accessing Old Input

After a failed form submission the previous input is available via request.old or the old/2 helper:

Request.input(request, "email")     # current request
Map.get(request.old, "email")       # previous request's input

# In a Blade template:
# {{ old('email') }}

Clone this wiki locally