Request Data & Replies

2 roadmaps 37 questions

The Request and Response objects a Laravel handler uses: input, uploads, the session, views, JSON, redirects, streams and API resources. Interviewers use them to check everyday handler fluency.

on this pageshow

explore

questions

page 1 of 2

In Laravel, what is an API resource class such as a JsonResource, and why return one instead of the Eloquent model itself?

juniormust knowfreq 62%

answer

a transformation layer between model and JSON
php artisan make:resource WorkoutResource
toArray(Request $request) returns the shape
$this proxies to the wrapped model
toResource() looks in App\Http\Resources

basics

~20 s

An API resource is a class extending JsonResource whose toArray() maps one model to the exact JSON the API promises, so column renames, new columns and internal fields do not leak into responses by accident.

solid answer

~40 s

A resource is generated with php artisan make:resource WorkoutResource into app/Http/Resources, extends Illuminate\Http\Resources\Json\JsonResource, and returns an explicit array from toArray(Request $request). Inside it, $this->title works because the resource forwards property reads and method calls to the wrapped model. You return it from a controller (new WorkoutResource($workout), or $workout->toResource() in Laravel 13), and Laravel turns it into a JsonResponse with the outermost payload wrapped in data. Returning the model directly serializes whatever its own toArray() produces, so the response contract follows the database schema; a resource makes the contract an explicit, reviewable allow-list that can rename fields, format dates and include relations conditionally.

A resource is generated with `php artisan make:resource WorkoutResource` into `app/Http/Resources`, extends `Illuminate\Http\Resources\Json\JsonResource`, and returns an explicit array from `toArray(Request $request)`. Inside it, `$this->title` works because the resource forwards property reads and method calls to the wrapped model. You return it from a controller (`new WorkoutResource($workout)`, or `$workout->toResource()` in Laravel 13), and Laravel turns it into a `JsonResponse` with the outermost payload wrapped in `data`. Returning the model directly serializes whatever its own `toArray()` produces, so the response contract follows the database schema; a resource makes the contract an explicit, reviewable allow-list that can rename fields, format dates and include relations conditionally.

code

bash · 2 lines

bash

php artisan make:resource WorkoutResource
php artisan make:resource WorkoutCollection

go deeper

for a junior

Recall the command, the base class and the one method: make:resource, JsonResource, toArray(Request). Be able to return new WorkoutResource($workout) from a controller and say the output is wrapped in data.

for a middle

Explain the delegation that makes $this->column work, why the stub's parent::toArray() exposes everything, and how toResource() and #[UseResource] find the class in Laravel 13.

for a senior

Argue the contract angle: a mobile API outlives app releases, so the response shape must be an explicit allow-list that a migration cannot silently widen, with model-level hiding as a backup only.

for a principal

Frame resources as the versioned boundary of a public API: when to fork a V2 resource instead of editing one, and how to keep response shapes reviewable across many teams and endpoints.

What an API resource is

An API resource in Laravel is a small class that sits between an Eloquent model and the JSON your API sends back. It extends Illuminate\Http\Resources\Json\JsonResource, receives the model through its constructor (stored in the public $resource property), and implements one method, toArray(Request $request), which returns the array that becomes the response body.

The class also implements Responsable, so a controller can return it directly: the router calls its toResponse() method, which builds an Illuminate\Http\JsonResponse. A companion class, ResourceCollection, does the same job for a list of models.

Think of a mobile fitness-tracker API. A Workout model has columns such as id, user_id, type, distance_m, duration_s, device_serial and created_at. The iOS and Android apps want distance_km, a human duration, and never the device serial. The resource is where that mapping lives.

Creating and returning one

Generate the class: php artisan make:resource WorkoutResource writes app/Http/Resources/WorkoutResource.php.
Replace the generated body of toArray() with an explicit array.
Return it from the controller: return new WorkoutResource($workout); or, in Laravel 13, return $workout->toResource();.

Two details of the generated file matter:

The stub's toArray() returns parent::toArray($request), and the parent simply calls the wrapped model's own toArray(). An untouched resource is therefore not a filter at all: it outputs every attribute the model would.
Inside toArray(), $this->distance_m and $this->user() work because the base class uses DelegatesToResource, whose __get, __isset and __call forward to $this->resource.

