How to Use API Resource Collection in Laravel for JSON Responses

In Laravel, use Resource Collections by creating a resource class that extends Illuminate\Http\Resources\Json\ResourceCollection. Return this collection from your controller to format multiple models into a consistent JSON structure automatically.

Syntax

To use an API resource collection in Laravel, create a resource collection class that extends ResourceCollection. Then return an instance of this collection from your controller method.

• ResourceCollection: Base class for collections of resources.
• toArray(): Method to customize the data array for each item.
• Return the collection instance from controller to send formatted JSON.

php

use Illuminate\Http\Resources\Json\ResourceCollection;

class UserCollection extends ResourceCollection
{
    public function toArray($request)
    {
        return [
            'data' => $this->collection->transform(function($user) {
                return [
                    'id' => $user->id,
                    'name' => $user->name,
                    'email' => $user->email,
                ];
            }),
        ];
    }
}

Example

This example shows how to create a UserCollection resource and use it in a controller to return a JSON response of all users formatted consistently.

php

<?php

namespace App\Http\Controllers;

use App\Models\User;
use App\Http\Resources\UserCollection;

class UserController extends Controller
{
    public function index()
    {
        $users = User::all();
        return new UserCollection($users);
    }
}

// UserCollection.php
namespace App\Http\Resources;

use Illuminate\Http\Resources\Json\ResourceCollection;

class UserCollection extends ResourceCollection
{
    public function toArray($request)
    {
        return [
            'data' => $this->collection->transform(function($user) {
                return [
                    'id' => $user->id,
                    'name' => $user->name,
                    'email' => $user->email,
                ];
            }),
        ];
    }
}

Output

{
  "data": [
    {"id":1,"name":"Alice","email":"[e-mail]"},
    {"id":2,"name":"Bob","email":"[e-mail]"}
  ]
}

Common Pitfalls

Common mistakes when using API resource collections include:

• Returning the raw model collection instead of wrapping it in a resource collection class.
• Not customizing the toArray() method, which can lead to exposing unwanted fields.
• Forgetting to import the resource collection class in the controller.

php

/* Wrong way: returning raw collection */
public function index()
{
    $users = User::all();
    return $users; // This returns raw data without formatting
}

/* Right way: wrapping in resource collection */
public function index()
{
    $users = User::all();
    return new UserCollection($users); // Properly formatted JSON
}

Quick Reference

• Create a resource collection class with php artisan make:resource UserCollection --collection.
• Customize toArray() to format each item.
• Return the collection instance from controller methods.
• Use transform() or map() on $this->collection to shape data.

Key Takeaways

Always wrap model collections in a resource collection class to format JSON responses.

Customize the toArray() method to control the output structure and fields.

Return the resource collection instance from your controller for consistent API responses.

Use Laravel's artisan command to generate resource collections quickly.

Avoid returning raw model collections directly to prevent exposing sensitive data.