🎁 API Resources and Transformations

Why Resources Exist

In the previous lesson we returned models straight from the controller with response()->json($product). That works, but it has real problems: it leaks every column (including cost_price and supplier_id), it uses your raw database field names, and the JSON shape is scattered across every controller action. Change the format once and you're hunting through the whole app.

API Resources fix this. A resource is a small class whose only job is to turn a model into an array. Your controller returns the resource; the resource decides the shape.

💡 Analogy: Think of a resource as a professional gift-wrapper. The database hands you the raw product; the resource wraps it so only what the recipient should see is presented — nicely formatted, nothing private poking out.

Creating & Using a Resource

Generate one with Artisan. It lands in app/Http/Resources:

php artisan make:resource ProductResource

<?php
// app/Http/Resources/ProductResource.php
namespace App\Http\Resources;

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

class ProductResource extends JsonResource
{
    /**
     * Transform the resource into an array.
     *
     * @return array<string, mixed>
     */
    public function toArray(Request $request): array
    {
        return [
            'id'          => $this->id,
            'name'        => $this->name,
            'price'       => $this->price,
            'description' => $this->description,
            'created_at'  => $this->created_at,
        ];
    }
}

Inside the resource, $this transparently proxies to the underlying model, so $this->name reads the model's name. In the controller you wrap a single model in the resource, or use ::collection() for many:

<?php
// app/Http/Controllers/Api/ProductController.php
namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use App\Http\Resources\ProductResource;
use App\Models\Product;

class ProductController extends Controller
{
    public function show(Product $product): ProductResource
    {
        return new ProductResource($product);
    }

    public function index()
    {
        // Pagination is preserved automatically
        return ProductResource::collection(Product::paginate(15));
    }
}

Transformation Techniques

The whole point of a resource is that toArray() is ordinary PHP — you can reshape the data however you like.

Rename fields

Give the API a public vocabulary that doesn't have to match your columns:

<?php
return [
    'id'           => $this->id,
    'product_name' => $this->name,        // renamed from "name"
    'details'      => $this->description, // renamed from "description"
];

Format values

Send clients data that's ready to display — grouped and pre-formatted:

<?php
return [
    'id'    => $this->id,
    'name'  => $this->name,
    'price' => [
        'amount'    => $this->price,
        'formatted' => '$' . number_format($this->price, 2),
    ],
    'created_at' => $this->created_at->toIso8601String(),
];

Computed properties

Add values that don't exist as columns at all:

<?php
return [
    'id'           => $this->id,
    'name'         => $this->name,
    'price'        => $this->price,
    'sale_price'   => round($this->price * (1 - $this->discount / 100), 2),
    'in_stock'     => $this->quantity > 0,
    'stock_status' => match (true) {
        $this->quantity > 10 => 'high',
        $this->quantity > 0  => 'low',
        default             => 'out_of_stock',
    },
];

Resource Collections

For lists you have two choices. The quick one is ::collection(), which wraps each item in the resource:

<?php
return ProductResource::collection(Product::paginate(15));

When you want collection-level metadata — a count, a store name, custom links — generate a dedicated collection class:

php artisan make:resource ProductCollection

<?php
// app/Http/Resources/ProductCollection.php
namespace App\Http\Resources;

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

class ProductCollection extends ResourceCollection
{
    public function toArray(Request $request): array
    {
        return [
            'data' => $this->collection,
            'meta' => [
                'total_products' => $this->collection->count(),
                'store_name'     => 'My Awesome Store',
                'api_version'    => '1.0',
            ],
        ];
    }
}

<?php
// In the controller
return new ProductCollection(Product::paginate(15));

Relationships & whenLoaded

Resources can embed related resources — a product's category, its tags, its reviews. The key method is whenLoaded(), which includes the relationship only if it was eager-loaded. This is what keeps you safe from the dreaded N+1 query problem.

<?php
// In ProductResource
public function toArray(Request $request): array
{
    return [
        'id'       => $this->id,
        'name'     => $this->name,
        'category' => new CategoryResource($this->whenLoaded('category')),
        'tags'     => TagResource::collection($this->whenLoaded('tags')),
        'reviews'  => ReviewResource::collection($this->whenLoaded('reviews')),
    ];
}

Then eager-load in the controller so the relationships are present when the resource asks for them:

<?php
public function show(Product $product): ProductResource
{
    $product->load(['category', 'tags', 'reviews']);
    return new ProductResource($product);
}

Conditional Attributes

