php 43 lines · 8 steps

Filtered, paginated JSON APIs in Laravel

An Eloquent query builder collects filters conditionally, then an API Resource shapes each row into clean JSON.

Explained by highlit

Laravel Intermediate eloquent query-builder api-resources pagination eager-loading

1class PostController extends Controller
2{
  public function index(Request $request): AnonymousResourceCollection
  {
      $posts = Post::query()
          ->with(['author', 'tags'])
          ->withCount('comments')
          ->when($request->filled('search'), function ($query) use ($request) {
              $query->where('title', 'like', "%{$request->string('search')}%");
          })
          ->when($request->filled('tag'), function ($query) use ($request) {
              $query->whereHas('tags', fn ($q) => $q->where('slug', $request->string('tag')));
          })
          ->latest('published_at')
          ->paginate($request->integer('per_page', 15))
          ->withQueryString();
17 
      return PostResource::collection($posts);
  }
20}
21 
22class PostResource extends JsonResource
23{
  public function toArray(Request $request): array
  {
      return [
          'id' => $this->id,
          'title' => $this->title,
          'slug' => $this->slug,
          'excerpt' => Str::limit(strip_tags($this->body), 160),
          'comments_count' => $this->comments_count,
          'author' => [
              'name' => $this->author->name,
              'avatar_url' => $this->author->avatar_url,
          ],
          'tags' => $this->tags->pluck('name'),
          'published_at' => $this->published_at?->toIso8601String(),
          'links' => [
              'self' => route('posts.show', $this->slug),
          ],
      ];
  }
43}

01 / 01

STEP 01

Walkthrough

Space play ←→ step click any line

Three takeaways

1Conditional query methods like when() let you build filters from request input without scattering if-statements.
2Eager loading with with() and withCount() prevents N+1 queries when the response touches related records.
3API Resources separate database shape from response shape, giving you a stable, deliberate JSON contract.

Related explainers

php

<?php
 
class NameParser
{

Parsing a full name into components in PHP

string-parsing arrays normalization

Intermediate 8 steps

php

<?php
 
namespace App\Services\Checkout;

Validating coupons with Laravel's Pipeline

pipeline chain of responsibility transactions

Intermediate 7 steps

php

<?php
 
namespace App\Services;

How a password strength validator works in PHP

validation regular-expressions data-driven

Intermediate 8 steps

php

<?php
 
namespace App\Services;

Building a cached daily leaderboard in Laravel

caching aggregation eager-loading

Intermediate 9 steps

php

<?php
 
final class RotatingFileLogger
{

How a rotating file logger works in PHP

logging file-rotation io

Intermediate 9 steps

php

class TwoFactorController extends Controller
{
    public function show(Request $request): View|RedirectResponse
    {

Two-factor auth challenge flow in Laravel

authentication two-factor middleware

Intermediate 10 steps

Share this explainer

Here's the card — post it anywhere.

Filtered, paginated JSON APIs in Laravel — share card

Made with highlit — turn any snippet into a walkthrough like this in about a minute.

Explain your code