Use whenLoaded() inside API Resources to include related models only when they have been explicitly eager-loaded by the controller.
When transforming Eloquent models into JSON responses using API Resources, referencing relationships directly ('author' => new UserResource($this->author)) causes lazy-loading queries if the controller did not eager-load the relation, triggering N+1 query bottlenecks.
whenLoaded() includes the relationship only if it was already loaded.
Using whenLoaded in API Resources
namespace App\Http\Resources;
use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\JsonResource;
class PostResource extends JsonResource
{
public function toArray(Request $request): array
{
return [
'id' => $this->id,
'title' => $this->title,
'slug' => $this->slug,
// Included in JSON only if $post->relationLoaded('author') is true
'author' => new UserResource($this->whenLoaded('author')),
// Included only if comments were eager-loaded
'comments' => CommentResource::collection($this->whenLoaded('comments')),
];
}
}Controller Usage
// Relationship included without N+1 queries
return PostResource::collection(Post::with('author')->paginate(15));
// Relationship omitted automatically from JSON output
return PostResource::collection(Post::paginate(15));Summary
- Prevents accidental lazy-loading queries during JSON serialization.
- Keeps API resources reusable across lightweight index listings and detailed show endpoints.
- Automatically omits un-eager-loaded keys from the serialized JSON payload.
Related Tips
View all tips →Handle Hybrid API and Web Controllers with $request->expectsJson()
Use $request->expectsJson() in hybrid controllers to serve formatted JSON responses to API/AJAX requests and redirects to standard web browsers.
Authenticate External API Requests Cleanly with withToken()
Use withToken() on the Laravel HTTP client to attach Authorization Bearer tokens without manual header string formatting.