toResource() (and toResourceCollection() on collections and paginators) find the class by convention: for App\Models\Workout they try App\Http\Resources\WorkoutResource, then App\Http\Resources\Workout. A #[UseResource(CustomWorkoutResource::class)] attribute on the model overrides the guess, and passing a class name, toResource(CustomWorkoutResource::class), overrides both. If nothing matches, a LogicException reports that no resource class was found. Laravel 13 also adds a --json-api flag to make:resource for its first-party JSON:API resources, a separate, spec-driven variant.

Why not return the model directly

Returning $workout from a route also produces JSON, via the model's own serialization (its toArray(), filtered by the model's hidden and visible lists). The difference is where the response contract is defined.

Concern	Returning the model	Returning a resource
Which fields appear	Every column and appended accessor not hidden on the model	Only the keys listed in `toArray()`
A new column in a migration	Appears in the API on the next deploy	Invisible until someone adds it to the resource
Renaming or formatting	Needs accessors on the model, affecting every use	Done per API shape, model untouched
Conditional fields and relations	Not expressible per request	`when()`, `whenLoaded()`, `whenCounted()`
Top-level wrapper and meta	None; bare object or paginator array	`data` wrapper, `with()`, `additional()`, pagination `links` and `meta`

For a public mobile API this is decisive: shipped app versions cannot be updated instantly, so the JSON shape is a contract, and a contract should be an explicit allow-list reviewed in one file rather than a side effect of the table schema. Hiding sensitive attributes on the model is a second, model-wide safety net; it is not a substitute for choosing what each endpoint exposes. Resources also keep presentation choices, such as ISO 8601 dates, rounded units and renamed keys, out of the model, so a web page, a queued export and the mobile API can each present the same model differently.

A minimal example

php

<?php

namespace App\Http\Resources;

use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\JsonResource;

class WorkoutResource extends JsonResource
{
    public function toArray(Request $request): array
    {
        return [
            'id' => $this->id,
            'type' => $this->type,
            'distance_km' => round($this->distance_m / 1000, 2),
            'duration_s' => $this->duration_s,
            'started_at' => $this->created_at?->toIso8601String(),
        ];
    }
}

The device_serial and user_id columns never reach the client, the unit conversion lives in one place, and the model stays free of API-specific accessors.

Common traps

Leaving the stub untouched and believing the resource hides anything; it returns the model's full array.
Reading relations directly ($this->user->name) inside a resource used for a list, which lazy-loads one query per item; use whenLoaded() and eager-load in the controller.
Calling ->toArray() on the resource yourself and returning that array, which skips the wrapper, with(), additional() and status handling that toResponse() provides.
Assuming the resource changes persistence: it is output only. Saving, mass assignment and validation happen elsewhere.