Not every client should see every field. The when() method includes a key only when a condition is true — the key is completely absent otherwise, not null.

Based on the authenticated user

<?php
return [
    'id'    => $this->id,
    'name'  => $this->name,
    'price' => $this->price,
    // Only admins see the internal cost
    'cost'  => $this->when($request->user()?->isAdmin(), $this->cost),
];

Based on a request parameter

Let clients opt into a heavier payload with ?detailed=1. Note when() can take a fallback as its third argument:

<?php
use Illuminate\Support\Str;

return [
    'id'   => $this->id,
    'name' => $this->name,
    'description' => $this->when(
        $request->boolean('detailed'),
        $this->description,                       // full text when detailed=1
        fn () => Str::limit($this->description, 100) // otherwise a preview
    ),
];

Metadata & Wrapping

Use the with() method to attach top-level data that isn't part of the resource itself — an API version, server time, or documentation links. It's merged into the outer response next to data:

<?php
// In ProductResource
public function with(Request $request): array
{
    return [
        'meta' => [
            'api_version' => '1.0',
            'server_time' => now()->toIso8601String(),
        ],
    ];
}

{
  "data": {
    "id": 1,
    "name": "Awesome Product",
    "price": 99.99
  },
  "meta": {
    "api_version": "1.0",
    "server_time": "2026-08-01T12:00:00+00:00"
  }
}

If your API convention doesn't use the data wrapper, disable it globally — typically in a service provider's boot() method:

<?php
use Illuminate\Http\Resources\Json\JsonResource;

public function boot(): void
{
    JsonResource::withoutWrapping();
}

Worked Example: A Rich Product Resource

Putting it all together — grouped data, computed fields, conditional attributes, eager-loaded relationships, and metadata in one realistic resource:

<?php
// app/Http/Resources/ProductResource.php
namespace App\Http\Resources;

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

class ProductResource extends JsonResource
{
    public function toArray(Request $request): array
    {
        return [
            'id'   => $this->id,
            'slug' => $this->slug,
            'name' => $this->name,

            'pricing' => [
                'amount'    => $this->price,
                'formatted' => '$' . number_format($this->price, 2),
                'on_sale'   => $this->discount > 0,
                'sale_price' => $this->when(
                    $this->discount > 0,
                    fn () => round($this->price * (1 - $this->discount / 100), 2)
                ),
            ],

            'inventory' => [
                'in_stock' => $this->quantity > 0,
                // Vendors alone see the exact quantity on hand
                'quantity' => $this->when(
                    $request->user()?->isVendor(),
                    $this->quantity
                ),
            ],

            'description' => $this->when(
                $request->boolean('detailed'),
                $this->description,
                fn () => Str::limit($this->description, 150)
            ),

            'category' => new CategoryResource($this->whenLoaded('category')),
            'tags'     => TagResource::collection($this->whenLoaded('tags')),

            'ratings' => $this->when($this->relationLoaded('reviews'), fn () => [
                'average' => round($this->reviews->avg('rating'), 1),
                'count'   => $this->reviews->count(),
            ]),

            'created_at' => $this->created_at->toIso8601String(),
        ];
    }

    public function with(Request $request): array
    {
        return ['meta' => ['currency' => 'USD']];
    }
}

The controller stays trivial — its only job is to fetch efficiently and hand off:

<?php
public function show(Product $product): ProductResource
{
    $product->load(['category', 'tags', 'reviews']);
    return new ProductResource($product);
}

Hands-on Exercise

<?php
namespace App\Http\Resources;

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

class UserResource extends JsonResource
{
    public function toArray(Request $request): array
    {
        $viewer = $request->user();

        return [
            'id'        => $this->id,
            'full_name' => trim("{$this->first_name} {$this->last_name}"),
            'email'     => $this->when(
                $viewer?->isAdmin() || $viewer?->is($this->resource),
                $this->email
            ),
            'posts'      => PostResource::collection($this->whenLoaded('posts')),
            'created_at' => $this->created_at->toIso8601String(),
        ];
    }
}

// Controller
public function show(User $user): UserResource
{
    return new UserResource($user->load('posts'));
}

Best Practices

Summary & Quiz

📚 Further Reading

• Laravel Docs — Eloquent: API Resources
• Laravel Docs — Eager Loading
• JSON:API — a resource formatting specification

🚀 What's Next?

Your API now returns beautifully shaped JSON — but anyone can call it. In the next lesson, API Authentication with Passport, you'll add a full OAuth2 server so only clients with a valid token can reach your protected endpoints.