Laravel API Resources & Cursor Pagination: Stop Leaking Sensitive Data & Crashing Large Tables

Laravel API Resources & Cursor Pagination: Stop Leaking Sensitive Data & Crashing Large Tables

TL;DR: Returning raw Eloquent models directly from controllers couples your database schema to your public API, risking catastrophic leaks of password hashes and internal keys. Wrapping your queries in Laravel API Resources creates an explicit DTO contract, while replacing offset paginate() with cursorPaginate() slashes deep pagination latency from 1,850ms down to 4ms.

📺Watch the 45-Second Video Summary: Prefer visual breakdowns? Watch our quick mobile-optimized breakdown on YouTube Shorts: Laravel API Resources & Pagination.

The Nightmare: A Silent Security Leak in Production

You added two new columns to your users table: stripe_customer_id and internal_risk_score. You ran the migration, deployed to production, and went home.

Next morning, your frontend developer pings you:"Hey, why is the public user list endpoint returning internal Stripe tokens and risk scores to unauthenticated visitors?"

Your controller had this innocent line:

// app/Http/Controllers/Api/UserController.php
public function index()
{
    return User::paginate(20);
}

Because you didn't update the model's$hidden array, Laravel serialized every newly created column straight into the public JSON response.

Worse, your database administrator calls 10 minutes later: the MySQL replica CPU hit 99%. A third-party scraper is requesting page 4,000 (/api/users?page=4000), forcing MySQL to read 80,000 rows into memory and throw them away on every request.

Two common developer habits. Two major production disasters.

The Trap: Raw Models and Offset Pagination

Let's look at the standard naive implementation:

namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use App\Models\User;
use Illuminate\Http\Request;

class UserController extends Controller
{
    public function index(Request $request)
    {
        // ❌ THE SECURITY BOTTLENECK:
        // Automatically serializes every single table column into JSON.
        // If someone adds 'ssn' or 'remember_token' to the DB, it leaks here.
        
        // ❌ THE PERFORMANCE BOTTLENECK:
        // Generates SQL: SELECT * FROM `users` LIMIT 20 OFFSET 80000;
        // Forces MySQL to scan 80,020 rows off disk just to return 20!
        return User::orderBy('id', 'desc')->paginate(20);
    }
}

Why$hiddenIs Never Enough

Many developers say:"Just add the column to protected $hidden in your Model!"

That is a fragile safeguard.

1. Developers forget. In a team of five engineers shipping migrations weekly, somebody will forget to touch the model file.

2. Different consumers need different data. A mobile app might need name and avatar, while a webhook needs webhook_secret. A single model can't maintain separate contracts safely.

3. You can't easily format values, compute conditional fields, or rename database columns without breaking client apps.

The Optimal Architecture: API Resources + Cursor Pagination

The solution rests on two solid engineering principles:

1. The DTO Principle: An API response is a public contract. Never expose your internal relational schema directly.

2. Seek-Based Pagination: Use index markers (WHERE id < ?) instead of counting offsets from row zero.

flowchart TD
    Client[Web & Mobile Clients] -->|GET /api/v1/users?cursor=eyJpZ...| Controller[UserController@index]
    Controller -->|cursorPaginate 20| DB[(MySQL / Postgres)]
    DB -->|B-Tree Index Seek: WHERE id < 104| Models[Hydrated Eloquent Models]
    Models -->|Encapsulate in DTO| Resource[UserResource::collection]
    Resource -->|Explicit Whitelist Only| Response[Safe JSON Output 200 OK]
    
    subgraph Security Boundary
        Resource
    end

Step-by-Step Implementation

Step 1: Generate the API Resource

Run the Artisan command in your terminal:

php artisan make:resource UserResource

This creates app/Http/Resources/UserResource.php.

Step 2: Define the Explicit Whitelist Contract

Open UserResource.php. Instead of dumping everything, define only the exact fields your API consumers are authorized to read:

<?php

namespace App\Http\Resources;

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

class UserResource extends JsonResource
{
    /**
     * Transform the resource into an array.
     */
    public function toArray(Request $request): array
    {
        return [
            'id'           => $this->id,
            'name'         => $this->name,
            'email'        => $this->email,
            'avatar_url'   => $this->avatar_path ? url($this->avatar_path) : null,
            'created_at'   => $this->created_at->toIso8601String(),
            
            // Mask or format computed properties cleanly:
            'is_verified'  => !is_null($this->email_verified_at),
            
            // Conditionally load relationships without N+1 overhead:
            'profile'      => new ProfileResource($this->whenLoaded('profile')),
        ];
    }
}

Now, even if someone adds raw_password, two_factor_secret, or stripe_id to the database, it never appears in the JSON output unless explicitly specified in this resource.

Step 3: Implement High-PerformancecursorPaginate()

Update your controller to use cursorPaginate() combined with the resource collection:

<?php

namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use App\Http\Resources\UserResource;
use App\Models\User;
use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\AnonymousResourceCollection;

class UserController extends Controller
{
    public function index(Request $request): AnonymousResourceCollection
    {
        // ✔ 1. Uses indexed B-tree seeking (WHERE id < ? ORDER BY id DESC LIMIT 20)
        // ✔ 2. Transforms every item through the secure UserResource whitelist
        $users = User::orderBy('id', 'desc')
            ->cursorPaginate(20);

        return UserResource::collection($users);
    }
}

Benchmarks: Offset Pagination vs Cursor Pagination (1,000,000 Rows)

We tested a table with 1,000,000 rows on MySQL 8.0, querying page 5,000 (deep pagination):

When to Use Which Pagination?

• Use cursorPaginate() for: Infinite scrolling feeds, mobile app list views, high-volume real-time chat histories, and public REST APIs where scrapers might crawl deep pages.

• Use paginate() for: Administrative backends or internal dashboards where operators explicitly demand jumping to "Page 14" or clicking numbered pagination links.

Frequently Asked Questions

Why is returning raw Eloquent models directly in Laravel controllers dangerous?

Returning raw Eloquent models serializes all database table attributes directly into JSON. If a developer adds sensitive columns like password_hash, remember_token, or internal billing IDs in a migration and forgets to add them to$hidden, those secrets get exposed to the public API automatically.

What is the difference between paginate() and cursorPaginate() in Laravel?

paginate() uses traditional SQL OFFSET and LIMIT, forcing MySQL to scan and discard every preceding row before returning the target page. cursorPaginate() uses a WHERE clause on an indexed column (like id or created_at), executing an instant index seek that takes 4ms even on tables with millions of rows.

When should you NOT use cursor pagination in Laravel?

Do not use cursor pagination when your frontend UI requires jumping to specific arbitrary page numbers (e.g. "Jump to Page 45") or displaying total page counts. Cursor pagination only supports Next and Previous infinite scrolling or load-more feeds.

How do Laravel API Resources protect against breaking API changes?

API Resources (JsonResource) act as a Data Transfer Object (DTO) layer. They decouple your database column names from your JSON keys, allowing you to rename database columns or restructure tables without altering the public API response contract.

Summary Checklist

• Never call return Model::all() in public controllers.

• Run php artisan make:resource ModelResource for every API endpoint.

• Whitelist only required fields inside toArray().

• Swap paginate() for cursorPaginate() on high-traffic lists.