## What an API resource is An **API resource** in Laravel is a small class that sits between an Eloquent model and the JSON your API sends back. It extends `Illuminate\Http\Resources\Json\JsonResource`, receives the model through its constructor (stored in the public `$resource` property), and implements one method, `toArray(Request $request)`, which returns the array that becomes the response body. The class also implements `Responsable`, so a controller can return it directly: the router calls its `toResponse()` method, which builds an `Illuminate\Http\JsonResponse`. A companion class, `ResourceCollection`, does the same job for a list of models. Think of a mobile fitness-tracker API. A `Workout` model has columns such as `id`, `user_id`, `type`, `distance_m`, `duration_s`, `device_serial` and `created_at`. The iOS and Android apps want `distance_km`, a human duration, and never the device serial. The resource is where that mapping lives. ## Creating and returning one 1. Generate the class: `php artisan make:resource WorkoutResource` writes `app/Http/Resources/WorkoutResource.php`. 2. Replace the generated body of `toArray()` with an explicit array. 3. Return it from the controller: `return new WorkoutResource($workout);` or, in Laravel 13, `return $workout->toResource();`. Two details of the generated file matter: - The stub's `toArray()` returns `parent::toArray($request)`, and the parent simply calls the wrapped model's own `toArray()`. **An untouched resource is therefore not a filter at all**: it outputs every attribute the model would. - Inside `toArray()`, `$this->distance_m` and `$this->user()` work because the base class uses `DelegatesToResource`, whose `__get`, `__isset` and `__call` forward to `$this->resource`. `toResource()` (and `toResourceCollection()` on collections and paginators) find the class by convention: for `App\Models\Workout` they try `App\Http\Resources\WorkoutResource`, then `App\Http\Resources\Workout`. A `#[UseResource(CustomWorkoutResource::class)]` attribute on the model overrides the guess, and passing a class name, `toResource(CustomWorkoutResource::class)`, overrides both. If nothing matches, a `LogicException` reports that no resource class was found. Laravel 13 also adds a `--json-api` flag to `make:resource` for its first-party JSON:API resources, a separate, spec-driven variant. ## Why not return the model directly Returning `$workout` from a route also produces JSON, via the model's own serialization (its `toArray()`, filtered by the model's hidden and visible lists). The difference is where the response contract is defined. | Concern | Returning the model | Returning a resource | |---|---|---| | Which fields appear | Every column and appended accessor not hidden on the model | Only the keys listed in `toArray()` | | A new column in a migration | Appears in the API on the next deploy | Invisible until someone adds it to the resource | | Renaming or formatting | Needs accessors on the model, affecting every use | Done per API shape, model untouched | | Conditional fields and relations | Not expressible per request | `when()`, `whenLoaded()`, `whenCounted()` | | Top-level wrapper and meta | None; bare object or paginator array | `data` wrapper, `with()`, `additional()`, pagination `links` and `meta` | For a public mobile API this is decisive: shipped app versions cannot be updated instantly, so the JSON shape is a contract, and a contract should be an explicit **allow-list** reviewed in one file rather than a side effect of the table schema. Hiding sensitive attributes on the model is a second, model-wide safety net; it is not a substitute for choosing what each endpoint exposes. Resources also keep presentation choices, such as ISO 8601 dates, rounded units and renamed keys, out of the model, so a web page, a queued export and the mobile API can each present the same model differently. ## A minimal example ```php <?php namespace App\Http\Resources; use Illuminate\Http\Request; use Illuminate\Http\Resources\Json\JsonResource; class WorkoutResource extends JsonResource { public function toArray(Request $request): array { return [ 'id' => $this->id, 'type' => $this->type, 'distance_km' => round($this->distance_m / 1000, 2), 'duration_s' => $this->duration_s, 'started_at' => $this->created_at?->toIso8601String(), ]; } } ``` The `device_serial` and `user_id` columns never reach the client, the unit conversion lives in one place, and the model stays free of API-specific accessors. ## Common traps - **Leaving the stub untouched** and believing the resource hides anything; it returns the model's full array. - **Reading relations directly** (`$this->user->name`) inside a resource used for a list, which lazy-loads one query per item; use `whenLoaded()` and eager-load in the controller. - **Calling `->toArray()` on the resource yourself** and returning that array, which skips the wrapper, `with()`, `additional()` and status handling that `toResponse()` provides. - **Assuming the resource changes persistence**: it is output only. Saving, mass assignment and validation happen elsewhere.

What does the toArray() in a freshly generated make:resource stub return?
It returns `parent::toArray($request)`, and `JsonResource::toArray()` returns the wrapped model's own `toArray()` (or the array itself if you wrapped an array, or `[]` for null). So an untouched resource outputs every visible attribute and appended accessor of the model; it only becomes an allow-list once you replace that line with explicit keys.
How does $this->distance_m resolve inside a resource that declares no such property?
`JsonResource` uses the `DelegatesToResource` trait. Its `__get` reads `$this->resource->{$key}`, `__isset` checks the same, and `__call` forwards method calls (after checking resource macros) to the wrapped model. Array access is forwarded too, so a resource wrapping an array also works with `$this['key']`.
What happens when $workout->toResource() cannot find a matching class?
It first honours a `#[UseResource]` attribute on the model, then tries `App\Http\Resources\WorkoutResource` and `App\Http\Resources\Workout`. If none of those classes exists it throws a `LogicException` saying it failed to find a resource class for the model. It never generates a class on the fly; pass a class name to `toResource()` or add the attribute.

saying these in an interview costs you the question

