Skip to content

Responses

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

HTTP Responses

All route handlers and controller actions must return a Laravex.Http.Response struct (or a plain binary, which the kernel wraps in an HTML response). The Laravex.Http.Response module provides constructors for every common response type.

Creating Responses

HTML

Response.html("<h1>Hello</h1>")
Response.html("<h1>Created</h1>", 201)

JSON

Response.json(%{name: "Alice", age: 30})
Response.json(%{message: "Created"}, 201)

String keys are normalised automatically. The Content-Type header is set to application/json; charset=utf-8.

Paginated JSON

Wrap a paginator page map in a Laravel-compatible LengthAwarePaginator envelope:

page = Laravex.Database.Query.table("posts") |> Laravex.Http.Paginator.paginate(request)
Response.json_paginated(page)

# Apply a mapper to transform each item:
Response.json_paginated(page, fn post ->
  Map.take(post, ["id", "title", "created_at"])
end)

The JSON envelope contains data, links (first/last/prev/next), and meta (current_page, last_page, per_page, total, from, to).

Plain Text / Raw

Response.new(200, "plain text", [{"content-type", "text/plain"}])

Redirects

Response.redirect("/posts")        # 302 Found
Response.redirect("/posts", 301)   # 301 Moved Permanently

Using the helper functions imported by use App.Http.Controllers.Controller:

redirect("/posts")
to_route("posts.index")                        # redirect by route name
to_route("posts.show", %{"id" => post.id})
back()                          # redirect to Referer / previous URL
back("/fallback")
refresh()                       # redirect to the current URL (page reload)
redirect_intended("/dashboard") # redirect to stored intended URL
redirect_with("/", %{status: "Profile updated"})  # with flash data
redirect_with_input("/form")    # redirect back with old input
redirect_with_errors("/form", errors)  # redirect back with validation errors

Status Codes

Constructor Status
Response.html/2 200 (default)
Response.json/2 200 (default)
Response.no_content/0 204
Response.created/1 201
Response.redirect/2 302 (default)

The full set of recognised reason phrases: 200, 201, 204, 302, 400, 401, 403, 404, 419, 422, 429, 500. Unknown codes default to "OK".

Abort with any status using the abort/2 helper:

abort(403)
abort(404, "Post not found")
abort(401, "Unauthenticated")

This raises Laravex.Http.HttpException, which the Error-Handling layer converts to the appropriate response.

File Downloads

# From binary content
Response.download(csv_data, "export.csv")
Response.download(csv_data, "export.csv", content_type: "text/csv")

# Inline display (PDF, images)
Response.download(pdf_bytes, "report.pdf",
  content_type: "application/pdf",
  inline: true)

# From a filesystem path
Response.file("/absolute/path/to/file.zip")
Response.file("/path/to/image.png", as: "photo.png", inline: true)

download/3 sets Content-Disposition: attachment by default. Pass inline: true to use Content-Disposition: inline instead.

Attaching Cookies

response
|> Response.with_cookie("token", "abc123")
|> Response.with_cookie("theme", "dark",
     max_age: 60 * 60 * 24 * 365,
     path:      "/",
     http_only: false,
     secure:    true,
     same_site: "strict")

Cookie defaults come from the session configuration (session.path, session.domain, session.secure, session.same_site, session.http_only).

Queue a cookie without direct access to the response using the cookie/3 helper (processed by AddQueuedCookies):

cookie("remember_me", user_token, max_age: 60 * 60 * 24 * 30)

Adding Headers

Build a response with custom headers via Response.new/3:

Response.new(200, body, [
  {"content-type", "application/xml"},
  {"x-request-id", request_id}
])

Fluently add headers to any existing response (Laravel withHeaders):

response
|> Response.with_header("x-custom", "value")
|> Response.with_headers(%{"x-foo" => "bar", "x-baz" => "qux"})
|> Response.with_headers([{"x-list", "a"}, {"x-list", "b"}])

Fluently change the status code:

response = Response.with_status(response, 201)

Or set cache headers with the cache.headers Middleware alias:

Router.get("/feed", {FeedController, :index},
  middleware: ["cache.headers:public;max_age=3600;etag"])

Clone this wiki locally