The make:resource stub already exposes only safe, whitelisted fields.
A resource changes how the model is stored or validated.
$this->title fails inside a resource because JsonResource has no title property.
Returning the model is just as safe, because new columns never reach the JSON.
toResource() generates a resource class at runtime when none exists.
Resources are only for collections; single models should be returned bare.

§explore

▾sections7 · 37 questions

▾roadmaps that cover this2

§questions

In Laravel, what is an API resource class such as a JsonResource, and why return one instead of the Eloquent model itself?

§ answer

basics

solid answer

code

§ go deeper

▾level notes4 levels

▾deep dive~4 min

What an API resource is

Creating and returning one

Why not return the model directly

A minimal example

Common traps

▾common follow-ups3 questions

▾red flags6 flags

In a Laravel controller, how do $request->input(), query(), all(), only() and except() differ when reading a search form?

basics

In Laravel, how do redirect()->to(), redirect()->route(), to_route(), back() and redirect()->away() differ, and which status do they send?

basics

In a Laravel route or controller, what response does the framework build when you return a string, an array, an Eloquent model or a view?

basics

In Laravel, how do you store, read and remove session data with get(), put(), push(), pull() and forget()?

basics

In a Laravel controller, how do you read an uploaded profile photo and save it to a disk with store()?

basics

In a Laravel API resource, what do whenLoaded() and whenCounted() do, and why use them instead of reading the relation directly?

basics

In Laravel, how do $request->has(), filled() and missing() differ for a search field submitted empty or not at all?

basics

In Laravel, how does redirect()->intended() send a bookshop customer back to the checkout page after login, and where does url.intended come from?

basics

In Laravel, how long does session flash data live, and what do reflash(), keep() and now() change about it?

basics

In Laravel, how do you use response()->streamDownload() to export a million-row sales report as CSV without building it in memory?

basics

In Laravel's UploadedFile, why prefer hashName() and extension() over getClientOriginalName() and clientExtension() when saving a photo?

basics

In Laravel, what changes when response()->stream() receives a generator closure instead of a plain closure that echoes output?

basics

In Laravel, when do you write a ResourceCollection class instead of calling WorkoutResource::collection(), and how do with() and additional() add top-level meta?

basics

In a Laravel API resource, how do when() and mergeWhen() include fields only for some viewers, and what removes the key otherwise?

basics

In Laravel, how do $request->flash(), flashOnly(), flashExcept() and the old() helper repopulate a form on the next request?

basics

In Laravel, what is the difference between $request->merge() and mergeIfMissing(), and why can mergeIfMissing() leave a blank field unset?

basics

In Laravel, what do $request->boolean(), integer(), date() and enum() return when a field is missing, empty or malformed?

basics

In Laravel, why do redirects after a POST default to 302, when would you send 303 instead, and how do you do it?

basics

On a Laravel RedirectResponse, what do with(), withInput() and withErrors() each put in the session for the next request?

basics

In Laravel, how do you set a cookie with response()->cookie() or withCookie() versus Cookie::queue(), and when do you need each?

basics

In Laravel, how do response()->download() and response()->file() differ when a concert-venue app serves a PDF ticket?

basics

In Laravel, when do you use response()->json() instead of returning an array, and what do its status, headers and options arguments control?

basics

In Laravel 13, what does SESSION_DRIVER default to, and how do the database, file, cookie, redis and array drivers differ?

basics

In Laravel, how does response()->eventStream() send a live progress feed, and what are StreamedEvent and the </stream> end marker for?

basics

In Laravel, what is the difference between $request->hasFile('photo') and $request->file('photo')->isValid() for an upload?

basics

In Laravel, what does storePublicly() change compared with store() on an UploadedFile, and what does it not change?

basics

In Laravel, what does JsonResource::withoutWrapping() change for a mobile API, and which resource responses still arrive wrapped in a data key?

basics

A Laravel API client posts JSON without an Accept header and gets a 302 redirect instead of JSON errors; what does expectsJson() check, and why?

basics

A Laravel bookshop redirects after login with redirect()->to($request->input('return')); why is that an open redirect, and how do you fix it?

basics

What an API resource is

Creating and returning one

Why not return the model directly

explore

questions

answer

go deeper