That is a cache stampede, also called the dogpile effect or thundering herd. The cache works perfectly at steady state and creates a synchronized burst of load exactly when it expires. There are four standard defenses: locking so only one caller recomputes, probabilistic early expiration (XFetch) so recomputation happens before expiry, stale-while-revalidate so users never wait for it, and TTL jitter so thousands of keys do not expire together. Laravel ships two of them out of the box.

Where the Herd Comes From

namespace App\Http\Controllers;

use App\Services\Leaderboard;
use Illuminate\Support\Facades\Cache;

final class LeaderboardController
{
    public function __invoke(Leaderboard $board): array
    {
        // 4 second query, cached for 5 minutes. Every 5 minutes, every request
        // that arrives during those 4 seconds runs the query too.
        return Cache::remember('leaderboard:global', 300, fn () => $board->compute());
    }
}

Cache::remember() is "get, and on miss compute and put". It has no coordination between processes. The more expensive the computation and the higher the traffic, the more callers land in the miss window: the expected number of duplicate computations is roughly request rate times computation time. A 4-second query at 300 rps means about 1,200 copies. A 50 ms query at 20 rps is one copy, which is why stampedes only show up on hot, expensive keys and are easy to miss in staging.

The same thing happens at a larger scale after a cache flush, a Redis failover, or a deploy that changes key prefixes: every key is cold at once.

The Four Defenses at a Glance

• Lock on miss: the first caller takes a lock and recomputes; others wait or get a fallback. Guarantees one computation per expiry, at the cost of waiting.
• Probabilistic early expiration: each reader, with a probability that rises as expiry approaches, decides to recompute early. One reader usually refreshes the key while everyone else still gets a hit. No locks needed.
• Stale-while-revalidate: keep serving the old value past its freshness window while a single refresh runs in the background. Users never wait.
• TTL jitter: randomize expiry times so keys populated together do not expire together.

Defense 1: A Lock with a Double-Check

Laravel's atomic locks work on Redis, Memcached, DynamoDB, the database and the array store. block() waits up to N seconds to acquire the lock and throws LockTimeoutException if it cannot.

namespace App\Cache;

use Closure;
use Illuminate\Contracts\Cache\LockTimeoutException;
use Illuminate\Support\Facades\Cache;

final class LockedRemember
{
    /**
     * Only one process recomputes a missing key; the others wait briefly
     * and read the value the winner stored.
     */
    public static function get(string $key, int $ttl, Closure $compute, int $waitSeconds = 5): mixed
    {
        $value = Cache::get($key);
        if ($value !== null) {
            return $value;
        }

        try {
            return Cache::lock("lock:{$key}", 30)->block($waitSeconds, function () use ($key, $ttl, $compute) {
                // Double-check: the previous lock holder probably filled it already.
                $value = Cache::get($key);
                if ($value !== null) {
                    return $value;
                }

                $value = $compute();
                Cache::put($key, $value, $ttl);

                return $value;
            });
        } catch (LockTimeoutException) {
            // The winner is too slow. Degrade instead of piling onto the database.
            return Cache::get($key) ?? throw new \RuntimeException("{$key} unavailable, try again");
        }
    }
}

Two details make or break this pattern. The double-check inside the lock: by the time a waiting process gets the lock, the winner has already stored the value, so the waiter must read again instead of recomputing. And the lock TTL (30 seconds here) must be longer than the worst-case compute time, otherwise the lock expires mid-computation and a second process starts. If compute time is unpredictable, prefer an owner-checked release (Laravel's release() only frees a lock you own) and a generous TTL.

The weakness is waiting. With 1,200 waiting requests, you have traded a database stampede for a pile of PHP-FPM workers blocked on a lock. That is better, but on a really hot key you want nobody to wait.

Defense 2: Probabilistic Early Expiration (XFetch)

XFetch, from the 2015 VLDB paper Optimal Probabilistic Cache Stampede Prevention by Vattani, Chierichetti and Lowenstein, stores two extra numbers with each value: delta, how long the last computation took, and expiry. On every read it recomputes when

now - delta * beta * ln(random()) >= expiry      with random() in (0, 1]

-ln(random()) is an exponentially distributed number with mean 1, so each reader pretends the clock is a little later than it is. Far from expiry, almost nobody crosses the line. As expiry approaches, the probability rises smoothly, and it rises earlier for keys that are expensive to compute (bigger delta), which is exactly where you need the head start. beta tunes eagerness: 1.0 is the paper's recommendation, values above 1 favor earlier refreshes.

namespace App\Cache;

use Closure;
use Illuminate\Contracts\Cache\Repository;

/**
 * Probabilistic early expiration (XFetch, Vattani et al., VLDB 2015).
 * Each entry stores the value, how long it took to compute (delta) and its logical expiry.
 */
final class XFetch
{
    public function __construct(
        private Repository $cache,
        private float $beta = 1.0,
        private ?Closure $clock = null,
        private ?Closure $random = null,
    ) {
        $this->clock ??= fn (): float => microtime(true);
        $this->random ??= fn (): float => mt_rand(1, mt_getrandmax()) / mt_getrandmax(); // (0, 1]
    }

    public function remember(string $key, int $ttl, Closure $compute): mixed
    {
        $entry = $this->cache->get($key);
        $now = ($this->clock)();

        if (is_array($entry)) {
            [$value, $delta, $expiry] = $entry;
            // log(random) <= 0, so this subtracts a random head start that grows
            // with compute time (delta) and with beta.
            if ($now - $delta * $this->beta * log(($this->random)()) < $expiry) {
                return $value;
            }
        }

        $start = ($this->clock)();
        $value = $compute();
        $delta = ($this->clock)() - $start;

        // Keep the physical TTL a bit longer than the logical one so late
        // readers still find the old value while someone recomputes.
        $this->cache->put($key, [$value, $delta, $start + $delta + $ttl], $ttl + (int) ceil($delta) + 60);

        return $value;
    }
}

There are no locks, no waiting and no background workers. Keep the physical TTL longer than the logical expiry so that the value stays readable while one reader recomputes.

Defense 3: Stale-While-Revalidate with Cache::flexible

Since Laravel 11, Cache::flexible() implements stale-while-revalidate directly. You give it two durations: how long the value is fresh, and how long a stale value may still be served.

use App\Services\Leaderboard;
use Illuminate\Support\Facades\Cache;

// Fresh for 60s. Between 60s and 300s the stale value is returned immediately
// and ONE refresh runs after the response is sent. After 300s it is a normal miss.
$board = Cache::flexible('leaderboard:global', [60, 300], function () {
    return app(Leaderboard::class)->compute();
});

Inside the fresh window it is a normal hit. Inside the stale window the caller gets the old value immediately, and Laravel schedules a refresh with defer(), so it runs after the response has been sent to the user, guarded by a lock so only one process refreshes. Past the stale window it behaves like remember(). Pick the stale window based on how wrong the data may be, not on performance: a leaderboard can be 5 minutes stale, an account balance cannot be stale at all.

Note that deferred work runs in the same PHP-FPM worker after the response, so it still occupies that worker. Keep the refresh itself reasonably fast, or dispatch a queued job from the closure for very slow recomputations.

Defense 4: TTL Jitter

Locks and XFetch protect one hot key. Jitter protects you from thousands of medium-hot keys that were written at the same moment, typically by a cache warmer or a deploy:

use Illuminate\Support\Facades\Cache;

// 10,000 product pages warmed by the same deploy expire at the same second
// unless you spread the TTLs out.
function ttlWithJitter(int $base, float $spread = 0.1): int
{
    $delta = (int) round($base * $spread);

    return $base + random_int(-$delta, $delta);
}

Cache::put('product:42', ['id' => 42], ttlWithJitter(3600));

Ten percent spread is usually enough. Combine it with any of the other three.

Testing Stampede Protection

The key to testing XFetch is injecting the clock and the random source, so "unlucky" and "lucky" draws are deterministic. exp(-5) as the random value produces a head start of exactly 5 * delta. The lock tests run on the array store, which supports atomic locks: one checks that the value is computed once and reused, the other holds the lock as if another process were mid-computation and asserts that the caller gives up after the wait instead of running the query.

// tests/Unit/XFetchTest.php
use App\Cache\LockedRemember;
use App\Cache\XFetch;
use Illuminate\Cache\ArrayStore;
use Illuminate\Cache\Repository;
use Illuminate\Support\Facades\Cache;

beforeEach(function () {
    $this->now = 1000.0;
    $this->rand = 1.0;
    $this->calls = 0;
    $this->cache = new XFetch(
        new Repository(new ArrayStore()),
        beta: 1.0,
        clock: fn () => $this->now,
        random: fn () => $this->rand,
    );
    $this->compute = function () {
        $this->calls++;
        $this->now += 2.0; // the expensive query takes 2 seconds

        return "v{$this->calls}";
    };
});

it('computes once on a miss and then serves from cache', function () {
    expect($this->cache->remember('k', 60, $this->compute))->toBe('v1');
    $this->now += 10;
    expect($this->cache->remember('k', 60, $this->compute))->toBe('v1')
        ->and($this->calls)->toBe(1);
});

it('recomputes early when the random draw is unlucky', function () {
    $this->cache->remember('k', 60, $this->compute);  // expiry = 1062
    $this->now = 1055.0;
    $this->rand = exp(-5);                             // head start = 2 * 5 = 10s
    expect($this->cache->remember('k', 60, $this->compute))->toBe('v2');
});

it('never recomputes early with a lucky draw', function () {
    $this->cache->remember('k', 60, $this->compute);
    $this->now = 1061.0;
    $this->rand = 1.0;                                 // log(1) = 0, no head start
    expect($this->cache->remember('k', 60, $this->compute))->toBe('v1');
});

it('computes once and reuses the stored value', function () {
    $runs = 0;
    $compute = function () use (&$runs) {
        $runs++;

        return 'fresh';
    };

    foreach (range(1, 20) as $_) {
        expect(LockedRemember::get('report', 60, $compute))->toBe('fresh');
    }
    expect($runs)->toBe(1);
});

it('does not compute while another process holds the lock', function () {
    $runs = 0;
    Cache::lock('lock:report', 30)->get();   // simulate the winner, still computing

    expect(fn () => LockedRemember::get('report', 60, function () use (&$runs) {
        $runs++;

        return 'fresh';
    }, waitSeconds: 1))->toThrow(RuntimeException::class);

    expect($runs)->toBe(0);
});

These tests prove the logic. For confidence under real concurrency, run a short load test (k6, ab, or hey) against a staging endpoint with a tiny TTL and count how many times the computation runs, for example with a Redis INCR inside the closure.

Common Pitfalls

• No double-check after acquiring the lock. Every waiter recomputes in turn: you serialized the stampede instead of preventing it.
• Lock TTL shorter than compute time. The lock expires, a second process enters, and the first one later releases a lock it no longer owns (Laravel's owner check stops that release, but the duplicate work already happened).
• Caching null or false with remember(). A computation that legitimately returns null is never cached, so every request misses. Wrap it, for example cache an empty array or a sentinel object.
• Using random() that can return 0. ln(0) is negative infinity and forces a recompute on every read. Draw from (0, 1].
• Stale windows on data that must be correct. Stale-while-revalidate is a product decision. Prices at checkout, permissions and balances need invalidation on write, not stale reads.
• Forgetting cold starts. All four defenses assume most keys are warm. After a full flush, warm the hottest keys before shifting traffic, or rate-limit the recompute path.
• Holding locks across slow external calls. If the computation calls a third-party API, a timeout there blocks every waiter. Set explicit HTTP timeouts shorter than the lock TTL.

When to Use Which, and When Not To

• Low traffic or cheap computation: plain remember() is fine. Do not add locks to a 20 ms query hit twice per minute.
• Hot key, staleness acceptable: Cache::flexible(). It is the easiest win in a Laravel app and users never wait.
• Hot key, expensive computation, no background work available (CLI, long-running workers, other frameworks): XFetch.
• Must never compute twice (calls to a paid API, rate-limited upstream): a lock with double-check, possibly combined with flexible.
• Many keys written together: add jitter regardless of the other choices.

Do not use caching tricks to hide a query that should be fixed. If the leaderboard takes 4 seconds, a summary table updated incrementally may remove the need for any of this.

Server Actions make mutations feel like calling a function, and that is precisely the danger. Everything you would do in a controller (authenticate, validate, authorize, handle errors without leaking internals) still has to happen, but now it has to happen inside the function, every time. This tip builds that pattern with zod and React 19's useActionState.

What a Server Action Really Is

When you mark a function with 'use server' and pass it to a form's action, Next.js gives it an ID and exposes it as a POST endpoint. The client sends the action ID and the serialized arguments; the server looks up the function and runs it. Some consequences follow directly:

• The action can be invoked by anyone who can send a POST to your app, with any arguments. The UI that normally calls it is not a security boundary.
• FormData values are strings (or files) controlled by the client. Hidden inputs are just inputs.
• Checks done in the page or layout that rendered the form do not run when the action is called.

Here is the action from the intro. It looks harmless and is completely open:

// app/projects/[id]/actions.ts  (do NOT ship this)
'use server'

import { db } from '@/lib/db'

export async function renameProject(formData: FormData) {
  const id = formData.get('projectId') as string
  const title = formData.get('title') as string

  // No session check, no ownership check, no validation:
  // anyone who can POST to this page can rename ANY project to ANY string.
  await db.project.update({ where: { id }, data: { title } })
}

Next.js does add some protection: actions only accept POST, the framework compares the Origin header with the host to block cross-site calls, and action IDs are not guessable from outside the client bundle. None of that knows who the user is or what they may change.

The Four Steps Every Action Needs

Treat each action like a public controller method. In order:

Authentication comes first so anonymous traffic never reaches your validation or database code. Validation comes before authorization so the ownership query receives clean, typed input. Authorization is per resource: "is logged in" is not the same as "may edit project 7".

Validating Input With zod

Put the schema in a shared module so the server action and, if you want, client-side hints use the same rules. Note the trim() before min(): a title of five spaces should fail.

// lib/validation/project.ts
import { z } from 'zod'

export const renameProjectSchema = z.object({
  projectId: z.string().regex(/^\d+$/, 'Invalid project'),
  title: z
    .string()
    .trim()
    .min(3, 'Title must be at least 3 characters')
    .max(80, 'Title must be at most 80 characters'),
})

export type RenameProjectInput = z.infer<typeof renameProjectSchema>

export type ActionState = {
  status: 'idle' | 'success' | 'error'
  message: string
  fieldErrors: Partial<Record<keyof RenameProjectInput, string[]>>
  values?: { title: string }
}

export const initialState: ActionState = { status: 'idle', message: '', fieldErrors: {} }

ActionState is the contract between the action and the form. It is plain serializable data: a status, a human message, per-field errors, and the values to put back in the form when validation fails.

The Secure Action

// app/projects/[id]/actions.ts
'use server'

import { revalidatePath } from 'next/cache'
import { redirect } from 'next/navigation'
import { z } from 'zod'
import { getCurrentUser } from '@/lib/auth'
import { db } from '@/lib/db'
import { logger } from '@/lib/logger'
import { type ActionState, renameProjectSchema } from '@/lib/validation/project'

export async function renameProject(_prev: ActionState, formData: FormData): Promise<ActionState> {
  // 1. Authenticate: this function is a public POST endpoint.
  const user = await getCurrentUser()
  if (!user) redirect('/login')

  // 2. Validate: FormData is untrusted input, whatever the form looks like.
  const parsed = renameProjectSchema.safeParse({
    projectId: formData.get('projectId'),
    title: formData.get('title'),
  })

  if (!parsed.success) {
    return {
      status: 'error',
      message: 'Please fix the highlighted fields.',
      fieldErrors: z.flattenError(parsed.error).fieldErrors,
      values: { title: String(formData.get('title') ?? '') },
    }
  }

  const { projectId, title } = parsed.data

  // 3. Authorize: the user must own THIS project. Same answer for "missing" and "not yours".
  const project = await db.project.findFirst({ where: { id: projectId, ownerId: user.id } })
  if (!project) {
    return { status: 'error', message: 'Project not found.', fieldErrors: {} }
  }

  // 4. Mutate, and translate failures into safe messages.
  try {
    await db.project.update({ where: { id: project.id }, data: { title } })
  } catch (error) {
    logger.error({ err: error, projectId, userId: user.id }, 'renameProject failed')
    return { status: 'error', message: 'Could not save the project. Please try again.', fieldErrors: {} }
  }

  revalidatePath(`/projects/${project.id}`)

  return { status: 'success', message: 'Project renamed.', fieldErrors: {} }
}

A few details matter here:

• redirect() sits outside any try/catch. It works by throwing a special error that Next.js handles. Wrapping it in try/catch swallows the redirect. The same applies to notFound().
• Ownership is part of the query. findFirst({ where: { id, ownerId } }) returns nothing for both "does not exist" and "belongs to someone else", so the response does not reveal which project IDs exist.
• Errors are logged with context and replaced by a generic message. Database errors can contain hostnames, SQL and constraint names. In production, Next.js already hides thrown error messages from the client, but returning a typed error state is better UX than letting the action throw into an error boundary.
• Expected errors are returned, unexpected ones are thrown. Validation failures and "not found" are part of the normal flow and come back as state. A bug in your code should still throw and hit error.tsx and your error tracker.

The Form With useActionState

React 19's useActionState wires the action to local state. It returns the latest state, a wrapped action to pass to the form, and a pending flag:

// app/projects/[id]/rename-form.tsx
'use client'

import { useActionState } from 'react'
import { initialState } from '@/lib/validation/project'
import { renameProject } from './actions'

export function RenameForm({ projectId, title }: { projectId: string; title: string }) {
  const [state, formAction, isPending] = useActionState(renameProject, initialState)

  return (
    <form action={formAction} noValidate>
      <input type="hidden" name="projectId" value={projectId} />

      <label htmlFor="title">Title</label>
      <input
        id="title"
        name="title"
        defaultValue={state.values?.title ?? title}
        aria-invalid={Boolean(state.fieldErrors.title)}
        aria-describedby="title-error"
      />
      <p id="title-error" role="alert">{state.fieldErrors.title?.[0]}</p>

      <button type="submit" disabled={isPending}>
        {isPending ? 'Saving…' : 'Save'}
      </button>

      {state.message && (
        <p aria-live="polite" data-status={state.status}>{state.message}</p>
      )}
    </form>
  )
}

The action receives the previous state as its first argument and the FormData as the second, which is why the signature is (_prev, formData). React resets uncontrolled form fields after an action completes, so on validation errors the action sends back values.title and the input uses it as defaultValue; the user does not lose what they typed. The hidden projectId is convenient for the UI and still untrusted on the server.

If you have many actions, the authentication and validation steps become boilerplate. A small wrapper keeps them impossible to forget, while leaving authorization inside each handler, where the resource is known:

// lib/safe-action.ts
import 'server-only'
import { redirect } from 'next/navigation'
import { z } from 'zod'
import { getCurrentUser, type User } from '@/lib/auth'

export type Result<TFields extends string> = {
  status: 'idle' | 'success' | 'error'
  message: string
  fieldErrors: Partial<Record<TFields, string[]>>
}

export function authedAction<S extends z.ZodObject>(
  schema: S,
  handler: (input: z.infer<S>, user: User) => Promise<Result<Extract<keyof z.infer<S>, string>>>,
) {
  return async (_prev: unknown, formData: FormData) => {
    const user = await getCurrentUser()
    if (!user) redirect('/login')

    const parsed = schema.safeParse(Object.fromEntries(formData))
    if (!parsed.success) {
      return {
        status: 'error' as const,
        message: 'Please fix the highlighted fields.',
        fieldErrors: z.flattenError(parsed.error).fieldErrors,
      }
    }

    return handler(parsed.data, user)
  }
}

Testing Server Actions

A Server Action is an async function, so you can test it like one. Mock the framework and data modules with Vitest and assert on the returned state and on what was not called:

// app/projects/[id]/actions.test.ts
import { beforeEach, describe, expect, it, vi } from 'vitest'

vi.mock('next/cache', () => ({ revalidatePath: vi.fn() }))
vi.mock('next/navigation', () => ({
  redirect: vi.fn(() => {
    throw new Error('NEXT_REDIRECT')
  }),
}))
vi.mock('@/lib/auth', () => ({ getCurrentUser: vi.fn() }))
vi.mock('@/lib/logger', () => ({ logger: { error: vi.fn() } }))
vi.mock('@/lib/db', () => ({ db: { project: { findFirst: vi.fn(), update: vi.fn() } } }))

import { getCurrentUser } from '@/lib/auth'
import { db } from '@/lib/db'
import { initialState } from '@/lib/validation/project'
import { renameProject } from './actions'

const form = (fields: Record<string, string>) => {
  const fd = new FormData()
  for (const [k, v] of Object.entries(fields)) fd.set(k, v)
  return fd
}

describe('renameProject', () => {
  beforeEach(() => {
    vi.clearAllMocks()
    vi.mocked(getCurrentUser).mockResolvedValue({ id: 'u1' } as never)
  })

  it('redirects anonymous users before touching the database', async () => {
    vi.mocked(getCurrentUser).mockResolvedValue(null)
    await expect(renameProject(initialState, form({ projectId: '1', title: 'New' }))).rejects.toThrow('NEXT_REDIRECT')
    expect(db.project.findFirst).not.toHaveBeenCalled()
  })

  it('returns field errors for invalid input', async () => {
    const state = await renameProject(initialState, form({ projectId: '1', title: ' x ' }))
    expect(state.status).toBe('error')
    expect(state.fieldErrors.title?.[0]).toMatch(/at least 3/)
    expect(db.project.update).not.toHaveBeenCalled()
  })

  it("refuses to rename someone else's project", async () => {
    vi.mocked(db.project.findFirst).mockResolvedValue(null)
    const state = await renameProject(initialState, form({ projectId: '7', title: 'Hijacked' }))
    expect(state).toMatchObject({ status: 'error', message: 'Project not found.' })
    expect(db.project.findFirst).toHaveBeenCalledWith({ where: { id: '7', ownerId: 'u1' } })
    expect(db.project.update).not.toHaveBeenCalled()
  })

  it('hides database errors from the client', async () => {
    vi.mocked(db.project.findFirst).mockResolvedValue({ id: '7', ownerId: 'u1' } as never)
    vi.mocked(db.project.update).mockRejectedValue(new Error('connection refused at 10.0.3.7'))
    const state = await renameProject(initialState, form({ projectId: '7', title: 'Roadmap' }))
    expect(state.message).not.toContain('10.0.3.7')
  })
})

The two most valuable tests are the negative ones: an anonymous call never touches the database, and a user cannot rename a project they do not own. Those are the behaviours the UI cannot protect, and they regress silently when someone refactors.

Common Pitfalls

• Relying on the page to authenticate. Middleware, layouts and pages do not wrap action calls. Check the session in every action, or in a shared wrapper.
• Trusting IDs from the form. Anything in FormData, including hidden fields and bound arguments, comes from the client. Re-check ownership on the server.
• Casting instead of parsing. formData.get('title') as string is a type assertion, not validation. It can be null, a File, or 10 MB of text.
• Catching redirects. A try/catch around redirect() turns a redirect into an error state. Call it after the try/catch.
• Returning raw error messages. return { message: String(error) } sends database internals to the browser. Log the error, return a generic message.
• Exposing internal actions. Every exported function in a 'use server' file is callable. Keep helpers that must not be called directly in a separate server-only module.

When to Use Server Actions, and When Not To

Use Server Actions for mutations that belong to your own UI: forms, buttons, inline edits. You get progressive enhancement (forms work before JavaScript loads), typed arguments, and built-in revalidation in one place.

Prefer a Route Handler when the endpoint is consumed by something other than your React UI: mobile apps, webhooks, third-party integrations, or anything that needs a stable URL, custom HTTP methods, specific status codes or caching headers. Also avoid Server Actions for reading data; they are designed for mutations, and calls from the same client are processed one at a time. Fetch data in Server Components instead.

Picking a deployment strategy is not just about how traffic moves from version N to N+1. It is about what happens while both versions run at the same time, against the same database, the same queues and the same caches. Every strategy has that window. The differences are how long it lasts, how much traffic sees the new version, and how fast you can get out.

Rolling Updates: The Default

A rolling update replaces pods a few at a time. It is the Kubernetes default and costs no extra infrastructure:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: shop-api
spec:
  replicas: 8
  minReadySeconds: 20          # a new pod must stay ready this long before it counts
  progressDeadlineSeconds: 600
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 25%            # up to 2 extra pods during the rollout
      maxUnavailable: 0        # never drop below 8 ready pods

maxUnavailable: 0 with a non-zero maxSurge keeps full capacity during the rollout. minReadySeconds stops a pod that passes readiness and then crashes ten seconds later from counting as "available", which otherwise lets a broken version roll through the whole fleet. If the rollout stalls past progressDeadlineSeconds, the Deployment is marked as failed, and kubectl rollout undo deployment/shop-api brings back the previous ReplicaSet.

The trade-off: during the rollout, users bounce between versions request by request. Old and new code must be compatible with each other's data, sessions and queued jobs. Rollback is another rolling update, so it takes as long as the deploy did.

Blue-Green: Two Full Stacks, One Switch

Blue-green runs the new version (green) next to the old one (blue) at full size, verifies it, then flips traffic in one step:

# Both stacks run side by side; the Service selector decides who gets traffic.
kubectl apply -f shop-api-green.yaml
kubectl rollout status deployment/shop-api-green --timeout=5m

# Smoke test green through its own internal Service before the switch.
curl -fsS http://shop-api-green.internal/ready

# Switch: one atomic change to the selector.
kubectl patch service shop-api -p '{"spec":{"selector":{"app":"shop-api","color":"green"}}}'

# Rollback is the same command with color=blue. Keep blue running until you are sure.

The switch is near-instant and so is the rollback, as long as blue is still running. You can test green with production config and real dependencies before any user sees it. The costs: double capacity during the deploy, and long-lived connections (WebSockets, streaming responses) that stay on blue until they close. The database is still shared, so blue-green does nothing to make a breaking migration safe. It only makes the moment of the switch sharper.

Canary: Real Traffic, Small Blast Radius

A canary sends a small slice of real traffic to the new version, compares its metrics with the stable version, and widens the slice step by step: 5%, 25%, 50%, 100%. Service meshes and tools like Argo Rollouts or Flagger automate this; the core idea fits in a few lines of nginx:

# nginx: send ~5% of clients to the canary, sticky per client address
split_clients "${remote_addr}" $shop_backend {
    5%      canary;
    *       stable;
}

upstream stable { server 10.0.1.10:8080; server 10.0.1.11:8080; }
upstream canary { server 10.0.2.10:8080; }

server {
    listen 80;
    location / { proxy_pass http://$shop_backend; }
}

Canaries catch what staging never will: real data shapes, real client versions, real load. They need two things to work. First, enough traffic for the metrics to mean anything; 5% of a service with 20 requests per minute tells you nothing in ten minutes. Second, an automated, pre-agreed decision rule. A human staring at a dashboard at 5% will rationalise a small error spike every time.

Choosing a Strategy

Notice that the database question comes first. No traffic strategy fixes a schema change that breaks the version still running.

Database Compatibility: Expand, Migrate, Contract

The rule that makes every strategy safe: each release must work with the schema of the release before and the release after it. That means breaking changes are split across several deploys:

1. Expand: add the new column or table, nullable, and backfill it. Old code ignores it.
2. Dual write: ship code that writes both name and full_name and reads the old one.
3. Switch reads: ship code that reads full_name. Rolling back to step 2 is still safe.
4. Contract: once nothing reads or writes name, drop it in a later release.

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Schema;

// Release 1 (expand): add the new column, nullable, no reads depend on it yet.
return new class extends Migration
{
    public function up(): void
    {
        Schema::table('customers', function (Blueprint $table): void {
            $table->string('full_name')->nullable()->after('name');
        });

        // Backfill in chunks so the migration never locks the table for long.
        DB::table('customers')->whereNull('full_name')->chunkById(1000, function ($rows): void {
            foreach ($rows as $row) {
                DB::table('customers')->where('id', $row->id)->update(['full_name' => $row->name]);
            }
        });
    }
};

The same thinking applies beyond SQL. Queued jobs serialized by version N will be processed by version N+1, so job payloads need to stay backward compatible for at least one release. Cache keys that change format should get a new prefix rather than overwrite old entries. API responses consumed by mobile apps outlive every deploy you will ever do.

Feature Flags: Deploy Is Not Release

Feature flags separate shipping code from turning behaviour on. With Laravel Pennant, the new checkout can be deployed to 100% of pods while only staff and 5% of users see it:

namespace App\Providers;

use App\Models\User;
use Illuminate\Support\ServiceProvider;
use Laravel\Pennant\Feature;

final class FeatureServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        // Code ships dark; the flag decides who sees it. Stable per user.
        Feature::define('new-checkout', function (User $user): bool {
            return $user->is_staff || $user->id % 100 < 5;
        });
    }
}

// In a controller:
// return Feature::active('new-checkout') ? $this->newCheckout($cart) : $this->legacyCheckout($cart);

Now the risky part (the new behaviour) is controlled by a flag that changes in seconds, and the deploy itself becomes boring. Flags are also the fastest rollback you have: turning one off does not need a build, a pipeline, or a database migration. Hashing on a stable key (here the user id) matters: users should not flip between old and new checkout on every request.

Automating the Canary Decision

Write the decision rule as code, agree on thresholds before the deploy, and let the pipeline call it after each step:

namespace App\Deploy;

final class CanaryJudge
{
    public function __construct(
        private int $minRequests = 500,
        private float $maxErrorDelta = 0.01,
        private float $maxLatencyRatio = 1.2,
    ) {}

    /** @param array{requests: int, errors: int, p95_ms: int} $baseline */
    public function decide(array $baseline, array $canary): string
    {
        if ($canary['requests'] < $this->minRequests) {
            return 'wait';
        }

        if ($this->errorRate($canary) - $this->errorRate($baseline) > $this->maxErrorDelta) {
            return 'rollback';
        }

        if ($baseline['p95_ms'] > 0 && $canary['p95_ms'] > $baseline['p95_ms'] * $this->maxLatencyRatio) {
            return 'rollback';
        }

        return 'promote';
    }

    private function errorRate(array $m): float
    {
        return $m['requests'] > 0 ? $m['errors'] / $m['requests'] : 0.0;
    }
}

Three outcomes, not two. wait stops the pipeline from promoting on a statistically meaningless sample. Comparing against the live baseline instead of a fixed number keeps the rule honest during an incident that affects both versions equally.

Testing the Deploy Gate

The judge decides whether broken code reaches every user, so it deserves tests that pin down each branch. Pest keeps them readable:

use App\Deploy\CanaryJudge;

$baseline = ['requests' => 20_000, 'errors' => 20, 'p95_ms' => 180];

it('waits until the canary has enough traffic', function () use ($baseline) {
    $canary = ['requests' => 120, 'errors' => 0, 'p95_ms' => 150];

    expect((new CanaryJudge())->decide($baseline, $canary))->toBe('wait');
});

it('rolls back when the error rate jumps', function () use ($baseline) {
    $canary = ['requests' => 1_000, 'errors' => 40, 'p95_ms' => 170];

    expect((new CanaryJudge())->decide($baseline, $canary))->toBe('rollback');
});

it('rolls back on a latency regression even with zero errors', function () use ($baseline) {
    $canary = ['requests' => 1_000, 'errors' => 0, 'p95_ms' => 260];

    expect((new CanaryJudge())->decide($baseline, $canary))->toBe('rollback');
});

it('promotes a healthy canary', function () use ($baseline) {
    $canary = ['requests' => 1_000, 'errors' => 2, 'p95_ms' => 190];

    expect((new CanaryJudge())->decide($baseline, $canary))->toBe('promote');
});

Beyond the unit tests, rehearse the rollback itself: in staging, deploy, roll back, and check that the previous version still works against the migrated schema. A rollback path you have never exercised is a hope, not a plan.

Common Pitfalls

Destructive migrations in the same release as the code change. Dropping or renaming a column while old pods still run is the most common deploy outage. Expand first, contract later.

Readiness that passes too early. If /ready returns 200 before caches are warm or config is loaded, the rolling update moves on and a broken version spreads. Combine a real readiness check with minReadySeconds.

Canary without session or cache isolation. A canary that writes a new cache format can poison the cache for stable pods. Version cache keys and session payloads.

Rollback that assumes the database rolls back too. It usually cannot. Data written by the new version must be readable by the old one, which is exactly what expand and contract give you.

Flags that never get removed. Every flag doubles the code paths to test. Put a removal ticket in the same pull request that adds the flag.

When to Use Which, and When Not To

Rolling is right for most stateless web services with backward-compatible changes. Do not use it when two versions must never serve traffic at the same time, for example a protocol change between client and server.

Blue-green fits when you need an instant, atomic switch and a fast rollback, and can afford double capacity for the deploy window. It is a poor fit for large stateful systems where duplicating the stack is expensive.

Canary pays off for high-traffic, high-risk changes where real traffic is the only meaningful test. Skip it for low-traffic services where the metrics will never reach significance; use flags and a careful rolling update instead.

Whatever you pick, the database rule does not change: two versions will overlap, so design every release to coexist with its neighbours.

On the server, the same shape shows up in reverse. A user opens a heavy report, gets bored after two seconds and closes the tab. Node keeps running the five downstream API calls and the database query for another twenty seconds, for a response nobody will read. Multiply that by a busy afternoon and you have a capacity problem made entirely of abandoned work.

The fix in both cases is the same primitive: AbortController. It is built into every modern browser and into Node.js, fetch understands it natively, and with AbortSignal.timeout and AbortSignal.any it covers timeouts and combined cancellation too.

How AbortController Works

The API is split into two objects with deliberately different powers:

• AbortController is the remote control. Whoever holds it can call controller.abort(reason).
• AbortSignal (controller.signal) is the read-only receiver. You pass it to the work you want to be cancellable. It exposes signal.aborted, signal.reason, signal.throwIfAborted() and an abort event.

That split matters: you hand the signal to a function, and the function can observe cancellation but cannot cancel anyone else. The caller keeps the controller.

A few rules worth memorising:

• abort() is idempotent. The first call wins; later calls do nothing, and reason keeps the first value.
• abort() with no argument sets reason to a DOMException named AbortError. abort(reason) uses whatever you pass, which is handy for telling apart "user navigated away" from "superseded by a newer query".
• A signal cannot be reset. Every operation that can be cancelled independently gets a new controller.
• abort listeners run synchronously inside abort(). Keep them small.

Search-as-You-Type, Step by Step

The rule is simple: when a new query starts, abort the previous one. Stale responses then never reach the code that renders results, because their promise rejects instead of resolving.

Cancelling fetch

fetch takes a signal option. When the signal aborts, the request is torn down (the browser closes the connection or cancels the HTTP/2 stream) and the promise rejects with the signal's reason. If the response headers already arrived, reading the body with res.json() rejects as well.

export function isAbortError(error: unknown): boolean {
  return error instanceof DOMException && error.name === 'AbortError';
}

export async function loadUser(id: string, signal?: AbortSignal) {
  const res = await fetch(`/api/users/${id}`, { signal });
  if (!res.ok) {
    throw new Error(`Request failed with ${res.status}`);
  }

  return res.json();
}

Aborting is an expected outcome, not an error worth reporting. Filter it out before the error goes to Sentry or to a toast, otherwise every fast typist generates noise. Note what aborting does not do: if the server already received the request, it may still finish processing it. Cancellation saves the client from waiting and frees the connection; it is not a transaction rollback. Never rely on it to prevent a write from happening.

Timeouts with AbortSignal.timeout

fetch has no timeout option. Before AbortSignal.timeout, people wrapped fetch in Promise.race with a timer, which stopped the waiting but left the request running. Now there is a static helper that returns a signal which aborts by itself:

try {
  const res = await fetch('/api/reports/monthly', { signal: AbortSignal.timeout(8000) });
  const report = await res.json();
  render(report);
} catch (error) {
  if (error instanceof DOMException && error.name === 'TimeoutError') {
    showMessage('The report is taking too long. Try a smaller date range.');
  } else {
    throw error;
  }
}

The reason here is a DOMException named TimeoutError, not AbortError, so you can tell "we gave up" from "the user cancelled". In browsers the timer counts active time, so it is effectively paused while a page sits in the back/forward cache. AbortSignal.timeout is available in Node.js 17.3+ and all evergreen browsers.

Combining Signals with AbortSignal.any

Real code often has several reasons to stop: the user typed again, the component unmounted, the request took too long, the whole server is shutting down. AbortSignal.any([...]) returns a signal that aborts as soon as any input aborts, and its reason is the reason of the first one. It shipped in Node.js 20.3 and in all major browsers during 2023 and 2024.

type Result = { id: string; title: string };

export function createSearch(
  fetchResults: (query: string, signal: AbortSignal) => Promise<Result[]>,
  timeoutMs = 5000,
) {
  let current: AbortController | null = null;

  return async function search(query: string): Promise<Result[] | null> {
    current?.abort();
    const controller = new AbortController();
    current = controller;

    const signal = AbortSignal.any([controller.signal, AbortSignal.timeout(timeoutMs)]);

    try {
      return await fetchResults(query, signal);
    } catch (error) {
      if (controller.signal.aborted) {
        return null;
      }
      throw error;
    }
  };
}

Look at the catch: it checks our own controller, not the combined signal. If this call was superseded, returning null tells the UI "ignore me". If the timeout fired, the TimeoutError propagates so the UI can show a message. Different reasons, different handling, one signal passed down.

React: Abort in the Effect Cleanup

In React the natural place for cancellation is the cleanup function of useEffect. It runs before the next effect and on unmount, which is exactly "a newer query started" and "nobody is listening anymore". Combine it with a small debounce so you also send fewer requests.

import { useEffect, useState } from 'react';

export function useSearch(query: string) {
  const [results, setResults] = useState<{ id: string; title: string }[]>([]);
  const [error, setError] = useState<Error | null>(null);

  useEffect(() => {
    if (query.trim().length < 2) {
      setResults([]);
      return;
    }

    const controller = new AbortController();
    const timer = setTimeout(() => {
      fetch(`/api/search?q=${encodeURIComponent(query)}`, { signal: controller.signal })
        .then((res) => res.json())
        .then((data) => {
          setResults(data);
          setError(null);
        })
        .catch((err) => {
          if (err.name !== 'AbortError') setError(err);
        });
    }, 250);

    return () => {
      clearTimeout(timer);
      controller.abort();
    };
  }, [query]);

  return { results, error };
}

This also makes the hook correct under React StrictMode in development, which mounts, unmounts and remounts effects on purpose: the first request is aborted by the cleanup and only the second one updates state. Data libraries like TanStack Query pass a signal into your query function for the same reason; forward it to fetch and you get cancellation for free.

Making Your Own Code Abortable

The signal only helps if the code that receives it listens. For your own async functions, follow two patterns: check signal.throwIfAborted() between steps, and turn timers or event waits into promises that reject on abort and clean up after themselves.

export function sleep(ms: number, signal?: AbortSignal): Promise<void> {
  return new Promise((resolve, reject) => {
    if (signal?.aborted) {
      reject(signal.reason);
      return;
    }

    const onAbort = () => {
      clearTimeout(timer);
      reject(signal!.reason);
    };

    const timer = setTimeout(() => {
      signal?.removeEventListener('abort', onAbort);
      resolve();
    }, ms);

    signal?.addEventListener('abort', onAbort, { once: true });
  });
}

export async function syncAll(ids: string[], signal: AbortSignal) {
  for (const id of ids) {
    signal.throwIfAborted();
    await syncOne(id, { signal });
    await sleep(100, signal);
  }
}

Removing the listener when the timer wins is not cosmetic. A long-lived signal (for example, a server shutdown signal) would otherwise collect one listener per call forever, and Node prints a MaxListenersExceededWarning when that happens. The same signal can also clean up DOM listeners: element.addEventListener('scroll', handler, { signal }) removes the handler when the signal aborts.

On the server, wire the signal to the client connection so abandoned requests stop their downstream work:

app.get('/reports/:id', async (req, res, next) => {
  const controller = new AbortController();
  res.on('close', () => {
    if (!res.writableEnded) controller.abort(new Error('client disconnected'));
  });

  try {
    const report = await buildReport(req.params.id, { signal: controller.signal });
    res.json(report);
  } catch (error) {
    if (controller.signal.aborted) return;
    next(error);
  }
});

Testing Cancellation with Vitest

Cancellation bugs are race conditions, so test the race explicitly: start two searches, make the first one slower, and assert that only the second one produces results.

import { describe, expect, it } from 'vitest';
import { createSearch, sleep } from './search';

describe('createSearch', () => {
  it('aborts the previous request when a new query starts', async () => {
    const signals: AbortSignal[] = [];

    const search = createSearch((query, signal) => {
      signals.push(signal);
      return new Promise((resolve, reject) => {
        signal.addEventListener('abort', () => reject(signal.reason), { once: true });
        setTimeout(() => resolve([{ id: query, title: query }]), query === 'lap' ? 50 : 10);
      });
    });

    const first = search('lap');
    const second = search('laptop');

    await expect(first).resolves.toBeNull();
    await expect(second).resolves.toEqual([{ id: 'laptop', title: 'laptop' }]);
    expect(signals[0].aborted).toBe(true);
    expect(signals[1].aborted).toBe(false);
  });
});

describe('sleep', () => {
  it('rejects with the abort reason', async () => {
    const controller = new AbortController();
    const pending = sleep(10_000, controller.signal);

    controller.abort(new Error('stop'));

    await expect(pending).rejects.toThrow('stop');
  });
});

Common Pitfalls

• Reusing a controller. Once aborted, a signal stays aborted. Every new request that should be cancellable on its own needs a new AbortController.
• Reporting aborts as errors. Filter AbortError before logging or showing an error toast.
• Checking error.name only for AbortError. AbortSignal.timeout produces TimeoutError, and a custom abort(reason) produces whatever you passed. Decide based on which signal aborted when the difference matters.
• Assuming abort undoes server work. The request may already be processed. Use idempotency keys for writes.
• Leaking listeners on long-lived signals. Use { once: true } and remove the listener on the success path.
• Swallowing the signal. A function that accepts signal but never forwards it to fetch or checks it gives a false sense of safety.

When to Use It and When Not To

Use AbortController when:

• Responses can arrive out of order and only the latest matters: search, autocomplete, filters, tab switches.
• A component or page can go away while work is in flight.
• You need a real timeout on fetch or on any API that accepts a signal (Node streams, timers/promises, events.once, many SDKs).
• Server work can be abandoned when the client disconnects or the process is shutting down.

Do not reach for it when:

• The operation is a write that must complete once started. Make it idempotent instead, and let it finish.
• The work is synchronous and CPU-bound. A signal cannot interrupt a busy loop unless that loop checks signal.aborted; move heavy work to a worker if it must be stoppable.
• A request deduplicator or a data library already handles cancellation for you. Forward its signal rather than adding another layer.

Every fetch that can become irrelevant should carry a signal. It is one extra argument, and it removes an entire class of "random" bugs.

Both incidents are the same bug: your code writes to the database and a broker, and no transaction spans both. Whichever one you write first, a crash between the two writes leaves them disagreeing. The transactional outbox pattern removes the second write from the request entirely.

The Dual-Write Problem

Here is the code that caused the first incident. It looks reasonable, and it works in every test you will ever write:

use App\Models\Order;
use Illuminate\Support\Facades\DB;

$order = DB::transaction(function () use ($cart) {
    $order = Order::createFromCart($cart);
    $order->items()->createMany($cart->lines());

    return $order;
});

// The process can die right here: OOM, deploy, network blip.
// The order exists, but nobody downstream ever hears about it.
$broker->publish('orders.placed', ['order_id' => $order->id]);

Publish inside the transaction instead and you get the second incident: the commit fails after the broker took the message. Laravel's DB::afterCommit() and ShouldDispatchAfterCommit events improve the ordering but not the guarantee: the callback still runs in the same PHP process after the commit, so a crash, timeout or broker outage at that moment still loses the message.

There is no clever ordering that fixes this. What fixes it is having only one write that matters, inside one transaction.

The Outbox Table

Instead of talking to the broker, the request writes the message into a table in the same database, in the same transaction as the business data. Either both the order and the message exist, or neither does. A separate relay process reads that table and publishes to the broker, retrying until it succeeds.

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    public function up(): void
    {
        Schema::create('outbox_messages', function (Blueprint $table) {
            $table->id();
            $table->uuid('message_id')->unique();
            $table->string('topic');
            $table->string('aggregate_type');
            $table->string('aggregate_id');
            $table->json('payload');
            $table->unsignedSmallInteger('attempts')->default(0);
            $table->timestamp('available_at')->useCurrent();
            $table->timestamp('published_at')->nullable();
            $table->timestamp('created_at')->useCurrent();

            $table->index(['published_at', 'available_at', 'id']);
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('outbox_messages');
    }
};

Notes:

• message_id is a UUID that travels with the message. Consumers use it to detect duplicates.
• aggregate_type and aggregate_id say what the message is about, for per-entity ordering and debugging.
• available_at and attempts give you backoff without a separate retry queue.
• The (published_at, available_at, id) index keeps "oldest pending" a range scan.

Recording Messages in the Same Transaction

A small service writes the row. It refuses to run outside a transaction, which turns the most common mistake into an immediate exception in development:

namespace App\Outbox;

use Illuminate\Support\Facades\DB;
use Illuminate\Support\Str;
use LogicException;

final class Outbox
{
    public function record(string $topic, string $aggregateType, string|int $aggregateId, array $payload): string
    {
        if (DB::transactionLevel() === 0) {
            throw new LogicException('Outbox messages must be recorded inside a database transaction.');
        }

        $messageId = (string) Str::uuid();

        DB::table('outbox_messages')->insert([
            'message_id' => $messageId,
            'topic' => $topic,
            'aggregate_type' => $aggregateType,
            'aggregate_id' => (string) $aggregateId,
            'payload' => json_encode($payload, JSON_THROW_ON_ERROR),
        ]);

        return $messageId;
    }
}

The use case then records the message right next to the business writes:

namespace App\Orders;

use App\Models\Cart;
use App\Models\Order;
use App\Outbox\Outbox;
use Illuminate\Support\Facades\DB;

final class PlaceOrder
{
    public function __construct(private Outbox $outbox) {}

    public function __invoke(Cart $cart): Order
    {
        return DB::transaction(function () use ($cart) {
            $order = Order::createFromCart($cart);
            $order->items()->createMany($cart->lines());

            $this->outbox->record('orders.placed', 'order', $order->id, [
                'order_id' => $order->id,
                'customer_id' => $order->customer_id,
                'total' => $order->total,
                'placed_at' => $order->created_at->toIso8601String(),
            ]);

            return $order;
        });
    }
}

If anything in the closure throws, the order, its items and the outbox row disappear together. If it commits, the message is guaranteed to be published eventually, even if the PHP process dies one microsecond later.

The Relay Worker

The relay is a loop: select a batch of pending messages, publish each one, mark it published. Here is the full flow, from the request to the consumer:

In Laravel, the relay is an Artisan command run by Supervisor (or a scheduled --once invocation for low volume):

namespace App\Console\Commands;

use App\Outbox\MessagePublisher;
use Illuminate\Console\Command;
use Illuminate\Support\Facades\DB;
use Throwable;

final class RelayOutbox extends Command
{
    protected $signature = 'outbox:relay {--batch=100} {--once}';

    protected $description = 'Publish pending outbox messages to the broker';

    public function handle(MessagePublisher $publisher): int
    {
        do {
            $sent = $this->relayBatch($publisher, (int) $this->option('batch'));

            if ($sent === 0 && ! $this->option('once')) {
                usleep(500_000);
            }
        } while (! $this->option('once'));

        return self::SUCCESS;
    }

    private function relayBatch(MessagePublisher $publisher, int $limit): int
    {
        return DB::transaction(function () use ($publisher, $limit) {
            $messages = DB::table('outbox_messages')
                ->whereNull('published_at')
                ->where('available_at', '<=', now())
                ->orderBy('id')
                ->limit($limit)
                ->lock('for update skip locked')
                ->get();

            $sent = 0;

            foreach ($messages as $message) {
                try {
                    $publisher->publish($message->topic, $message->message_id, json_decode($message->payload, true));
                } catch (Throwable $e) {
                    report($e);
                    DB::table('outbox_messages')->where('id', $message->id)->update([
                        'attempts' => $message->attempts + 1,
                        'available_at' => now()->addSeconds(min(300, 2 ** $message->attempts)),
                    ]);

                    break;
                }

                DB::table('outbox_messages')->where('id', $message->id)->update(['published_at' => now()]);
                $sent++;
            }

            return $sent;
        });
    }
}

Design choices in that command:

• FOR UPDATE SKIP LOCKED. You will run more than one relay, during deploys if nothing else. Row locks with SKIP LOCKED (MySQL 8.0+ and PostgreSQL) let several workers share the table without publishing the same row twice and without blocking each other.
• Order by id and stop on the first failure. Breaking out of the loop keeps messages in commit order, which matters when consumers expect orders.placed before orders.cancelled. If you need parallelism, partition by aggregate_id instead of dropping ordering globally.
• Backoff via available_at. A broker outage does not become a hot loop.
• Publish, then mark. If the worker crashes after publishing but before the update commits, the message is published again on the next run. That is the price of the pattern: at-least-once delivery. Exactly-once delivery across a network does not exist, so the consumer has to cope.

Keep batches small: locks are held while you talk to the broker, so 100 messages at 50 ms each hold locks for 5 seconds.

Idempotent Consumers

Because the relay can deliver a message twice, and most brokers redeliver on consumer crashes anyway, every consumer must be safe to run twice with the same message. The robust way is a processed_messages table with a unique key on message_id, written in the same transaction as the consumer's own side effects:

namespace App\Warehouse;

use Illuminate\Support\Facades\DB;

final class HandleOrderPlaced
{
    public function __construct(private ShipmentPlanner $planner) {}

    public function __invoke(string $messageId, array $payload): void
    {
        DB::transaction(function () use ($messageId, $payload) {
            $inserted = DB::table('processed_messages')->insertOrIgnore([
                'message_id' => $messageId,
                'consumer' => 'warehouse.order-placed',
                'processed_at' => now(),
            ]);

            if ($inserted === 0) {
                return;
            }

            $this->planner->planFor((int) $payload['order_id']);
        });
    }
}

insertOrIgnore returns the number of inserted rows. Zero means another delivery of the same message already got there first, so you return without doing the work. Because the dedupe row and the shipment plan commit together, a crash halfway leaves neither, and the redelivery runs the full handler again.

Naturally idempotent handlers ("set status to shipped", an upsert keyed by order_id) can skip the table. "Add loyalty points" or "send an email" cannot.

Testing the Outbox

The properties to prove are the ones that failed in production: the message is written atomically with the order, nothing is written on rollback, and a broker failure is retried rather than lost. Bind a fake publisher in the container and drive the relay with --once:

use App\Models\Cart;
use App\Orders\PlaceOrder;
use App\Outbox\MessagePublisher;
use Illuminate\Support\Facades\DB;

final class FakePublisher implements MessagePublisher
{
    public array $sent = [];

    public bool $failNext = false;

    public function publish(string $topic, string $messageId, array $payload): void
    {
        if ($this->failNext) {
            $this->failNext = false;

            throw new RuntimeException('broker down');
        }

        $this->sent[] = [$topic, $messageId, $payload];
    }
}

beforeEach(function () {
    $this->publisher = new FakePublisher();
    $this->app->instance(MessagePublisher::class, $this->publisher);
});

it('writes the order and its outbox message in one transaction', function () {
    $order = app(PlaceOrder::class)(Cart::factory()->withLines(2)->create());

    $this->assertDatabaseHas('outbox_messages', [
        'topic' => 'orders.placed',
        'aggregate_id' => (string) $order->id,
        'published_at' => null,
    ]);
});

it('publishes pending messages and retries after a broker failure', function () {
    app(PlaceOrder::class)(Cart::factory()->withLines(1)->create());
    $this->publisher->failNext = true;

    $this->artisan('outbox:relay', ['--once' => true])->assertSuccessful();
    expect($this->publisher->sent)->toBeEmpty();

    $this->travel(5)->seconds();
    $this->artisan('outbox:relay', ['--once' => true])->assertSuccessful();

    expect($this->publisher->sent)->toHaveCount(1)
        ->and(DB::table('outbox_messages')->whereNull('published_at')->count())->toBe(0);
});

$this->travel() moves Laravel's clock past the backoff window, so the retry test does not sleep. Also test the rollback case (throw inside an outer transaction, assert outbox_messages is empty) and the consumer: call it twice with the same message_id and assert the side effect happened once.

Common Pitfalls

• Recording outside the transaction. Calling record() after DB::transaction() returns brings the dual-write problem straight back. The transactionLevel() guard catches this early.

• Huge payloads. The outbox is not a document store. Put IDs and the fields consumers need, not the entire model graph with relations.

• Unbounded table growth. Published rows pile up fast. Schedule a daily job that deletes rows published more than seven days ago, in chunks of a few thousand.

• Assuming exactly-once. Every consumer you do not control will receive duplicates eventually. Send message_id in a header and document that it is the dedupe key.

• Never restarting the relay. Exit after N batches, like queue:work --max-jobs, and let Supervisor restart it with fresh code and config.

• Monitoring nothing. Alert on the age of the oldest unpublished message. If it grows, the relay is stuck, and orders are silently waiting.

When to Use the Outbox and When Not To

Use the transactional outbox when:

• a database change must be followed by a message to another service or broker, and losing or inventing that message has a business cost: orders, payments, inventory, account state;
• you integrate services over Kafka, RabbitMQ, SQS or webhooks and cannot share a database transaction with them;

You probably do not need it when:

• the side effect is best effort: analytics pings, cache warming, a "welcome" email where a rare miss is acceptable. afterCommit dispatch is simpler;
• everything happens inside one Laravel app with the database queue driver. A job dispatched inside the transaction on the database queue is already written atomically with your data, which is effectively an outbox;
• you already run change data capture (Debezium reading the binlog). CDC can replace the polling relay, though the outbox table is still a useful explicit contract.

One table, one worker, one dedupe check per consumer, and "paid but never shipped" stops being a 2 AM incident.

CORS is one of those topics people configure by trial and error until the error goes away. It is worth fifteen minutes to understand what the browser is actually doing, because the "make the error go away" fixes are exactly the ones that open a hole.

Same-Origin Policy First

An origin is the triple scheme + host + port. https://app.example.com and https://api.example.com are different origins; so are http:// and https:// of the same host, and :443 vs :8443.

The same-origin policy is a browser rule: JavaScript running on one origin may send many kinds of requests to another origin, but it may not read the response unless that other origin explicitly allows it. It protects the user, not the server. Without it, any page you visit could call fetch('https://your-bank.com/api/accounts', {credentials: 'include'}) and read the result with your session cookie attached.

CORS (Cross-Origin Resource Sharing) is the opt-out: a set of response headers with which a server says "these origins may read my responses, with these methods and headers, with or without credentials". Two consequences people often miss:

• CORS is enforced by the browser. curl, Postman, server-to-server calls and mobile apps ignore it completely. CORS is not authentication and not an API firewall.
• CORS is a relaxation. A server that sends no CORS headers at all is the most locked-down configuration. Every header you add loosens something.

Simple Requests vs Preflight

Browsers split cross-origin requests into two groups.

A simple request is one an HTML form could already send before CORS existed: method GET, HEAD or POST, only safelisted headers (such as Accept, Accept-Language, Content-Language), and a Content-Type of application/x-www-form-urlencoded, multipart/form-data or text/plain. The browser sends it immediately with an Origin header, then decides whether JavaScript may see the response.

Anything else (a PUT or DELETE, a JSON Content-Type, an Authorization header, any custom X- header) triggers a preflight: an OPTIONS request that asks permission first. Only if the answer allows the method, the headers and the origin does the browser send the real request.

A real preflight exchange for a JSON POST with a bearer token:

OPTIONS /api/orders HTTP/1.1
Host: api.example.com
Origin: https://app.example.com
Access-Control-Request-Method: POST
Access-Control-Request-Headers: authorization, content-type

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Methods: POST
Access-Control-Allow-Headers: authorization, content-type
Access-Control-Allow-Credentials: true
Access-Control-Max-Age: 7200
Vary: Origin

Two important details. First, a simple request does reach your server and run, even when the browser later hides the response. CORS does not protect a state-changing POST with a form content type; that is CSRF territory and needs CSRF tokens or SameSite cookies. Second, Access-Control-Max-Age lets the browser cache the preflight answer. Chromium caps it at 7200 seconds and Firefox at 86400, so larger values are silently reduced.

Credentials: Cookies Change the Rules

By default fetch() does not send cookies cross-origin. To send them you set credentials: 'include' (or withCredentials: true in axios):

// Runs on https://app.example.com
const res = await fetch('https://api.example.com/api/orders', {
  method: 'POST',
  credentials: 'include', // send cookies; requires Allow-Credentials and an explicit origin
  headers: { 'Content-Type': 'application/json', 'X-XSRF-TOKEN': xsrfToken },
  body: JSON.stringify({ sku: 'LAP-14', qty: 1 }),
});

Once credentials are involved, the server's response must satisfy stricter rules, or the browser refuses to expose it:

• Access-Control-Allow-Credentials: true must be present.
• Access-Control-Allow-Origin must be the exact origin, never *.
• For credentialed requests, * in Allow-Headers, Allow-Methods and Expose-Headers is treated as a literal string, not a wildcard. List them explicitly.

Whenever the Allow-Origin value depends on the request, add Vary: Origin. Otherwise a CDN or shared cache can store the response for origin A and serve it to origin B, which either breaks B or, worse, grants it access.

Laravel 13: config/cors.php

Laravel ships the HandleCors middleware in the global stack, powered by fruitcake/php-cors. It only acts on paths listed in config/cors.php, which you publish with php artisan config:publish cors. A production config for a first-party SPA that uses cookie auth looks like this:

// config/cors.php
return [
    'paths' => ['api/*', 'sanctum/csrf-cookie'],

    'allowed_methods' => ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'],

    'allowed_origins' => array_filter(explode(',', (string) env('CORS_ALLOWED_ORIGINS', ''))),

    // Anchored on both ends: preview deploys like https://pr-123.preview.example.com
    'allowed_origins_patterns' => ['#^https://pr-\d+\.preview\.example\.com$#'],

    'allowed_headers' => ['Content-Type', 'Authorization', 'X-Requested-With', 'X-XSRF-TOKEN'],

    'exposed_headers' => ['X-RateLimit-Remaining'],

    'max_age' => 7200,

    'supports_credentials' => true,
];

What each choice buys you:

• paths limits CORS to the API and the Sanctum CSRF cookie endpoint. Web routes and the admin panel get no CORS headers at all.
• allowed_origins comes from an env var (CORS_ALLOWED_ORIGINS=https://app.example.com,https://admin.example.com), so staging and production differ without code changes.
• allowed_origins_patterns are full regexes. Anchor them with ^ and $ and escape the dots, or example.com.evil.io will match.
• exposed_headers controls which response headers JavaScript can read beyond the safelisted ones. Without it, res.headers.get('X-RateLimit-Remaining') returns null even though the header is in the network tab.
• supports_credentials must be true for cookie-based auth (Sanctum SPA mode). With Sanctum, also set SANCTUM_STATEFUL_DOMAINS and a SESSION_DOMAIN like .example.com so the session cookie is shared across subdomains.

Watch out for one default: with allowed_origins => ['*'] and supports_credentials => true, the library does not send a literal * (browsers would reject it). It echoes back the request's origin instead. That makes the browser happy and makes your API readable, with cookies, from any site. Never combine the two.

Doing It by Hand in Express

When there is no framework helper, the logic fits in one small middleware. The important parts are the allowlist lookup, Vary: Origin, and answering preflights without hitting your route handlers:

const ALLOWED = new Set(['https://app.example.com', 'https://admin.example.com']);
const METHODS = 'GET, POST, PUT, PATCH, DELETE';
const HEADERS = 'content-type, authorization, x-xsrf-token';

function cors(req, res, next) {
  const origin = req.get('Origin');
  res.vary('Origin'); // caches must not mix responses for different origins

  if (origin && ALLOWED.has(origin)) {
    res.set('Access-Control-Allow-Origin', origin);
    res.set('Access-Control-Allow-Credentials', 'true');
  }

  if (req.method === 'OPTIONS' && req.get('Access-Control-Request-Method')) {
    if (!origin || !ALLOWED.has(origin)) {
      return res.sendStatus(403);
    }
    res.set('Access-Control-Allow-Methods', METHODS);
    res.set('Access-Control-Allow-Headers', HEADERS);
    res.set('Access-Control-Max-Age', '7200');
    return res.sendStatus(204);
  }

  next();
}

module.exports = { cors };

And here are the patterns to grep for in code review, because each one has shipped in real products:

// All of these are real-world bugs. Do not ship them.
res.set('Access-Control-Allow-Origin', req.get('Origin'));        // reflects ANY origin
if (origin.endsWith('example.com')) allow(origin);                // matches evil-example.com
if (/https:\/\/.*\.example\.com/.test(origin)) allow(origin);     // unanchored: example.com.evil.io
if (origin === 'null' || ALLOWED.has(origin)) allow(origin);      // sandboxed iframes send null

Testing Your CORS Setup

CORS bugs show up in browsers, but you can pin down the server side with ordinary feature tests. Assert both the happy path and that hostile origins get nothing:

it('answers a preflight from an allowed origin', function () {
    config(['cors.allowed_origins' => ['https://app.example.com']]);

    $this->withHeaders([
        'Origin' => 'https://app.example.com',
        'Access-Control-Request-Method' => 'POST',
        'Access-Control-Request-Headers' => 'content-type, authorization',
    ])->options('/api/orders')
        ->assertHeader('Access-Control-Allow-Origin', 'https://app.example.com')
        ->assertHeader('Access-Control-Allow-Credentials', 'true')
        ->assertHeader('Access-Control-Max-Age', '7200');
});

it('gives no CORS headers to an unknown origin', function () {
    config(['cors.allowed_origins' => ['https://app.example.com']]);

    $this->withHeaders(['Origin' => 'https://app.example.com.evil.io'])
        ->getJson('/api/health')
        ->assertHeaderMissing('Access-Control-Allow-Origin');
});

it('never combines a wildcard with credentials', function () {
    $origins = config('cors.allowed_origins');

    expect(config('cors.supports_credentials') && in_array('*', $origins, true))->toBeFalse();
});

The third test is a cheap guard rail: it fails the build the moment someone sets the dangerous wildcard plus credentials combination. For an end-to-end check, run your SPA's Playwright suite against a staging API on its real domain, not through a dev proxy that hides CORS entirely.

Common Pitfalls

• Reflecting the Origin header. Equivalent to * with credentials. Always check against an allowlist.
• Suffix and unanchored regex matching. endsWith('example.com') accepts evil-example.com. Match exact origins, or anchored patterns.
• Allowing null. Sandboxed iframes, file:// pages and some redirects send Origin: null. An attacker can produce it on purpose.
• Forgetting Vary: Origin. Leads to cached responses with the wrong origin, which looks like random CORS failures behind a CDN.
• CORS errors that are really 401, 413 or 502. If Nginx, a load balancer or a crashed PHP worker answers without CORS headers, the browser reports a CORS error and hides the real status. Check the network tab or server logs before touching CORS config.
• Treating CORS as access control. It stops browsers from reading responses. It does not stop curl, does not stop a simple POST from executing, and does not replace authentication or CSRF protection.
• Preflight hitting auth middleware. OPTIONS requests carry no Authorization header. If your auth layer runs before CORS and returns 401, the preflight fails. In Laravel, HandleCors is global and runs first, so keep it there.

When to Use CORS (and When Not To)

• Use it when browser JavaScript on one origin legitimately needs another origin's API: an SPA on app. calling api., a public read-only API used by third-party sites (here * without credentials is fine), or a widget embedded on customer domains with an explicit allowlist.
• Avoid it when you can serve the frontend and API from the same origin. Putting the API under https://example.com/api behind the same reverse proxy (or using Next.js rewrites) removes CORS, preflight latency and cookie domain headaches entirely.
• Do not reach for it for server-to-server calls, mobile apps or CLI tools. They do not enforce it, so it neither helps nor protects.
• Keep it narrow: specific paths, explicit origins, explicit headers, and credentials only where you really use cookies.

If you remember one rule: CORS is the server telling the browser whom it trusts. Make that list short, exact and boring.

The code was the usual one: read the file into an array, map it into another array, loop. Memory grows with input size, so every larger file is a new incident. Generators flip that around: you process one row at a time and memory stays flat no matter how big the file gets. They have been in PHP since 5.5 and are still underused, so here is the full toolbox: yield, keys, yield from, send(), and how Laravel's LazyCollection builds on them.

Why the Naive Version Explodes

// Loads the whole file, then builds a second full copy as arrays.
function importOrders(string $path): int
{
    $lines = file($path, FILE_IGNORE_NEW_LINES);   // 2 GB of strings
    $header = str_getcsv(array_shift($lines), ',', '"', '');
    $rows = array_map(
        fn (string $line) => array_combine($header, str_getcsv($line, ',', '"', '')),
        $lines,
    );                                              // another few GB of arrays

    foreach ($rows as $row) {
        // insert...
    }

    return count($rows);
}

PHP strings and arrays carry overhead. A 2 GB CSV loaded with file() costs more than 2 GB, and turning each line into an associative array multiplies that several times. Even array_map over a smaller file keeps the source and the result alive at the same time. The fix is not more RAM. The fix is never holding more than one row.

How a Generator Works

Any function that contains yield becomes a generator function. Calling it runs no code; it returns a Generator object. Each time the consumer asks for the next value, the function body resumes from where it paused, runs until the next yield, hands over a value, and freezes again with its local variables intact.

Only the current row exists in memory. The file handle, the header and the line counter live in the generator's paused stack frame. When the consumer stops (a break, an exception, or the generator going out of scope), PHP destroys the generator and runs any pending finally blocks, so the file still gets closed.

Implementation: Streaming a CSV

/**
 * Stream a CSV file one row at a time.
 *
 * @return Generator<int, array<string, string>> line number => associative row
 */
function readCsv(string $path): Generator
{
    $handle = fopen($path, 'rb');
    if ($handle === false) {
        throw new RuntimeException("Cannot open $path");
    }

    try {
        $header = fgetcsv($handle, null, ',', '"', '');
        $line = 1;

        while (($fields = fgetcsv($handle, null, ',', '"', '')) !== false) {
            $line++;
            if ($fields === [null]) {
                continue; // blank line
            }
            yield $line => array_combine($header, $fields);
        }
    } finally {
        fclose($handle); // runs even if the consumer stops early
    }
}

foreach (readCsv('/data/orders.csv') as $line => $row) {
    if ($row['status'] === 'cancelled') {
        continue;
    }
    // process one row; previous rows are already garbage
}

echo round(memory_get_peak_usage() / 1024 / 1024, 1), " MB\n";

A few details that matter in production:

• Keys. yield $key => $value sets the key. Without it, keys are auto-incremented integers like a list. Using the line number as the key gives you precise error messages for free.
• try/finally. Put cleanup in finally, not after the loop. If the consumer breaks early, code after the loop never runs, but finally does when the generator is destroyed.
• Explicit CSV escape. Since PHP 8.4, relying on the default $escape argument of fgetcsv() and str_getcsv() is deprecated. Pass '' to get RFC 4180 behaviour.
• Blank lines. fgetcsv() returns [null] for an empty line. Skip it explicitly or array_combine() will throw a ValueError about mismatched counts.

With this version the peak memory for the 2.1 GB file was about 2 MB, the same as for a 2 KB file.

Composing Generators with yield from

yield from delegates to another generator (or any iterable) and passes its values straight through. Its value as an expression is the inner generator's return value, which is a neat way to aggregate stats while streaming:

/** Concatenate several CSV exports into one stream and report the total. */
function readAll(array $paths): Generator
{
    $total = 0;
    foreach ($paths as $path) {
        // yield from forwards every key/value of the inner generator
        // and evaluates to the inner generator's return value.
        $total += yield from countingReader($path);
    }

    return $total;
}

function countingReader(string $path): Generator
{
    $n = 0;
    foreach (readCsv($path) as $line => $row) {
        $n++;
        yield $line => $row;
    }

    return $n;
}

$stream = readAll(['/data/2026-10.csv', '/data/2026-11.csv']);
foreach ($stream as $line => $row) {
    // keys restart at 2 for each file: they are NOT unique across files
}
echo $stream->getReturn(), " rows\n";

// Pitfall: iterator_to_array() keeps keys by default, so duplicate keys overwrite.
$rows = iterator_to_array(readAll(['/data/a.csv', '/data/b.csv']), preserve_keys: false);

$generator->getReturn() is available only after the generator has finished; calling it earlier throws. And watch the keys: yield from forwards inner keys unchanged, so two files both produce key 2. iterator_to_array() preserves keys by default and silently overwrites, which is how "the import only kept the last file's rows" bugs are born. Pass preserve_keys: false or do not materialize at all.

Two-Way Generators with send()

Generators can also receive values. $gen->send($value) resumes the generator and makes the paused yield expression evaluate to $value. That turns a generator into a small coroutine, which is handy for a batching sink:

/**
 * A coroutine: receives rows through send(), flushes them in batches,
 * and returns the number of rows written when it receives null.
 */
function batchWriter(Closure $flush, int $size = 1000): Generator
{
    $buffer = [];
    $written = 0;

    while (true) {
        $row = yield;              // pauses here until send($row)
        if ($row === null) {
            break;
        }
        $buffer[] = $row;
        if (count($buffer) >= $size) {
            $flush($buffer);
            $written += count($buffer);
            $buffer = [];
        }
    }

    if ($buffer !== []) {
        $flush($buffer);
        $written += count($buffer);
    }

    return $written;
}

$writer = batchWriter(fn (array $rows) => printf("flush %d\n", count($rows)), 2);
$writer->current();               // run to the first yield
foreach ([['id' => 1], ['id' => 2], ['id' => 3]] as $row) {
    $writer->send($row);
}
$writer->send(null);              // flush 2, flush 1
echo $writer->getReturn(), "\n";  // 3

The first send() implicitly runs the generator to its first yield before delivering the value, but calling current() first makes the intent explicit. Most application code never needs send(); reach for it when a consumer-side state machine (batching, rate counting, a parser that receives chunks) reads more clearly as one function than as a class with fields.

Laravel: LazyCollection

LazyCollection wraps a generator and gives you the Collection API (filter, map, chunk, take, each, reduce) while staying lazy: each operation pulls items through one at a time instead of building intermediate arrays. Here is the import job rewritten as an Artisan command:

namespace App\Console\Commands;

use Illuminate\Console\Command;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\LazyCollection;

final class ImportOrders extends Command
{
    protected $signature = 'orders:import {path}';

    protected $description = 'Stream a large CSV into the orders table';

    public function handle(): int
    {
        $path = $this->argument('path');

        $imported = self::rows($path)
            ->filter(fn (array $row) => $row['status'] !== 'cancelled')
            ->map(fn (array $row) => [
                'external_id' => $row['id'],
                'email' => strtolower(trim($row['email'])),
                'total_cents' => (int) round(((float) $row['total']) * 100),
                'created_at' => $row['created_at'],
            ])
            ->chunk(1000)
            ->reduce(function (int $count, LazyCollection $chunk) {
                DB::table('orders')->upsert($chunk->values()->all(), ['external_id']);

                return $count + $chunk->count();
            }, 0);

        $this->info("Imported {$imported} rows, peak "
            . round(memory_get_peak_usage(true) / 1048576) . ' MB');

        return self::SUCCESS;
    }

    /** @return LazyCollection<int, array<string, string>> */
    public static function rows(string $path): LazyCollection
    {
        return LazyCollection::make(function () use ($path) {
            $handle = fopen($path, 'rb');
            try {
                $header = fgetcsv($handle, null, ',', '"', '');
                while (($fields = fgetcsv($handle, null, ',', '"', '')) !== false) {
                    if ($fields !== [null]) {
                        yield array_combine($header, $fields);
                    }
                }
            } finally {
                fclose($handle);
            }
        });
    }
}

chunk(1000) yields LazyCollection chunks, so you batch the database writes (one upsert per 1000 rows instead of 1000 queries) while still holding at most 1000 rows in memory. upsert keyed on external_id makes the import safe to rerun after a crash halfway through.

Eloquent has lazy readers too, and they are not interchangeable:

use App\Models\Order;

// One query, models hydrated one at a time.
foreach (Order::query()->where('status', 'paid')->cursor() as $order) {
    // ...
}

// Many small queries keyed by id: stable memory, safe while updating rows.
Order::query()->where('status', 'paid')->lazyById(1000)->each(function (Order $order) {
    $order->update(['exported_at' => now()]);
});

cursor() runs one query and hydrates models one by one, but on MySQL the PDO driver buffers the entire result set by default, so very large results can still eat memory. lazy() and lazyById() page through the table with many small queries; lazyById() is the safe choice when you update the rows you are iterating, because it pages by primary key instead of offset.

Testing It

Two things deserve a test: the stream really is lazy, and memory stays bounded on a large input. Generating a 200k-row file in the test takes about a second and catches the regression where someone adds ->all() or ->collect() in the middle of the pipeline, which forces the whole file into memory.

// tests/Feature/ImportOrdersTest.php
use App\Console\Commands\ImportOrders;
use Illuminate\Support\Facades\DB;

function writeCsv(int $rows): string
{
    $path = tempnam(sys_get_temp_dir(), 'orders');
    $h = fopen($path, 'wb');
    fwrite($h, "id,email,total,status,created_at\n");
    for ($i = 1; $i <= $rows; $i++) {
        $status = $i % 10 === 0 ? 'cancelled' : 'paid';
        fwrite($h, "{$i}, User{$i}@Example.com ,19.99,{$status},2026-11-01 10:00:00\n");
    }
    fclose($h);

    return $path;
}

it('streams rows lazily', function () {
    $path = writeCsv(5);
    $rows = ImportOrders::rows($path);

    expect($rows->first())->toMatchArray(['id' => '1', 'status' => 'paid'])
        ->and($rows->take(3)->count())->toBe(3);
});

it('imports a big file in bounded memory', function () {
    DB::table('orders')->delete();
    $path = writeCsv(200_000);
    $before = memory_get_usage();

    $this->artisan('orders:import', ['path' => $path])->assertSuccessful();

    expect(DB::table('orders')->count())->toBe(180_000)
        ->and(DB::table('orders')->where('external_id', '1')->value('email'))->toBe('user1@example.com')
        ->and(memory_get_peak_usage() - $before)->toBeLessThan(64 * 1024 * 1024);
});

The memory assertion is deliberately generous. For unit-level checks of pure generator functions, assert on iterator_to_array($gen, false) with small inputs and feed an infinite generator to prove that only the needed items are pulled.

Common Pitfalls

• Iterating twice. A generator is single-use. A second foreach throws Exception: Cannot traverse an already closed generator. LazyCollection::make(fn () => ...) takes a closure exactly so it can create a fresh generator for every pass, which also means each pass re-reads the file.
• Calling count() or ->all() on the stream. Anything that needs the whole sequence materializes it. LazyCollection::count() iterates everything; ->all() builds the full array.
• iterator_to_array() with duplicate keys. Values get overwritten silently. Use preserve_keys: false.
• Cleanup after the loop instead of in finally. Early break skips it and you leak file handles or database cursors.
• Expecting laziness from cursor() on MySQL. The query is lazy, the result buffer is not. Use lazyById() for huge tables.
• Holding references. Pushing each row into $this->seen[] for deduplication rebuilds the memory problem. Keep a set of ids or hashes, or deduplicate in the database.

When to Use Generators and When Not To

Use them when:

• input size is unbounded or large: files, exports, API pagination, database tables;
• you want a pipeline (read, filter, transform, batch, write) without intermediate arrays;
• you need to stop early: take(10) on a lazy stream reads only what it needs;
• you want to separate "how to fetch" from "what to do with each item" without callbacks.

Avoid them when:

• the data is small and you need random access, sorting, or multiple passes; a plain array is simpler and faster;
• you need the total count up front, for example for a progress bar, unless you can get it cheaply from somewhere else;
• the work is CPU-bound per item and you want parallelism; generators are sequential, so use queued jobs per chunk instead;
• debugging lazy chains confuses your team more than the memory saving helps.

Memory usage should depend on the batch size you pick, not on the size of the input file.

This is the lost update problem. Each request did a perfectly valid read-modify-write; the bug is the gap between the read and the write. Database transactions alone do not fix it, because the read happened in one HTTP request and the write in another, minutes apart. The fix is to make the write conditional on the data not having changed since it was read.

The Lost Update, Step by Step

Here is what the two saves look like at the SQL level. Most CRUD forms send every field back, not just the changed ones, which is exactly what makes the second save overwrite the first:

-- 10:00:00  Agent A loads product 42: price = 100, stock = 7
-- 10:00:02  Agent B loads product 42: price = 100, stock = 7
-- 10:00:05  Agent A saves a new price
UPDATE products SET price = 90, stock = 7 WHERE id = 42;
-- 10:00:09  Agent B saves a stock correction, using the price it loaded
UPDATE products SET price = 100, stock = 5 WHERE id = 42;
-- Result: price is back to 100. Agent A's change is gone and nobody got an error.

Even if your form only sent changed fields, the problem returns as soon as a value is derived from what was read: "add 10% to the price", "subtract 2 from stock". Any read-modify-write that spans time is exposed.

Optimistic Locking With a Version Column

Optimistic locking assumes conflicts are rare and checks for them at write time instead of preventing them up front. Add an integer version to the row. Every reader gets the version along with the data. Every writer says "apply this change only if the version is still the one I saw" and bumps it in the same statement:

-- Each writer sends the version it read. Only one of them can match.
UPDATE products
SET price = 90, version = version + 1
WHERE id = 42 AND version = 7;   -- Agent A: 1 row affected, version is now 8

UPDATE products
SET stock = 5, version = version + 1
WHERE id = 42 AND version = 7;   -- Agent B: 0 rows affected, conflict detected

The WHERE ... AND version = 7 makes the check and the write a single atomic operation. The database already serializes updates to the same row, so exactly one of the two statements can match. The loser sees zero affected rows and knows its view of the data is stale.

You could use updated_at as the version, but timestamps have second or millisecond resolution and two saves inside the same tick would both match. An integer that only ever increments is unambiguous.

Laravel Implementation

Start with the column. A default of 1 makes existing rows valid immediately:

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    public function up(): void
    {
        Schema::table('products', function (Blueprint $table) {
            $table->unsignedInteger('version')->default(1)->after('id');
        });
    }

    public function down(): void
    {
        Schema::table('products', function (Blueprint $table) {
            $table->dropColumn('version');
        });
    }
};

Eloquent's save() does not tell you how many rows an update affected, so do the conditional update through the query builder, where update() returns the affected row count:

namespace App\Services;

use App\Exceptions\StaleModelException;
use App\Models\Product;
use Illuminate\Support\Facades\DB;

final class ProductWriter
{
    /**
     * @param array<string, mixed> $changes
     * @throws StaleModelException when someone else saved first
     */
    public function update(int $productId, int $expectedVersion, array $changes): int
    {
        $affected = Product::query()
            ->whereKey($productId)
            ->where('version', $expectedVersion)
            ->update([...$changes, 'version' => DB::raw('version + 1')]);

        if ($affected === 0) {
            throw new StaleModelException(
                Product::class,
                $productId,
                $expectedVersion,
                Product::whereKey($productId)->value('version'),
            );
        }

        return $expectedVersion + 1;
    }
}

A dedicated exception carries enough context to log and to answer the client. Laravel calls render() on exceptions that define it, so controllers stay clean:

namespace App\Exceptions;

use RuntimeException;

final class StaleModelException extends RuntimeException
{
    public function __construct(
        public readonly string $model,
        public readonly int $id,
        public readonly int $expectedVersion,
        public readonly ?int $currentVersion,
    ) {
        parent::__construct(
            $currentVersion === null
                ? "{$model} #{$id} no longer exists."
                : "{$model} #{$id} was modified: expected version {$expectedVersion}, found {$currentVersion}."
        );
    }

    public function render(): \Illuminate\Http\JsonResponse
    {
        return response()->json([
            'message' => 'This record was changed by someone else. Reload and try again.',
            'current_version' => $this->currentVersion,
        ], $this->currentVersion === null ? 404 : 409);
    }
}

The version has to travel with the data. For a JSON API, return it in the body and as an ETag, and require the client to send back the version it edited. For a Blade or Livewire form, a hidden version field does the same job:

namespace App\Http\Controllers;

use App\Models\Product;
use App\Services\ProductWriter;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;

final class ProductController
{
    public function show(Product $product): JsonResponse
    {
        return response()
            ->json($product)
            ->header('ETag', '"'.$product->version.'"');
    }

    public function update(Request $request, Product $product, ProductWriter $writer): JsonResponse
    {
        $data = $request->validate([
            'price' => ['sometimes', 'integer', 'min:0'],
            'stock' => ['sometimes', 'integer', 'min:0'],
            'version' => ['required', 'integer', 'min:1'],
        ]);

        $version = $writer->update($product->id, $data['version'], collect($data)->except('version')->all());

        return response()->json(['version' => $version])->header('ETag', '"'.$version.'"');
    }
}

The 409 response is a feature. The frontend can show "Someone changed this product while you were editing", reload the latest data, and let the user reapply their change knowingly. That is far better than silently discarding work.

Retrying When There Is No Human

Background jobs and scheduled tasks have nobody to show a conflict dialog to. For them, the right response to a stale version is usually: re-read, recompute, try again, a bounded number of times. Laravel's retry() helper fits well:

namespace App\Services;

use App\Exceptions\StaleModelException;
use App\Models\Product;
use Closure;

final class PriceAdjuster
{
    public function __construct(private ProductWriter $writer) {}

    /** Background jobs have no human to ask, so they re-read and retry a few times. */
    public function applyDiscount(int $productId, int $percent, int $maxAttempts = 3): void
    {
        retry($maxAttempts, function () use ($productId, $percent): void {
            $product = Product::findOrFail($productId);
            $newPrice = intdiv($product->price * (100 - $percent), 100);

            $this->writer->update($product->id, $product->version, ['price' => $newPrice]);
        }, sleepMilliseconds: fn (int $attempt): int => random_int(10, 50) * $attempt,
            when: fn (\Throwable $e): bool => $e instanceof StaleModelException);
    }
}

The re-read is essential: retrying the same write with the same old version would fail forever. The small random sleep spreads out competing workers so they do not collide again on the next attempt.

Optimistic vs Pessimistic: lockForUpdate

The alternative is to prevent conflicts instead of detecting them. lockForUpdate() issues SELECT ... FOR UPDATE, which locks the row until the transaction commits; any other transaction that wants the same lock waits:

use App\Models\Product;
use Illuminate\Support\Facades\DB;

// Pessimistic: lock the row, everyone else waits until commit.
DB::transaction(function () use ($productId, $quantity): void {
    $product = Product::whereKey($productId)->lockForUpdate()->firstOrFail();

    if ($product->stock < $quantity) {
        throw new \DomainException('Not enough stock.');
    }

    $product->decrement('stock', $quantity);
}, attempts: 3);

// Often better for a single counter: let the database do the check atomically.
$reserved = Product::whereKey($productId)
    ->where('stock', '>=', $quantity)
    ->decrement('stock', $quantity);

Pessimistic locking only works inside a single transaction. You cannot hold a row lock while an admin thinks for two minutes; that would block every other writer and exhaust connections. So the two approaches cover different shapes of work:

• Pessimistic for short, server-side critical sections where conflicts are frequent: reserving stock at checkout, allocating seats, moving money between wallets.
• Optimistic for anything with think time between read and write (forms, editors, mobile apps syncing offline changes) and for rows that are read often but rarely edited at the same time.

The second snippet above shows a third option that beats both for simple counters: an atomic conditional update. stock = stock - 3 WHERE stock >= 3 needs no version and no lock held across round trips.

Testing the Conflict Path

The conflict path is the code you hope never runs, which is exactly why it needs a test. Simulate the two agents by writing twice with the same starting version:

use App\Exceptions\StaleModelException;
use App\Models\Product;
use App\Services\ProductWriter;

it('rejects the second writer that loaded the same version', function () {
    $product = Product::factory()->create(['price' => 100, 'stock' => 7, 'version' => 1]);
    $writer = app(ProductWriter::class);

    expect($writer->update($product->id, 1, ['price' => 90]))->toBe(2);

    expect(fn () => $writer->update($product->id, 1, ['stock' => 5]))
        ->toThrow(StaleModelException::class);

    expect($product->fresh())
        ->price->toBe(90)
        ->stock->toBe(7)
        ->version->toBe(2);
});

it('returns 409 with the current version over HTTP', function () {
    $product = Product::factory()->create(['version' => 3]);

    $this->actingAs(\App\Models\User::factory()->create())
        ->putJson("/api/products/{$product->id}", ['price' => 50, 'version' => 2])
        ->assertStatus(409)
        ->assertJsonPath('current_version', 3);
});

The first test proves that the losing write changes nothing (stock is still 7). The second proves the HTTP contract the frontend depends on. If you have a retrying writer, add a test where the first attempt is made stale on purpose, as the challenge below does.

Common Pitfalls

• Bumping the version in PHP instead of SQL. ['version' => $model->version + 1] without the WHERE version = ? check is just a counter. The condition is the lock.
• Ignoring the affected row count. On MySQL, an UPDATE that matches a row but changes no values can report 0 affected rows by default. Because the version always increments, a matching row always changes, so 0 really means "no match".
• Taking the version from the database at save time. If the controller loads the model and uses its current version, the check always passes. The version must come from what the client read.
• Mass updates that skip the version. A maintenance script or Product::query()->update([...]) that does not bump version lets stale clients overwrite its changes. Every writer must participate.
• Retrying forever. Unbounded retries on a hot row turn a conflict into a livelock. Cap attempts and surface the failure.

When to Use It, and When Not To

Use optimistic locking when edits are human-paced, conflicts are uncommon, and losing a write is unacceptable: admin panels, CMS content, settings, orders being edited by staff, offline-first mobile sync. It costs one integer column and one extra WHERE condition, and it never blocks readers or other writers.

Do not use it for highly contended rows where many processes write constantly, such as a global counter or a popular item's stock during a flash sale; most writers will lose and retry. Use an atomic update or a short pessimistic lock there. And do not add it to append-only tables or rows that only one process ever writes; there is no conflict to detect.

Health checks look like a one-line YAML concern, but each probe type answers a different question and triggers a different action. Mix them up and the platform that is supposed to heal your app amplifies every incident instead.

Three Probes, Three Questions

Kubernetes has three probe types. Docker has one HEALTHCHECK. What matters is the question each one asks and what happens when the answer is "no":

• Liveness: "Is this process broken beyond self-repair?" On failure the kubelet kills the container and restarts it. Only deadlocks, wedged event loops or corrupted in-memory state justify this. A restart fixes nothing outside the container.
• Readiness: "Should this pod receive traffic right now?" On failure the pod is removed from the Service endpoints. Nothing is restarted. When the probe passes again, traffic comes back. This is where dependency awareness belongs, carefully.
• Startup: "Has the app finished booting?" While it has not passed, liveness and readiness are not run. It protects slow starters (cache warmup, migration checks, JIT warmup) from being killed by a liveness probe tuned for steady state.

The defaults are periodSeconds: 10, timeoutSeconds: 1, failureThreshold: 3, successThreshold: 1. That one-second timeout bites PHP apps under load more often than any other setting.

The Probe Lifecycle

Read it as two separate loops after startup: liveness decides whether to restart, readiness decides whether to route. A pod can be alive and unready (draining, dependency down, warming up) for as long as needed without being restarted, which is exactly the state you want during a database failover.

What to Check, and What Not To

Liveness should check almost nothing. The request reaching your code and getting a response is the check. In Laravel that is the built-in /up route: it boots the framework, fires a DiagnosingHealth event, and returns 200, or 500 if something throws. No database, no Redis, no external API. If PHP-FPM is out of workers the probe times out, which is a fair signal that the container is stuck.

Readiness may check dependencies this pod cannot work without, and only those. If every request needs MySQL, a failing MySQL check is a reason to stop routing to this pod. But think about the fleet: if all pods share the same database, all of them go unready together and the Service has zero endpoints. Users get connection errors from the load balancer instead of a clean 503 from your app. For shared dependencies, many teams deliberately keep readiness green and let the app return proper errors, circuit-break, or serve cached data.

Never check third-party APIs in any probe. A payment provider outage should degrade checkout, not pull your whole API out of rotation.

Keep probes cheap and bounded. A probe runs every few seconds on every pod. A SELECT COUNT(*) on a large table, or an uncapped connection attempt that waits for the default TCP timeout, turns the probe into load and makes it time out on its own.

Laravel: /up for Liveness, /ready for Readiness

Laravel 11 and later register the health route in bootstrap/app.php. Keep it as the liveness endpoint:

// bootstrap/app.php
use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Exceptions;
use Illuminate\Foundation\Configuration\Middleware;

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        commands: __DIR__.'/../routes/console.php',
        health: '/up', // liveness: boots the framework, touches no dependency
    )
    ->withMiddleware(function (Middleware $middleware): void {})
    ->withExceptions(function (Exceptions $exceptions): void {})
    ->create();

For readiness, add a separate invokable controller that runs fast checks and returns 503 when a critical one fails:

namespace App\Http\Controllers;

use Illuminate\Http\JsonResponse;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Redis;
use Throwable;

final class ReadinessController
{
    public function __invoke(): JsonResponse
    {
        $checks = [
            'database' => ['critical' => true, 'run' => fn () => DB::select('select 1')],
            'redis' => ['critical' => true, 'run' => fn () => Redis::connection()->ping()],
        ];

        $results = [];
        $ready = true;

        foreach ($checks as $name => $check) {
            try {
                ($check['run'])();
                $results[$name] = 'ok';
            } catch (Throwable $e) {
                report($e);
                $results[$name] = 'fail';
                $ready = $ready && ! $check['critical'];
            }
        }

        return response()->json(
            ['status' => $ready ? 'ready' : 'not_ready', 'checks' => $results],
            $ready ? 200 : 503,
        );
    }
}

Register it with Route::get('/ready', ReadinessController::class); outside any auth or session middleware, and exclude both routes from rate limiting. The critical flag is the important design choice: a non-critical dependency (a search index, a recommendations service) can fail without taking the pod out of rotation. Reporting the exception with report() gives you the cause in your error tracker instead of a bare 503 in the kubelet events.

Kubernetes Configuration

Point liveness and startup at /up, readiness at /ready, and size the startup window from measured boot time:

containers:
  - name: app
    image: registry.example.com/shop-api:2026.11.04
    ports:
      - containerPort: 8080
    startupProbe:            # gate: liveness/readiness wait until this passes
      httpGet: { path: /up, port: 8080 }
      periodSeconds: 5
      failureThreshold: 24   # up to 120s to boot
    livenessProbe:           # "is the process wedged?" -> restart
      httpGet: { path: /up, port: 8080 }
      periodSeconds: 10
      timeoutSeconds: 2
      failureThreshold: 3
    readinessProbe:          # "can it serve traffic right now?" -> remove from Service
      httpGet: { path: /ready, port: 8080 }
      periodSeconds: 5
      timeoutSeconds: 2
      failureThreshold: 2
    lifecycle:
      preStop:
        exec: { command: ["sleep", "5"] }  # let endpoints update before SIGTERM

failureThreshold * periodSeconds on the startup probe is the maximum boot time you allow: 24 x 5 = 120 seconds here. The preStop sleep covers the gap between the pod being marked terminating and every node's proxy dropping it from the endpoints; without it, a rolling deploy sends a few requests to a container that is already shutting down. That command needs a sleep binary in the image.

Docker and Compose Healthchecks

Plain Docker only has one healthcheck, and it is informational: Docker marks the container healthy or unhealthy but does not restart it (Swarm and Compose depends_on conditions do act on it). Use the liveness endpoint:

# Dockerfile
HEALTHCHECK --interval=15s --timeout=3s --start-period=30s --retries=3 \
  CMD curl -fsS http://127.0.0.1:8080/up || exit 1

--start-period is Docker's version of a startup probe: failures during that window do not count against --retries. Use 127.0.0.1 rather than localhost to avoid IPv6 resolution surprises, and make sure curl (or wget) actually exists in your final image; distroless and slim images often lack both.

When something goes wrong, look at what the platform saw, not what you think the endpoint returns:

docker inspect --format '{{json .State.Health}}' shop-api | jq '.Status, .Log[-1]'
kubectl describe pod shop-api-7c9f8 | grep -A3 -E 'Liveness|Readiness|Startup'
kubectl get endpoints shop-api   # unready pods disappear from this list

Testing Health Endpoints

Health endpoints are code, and the most important property to test is the negative one: liveness must stay green when dependencies fail. A Pest feature test with facade mocks covers it:

use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Redis;

it('keeps /up green even when the database is down', function () {
    DB::shouldReceive('select')->andThrow(new RuntimeException('db down'));

    $this->get('/up')->assertOk();
});

it('reports not ready when a critical dependency fails', function () {
    DB::shouldReceive('select')->andThrow(new RuntimeException('db down'));
    Redis::shouldReceive('connection->ping')->andReturn(true);

    $this->getJson('/ready')
        ->assertStatus(503)
        ->assertJsonPath('checks.database', 'fail')
        ->assertJsonPath('checks.redis', 'ok');
});

it('reports ready when every check passes', function () {
    DB::shouldReceive('select')->andReturn([]);
    Redis::shouldReceive('connection->ping')->andReturn(true);

    $this->getJson('/ready')->assertOk()->assertJsonPath('status', 'ready');
});

The first test is the one that would have prevented the 02:14 incident. If someone later adds a database call to a DiagnosingHealth listener, it fails in CI instead of in production. Back it up with one end-to-end check in your deploy pipeline: start the container, wait for the healthcheck to report healthy, and fail the pipeline if it never does.

Common Pitfalls

Dependencies in liveness. The classic cascading failure. A shared dependency fails, every pod restarts at once, and recovery gets slower and noisier. Liveness checks the process, nothing else.

Same endpoint for liveness and readiness. It forces you to choose between restarts on dependency blips and no traffic control at all. Two endpoints, two questions.

Timeouts tighter than real latency. A one-second timeout on a pod at 90% CPU fails intermittently, the pod flaps between ready and unready, and the load shifts to the others, which then flap too. Measure p99 of the probe under load and set the timeout well above it.

No startup probe for slow boots. Teams compensate with a huge initialDelaySeconds on liveness, which also delays detection of real hangs forever after a restart. Use a startup probe instead.

Probes behind auth, sessions or rate limits. A probe that hits session middleware writes a session per call; one behind a rate limiter fails during traffic spikes, exactly when you need it to be accurate.

Health checks that log every call. At three probes every five seconds across 30 pods, access logs fill with noise. Exclude the probe paths from access logging or sample them.

When to Use Each Probe, and When Not To

Use readiness on every service that receives traffic through a Service or load balancer. It is the probe with the best risk/benefit ratio, because failing it never destroys anything.

Use liveness only when you have a realistic failure mode that a restart fixes: memory leaks that wedge workers, deadlocks, an event loop that stops processing. If you cannot name one, leaving liveness off is a valid choice; a missing liveness probe is safer than a wrong one.

Use startup whenever boot time is longer or more variable than your liveness budget, which is typical for apps that warm caches or wait for config at boot.

Skip dependency checks in readiness when the dependency is shared by the whole fleet and the app can return meaningful errors on its own. Skip HTTP probes entirely for queue workers that expose no port; an exec probe that checks a heartbeat file written by the worker loop is a better fit there.

Both incidents come from the same gap: treating the promise combinators as interchangeable "run things in parallel" helpers. They are not. Promise.all, Promise.allSettled, Promise.race and Promise.any differ in when they settle, what they do with failures, and what they return. None of them limits concurrency, and none of them cancels anything. Pick the right one and add the missing pieces yourself.

The Four Combinators at a Glance

All four take an iterable of promises (or plain values) and return a single promise. The difference is the rule for settling:

Two facts apply to all of them and cause most real bugs:

1. The work starts before the combinator is called. fetch(url) starts the request the moment you call it. Promise.all only observes promises that are already running. That is why Promise.all(customers.map(sendEmail)) fires 8,000 requests at once: the map started them all.
2. Nothing gets cancelled. When Promise.all rejects early, or Promise.race picks a winner, the other operations keep running to completion. Their results are just ignored. If you need cancellation, you need AbortController on top.

Choosing the Right One

Promise.all: All or Nothing, Fail Fast

Use Promise.all when every result is required and one failure means the whole operation is meaningless. Building an invoice needs the customer, the line items and the tax rates; if any is missing, there is no invoice.

async function buildInvoice(orderId: string) {
  const [customer, items, taxRates] = await Promise.all([
    customers.forOrder(orderId),
    orderItems.list(orderId),
    tax.ratesFor(orderId),
  ]);

  return renderInvoice(customer, items, taxRates);
}

The result array is in input order, not completion order, and destructuring keeps the types precise in TypeScript. The promise rejects with the first rejection reason as soon as it happens, which is great for latency: you do not wait for slow siblings when the answer is already "error".

The flip side: the other promises are still running and, if they reject later, those rejections are handled by Promise.all internally, so you will not get unhandled rejection warnings, but you also will not hear about them. If a sibling had side effects (writes, payments), they happen anyway.

Promise.allSettled: Partial Results Are Fine

The dashboard is the classic case for allSettled: each widget is independent, and a broken widget should render as "unavailable", not take the whole page down.

type Widget = 'profile' | 'orders' | 'recommendations';

async function loadDashboard(userId: string) {
  const loaders: Record<Widget, () => Promise<unknown>> = {
    profile: () => api.profile(userId),
    orders: () => api.orders(userId),
    recommendations: () => api.recommendations(userId),
  };

  const names = Object.keys(loaders) as Widget[];
  const results = await Promise.allSettled(names.map((name) => loaders[name]()));

  return Object.fromEntries(
    results.map((result, i) => {
      if (result.status === 'fulfilled') {
        return [names[i], { ok: true, data: result.value }];
      }

      logger.warn('widget failed', { widget: names[i], reason: String(result.reason) });

      return [names[i], { ok: false, data: null }];
    }),
  );
}

allSettled never rejects, which means you are responsible for looking at the failures. A common mistake is to call allSettled, map over value, and silently render undefined for failed entries. Always branch on status, and log or count the reason, or you lose all visibility into failures. In TypeScript, narrowing on result.status === 'fulfilled' gives you PromiseFulfilledResult<T>, so result.value is typed.

Promise.race: Timeouts, and the Timer You Forgot

race settles with whichever input settles first, fulfilled or rejected. Its main practical use is a timeout around an operation that does not support one natively:

export function withTimeout<T>(promise: Promise<T>, ms: number, label = 'operation'): Promise<T> {
  let timer: ReturnType<typeof setTimeout> | undefined;

  const timeout = new Promise<never>((_, reject) => {
    timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms);
  });

  return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
}

Two things are easy to get wrong here. First, the clearTimeout in finally: without it, every successful call leaves a live timer behind, which keeps a Node process alive at shutdown and, in a long-running server, means thousands of pending timers. Second, the timeout only stops you from waiting. The underlying operation is still running. For fetch, pass AbortSignal.timeout(ms) as the signal instead so the request is really cancelled; keep the race pattern for things that cannot be aborted, like a third-party SDK call.

Also remember that race with a rejection wins too. If the operation fails in 5 ms, the race rejects with that error immediately, which is usually what you want.

Promise.any: First Success Wins

any ignores rejections until every input has rejected. It fits redundancy: query three mirrors or replicas and use whichever answers successfully first.

async function fetchFromFastestMirror(path: string): Promise<unknown> {
  const mirrors = ['https://eu.cdn.example.com', 'https://us.cdn.example.com', 'https://ap.cdn.example.com'];

  try {
    return await Promise.any(
      mirrors.map(async (base) => {
        const res = await fetch(`${base}${path}`);
        if (!res.ok) {
          throw new Error(`${base} answered ${res.status}`);
        }
        return res.json();
      }),
    );
  } catch (error) {
    if (error instanceof AggregateError) {
      console.error('all mirrors failed', error.errors.map(String));
    }
    throw error;
  }
}

Note the if (!res.ok) throw. fetch only rejects on network errors, not on HTTP 500, so without that check a mirror that quickly returns an error page would "win". AggregateError.errors holds every individual reason in input order, which is exactly what you want in the log line. Using any here triples the load on your mirrors, so reserve it for small, idempotent reads.

Concurrency Limiting: What None of Them Do

For the 8,000 emails, none of the combinators help, because the work already started inside map. The fix is to control when each task starts: a small pool of workers that pull the next item from a shared index.

export async function mapWithConcurrency<T, R>(
  items: readonly T[],
  limit: number,
  fn: (item: T, index: number) => Promise<R>,
): Promise<R[]> {
  if (!Number.isInteger(limit) || limit < 1) {
    throw new RangeError('limit must be a positive integer');
  }

  const results = new Array<R>(items.length);
  let next = 0;
  let failed = false;

  async function worker(): Promise<void> {
    while (!failed && next < items.length) {
      const index = next++;
      try {
        results[index] = await fn(items[index], index);
      } catch (error) {
        failed = true;
        throw error;
      }
    }
  }

  const workers = Array.from({ length: Math.min(limit, items.length) }, () => worker());
  await Promise.all(workers);

  return results;
}

Because JavaScript is single-threaded, const index = next++ is atomic; no lock is needed. Results go into results[index], so output order matches input order regardless of which task finishes first. The failed flag gives fail-fast semantics like Promise.all, and also stops the pool from starting new items after the first error, which matters when each item sends an email or charges a card. If you prefer collect-all semantics, catch inside the worker and store { ok: false, error } instead.

Libraries like p-limit and p-map implement the same idea with more options. The point is to understand the shape: a fixed number of in-flight promises, not a fixed number of batches. Chunking into groups of 50 with Promise.all per chunk works, but each chunk waits for its slowest member, so throughput drops to the speed of the worst request in every batch.

Testing Combinator Logic with Vitest

Concurrency code is where "it worked on my machine" lives. Test the properties that matter: peak concurrency, order, and failure behaviour. Fake timers make timeout tests instant and deterministic.

import { afterEach, describe, expect, it, vi } from 'vitest';
import { mapWithConcurrency, withTimeout } from './async-utils';

const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));

describe('mapWithConcurrency', () => {
  it('never runs more than limit tasks and keeps input order', async () => {
    let active = 0;
    let peak = 0;

    const out = await mapWithConcurrency([30, 10, 20, 5], 2, async (ms) => {
      active++;
      peak = Math.max(peak, active);
      await sleep(ms);
      active--;
      return ms * 2;
    });

    expect(out).toEqual([60, 20, 40, 10]);
    expect(peak).toBe(2);
  });

  it('rejects with the first error and starts no new work', async () => {
    const started: number[] = [];

    await expect(
      mapWithConcurrency([1, 2, 3, 4], 1, async (n) => {
        started.push(n);
        if (n === 2) throw new Error('boom');
        return n;
      }),
    ).rejects.toThrow('boom');

    expect(started).toEqual([1, 2]);
  });
});

describe('withTimeout', () => {
  afterEach(() => vi.useRealTimers());

  it('rejects when the promise is too slow', async () => {
    vi.useFakeTimers();
    const pending = withTimeout(new Promise(() => {}), 1000, 'report');
    const assertion = expect(pending).rejects.toThrow('report timed out after 1000ms');

    await vi.advanceTimersByTimeAsync(1000);
    await assertion;
  });
});

Attach the rejects assertion before advancing the timers; otherwise the rejection happens with no handler attached and Vitest reports it as unhandled.

Common Pitfalls

• Expecting Promise.all to cancel siblings. It does not. Pass an AbortSignal to the operations and abort it in a catch if you need that.
• Promise.all over an unbounded array. items.map(asyncFn) starts everything at once. Use a concurrency limit for anything that touches the network or the database.
• Ignoring allSettled failures. It never rejects, so errors vanish unless you check status and log reason.
• Promise.race([]) hangs forever. If the list can be empty, guard it.
• Timeouts that leak timers. Always clear the timer in finally.
• Treating HTTP errors as success. fetch resolves on 4xx and 5xx. Check res.ok before handing the promise to any or all.
• Sequential await in a loop when work is independent. for (const id of ids) await load(id) takes the sum of all latencies. That is fine when order or rate matters, but it is a common accidental slowdown.

When to Use Which, and When Not To

• Promise.all: a fixed, small set of required results, where any failure invalidates the whole. Not for large or user-controlled lists without a concurrency limit.
• Promise.allSettled: independent tasks where partial success is acceptable and you will report failures individually. Not when one failure should stop the rest quickly; it always waits for the slowest.
• Promise.race: timeouts and "whichever settles first" signals, such as racing work against a shutdown signal. Not for picking the fastest successful source, because a fast failure wins.
• Promise.any: redundant, idempotent reads where any success is good enough. Not for writes, and not when the extra load on the backends is a problem.
• A concurrency limiter: any batch job over many items. Pair it with all-style or allSettled-style error handling depending on whether one failure should stop the batch.

The combinators answer "how do I wait?". Concurrency limits and cancellation answer "how much do I start?" and "how do I stop?". Production code usually needs all three.

The work itself is fine. It is a sequence of steps, each one taking the same piece of data, doing one thing to it, and passing it on. Laravel already has a tool built for exactly that shape, and you use it on every request without noticing: the pipeline that runs your middleware. It is available to your own code through the Pipeline facade.

How the Pipeline Works

A pipeline takes a "passable" (any value: a DTO, a query builder, a string) and sends it through a list of pipes. Each pipe receives the passable and a $next closure. It can modify the passable, call $next($passable) to continue, do work after $next returns, or stop the chain by returning or throwing without calling $next. That is exactly the middleware contract.

Pipeline::send($passable)   the value travelling through
    ->through([...pipes])   classes, class strings or closures
    ->via('handle')         method to call on class pipes (default: handle)
    ->then($destination)    final closure, receives the processed value
    ->thenReturn()          shortcut: return the processed value as is

Internally Laravel builds an onion: it wraps the destination closure in the last pipe, wraps that in the previous pipe, and so on with array_reduce, then calls the outermost one. Class-string pipes are resolved from the container at call time, so their constructors can type-hint any dependency.

Designing the Passenger Object

Before writing pipes, decide what travels through them. Passing the raw Request or a loose array works for a demo but makes every pipe guess at keys. A small mutable DTO, the "passenger", gives each step a typed place to read inputs and write results:

namespace App\Checkout;

use App\Models\Cart;
use App\Models\Coupon;
use App\Models\Order;
use App\Models\User;

final class CheckoutData
{
    public int $subtotal = 0;
    public int $discount = 0;
    public int $tax = 0;
    public ?Coupon $coupon = null;
    public ?Order $order = null;
    public ?string $paymentReference = null;

    public function __construct(
        public readonly User $user,
        public readonly Cart $cart,
        public readonly ?string $couponCode = null,
    ) {}

    public function total(): int
    {
        return max(0, $this->subtotal - $this->discount) + $this->tax;
    }
}

Inputs are readonly because no pipe should change who is checking out or which cart is being bought. Outputs are plain public properties that pipes fill in order. Money is stored as integer minor units (for VND that is simply the amount) so there is no float rounding.

Pipes as Classes

Each step becomes a class with one handle method. Here is the coupon step:

namespace App\Checkout\Pipes;

use App\Checkout\CheckoutData;
use App\Checkout\CheckoutFailed;
use App\Models\Coupon;
use Closure;

final class ApplyCoupon
{
    public function handle(CheckoutData $data, Closure $next): mixed
    {
        if ($data->couponCode === null) {
            return $next($data);
        }

        $coupon = Coupon::query()
            ->where('code', $data->couponCode)
            ->where('expires_at', '>', now())
            ->first();

        if ($coupon === null) {
            throw CheckoutFailed::because('Coupon is invalid or expired.');
        }

        $data->coupon = $coupon;
        $data->discount = min($data->subtotal, $coupon->amountOff($data->subtotal));

        return $next($data);
    }
}

Read it top to bottom and you know everything the step does. It does not know about tax, payment or the HTTP request. It has one reason to change. The early return $next($data) for "no coupon" is the pattern you will use most often: a pipe that does not apply simply passes the data along.

Throwing is how a pipe aborts the whole flow. Because the next pipes are only called through $next, an exception in ApplyCoupon means CreateOrder and ChargePayment never run.

Building the Checkout Pipeline

The action that ties it together is now short enough to fit on one screen, and the order of steps reads like the business process:

namespace App\Checkout;

use App\Checkout\Pipes\ApplyCoupon;
use App\Checkout\Pipes\CalculateSubtotal;
use App\Checkout\Pipes\CalculateTax;
use App\Checkout\Pipes\ChargePayment;
use App\Checkout\Pipes\CreateOrder;
use App\Checkout\Pipes\EnsureItemsInStock;
use App\Checkout\Pipes\ReserveInventory;
use App\Models\Order;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Pipeline;

final class PlaceOrder
{
    /** @var list<class-string> */
    private array $pipes = [
        EnsureItemsInStock::class,
        CalculateSubtotal::class,
        ApplyCoupon::class,
        CalculateTax::class,
        CreateOrder::class,
        ReserveInventory::class,
        ChargePayment::class,
    ];

    public function __invoke(CheckoutData $data): Order
    {
        return DB::transaction(fn () => Pipeline::send($data)
            ->through($this->pipes)
            ->then(fn (CheckoutData $data): Order => $data->order));
    }
}

Wrapping the pipeline in DB::transaction means any exception rolls back the order row and the inventory reservation together. Keep in mind that the payment call is a side effect outside the database: if ChargePayment succeeds and the commit fails afterwards, you have charged a customer for an order that does not exist. Put the charge last, keep it idempotent with a reference you store on the order, and consider the transactional outbox pattern for anything that must happen exactly once after commit.

Because a pipe controls when $next runs, you can also write steps that wrap the rest of the chain, just like middleware measures response time:

namespace App\Checkout\Pipes;

use App\Checkout\CheckoutData;
use Closure;
use Illuminate\Support\Facades\Log;

final class LogCheckoutDuration
{
    public function handle(CheckoutData $data, Closure $next): mixed
    {
        $startedAt = hrtime(true);

        $result = $next($data);

        Log::info('checkout.completed', [
            'user_id' => $data->user->id,
            'total' => $data->total(),
            'ms' => (hrtime(true) - $startedAt) / 1e6,
        ]);

        return $result;
    }
}

Put it first in the list and it measures everything after it. Adding cross-cutting behaviour like this no longer means editing the business steps.

Pipelines for Query Filters

The second classic use is filtering a listing endpoint. The passable is an Eloquent Builder, and each filter adds its own where clause only when its query string parameter is present:

namespace App\Http\Controllers;

use App\Models\Product;
use App\QueryFilters\Category;
use App\QueryFilters\InStock;
use App\QueryFilters\PriceRange;
use App\QueryFilters\Search;
use App\QueryFilters\Sort;
use Illuminate\Contracts\Pagination\CursorPaginator;
use Illuminate\Support\Facades\Pipeline;

final class ProductIndexController
{
    public function __invoke(): CursorPaginator
    {
        return Pipeline::send(Product::query()->where('is_active', true))
            ->through([
                Search::class,
                Category::class,
                PriceRange::class,
                InStock::class,
                Sort::class,
            ])
            ->thenReturn()
            ->cursorPaginate(24)
            ->withQueryString();
    }
}

namespace App\QueryFilters;

use Closure;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Http\Request;

final class PriceRange
{
    public function __construct(private Request $request) {}

    public function handle(Builder $query, Closure $next): mixed
    {
        $min = $this->request->integer('min_price');
        $max = $this->request->integer('max_price');

        if ($min > 0) {
            $query->where('price', '>=', $min);
        }

        if ($max > 0) {
            $query->where('price', '<=', $max);
        }

        return $next($query);
    }
}

Each filter is resolved from the container, so Request is injected through the constructor. Adding a new filter is one class and one line in the array, with no changes to the controller logic. thenReturn() hands back the builder, and you paginate as usual.

Two more features are worth knowing. A class string can carry parameters after a colon, which arrive as extra string arguments to handle (exactly like throttle:60,1 in middleware). And closures can be mixed with classes for tiny one-off steps. via() changes the method name if your pipes use something other than handle:

use App\Checkout\Pipes\EnsureMinimumTotal;
use Illuminate\Support\Facades\Pipeline;

$result = Pipeline::send($data)
    ->through([
        EnsureMinimumTotal::class . ':50000,VND',
        fn ($data, $next) => $next($data),
    ])
    ->via('process')
    ->thenReturn();

Testing Pipes and Pipelines

Because each pipe is a class with one method and an explicit $next, unit tests do not need the HTTP layer. Call handle directly and pass a closure as $next that records whether it was called:

use App\Checkout\CheckoutData;
use App\Checkout\CheckoutFailed;
use App\Checkout\Pipes\ApplyCoupon;
use App\Models\Cart;
use App\Models\Coupon;
use App\Models\User;

function checkoutData(?string $code, int $subtotal): CheckoutData
{
    $data = new CheckoutData(User::factory()->make(), Cart::factory()->make(), $code);
    $data->subtotal = $subtotal;

    return $data;
}

it('applies a valid coupon and passes the data on', function () {
    Coupon::factory()->create(['code' => 'TET2027', 'amount' => 50_000, 'expires_at' => now()->addDay()]);
    $called = false;

    $result = (new ApplyCoupon())->handle(checkoutData('TET2027', 300_000), function ($data) use (&$called) {
        $called = true;

        return $data;
    });

    expect($called)->toBeTrue()
        ->and($result->discount)->toBe(50_000)
        ->and($result->total())->toBe(250_000);
});

it('stops the pipeline when the coupon is expired', function () {
    Coupon::factory()->create(['code' => 'OLD', 'expires_at' => now()->subDay()]);

    (new ApplyCoupon())->handle(checkoutData('OLD', 300_000), fn () => throw new LogicException('next must not run'));
})->throws(CheckoutFailed::class);

it('skips silently when no coupon code is given', function () {
    $result = (new ApplyCoupon())->handle(checkoutData(null, 120_000), fn ($data) => $data);

    expect($result->discount)->toBe(0);
});

Three cases cover most pipes: it transforms the data and calls $next, it aborts without calling $next, and it passes through untouched when it does not apply. Make the "abort" test's $next throw, so a pipe that forgets to stop is caught loudly.

Then one or two tests at the pipeline level check the order and the contract between steps. Because class pipes are resolved from the container, you can swap one for a mock:

use App\Checkout\Pipes\ChargePayment;
use App\Checkout\PlaceOrder;

it('never charges the card when an earlier pipe fails', function () {
    $this->mock(ChargePayment::class)->shouldNotReceive('handle');

    $data = checkoutData('DOES-NOT-EXIST', 300_000);

    expect(fn () => app(PlaceOrder::class)($data))->toThrow(App\Checkout\CheckoutFailed::class);
    $this->assertDatabaseCount('orders', 0);
});

That test protects the most expensive mistake in a checkout flow: charging money when the order should have been rejected.

Common Pitfalls

• Forgetting to return $next($data). Calling $next($data); without return drops the result, and then receives null. Static analysis catches this if handle declares a return type.
• Hidden ordering dependencies. CalculateTax needs subtotal and discount, so it must come after ApplyCoupon. Document these in the passenger class, or assert preconditions at the top of the pipe and throw early.
• Passing the Request around. If pipes read from the request directly, they cannot be reused from a queued job or an Artisan command. Copy the inputs into the passenger once at the boundary.
• Using a pipeline for two steps. Pipeline::send()->through([A::class, B::class]) for a two-line function is indirection without benefit. A plain method call is clearer.
• Swallowing exceptions in a wrapping pipe. A logging or timing pipe that catches Throwable and returns something else turns a failed payment into a "successful" checkout. Rethrow.
• Side effects that cannot be rolled back. Database work inside the transaction is safe; emails, webhooks and payments are not. Dispatch those after commit (ShouldQueueAfterCommit, DB::afterCommit(), or an outbox).

When to Use a Pipeline and When Not To

A pipeline fits well when:

• a process is a linear sequence of steps over the same data: checkout, user onboarding, import row processing, document publishing;
• steps are optional or configurable: build the pipe list from feature flags, tenant settings or the order type;
• you want filters on a listing where each parameter maps to one query clause;
• you need around behaviour (timing, logging, locking) without touching each step.

Reach for something else when:

• the flow branches heavily ("if B2B then this five-step path, else that one"): a state machine or separate actions per path are easier to follow;
• steps need to run in parallel or survive restarts: use queued jobs with Bus::chain() or Bus::batch(), which add retries and persistence that an in-memory pipeline does not have;
• there are only one or two steps: just call them.

Back to that 340-line controller: after the refactor it validates the request, builds a CheckoutData, calls PlaceOrder, and returns a resource. Each business rule lives in a class you can test in isolation, and the next "gift wrap" request is a new pipe and one line in the list.

Almost every serious provider (Stripe, GitHub, Shopify, Svix-based services, Paddle) solves this the same way: they sign each request with HMAC using a secret only you and they know. Verifying that signature correctly takes about 40 lines, but there are four details that people get wrong over and over: the raw body, timing-safe comparison, the timestamp window, and replay protection.

How an HMAC Webhook Signature Works

HMAC-SHA256 takes a secret key and a message and produces a 32-byte tag. Without the key you cannot produce a valid tag for a modified message, and you cannot recover the key from tags you have seen. The provider computes the tag over the exact bytes it sends and puts it in a header. You recompute it over the exact bytes you received and compare.

A typical scheme looks like this (the header names vary by provider; the structure is nearly identical):

Webhook-Id: evt_01JC8Z4K
Webhook-Signature: t=1761900000,v1=<64 lowercase hex chars>

signed string = "1761900000" + "." + <exact raw request body bytes>
v1            = hex( HMAC-SHA256( secret, signed string ) )

Two things make this scheme stronger than "HMAC the body". The timestamp is part of the signed string, so an attacker cannot take an old captured request and change its timestamp. And the header can carry several v1 values, which lets the provider sign with both the old and new secret during a secret rotation.

The Verification Flow

The order matters. Cheap checks first (timestamp), then the cryptographic check, then the stateful replay check. Only a request that passed all three reaches your controller. Note what is not in the list: parsing JSON. You verify bytes, and only then trust and decode them.

Laravel Middleware Implementation

Put the verification in middleware so every webhook route gets the same guarantees and controllers stay focused on business logic. The provider name is a middleware parameter, so one class serves every integration.

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Cache;
use Symfony\Component\HttpFoundation\Response;

final class VerifyWebhookSignature
{
    private const TOLERANCE_SECONDS = 300;

    public function handle(Request $request, Closure $next, string $provider): Response
    {
        $secrets = (array) config("services.{$provider}.webhook_secrets", []);
        $header = (string) $request->header('Webhook-Signature', '');
        $parts = $this->parseHeader($header);
        $timestamp = (int) ($parts['t'][0] ?? 0);

        abort_if(abs(now()->getTimestamp() - $timestamp) > self::TOLERANCE_SECONDS, 401, 'Stale timestamp.');

        // getContent() is the raw body. Never rebuild it from $request->all().
        $payload = $request->getContent();

        abort_unless($this->matchesAny($secrets, "{$timestamp}.{$payload}", $parts['v1'] ?? []), 401, 'Bad signature.');

        $key = "webhook:{$provider}:".$request->header('Webhook-Id', hash('sha256', $header));

        if (! Cache::add($key, true, self::TOLERANCE_SECONDS * 2)) {
            return response()->noContent(); // replay or duplicate delivery: ack, do nothing
        }

        $response = $next($request);

        if (! $response->isSuccessful()) {
            Cache::forget($key); // let the provider's retry through
        }

        return $response;
    }

    /** @return array<string, list<string>> */
    private function parseHeader(string $header): array
    {
        $parts = [];

        foreach (explode(',', $header) as $item) {
            [$key, $value] = array_pad(explode('=', trim($item), 2), 2, '');
            $parts[$key][] = $value;
        }

        return $parts;
    }

    /** @param list<string> $signatures */
    private function matchesAny(array $secrets, string $signed, array $signatures): bool
    {
        foreach ($secrets as $secret) {
            $expected = hash_hmac('sha256', $signed, $secret);

            foreach ($signatures as $signature) {
                if (hash_equals($expected, $signature)) {
                    return true;
                }
            }
        }

        return false;
    }
}

A few deliberate choices in there:

• $request->getContent() returns the body exactly as received. json_encode($request->all()) would not: key order, whitespace, slash escaping and Unicode escaping can all differ, and the signature will fail randomly for some payloads.
• hash_equals() compares in constant time. A plain === returns as soon as the first byte differs, which in principle leaks how many leading characters an attacker got right. Over a network the signal is noisy, but it is free to avoid, so avoid it.
• Secrets come from config('services.billing.webhook_secrets'), an array. During rotation, set it to array_filter([env('BILLING_WEBHOOK_SECRET'), env('BILLING_WEBHOOK_SECRET_PREVIOUS')]) and drop the old one when the provider confirms the switch.
• Replay protection uses Cache::add(), which only writes if the key does not exist and is atomic on Redis, Memcached and the database store. The TTL just needs to outlive the timestamp window: after 5 minutes the timestamp check rejects the request anyway.
• If the controller fails, the key is removed so the provider's retry is processed instead of silently swallowed.

Register the alias and attach it to the route:

// bootstrap/app.php
use App\Http\Middleware\VerifyWebhookSignature;
use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Exceptions;
use Illuminate\Foundation\Configuration\Middleware;

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        api: __DIR__.'/../routes/api.php',
    )
    ->withMiddleware(function (Middleware $middleware): void {
        $middleware->alias(['webhook.signed' => VerifyWebhookSignature::class]);
    })
    ->withExceptions(function (Exceptions $exceptions): void {
        //
    })
    ->create();

// routes/api.php
use App\Http\Controllers\BillingWebhookController;
use Illuminate\Support\Facades\Route;

Route::post('/webhooks/billing', BillingWebhookController::class)
    ->middleware('webhook.signed:billing');

Routes in routes/api.php do not run CSRF verification. If you put webhook routes in web.php, you must exclude them with $middleware->validateCsrfTokens(except: ['webhooks/*']), otherwise every delivery gets a 419.

The Same Check in Node.js and Python

In Express, the classic bug is a global app.use(express.json()) that consumes and parses the body before your route sees it. Use express.raw() on the webhook route so req.body stays a Buffer.

const crypto = require('node:crypto');
const express = require('express');

const app = express();

function safeEqualHex(a, b) {
  const left = Buffer.from(a, 'hex');
  const right = Buffer.from(b, 'hex');
  // timingSafeEqual throws on different lengths, so check first
  return left.length === right.length && crypto.timingSafeEqual(left, right);
}

// express.raw keeps req.body as a Buffer; register it BEFORE any global express.json()
app.post('/webhooks/billing', express.raw({ type: 'application/json' }), (req, res) => {
  const parts = Object.fromEntries(
    (req.get('Webhook-Signature') ?? '').split(',').map((p) => p.trim().split('=', 2)),
  );
  const ts = Number(parts.t);

  if (!Number.isInteger(ts) || Math.abs(Date.now() / 1000 - ts) > 300) {
    return res.sendStatus(401);
  }

  const expected = crypto
    .createHmac('sha256', process.env.BILLING_WEBHOOK_SECRET)
    .update(`${ts}.`)
    .update(req.body)
    .digest('hex');

  if (!safeEqualHex(expected, parts.v1 ?? '')) {
    return res.sendStatus(401);
  }

  const event = JSON.parse(req.body.toString('utf8'));
  // enqueue event.id + payload, then answer quickly
  res.sendStatus(200);
});

crypto.timingSafeEqual() throws a RangeError when the buffers have different lengths, which an attacker can trigger with a short signature. Check the length first and treat a mismatch as invalid. In Python, hmac.compare_digest() handles different lengths for you:

import hashlib
import hmac
import time


def verify_webhook(secret: str, header: str, body: bytes, tolerance: int = 300) -> bool:
    parts: dict[str, list[str]] = {}
    for item in header.split(","):
        key, _, value = item.strip().partition("=")
        parts.setdefault(key, []).append(value)

    raw_ts = parts.get("t", [""])[0]
    if not raw_ts.isdigit() or abs(time.time() - int(raw_ts)) > tolerance:
        return False

    expected = hmac.new(secret.encode(), raw_ts.encode() + b"." + body, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(expected, sig) for sig in parts.get("v1", []))

In Django or Flask, use request.body / request.get_data(), which are bytes, never the parsed JSON.

Testing the Middleware

The tests that matter are the negative ones: a valid request is easy to get right by accident, a rejected forgery is what you are actually buying. With Pest you can register a throwaway route in the test and drive it with raw content:

use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Facades\Route;

beforeEach(function () {
    config(['services.billing.webhook_secrets' => ['whsec_test']]);

    Route::post('/_test/webhook', function () {
        Cache::increment('handled');

        return response()->noContent();
    })->middleware('webhook.signed:billing');
});

function sendWebhook(string $body, int $timestamp, string $secret = 'whsec_test'): Illuminate\Testing\TestResponse
{
    $signature = hash_hmac('sha256', "{$timestamp}.{$body}", $secret);

    return test()->call('POST', '/_test/webhook', [], [], [], [
        'HTTP_WEBHOOK_SIGNATURE' => "t={$timestamp},v1={$signature}",
        'HTTP_WEBHOOK_ID' => 'evt_1',
        'CONTENT_TYPE' => 'application/json',
    ], $body);
}

it('accepts a correctly signed payload once', function () {
    $body = '{"id":"evt_1","type":"invoice.paid"}';

    sendWebhook($body, now()->getTimestamp())->assertNoContent();
    sendWebhook($body, now()->getTimestamp())->assertNoContent(); // replay

    expect(Cache::get('handled'))->toBe(1);
});

it('rejects a tampered body', function () {
    $signature = hash_hmac('sha256', now()->getTimestamp().'.{"amount":100}', 'whsec_test');

    test()->call('POST', '/_test/webhook', [], [], [], [
        'HTTP_WEBHOOK_SIGNATURE' => 't='.now()->getTimestamp().",v1={$signature}",
    ], '{"amount":1000000}')->assertUnauthorized();
});

it('rejects stale timestamps and wrong secrets', function () {
    sendWebhook('{}', now()->subMinutes(6)->getTimestamp())->assertUnauthorized();
    sendWebhook('{}', now()->getTimestamp(), 'whsec_wrong')->assertUnauthorized();

    expect(Cache::get('handled'))->toBeNull();
});

Laravel's test clock helpers ($this->travel() / travelTo()) work here because the middleware uses now() instead of time(). If you switch to a real Redis cache in tests, flush the replay keys between tests or each test will look like a replay of the previous one.

Common Pitfalls

• Verifying re-encoded JSON. Always hash the raw bytes. This is the number one cause of "signature works in tests, fails for some production events".
• Comparing with ==. Besides the timing leak, PHP's loose comparison treats "0e1234..." hex strings as equal numbers. Use hash_equals().
• No timestamp check. A valid request captured from a log or a proxy can be replayed forever. GitHub-style signatures (X-Hub-Signature-256: sha256=...) do not sign a timestamp, so for those, deduplicate on the delivery id header instead.
• Too tight a window. Clock skew and provider retries exist. Five minutes is the common default; do not go below one minute.
• Doing slow work before responding. Providers time out after a few seconds and retry, so you get duplicates. Verify, store or queue the event, return 2xx, and process it in a job.
• Trusting fields that are not signed. Headers such as Webhook-Id are only safe to use for dedup if the provider includes them in the signed string or you dedup on the event id inside the verified body.
• Leaking the secret. Do not log full headers, do not commit .env, and keep a separate secret per environment and per tenant so staging leaks cannot forge production events.

When to Use This (and When Not To)

Use HMAC verification for any inbound webhook from a provider that supports it, and for webhooks you send to your own customers: sign outgoing requests the same way so they can verify you.

HMAC is not the right tool when:

• The sender cannot keep a secret. Browsers and mobile apps cannot hold an HMAC key; anyone can extract it. Authenticate users instead.
• Many independent receivers must verify the same message. A shared secret means every receiver can also forge messages. Use asymmetric signatures (Ed25519, or the RS256/ES256 used in JWTs) so only the sender holds the private key.
• You need confidentiality. HMAC proves who sent the bytes and that they were not changed. It does not hide them. The transport still needs TLS.

As a final layer, some providers publish their source IP ranges. An IP allowlist is a nice extra, but it is not a replacement: IP ranges change, and the signature is what actually proves authenticity.

A transaction gives you atomicity: all of it commits or none of it does. It does not, on its own, make concurrent transactions behave as if they ran one after another. How much they can see of each other is controlled by the isolation level, and MySQL and PostgreSQL ship with different defaults and different behaviour under the same names. Here is what each level really guarantees and how to pick one in Laravel.

The Bug in Slow Motion

This is a lost update. Nothing in it is exotic:

-- Session A                                  -- Session B
BEGIN;                                        BEGIN;
SELECT stock FROM products WHERE id = 7;      SELECT stock FROM products WHERE id = 7;
-- app sees 5, computes 5 - 1 = 4             -- app sees 5, computes 5 - 1 = 4
UPDATE products SET stock = 4 WHERE id = 7;
COMMIT;
                                              UPDATE products SET stock = 4 WHERE id = 7;
                                              COMMIT;
-- Two units sold, stock went from 5 to 4.

Under MySQL's default REPEATABLE READ and PostgreSQL's default READ COMMITTED, this interleaving commits happily. PostgreSQL REPEATABLE READ would reject session B's update with could not serialize access due to concurrent update. MySQL REPEATABLE READ would not, because InnoDB's UPDATE reads the latest committed row (a "current read"), not the transaction's snapshot. Same name, different outcome.

The Read Anomalies

The SQL standard defines isolation levels by which anomalies they forbid:

• Dirty read: you see data another transaction has not committed and may roll back.
• Non-repeatable read: you read the same row twice and get different values because someone committed in between.
• Phantom read: you run the same range query twice and new rows appear (or vanish) because someone inserted or deleted matching rows.

The standard says what must not happen. Engines are free to forbid more, and both of the big ones do.

MySQL InnoDB vs PostgreSQL

MySQL InnoDB, default REPEATABLE READ. Plain SELECTs are consistent reads from a snapshot taken at the first read of the transaction, so they see neither non-repeatable reads nor phantoms. Locking reads (SELECT ... FOR UPDATE, FOR SHARE) and UPDATE/DELETE work on the latest committed rows and take next-key locks (row plus gap) on the scanned index range, which blocks phantoms for writes but also blocks inserts into those gaps, a common source of deadlocks. READ UNCOMMITTED really does allow dirty reads. SERIALIZABLE turns plain SELECT into SELECT ... FOR SHARE when autocommit is off, so it is lock based and prone to lock waits.

PostgreSQL, default READ COMMITTED. Each statement sees a fresh snapshot of committed data. READ UNCOMMITTED is accepted but behaves exactly like READ COMMITTED; Postgres never shows dirty data. REPEATABLE READ is snapshot isolation: one snapshot for the whole transaction, no phantoms, and if you try to update a row that someone else changed after your snapshot, you get SQLSTATE 40001 and must retry. SERIALIZABLE adds Serializable Snapshot Isolation (SSI): it tracks read/write dependencies and aborts one transaction when the combination could not have happened serially. It uses no extra blocking locks for reads, but you must be ready to retry.

Snapshot isolation in both engines still allows write skew: two transactions read the same facts, each writes a different row, and together they break an invariant.

-- Rule: at least one doctor must stay on call for shift 42.
-- Both transactions run under REPEATABLE READ (snapshot isolation).

-- A: SELECT COUNT(*) FROM on_call WHERE shift_id = 42;   -> 2, ok to leave
-- B: SELECT COUNT(*) FROM on_call WHERE shift_id = 42;   -> 2, ok to leave
-- A: DELETE FROM on_call WHERE shift_id = 42 AND doctor_id = 1; COMMIT;
-- B: DELETE FROM on_call WHERE shift_id = 42 AND doctor_id = 2; COMMIT;
-- Result: nobody on call. Different rows were written, so no write conflict.
-- PostgreSQL SERIALIZABLE detects this and aborts one of them with SQLSTATE 40001.

Only PostgreSQL SERIALIZABLE (or explicit locking) prevents that.

Setting the level is also slightly different:

-- MySQL: applies to the NEXT transaction in this session only
SET TRANSACTION ISOLATION LEVEL READ COMMITTED;
START TRANSACTION;
-- ...
COMMIT;

-- PostgreSQL: must be the first statement inside the transaction
BEGIN;
SET TRANSACTION ISOLATION LEVEL SERIALIZABLE;
-- ...
COMMIT;

-- Check the current level
SELECT @@transaction_isolation;        -- MySQL
SHOW transaction_isolation;            -- PostgreSQL

Choosing a Level

The isolation level is a blunt instrument. Most correctness bugs have a sharper fix, and the decision usually goes like this:

• Single-row read-modify-write (stock, balances, counters): do the math in SQL with an atomic UPDATE ... SET stock = stock - 1 WHERE stock >= 1, or lock the row with lockForUpdate(). Works at any level, on both engines.
• Reports and multi-query reads that must be internally consistent (totals matching line items): REPEATABLE READ gives one snapshot for the whole transaction. MySQL already does this by default; on PostgreSQL ask for it.
• Invariants spanning rows you cannot easily lock (on-call rules, booking overlaps, "max 3 active sessions"): PostgreSQL SERIALIZABLE with retries, or a lock on a parent row (lock the shift, then touch on_call).
• High-throughput OLTP on MySQL: many teams switch the session default to READ COMMITTED to reduce gap locks and deadlocks, then rely on explicit locks where needed.

Implementation in Laravel

Make the level explicit and type-safe with a backed enum, so nobody can pass arbitrary SQL into a SET statement:

namespace App\Database;

enum IsolationLevel: string
{
    case ReadCommitted = 'READ COMMITTED';
    case RepeatableRead = 'REPEATABLE READ';
    case Serializable = 'SERIALIZABLE';
}

Laravel's DB::transaction($callback, $attempts) already retries when it detects a concurrency error (deadlocks, lock wait timeouts, SQLSTATE 40001). What it does not do is set the isolation level for you. The helper below wraps that, and handles the driver difference: PostgreSQL needs SET TRANSACTION as the first statement inside the transaction, MySQL needs it right before BEGIN, and since it only applies to the next transaction it has to be reissued on every retry.

namespace App\Database;

use Closure;
use Illuminate\Database\ConnectionInterface;
use Illuminate\Database\QueryException;
use Illuminate\Support\Facades\DB;
use Throwable;

final class Isolated
{
    /** SQLSTATEs that mean "safe to retry the whole transaction". */
    private const RETRYABLE = ['40001', '40P01'];

    /** @param Closure(ConnectionInterface): mixed $callback */
    public static function run(
        IsolationLevel $level,
        Closure $callback,
        int $attempts = 3,
        ?string $connection = null,
    ): mixed {
        $db = DB::connection($connection);

        for ($attempt = 1; ; $attempt++) {
            try {
                if ($db->getDriverName() === 'pgsql') {
                    return $db->transaction(function () use ($db, $level, $callback) {
                        // Must be the first statement of the transaction in PostgreSQL.
                        $db->statement('SET TRANSACTION ISOLATION LEVEL ' . $level->value);

                        return $callback($db);
                    });
                }

                // MySQL / MariaDB: SET TRANSACTION affects the next transaction only,
                // so it has to be issued before BEGIN, on every attempt.
                $db->statement('SET TRANSACTION ISOLATION LEVEL ' . $level->value);

                return $db->transaction(fn () => $callback($db));
            } catch (QueryException $e) {
                if ($attempt >= $attempts || ! self::isRetryable($e)) {
                    throw $e;
                }
                usleep(random_int(5_000, 20_000) * $attempt);
            }
        }
    }

    public static function isRetryable(Throwable $e): bool
    {
        $state = $e instanceof QueryException ? ($e->errorInfo[0] ?? $e->getCode()) : $e->getCode();

        return in_array((string) $state, self::RETRYABLE, true);
    }
}

Then use the cheapest tool that is correct for each case:

namespace App\Actions;

use App\Database\Isolated;
use App\Database\IsolationLevel;
use App\Models\OnCall;
use App\Models\Product;
use DomainException;
use Illuminate\Support\Facades\DB;

final class InventoryActions
{
    /** Atomic decrement: no isolation tricks needed, the row lock does the work. */
    public function sell(int $productId, int $qty): void
    {
        $affected = Product::query()
            ->whereKey($productId)
            ->where('stock', '>=', $qty)
            ->decrement('stock', $qty);

        if ($affected === 0) {
            throw new DomainException('Out of stock');
        }
    }

    /** Invariant across several rows: let SERIALIZABLE catch write skew, then retry. */
    public function leaveShift(int $shiftId, int $doctorId): void
    {
        Isolated::run(IsolationLevel::Serializable, function () use ($shiftId, $doctorId) {
            $count = OnCall::query()->where('shift_id', $shiftId)->count();

            if ($count <= 1) {
                throw new DomainException('Someone has to stay on call');
            }

            OnCall::query()
                ->where('shift_id', $shiftId)
                ->where('doctor_id', $doctorId)
                ->delete();
        }, attempts: 5);
    }
}

Testing Isolation Behaviour

Isolation is about concurrency, so a meaningful test needs two real connections to a real database. Clone the connection config under a second name, open a transaction on one, commit a change through the other, and assert what the first one sees. Do not use RefreshDatabase here: it wraps the test in a transaction on the default connection, which hides exactly the behaviour you want to observe.

// tests/Feature/IsolationLevelTest.php  (runs against a real PostgreSQL database)
use Illuminate\Database\QueryException;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Schema;

beforeEach(function () {
    config(['database.connections.pgsql_b' => config('database.connections.pgsql')]);
    Schema::connection('pgsql')->dropIfExists('iso_accounts');
    Schema::connection('pgsql')->create('iso_accounts', function ($table) {
        $table->id();
        $table->integer('balance');
    });
    DB::connection('pgsql')->table('iso_accounts')->insert(['id' => 1, 'balance' => 100]);
});

afterEach(function () {
    DB::purge('pgsql_b');
    Schema::connection('pgsql')->dropIfExists('iso_accounts');
});

function balance(string $connection): int
{
    return (int) DB::connection($connection)->table('iso_accounts')->where('id', 1)->value('balance');
}

it('sees a non-repeatable read under READ COMMITTED', function () {
    $a = DB::connection('pgsql');
    $a->beginTransaction();
    expect(balance('pgsql'))->toBe(100);

    DB::connection('pgsql_b')->table('iso_accounts')->where('id', 1)->update(['balance' => 50]);

    expect(balance('pgsql'))->toBe(50);
    $a->rollBack();
});

it('keeps a stable snapshot under REPEATABLE READ', function () {
    $a = DB::connection('pgsql');
    $a->beginTransaction();
    $a->statement('SET TRANSACTION ISOLATION LEVEL REPEATABLE READ');
    expect(balance('pgsql'))->toBe(100);

    DB::connection('pgsql_b')->table('iso_accounts')->where('id', 1)->update(['balance' => 50]);

    expect(balance('pgsql'))->toBe(100);

    expect(fn () => $a->table('iso_accounts')->where('id', 1)->update(['balance' => 90]))
        ->toThrow(QueryException::class, 'could not serialize access');
    $a->rollBack();
});

Common Pitfalls

• Thinking DB::transaction() prevents lost updates. It does not. Read-modify-write in PHP needs lockForUpdate() or an atomic SQL update.
• Assuming "REPEATABLE READ" means the same thing everywhere. MySQL's version lets UPDATE see newer data than your SELECT; PostgreSQL's version aborts with 40001.
• Using SERIALIZABLE without retries. Serialization failures are normal, not exceptional. No retry loop means random 500s under load.
• Side effects inside a retried transaction. A retry replays the closure. Charging a card or dispatching a job inside it can happen twice.
• Setting the level at the wrong time. In PostgreSQL, SET TRANSACTION after any query in the transaction fails. In MySQL, issuing it inside an active transaction fails; issuing it once and then retrying silently runs the retry at the session default.
• Long transactions under REPEATABLE READ. Old snapshots keep old row versions alive (InnoDB undo log, Postgres dead tuples), which bloats storage and slows vacuum and purge.
• Gap-lock deadlocks on MySQL. SELECT ... FOR UPDATE on a range in REPEATABLE READ locks gaps too. Lock by primary key where you can, keep a consistent lock order, and keep transactions short.

When to Use What, and When Not To

Use the defaults when your writes are single-row and expressed as atomic SQL, or protected by lockForUpdate(). That covers most CRUD apps.

Use REPEATABLE READ for multi-statement reads that must agree with each other, such as exports, invoices and reconciliation jobs, especially on PostgreSQL where it is not the default.

Use PostgreSQL SERIALIZABLE for business invariants across rows when locking is awkward, and only together with a retry loop and idempotent transaction bodies.

Do not raise the isolation level globally "to be safe". It increases aborts, lock waits and deadlocks across the whole app and still does not fix application-level read-modify-write on MySQL. Never use READ UNCOMMITTED for business logic.

The App Router gives you powerful caching, but it is explicit now. Since Next.js 15, fetch is not cached unless you ask, and Next.js 16 tightened the revalidation APIs (revalidateTag takes a profile, updateTag was added for Server Actions). This tip covers the model most production apps still run on: fetch caching, segment-level revalidate, ISR, and on-demand invalidation. Cache Components ('use cache', behind the cacheComponents flag) is a separate opt-in model and is mentioned only where it changes the advice.

The Layers, From Request to Origin

There are three server-side ideas to keep apart:

• Request memoization. Identical GET fetches during one render are executed once. It lasts for a single render pass and needs no configuration.
• Data Cache. The persistent cache for fetch results (and unstable_cache results). It survives across requests and deployments on platforms that persist it. You opt in with cache: 'force-cache' or next.revalidate.
• Full Route Cache. The rendered HTML and RSC payload of a static route. This is what ISR regenerates.

On top of that, the browser keeps a client-side router cache for navigations, which revalidatePath and updateTag also refresh when called from a Server Action.

Caching fetch and Tagging Data

Put data access in one module so every caller gets the same cache settings. Each fetch states its maximum age and the tags that can invalidate it:

// lib/products.ts
import 'server-only'

export type Product = { id: string; slug: string; name: string; price: number; stock: number }

const API = process.env.CATALOG_API_URL!

export async function getProduct(slug: string): Promise<Product | null> {
  const res = await fetch(`${API}/products/${slug}`, {
    next: {
      revalidate: 300, // at most 5 minutes old
      tags: ['products', `product:${slug}`],
    },
  })

  if (res.status === 404) return null
  if (!res.ok) throw new Error(`Catalog API failed: ${res.status}`)

  return res.json()
}

export async function getProductSlugs(): Promise<string[]> {
  const res = await fetch(`${API}/products?fields=slug&limit=500`, {
    cache: 'force-cache',
    next: { tags: ['products'] },
  })

  return (await res.json()).map((p: { slug: string }) => p.slug)
}

next.revalidate: 300 means the response may be up to five minutes old. After that, the next request still gets the cached value while Next.js refetches in the background: classic stale-while-revalidate. Tags are free-form strings; a broad tag (products) plus a precise one (product:${slug}) lets you invalidate one item or the whole catalog.

For data that does not come from fetch, such as an ORM call, wrap the function with unstable_cache. Despite the name, it is the documented way to cache non-fetch work in this model:

// lib/categories.ts
import 'server-only'
import { unstable_cache } from 'next/cache'
import { db } from '@/lib/db'

export const getCategoryTree = unstable_cache(
  async (locale: string) => db.category.findMany({ where: { locale }, orderBy: { position: 'asc' } }),
  ['category-tree'], // key prefix; the locale argument is part of the key too
  { revalidate: 3600, tags: ['categories'] },
)

ISR: Static Pages That Stay Fresh

Incremental Static Regeneration is just a static route with a revalidation time. Combine generateStaticParams to prebuild the hot pages, dynamicParams to render the long tail on first request, and a segment revalidate:

// app/products/[slug]/page.tsx
import { notFound } from 'next/navigation'
import { getProduct, getProductSlugs } from '@/lib/products'

// ISR: route default is one hour. getProduct() asks for 300 seconds, and the
// lowest value wins, so this route actually regenerates every 5 minutes at most.
export const revalidate = 3600

// Slugs not returned below are rendered on first request, then cached too.
export const dynamicParams = true

export async function generateStaticParams() {
  const slugs = await getProductSlugs()
  return slugs.slice(0, 100).map((slug) => ({ slug })) // prebuild the top 100 only
}

export default async function ProductPage({ params }: { params: Promise<{ slug: string }> }) {
  const { slug } = await params
  const product = await getProduct(slug)

  if (!product) notFound()

  return (
    <main>
      <h1>{product.name}</h1>
      <p>{product.price.toLocaleString('en-US')} USD</p>
      <p>{product.stock > 0 ? 'In stock' : 'Sold out'}</p>
    </main>
  )
}

Read the comment on revalidate twice. The lowest revalidation value among the route's layouts, page and fetches decides how often the route regenerates. A single fetch with revalidate: 300 silently turns your "hourly" page into a five-minute page. That is usually fine, but it should be a decision, not a surprise.

When a Route Becomes Dynamic

A route is rendered per request as soon as it uses a request-time API (cookies(), headers(), searchParams, connection()) or a fetch with cache: 'no-store'. That is exactly what you want for personal data:

// app/dashboard/page.tsx
import { cookies } from 'next/headers'

export default async function Dashboard() {
  // Reading cookies is a request-time API: this route now renders per request.
  const session = (await cookies()).get('session')?.value

  const orders = await fetch(`${process.env.ORDERS_API_URL}/me/orders`, {
    headers: { authorization: `Bearer ${session}` },
    cache: 'no-store', // per-user data: never put it in the shared cache
  }).then((r) => r.json())

  return <pre>{JSON.stringify(orders, null, 2)}</pre>
}

The rule that prevents the leak from the intro: never cache a response that depends on who is asking. force-cache caches requests even when they carry authorization or cookie headers, and the cache key is built from the URL, method, headers and body. Different tokens get different keys, so it will not mix users up by accident, but it will happily store personal data in a shared cache where it outlives the session. Use no-store for per-user data and keep cached data public.

You can also force the mode with export const dynamic = 'force-dynamic' or 'force-static'. Prefer letting the APIs you call decide; the forced modes are useful as guard rails (dynamic = 'error' fails the build if a route you expect to be static turns dynamic).

On-Demand Revalidation: updateTag, revalidateTag, revalidatePath

Time-based revalidation is a ceiling. When you know data changed, invalidate it. The three functions behave differently:

• updateTag(tag) works only in Server Actions. It expires the tagged entries immediately, so the user who just saved sees their own change on the next render. Use it after a mutation in your app.
• revalidateTag(tag, 'max') marks tagged data stale. The next visitor gets the old content while it regenerates. Use it from webhooks and Route Handlers where nobody is waiting to read their own write. Pass { expire: 0 } instead of 'max' if the data must be gone right away. The single-argument form is deprecated.
• revalidatePath(path) invalidates a specific route path. For a dynamic segment pattern, add the type: revalidatePath('/products/[slug]', 'page').

The admin action, which needs read-your-own-writes:

// app/admin/products/actions.ts
'use server'

import { revalidatePath, updateTag } from 'next/cache'
import { requireAdmin } from '@/lib/auth'
import { catalog } from '@/lib/catalog-client'

export async function updatePrice(slug: string, price: number) {
  await requireAdmin()
  await catalog.updatePrice(slug, price)

  // The admin who clicked Save must see the new price on the next render:
  // updateTag expires the entry immediately (read-your-own-writes).
  updateTag(`product:${slug}`)

  // The listing page has its own cached HTML; refresh that path too.
  revalidatePath('/products')
}

The CMS webhook, which only needs eventual freshness:

// app/api/revalidate/route.ts
import { revalidateTag } from 'next/cache'
import type { NextRequest } from 'next/server'

export async function POST(request: NextRequest) {
  if (request.headers.get('x-webhook-secret') !== process.env.CATALOG_WEBHOOK_SECRET) {
    return Response.json({ ok: false }, { status: 401 })
  }

  const { slug } = (await request.json()) as { slug?: string }
  if (!slug) return Response.json({ ok: false, error: 'slug required' }, { status: 400 })

  // Stale-while-revalidate: visitors keep getting the old page while it regenerates.
  revalidateTag(`product:${slug}`, 'max')

  return Response.json({ ok: true, revalidated: `product:${slug}` })
}

Testing Cache Invalidation

You cannot meaningfully unit-test Next.js's cache itself, but you can test the part that breaks in practice: whether your actions invalidate the right tags, in the right order, and only after a successful write. Mock next/cache with Vitest:

// app/admin/products/actions.test.ts
import { beforeEach, describe, expect, it, vi } from 'vitest'

vi.mock('next/cache', () => ({ updateTag: vi.fn(), revalidatePath: vi.fn(), revalidateTag: vi.fn() }))
vi.mock('@/lib/auth', () => ({ requireAdmin: vi.fn().mockResolvedValue({ id: 'u1' }) }))
vi.mock('@/lib/catalog-client', () => ({ catalog: { updatePrice: vi.fn().mockResolvedValue(undefined) } }))

import { revalidatePath, updateTag } from 'next/cache'
import { catalog } from '@/lib/catalog-client'
import { updatePrice } from './actions'

describe('updatePrice', () => {
  beforeEach(() => vi.clearAllMocks())

  it('writes first, then expires the product tag and the listing path', async () => {
    await updatePrice('blue-mug', 12)

    expect(catalog.updatePrice).toHaveBeenCalledWith('blue-mug', 12)
    expect(updateTag).toHaveBeenCalledWith('product:blue-mug')
    expect(revalidatePath).toHaveBeenCalledWith('/products')
  })

  it('does not touch the cache when the write fails', async () => {
    vi.mocked(catalog.updatePrice).mockRejectedValueOnce(new Error('API down'))

    await expect(updatePrice('blue-mug', 12)).rejects.toThrow('API down')
    expect(updateTag).not.toHaveBeenCalled()
  })
})

Then verify the build output and the response headers against a production build, because development mode always renders on demand:

next build
# The route table marks each route:
#   ○ Static   ● SSG (prerendered via generateStaticParams)   ƒ Dynamic
# If /products/[slug] shows ƒ, something in it reads cookies, headers or no-store data.

next start &
curl -sI http://localhost:3000/products/blue-mug | grep -i x-nextjs-cache
# x-nextjs-cache: HIT   (MISS on the first visit, STALE while regenerating)

Common Pitfalls

• Testing caching in next dev. Pages are always rendered on demand in development. Check behaviour with next build && next start.
• Expecting fetch to be cached by default. It is not since Next.js 15. Without force-cache or revalidate, a fetch is fetched at build time for a static route and on every request for a dynamic one.
• Revalidating a tag nobody set. revalidateTag('product-1') does nothing if the fetch used product:1. Build tag strings in one helper and reuse it on both sides.
• Conflicting fetch options. { cache: 'no-store', next: { revalidate: 60 } } is invalid; both are ignored with a warning in development.
• Calling revalidateTag in a Server Action and wondering why the admin sees old data. With 'max', the first read after invalidation is stale by design. Use updateTag there.
• Unprotected revalidation endpoints. Anyone who can hit /api/revalidate can force regeneration of your whole catalog. Check a secret or signature.

When to Use What, and When Not To

Use time-based revalidate for content where a few minutes of staleness is acceptable and you have no change events: exchange rates, public stats, third-party feeds.

Use ISR with tags for catalog, blog and docs pages: static speed, with webhooks for freshness.

Use updateTag in Server Actions when a user edits something and expects to see it immediately.

Use dynamic rendering for anything personal, permission-dependent or truly real-time. Do not try to cache your way around it with clever keys; the cost of a leak is far higher than the cost of a render.

If you are starting a new Next.js 16 app, look at Cache Components too: 'use cache' with cacheLife and cacheTag replaces most segment config, and dynamic / revalidate exports do not apply there. The invalidation ideas in this tip carry over unchanged.

Native enums landed in PHP 8.1 and they fix exactly this class of bug. Most teams adopt them halfway, though: they declare case Paid = 'paid' and keep the business rules in if statements spread around the codebase. This tip goes further: backed enums as the single source of truth, behaviour living on the enum, interfaces and constants, safe parsing with tryFrom(), Eloquent casts, and a migration path off magic strings that does not break production data.

Pure Enums vs Backed Enums

An enum is a closed set of named values. PHP gives you two flavours:

enum Suit { case Hearts; case Spades; } // pure: no scalar value

// backed: every case maps to a unique int or string you can persist
enum OrderStatus: string
{
    case Pending = 'pending';
    case Paid = 'paid';
    case Shipped = 'shipped';
    case Delivered = 'delivered';
    case Cancelled = 'cancelled';
}

echo OrderStatus::Paid->name;   // "Paid"  (the identifier in code)
echo OrderStatus::Paid->value;  // "paid"  (what goes into the database)

var_dump(OrderStatus::Paid === OrderStatus::from('paid')); // bool(true): cases are singletons

A pure enum has cases and nothing else. Use it for states that never leave the process: a parser mode, a UI variant, a strategy selector. A backed enum gives each case a scalar (int or string, nothing else) that must be unique and constant. That scalar is what you store in the database, put in JSON, and receive from forms.

A few facts worth knowing before you build on them:

• ->name is the identifier you wrote in code. ->value is the persisted value. Renaming a case is a refactor; changing a value is a data migration.
• Every case is a singleton object, so === works and is the comparison you want.
• Backed enums implement BackedEnum (which extends UnitEnum); pure enums implement only UnitEnum. You can type-hint against those interfaces in generic code.
• json_encode() turns a backed case into its value. A pure case cannot be serialised to JSON at all: with JSON_THROW_ON_ERROR you get a JsonException saying non-backed enums have no default serialization.

Prefer string backing: status = 3 in a support query tells nobody anything.

Put Behaviour on the Enum: Methods and match

The real payoff comes when the rules that belong to a status live next to it. Enums can have methods (instance and static), and match ($this) makes them compact:

enum OrderStatus: string
{
    case Pending = 'pending';
    case Paid = 'paid';
    case Shipped = 'shipped';
    case Delivered = 'delivered';
    case Cancelled = 'cancelled';

    public function label(): string
    {
        return match ($this) {
            self::Pending => 'Waiting for payment',
            self::Paid => 'Paid',
            self::Shipped => 'On the way',
            self::Delivered => 'Delivered',
            self::Cancelled => 'Cancelled',
        };
    }

    public function isFinal(): bool
    {
        return $this === self::Delivered || $this === self::Cancelled;
    }

    /** @return list<self> */
    public function allowedTransitions(): array
    {
        return match ($this) {
            self::Pending => [self::Paid, self::Cancelled],
            self::Paid => [self::Shipped, self::Cancelled],
            self::Shipped => [self::Delivered],
            self::Delivered, self::Cancelled => [],
        };
    }

    public function canTransitionTo(self $next): bool
    {
        return in_array($next, $this->allowedTransitions(), true);
    }
}

Two details make this robust. First, there is no default arm in the match expressions. If someone adds case Refunded = 'refunded' and forgets to handle it, PHP throws UnhandledMatchError the first time that path runs, and a test that loops over cases() catches it before production. A default arm would silently give refunded orders the wrong label.

Second, the transition table now has exactly one home. Controllers ask $order->status->canTransitionTo(OrderStatus::Shipped) instead of re-implementing in_array($order->status, ['paid']). When product changes the rules, you change one method and the tests that cover it.

What enums cannot do: hold state. An enum may not declare properties, not even static ones, and cases cannot be constructed with new.

Constants, Static Methods and Interfaces

Enums can implement interfaces, use traits (as long as the trait declares no properties), declare constants, and have static methods. That lets them plug into generic code:

interface HasLabel
{
    public function label(): string;
}

trait ListsValues
{
    /** @return list<string> */
    public static function values(): array
    {
        return array_column(self::cases(), 'value');
    }
}

enum PaymentMethod: string implements HasLabel
{
    use ListsValues;

    case Card = 'card';
    case BankTransfer = 'bank_transfer';
    case Wallet = 'wallet';

    public const DEFAULT = self::Card;
    public const DEFAULT_VALUE = self::Card->value; // allowed since PHP 8.2

    public function label(): string
    {
        return match ($this) {
            self::Card => 'Credit / debit card',
            self::BankTransfer => 'Bank transfer',
            self::Wallet => 'E-wallet',
        };
    }
}

echo implode(',', PaymentMethod::values()); // card,bank_transfer,wallet

HasLabel lets a form component render any labelled enum. The ListsValues trait removes a line you would otherwise copy into every enum. Constants are handy for defaults: PaymentMethod::DEFAULT is a real case, so it is type-safe everywhere it is used. Since PHP 8.2 you can also read ->value inside a constant expression, which is useful for attribute arguments and migration defaults.

from() vs tryFrom(): Parsing Untrusted Input

Backed enums come with two constructors for turning a scalar back into a case:

enum OrderStatus: string
{
    case Pending = 'pending';
    case Paid = 'paid';
    case Cancelled = 'cancelled';
}

// from(): use when an invalid value is a bug. Throws ValueError.
$status = OrderStatus::from('paid');

// tryFrom(): use at the boundary, where bad input is expected. Returns null.
function statusFromWebhook(array $payload): OrderStatus
{
    $raw = $payload['status'] ?? null;

    if (! is_string($raw)) {
        throw new InvalidArgumentException('Webhook payload has no status.');
    }

    // Normalise known aliases first.
    $normalised = match (strtolower(trim($raw))) {
        'canceled' => 'cancelled',
        default => strtolower(trim($raw)),
    };

    return OrderStatus::tryFrom($normalised)
        ?? throw new InvalidArgumentException("Unknown order status [{$raw}].");
}

echo statusFromWebhook(['status' => ' Canceled '])->name; // Cancelled

The rule of thumb:

• from() when an invalid value means a bug in your own system: a value you wrote yourself, a config key, a column you control. It throws ValueError, and you want it loud.
• tryFrom() at the edges: webhooks, CSV imports, query strings, anything a third party sends. It returns null, and the ?? throw idiom turns that into a domain-specific exception with a useful message.

Watch the types under declare(strict_types=1): an int-backed enum's from('1') throws a TypeError, not a ValueError, because the argument must be an int. Cast at the boundary ((int) $request->input('level')) after validating that it is numeric.

Eloquent Enum Casts in Laravel 13

Laravel casts a column straight to a backed enum. Reading gives you a case, writing accepts a case (or its value), and the query builder binds enum cases as their scalar value:

namespace App\Models;

use App\Enums\OrderStatus;
use App\Enums\PaymentMethod;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Casts\AsEnumCollection;
use Illuminate\Database\Eloquent\Model;

final class Order extends Model
{
    protected $fillable = ['status', 'payment_method', 'allowed_methods'];

    protected function casts(): array
    {
        return [
            'status' => OrderStatus::class,
            'payment_method' => PaymentMethod::class,
            'allowed_methods' => AsEnumCollection::of(PaymentMethod::class),
        ];
    }

    public function markAsPaid(): void
    {
        if (! $this->status->canTransitionTo(OrderStatus::Paid)) {
            throw new \DomainException("Cannot pay an order that is {$this->status->value}.");
        }

        $this->status = OrderStatus::Paid;
        $this->save();
    }

    public function scopeOpen(Builder $query): void
    {
        // The query builder binds BackedEnum cases as their ->value.
        $query->whereIn('status', [OrderStatus::Pending, OrderStatus::Paid, OrderStatus::Shipped]);
    }
}

AsEnumCollection::of() stores a JSON array of values and hydrates a collection of cases, which fits "allowed methods per merchant" style columns. For input, Rule::enum() validates against the cases, only() / except() narrow it, and $request->enum('status', OrderStatus::class) returns the case (or null):

namespace App\Http\Requests;

use App\Enums\OrderStatus;
use Illuminate\Foundation\Http\FormRequest;
use Illuminate\Validation\Rule;

final class UpdateOrderStatusRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            'status' => ['required', Rule::enum(OrderStatus::class)->only([OrderStatus::Shipped, OrderStatus::Cancelled])],
        ];
    }}

Route binding understands backed enums too: type-hint OrderStatus $status and /orders/status/bogus returns a 404 with no code from you.

For the column itself, keep a plain string (say varchar(32)) with ->default(OrderStatus::Pending->value) rather than a database ENUM type. Adding a case then needs no schema change, and the PHP enum stays the single source of truth.

Replacing Magic Strings Without Breaking Production

Migrating is a sequence, not a big bang, because the cast throws on the first value it cannot map:

1. Grep the strings, including views, JavaScript and SQL reports. This is your checklist.
2. Audit the database. Before writing the cast, find out what is actually stored. Legacy rows always contain surprises:

-- Run this BEFORE adding the cast. Every row must map to a case.
SELECT status, COUNT(*) AS total
FROM orders
GROUP BY status
ORDER BY total DESC;

3. Create the enum with the values the database really contains after cleanup.
4. Add the cast. Every $order->status === 'paid' comparison is now silently false; fix them in the same pull request using the grep list.
5. Validate input with Rule::enum() so new bad values cannot get in.
6. Move logic into the enum: transitions, labels, colours, "is this final".
7. Delete the old constants (Order::STATUS_PAID and friends) once nothing references them.

Steps 4 and 6 can ship in separate deploys; the audit must happen before the cast goes live.

Testing Enums with Pest

Enum logic is pure, so tests are fast and need no setup. Test the transition table with a dataset, loop over cases() so new cases cannot slip through untested, and add one database-level guard:

use App\Enums\OrderStatus;
use Illuminate\Support\Facades\DB;

it('allows only the documented transitions', function (OrderStatus $from, OrderStatus $to, bool $allowed) {
    expect($from->canTransitionTo($to))->toBe($allowed);
})->with([
    'pay a pending order' => [OrderStatus::Pending, OrderStatus::Paid, true],
    'ship a paid order' => [OrderStatus::Paid, OrderStatus::Shipped, true],
    'ship an unpaid order' => [OrderStatus::Pending, OrderStatus::Shipped, false],
    'revive a cancelled order' => [OrderStatus::Cancelled, OrderStatus::Pending, false],
]);

it('gives every case a label', function () {
    foreach (OrderStatus::cases() as $case) {
        expect($case->label())->toBeString()->not->toBeEmpty();
    }
});

it('has no status values in the database that the enum cannot read', function () {
    $unknown = DB::table('orders')
        ->distinct()
        ->pluck('status')
        ->reject(fn (string $value): bool => OrderStatus::tryFrom($value) !== null);

    expect($unknown)->toBeEmpty();
});

Run the last test against a staging snapshot and it tells you whether the cast will throw on real data. The cases() loop catches a new case without a label.

Common Pitfalls

Comparing a cast attribute to a string. After adding the cast, $order->status === 'paid' is always false because you are comparing an object to a string. No error, just wrong behaviour. Compare to the case: $order->status === OrderStatus::Paid.

Using cases as array keys. Enums are objects, so [Plan::Free => 10] throws a TypeError. Use $limits[Plan::Pro->value], or a WeakMap when you really need the case itself as the key.

A default arm in match. It defeats the exhaustiveness check that makes enums safer than strings. Leave it out unless "everything else" is a real business rule.

Invalid rows crash reads. If the database contains a value the enum does not know, reading the attribute throws ValueError. That happens on page loads and in queue workers, not just in the code that wrote the bad value. Clean data first, then cast.

Changing a case value casually. The value lives in rows, cache entries, queued jobs and API clients. Treat it like a column rename: add the new value, migrate data, remove the old one.

When to Use Enums and When Not To

Use a backed enum when the set of values is closed and owned by your code: order states, roles with hard-coded permissions, payment methods you actually integrate with, log levels, feature tiers. Adding a case is a code change that goes through review, which is exactly what you want for values that carry logic.

Use a pure enum for in-process choices that are never stored, like sort directions.

Do not use an enum when the list is data rather than code. Product categories that admins create, per-tenant ticket statuses, countries with editable metadata: those belong in a table with a foreign key. If adding a value should not require a deploy, it is not an enum.

The goal is simple: every place that cares about a status should ask the enum, and the database should only ever contain values the enum can read.

Nothing in that story is a bug in the migration itself. The bug is the assumption that schema and code change at the same instant. They never do. During every deploy there is a window where old code runs against the new schema, or new code runs against the old schema, and on a rolling or blue/green deploy that window can last minutes. Zero-downtime migrations are about making every schema change compatible with both versions of the code that might be running at the same time.

Why "Just Run the Migration" Breaks in Production

A typical deploy does three things: ship new code, run php artisan migrate --force, switch traffic. Whatever order you pick, there is overlap:

• Migrate first, then switch code: old code runs against the new schema. Renames and drops break it immediately.
• Switch code first, then migrate: new code runs against the old schema. Any new column it reads does not exist yet.
• Rolling deploys (Kubernetes, multiple Forge servers, Vapor): both versions serve traffic at the same time for the whole rollout.
• Queue workers and scheduled commands keep the old code in memory until they restart, so they lag behind web servers.
• Rollback: if the new release is bad, you redeploy the old code. If the migration already dropped something, the old code is now broken too.

There is also the database side. On a large table, some ALTER TABLE operations take a metadata lock or rewrite the table. MySQL 8 can do many changes with ALGORITHM=INSTANT or INPLACE, and PostgreSQL adds nullable columns without a rewrite, but a long-running UPDATE users SET full_name = name on 20 million rows will hold row locks, bloat the undo log or WAL, and stall replication. So "zero downtime" has two halves: compatible code, and small, lock-friendly database operations.

The Expand/Contract Pattern

Expand/contract (also called parallel change) splits one breaking change into several non-breaking ones. You expand the schema so that both old and new shapes exist, migrate the data and the code in small steps, then contract by removing the old shape once nothing uses it. Each step is its own deploy, and each deploy is safe to roll back to the previous one.

For the name to full_name rename, the phases look like this:

1. Expand: add full_name as a nullable column. Old code ignores it. Nothing breaks.
2. Dual write: deploy code that writes to both name and full_name, but still reads name. Every new or updated row now has both values.
3. Backfill: copy name into full_name for old rows, in small batches, from a job or command, not inside the migration transaction.
4. Switch reads: deploy code that reads full_name (with a fallback to name if you are cautious), still writing both.
5. Stop writing the old column: deploy code that only touches full_name. Keep name around for one more release so a rollback still works.
6. Contract: drop name in a later release, and only then make full_name NOT NULL if you need that.

Yes, that is up to five deploys for one rename. That is the price of never having an outage window, and it pays for itself the first time you need to roll back.

Implementation in Laravel

Phase 1: expand

Keep the migration tiny and additive. No data copying here.

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    public function up(): void
    {
        Schema::table('users', function (Blueprint $table) {
            $table->string('full_name')->nullable()->after('name');
        });
    }

    public function down(): void
    {
        Schema::table('users', function (Blueprint $table) {
            $table->dropColumn('full_name');
        });
    }
};

The column is nullable on purpose. If you add NOT NULL with no default, old code that inserts users without full_name will fail on the very next signup.

Phase 2: dual write in the model

The cleanest place to dual write is a model event or a mutator, so every code path (controllers, imports, Filament forms, seeders) gets it for free.

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable
{
    protected $fillable = ['name', 'full_name', 'email', 'password'];

    protected static function booted(): void
    {
        static::saving(function (User $user): void {
            if ($user->isDirty('name') && ! $user->isDirty('full_name')) {
                $user->full_name = $user->name;
            }

            if ($user->isDirty('full_name') && ! $user->isDirty('name')) {
                $user->name = $user->full_name;
            }
        });
    }
}

Model events do not fire for query builder updates like User::where(...)->update([...]) or raw SQL. Search the codebase for mass updates on that table and fix them by hand, or the backfill will keep finding stale rows.

Phase 3: backfill in batches

Run the backfill as an Artisan command or a queued job, not inside the migration. Migrations run inside the deploy and, on PostgreSQL, inside a transaction; a twenty-minute migration blocks the deploy and holds locks for twenty minutes.

namespace App\Console\Commands;

use Illuminate\Console\Command;
use Illuminate\Support\Facades\DB;

class BackfillUserFullName extends Command
{
    protected $signature = 'backfill:user-full-name {--batch=1000} {--sleep=100}';

    protected $description = 'Copy users.name into users.full_name in small batches';

    public function handle(): int
    {
        $batch = (int) $this->option('batch');
        $sleepMs = (int) $this->option('sleep');
        $total = 0;

        DB::table('users')
            ->whereNull('full_name')
            ->select(['id'])
            ->chunkById($batch, function ($rows) use (&$total, $sleepMs): void {
                $ids = $rows->pluck('id')->all();

                $updated = DB::table('users')
                    ->whereIn('id', $ids)
                    ->whereNull('full_name')
                    ->update(['full_name' => DB::raw('name')]);

                $total += $updated;
                $this->info("Updated {$total} rows, last id {$ids[array_key_last($ids)]}");

                usleep($sleepMs * 1000);
            });

        $this->info("Done. {$total} rows backfilled.");

        return self::SUCCESS;
    }
}

A few details matter here:

• chunkById pages with WHERE id > ? ORDER BY id LIMIT n (keyset pagination). Plain chunk() uses OFFSET, which gets slower on every page and, worse, skips rows when the WHERE condition changes under it. Because we are updating exactly the column we filter on, chunk() would silently skip half the table.
• The update repeats whereNull('full_name'), so the command is idempotent. If a user edits their profile mid-backfill, the dual write already set full_name and we do not overwrite it. You can kill and restart the command safely.
• Each batch is its own short statement, so locks are held for milliseconds, and replicas can keep up. The sleep gives replication and other traffic room to breathe. Watch replica lag while it runs and tune --batch and --sleep accordingly.
• DB::raw('name') makes the database copy the value directly, with no round trip through PHP.

If the table is huge and the IDs are dense, an even simpler loop is to walk fixed ID ranges (WHERE id BETWEEN 1 AND 1000, then 1001 to 2000 and so on). That avoids the extra SELECT per batch and makes progress trivially resumable: just log the last range you finished. The challenge below asks you to build exactly that range splitter.

Phase 4 and 5: switch reads, then stop writing the old column

Switch reads with an accessor fallback for one release. It costs nothing and protects you from rows the backfill missed.

namespace App\Models;

use Illuminate\Database\Eloquent\Casts\Attribute;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable
{
    protected function displayName(): Attribute
    {
        return Attribute::get(fn (): string => $this->full_name ?? $this->name ?? '');
    }
}

Before phase 5, verify that the backfill really finished: SELECT COUNT(*) FROM users WHERE full_name IS NULL AND name IS NOT NULL must be zero. Then remove every write to name. Grep for it in Blade views, API resources, exports, raw SQL and $fillable.

Phase 6: contract

Only after the release that stopped writing name has been live long enough that you will not roll back past it, drop the column. Tightening full_name to NOT NULL can go in the same migration.

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    public function up(): void
    {
        Schema::table('users', function (Blueprint $table) {
            $table->string('full_name')->nullable(false)->change();
            $table->dropColumn('name');
        });
    }

    public function down(): void
    {
        Schema::table('users', function (Blueprint $table) {
            $table->string('name')->nullable()->after('id');
            $table->string('full_name')->nullable()->change();
        });
    }
};

Notice that down() cannot restore the data in name. That is normal for a contract step and the reason it ships last, after you are confident. Since Laravel 11, ->change() requires you to repeat every attribute you want to keep (length, default, comment), because modifiers that you omit are dropped.

Deploy Order Cheat Sheet

The rule of thumb: additive schema changes go before the code that needs them; destructive schema changes go after the code that stopped needing them.

Also restart queue workers in every deploy (php artisan queue:restart, or php artisan horizon:terminate with Horizon); they are the slowest part of your fleet to pick up new code.

Testing the Backfill

You cannot unit test downtime, but you can test that each phase does what it claims: that the backfill is idempotent, does not overwrite rows the dual write already handled, and processes everything across multiple batches. A Pest feature test with RefreshDatabase covers it.

use App\Models\User;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Illuminate\Support\Facades\DB;

uses(RefreshDatabase::class);

it('backfills full_name in batches without overwriting newer values', function () {
    User::factory()->count(25)->create(['full_name' => null]);
    DB::table('users')->update(['full_name' => null]);

    $edited = User::factory()->create(['name' => 'Old Name']);
    DB::table('users')->where('id', $edited->id)->update(['full_name' => 'New Name']);

    $this->artisan('backfill:user-full-name', ['--batch' => 10, '--sleep' => 0])
        ->assertSuccessful();

    expect(DB::table('users')->whereNull('full_name')->count())->toBe(0)
        ->and(DB::table('users')->where('id', $edited->id)->value('full_name'))->toBe('New Name');

    $this->artisan('backfill:user-full-name', ['--batch' => 10, '--sleep' => 0])
        ->assertSuccessful();

    expect(DB::table('users')->whereColumn('full_name', '!=', 'name')->count())->toBe(1);
});

The batch size of 10 against 26 rows forces at least three chunks, which is where pagination bugs hide. In CI, also run php artisan migrate:rollback --step=1 after each expand migration to prove the down() method works; a rollback that has never been executed is a rollback that does not work.

Common Pitfalls

• Backfilling inside the migration. It runs during the deploy, blocks the pipeline and holds locks. Keep migrations to schema changes; move data to commands or jobs.
• Using chunk() while modifying the filter column. Offset pagination skips rows. Use chunkById() or lazyById().
• Adding NOT NULL in the expand step. Old code that does not know the column will fail on insert. Add constraints only after the backfill and after every writer sets the value.
• Forgetting non-Eloquent writers. Query builder updates, raw SQL, other services sharing the database, and database triggers all bypass model events.
• Dropping too early. If you drop in the same release that stopped using the column, a rollback brings back code that needs it. Wait one release.
• Long-running ALTER TABLE on hot tables. Check whether your engine can do the change online. For MySQL, tools like gh-ost or pt-online-schema-change exist for changes that are not instant.
• Not restarting workers. Queue workers keep old code alive long after the web tier switched.

When to Use It and When Not To

Use expand/contract when:

• You deploy to more than one server, use rolling or blue/green deploys, or run long-lived queue workers.
• The table is large enough that a full rewrite or single big UPDATE would lock it noticeably.
• You need the option to roll back code without restoring a database backup.
• Several services or apps read the same table and cannot all deploy at once.

Skip it, or shortcut it, when:

• It is a brand-new table nobody reads yet: just change it.
• The app is small, single-server, and a two-minute php artisan down window is acceptable to your users.
• The change is purely additive (new nullable column, new table, new index created online). That is already the expand step; there is nothing to contract.

The mental shift is the important part: stop thinking of a migration as one event, and start thinking of it as a sequence of states where every state is compatible with the code before it and the code after it.

All three symptoms have the same root cause: LIMIT ... OFFSET .... Offset pagination is the default in every framework because it is easy to reason about, but it does work proportional to how deep you are, and it describes a position ("row number 80,000") instead of a place in the data ("after this exact row"). Keyset pagination, also called cursor pagination, fixes both problems.

Why OFFSET Gets Slow

The database cannot jump to row 200,000. It has no idea where row 200,000 is until it has produced the first 199,999 rows in the requested order. Even with a perfect index on the sort columns, the engine walks the index from the start, counts and discards OFFSET entries, then returns LIMIT rows.

-- Page 1: fast
SELECT id, title, created_at FROM posts
ORDER BY created_at DESC, id DESC
LIMIT 20 OFFSET 0;

-- Page 10,000: the server reads 200,020 index entries and throws 200,000 away
SELECT id, title, created_at FROM posts
ORDER BY created_at DESC, id DESC
LIMIT 20 OFFSET 200000;

Without a covering index it is worse: MySQL may fetch the full row for every skipped entry or fall back to a filesort. Run EXPLAIN ANALYZE on a deep page and you will see the "rows examined" number grow linearly with the offset while the result stays at 20 rows. Page 1 and page 10,000 return the same amount of data, but the second one costs ten thousand times more work.

There is also a correctness problem. An offset is relative to the current state of the table:

• A new post is inserted at the top while a user is on page 3. Everything shifts down by one, and the first row of page 4 is the last row they already saw on page 3. Duplicate.
• A post on page 2 is deleted. Everything shifts up by one, and a row that would have been the first item of page 4 is now the last item of page 3, which the user already loaded. Skipped.

In an admin table that is an annoyance; in an export or a feed it is a bug.

How Keyset Pagination Works

Instead of telling the database "skip N rows", you tell it "give me rows that come after this one". The client sends back the sort values of the last row it received, and the next query turns them into a WHERE clause:

-- First page
SELECT id, title FROM posts
ORDER BY id DESC
LIMIT 20;

-- Next page: the client sends back the last id it saw, e.g. 981234
SELECT id, title FROM posts
WHERE id < 981234
ORDER BY id DESC
LIMIT 20;

With an index on id, the engine does an index seek straight to 981234 and reads 20 entries. The cost is the same on page 1 and page 1,000,000: roughly O(log n + limit).

It is also stable. Inserting a newer post does not change which rows are older than 981234, and deleting a row on an earlier page does not move anything. Every row is returned exactly once, in order, as long as the sort key itself does not change.

Here is the full round trip, including the "fetch one extra row" trick that tells you whether a next page exists without running COUNT(*):

Composite Cursors for Non-Unique Sort Columns

Sorting by id alone is rare. Feeds sort by created_at, shops by price. None of these are unique: a bulk import can create 500 rows with the same created_at second. If your cursor is only created_at < '2026-10-20 08:15:00', every row that shares that timestamp and did not fit on the previous page is silently skipped. If you use <=, they are repeated forever.

The fix is a tiebreaker: add a unique column (usually the primary key) as the last sort key, and make the cursor a tuple of all sort columns.

CREATE INDEX posts_created_at_id_index ON posts (created_at, id);

-- Row constructor form (MySQL 8 and PostgreSQL can use the index for this range)
SELECT id, title, created_at FROM posts
WHERE (created_at, id) < ('2026-10-20 08:15:00', 981234)
ORDER BY created_at DESC, id DESC
LIMIT 21;

-- Expanded form: same meaning, works everywhere, and also handles mixed directions
SELECT id, title, created_at FROM posts
WHERE created_at < '2026-10-20 08:15:00'
   OR (created_at = '2026-10-20 08:15:00' AND id < 981234)
ORDER BY created_at DESC, id DESC
LIMIT 21;

Three rules make this work:

1. The ORDER BY must be fully deterministic: the column list ends with something unique.
2. The WHERE comparison uses the same columns in the same order and direction as the ORDER BY.
3. There is an index whose columns match that order, so the database seeks rather than scans. In InnoDB, a secondary index on (created_at) already carries the primary key, but declaring (created_at, id) explicitly makes the intent obvious and keeps the plan predictable.

The row constructor form (a, b) < (x, y) is concise and both MySQL 8 and PostgreSQL optimize it as a range. The expanded OR form says the same thing and is the one you need when directions are mixed, such as ORDER BY price ASC, id DESC: flip the operator per column (price > ? OR (price = ? AND id < ?)) and back it with a matching (price ASC, id DESC) index.

MySQL 8.0 added real descending indexes, so (price ASC, id DESC) can be scanned in one pass. On older versions mixed directions often meant a filesort.

Laravel cursorPaginate

Laravel ships keyset pagination out of the box. Swap paginate() for cursorPaginate() and make sure the ordering ends with a unique column:

namespace App\Http\Controllers\Api;

use App\Http\Resources\PostResource;
use App\Models\Post;
use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\AnonymousResourceCollection;

final class PostFeedController
{
    public function __invoke(Request $request): AnonymousResourceCollection
    {
        $perPage = min((int) $request->integer('per_page', 20), 100);

        $posts = Post::query()
            ->select(['id', 'title', 'excerpt', 'created_at'])
            ->where('status', 'published')
            ->orderByDesc('created_at')
            ->orderByDesc('id')
            ->cursorPaginate($perPage)
            ->withQueryString();

        return PostResource::collection($posts);
    }
}

Under the hood the paginator fetches perPage + 1 rows, reads the order columns from the query, and builds the expanded where ... or (... and ...) condition from the decoded cursor. The cursor itself is a base64-encoded JSON object of the sort column values plus a flag that says whether it points forward or backward, and it travels in the cursor query string parameter. Returned through an API resource, the meta block contains path, per_page, next_cursor and prev_cursor, and links.next is a ready-to-call URL.

Notice what is missing: there is no total, no last_page, no current_page. The paginator never runs COUNT(*), which on a large filtered table is often the slowest query of the whole request. prev_cursor works too, so "back" navigation is supported.

Things the framework expects from you:

• Every orderBy column must be selected and must not contain NULL values. Cursor values are compared with < and >, and SQL comparisons with NULL are never true.
• Ordering by an expression only works if it is aliased and present in the select. Expressions with bound parameters are not supported.
• The cursor is encoded, not encrypted or signed. A client can decode it, edit the values and send it back. That is harmless for public feeds because the query still applies your where filters, but do not put anything secret in the sort columns.

Rolling Your Own Cursor

Sometimes you want control over the format: a signed cursor that cannot be tampered with, a short string for a mobile client, or the same pagination logic over a raw query builder or an Elasticsearch result. The pattern is small enough to write yourself. First, a value object that encodes and signs the tuple:

namespace App\Support\Pagination;

use InvalidArgumentException;

final class FeedCursor
{
    public function __construct(
        public readonly string $createdAt,
        public readonly int $id,
    ) {}

    public static function fromRow(object $row): self
    {
        return new self((string) $row->created_at, (int) $row->id);
    }

    public function encode(string $key): string
    {
        $payload = json_encode([$this->createdAt, $this->id], JSON_THROW_ON_ERROR);
        $body = rtrim(strtr(base64_encode($payload), '+/', '-_'), '=');
        $sig = substr(hash_hmac('sha256', $body, $key), 0, 16);

        return $body . '.' . $sig;
    }

    public static function decode(string $cursor, string $key): self
    {
        [$body, $sig] = array_pad(explode('.', $cursor, 2), 2, '');

        if (! hash_equals(substr(hash_hmac('sha256', $body, $key), 0, 16), $sig)) {
            throw new InvalidArgumentException('Invalid cursor.');
        }

        $json = base64_decode(strtr($body, '-_', '+/'), true);
        $data = $json === false ? null : json_decode($json, true);

        if (! is_array($data) || count($data) !== 2 || ! is_int($data[1])) {
            throw new InvalidArgumentException('Malformed cursor.');
        }

        return new self((string) $data[0], $data[1]);
    }
}

In the query, decode the incoming cursor, apply the same expanded created_at < ? OR (created_at = ? AND id < ?) condition shown earlier, fetch limit + 1 rows, and encode FeedCursor::fromRow() of the last kept row only when the extra row came back.

Truncating the signature to 16 hex characters keeps the cursor short and still makes forgery impractical. Rotating the key invalidates every outstanding cursor, so clients should treat 400 Invalid cursor as "restart from page one".

API Design With Cursors

Keyset pagination changes the contract, so design the API around it rather than bolting a cursor onto a page-number API:

• Make the cursor opaque. Document it as "a string you send back unchanged", so adding a sort column never breaks clients.
• Return next_cursor and has_more, or null at the end. That is all an infinite scroll or a sync job needs.
• Bind the cursor to the query. If the client changes sort or a filter, the old cursor is meaningless. Either reject it (store a hash of the filters inside the cursor) or document that filters must stay identical across pages.
• Cap limit. min($perPage, 100) stops one client from asking for 50,000 rows in a single request.
• Offer total counts separately, if at all. If the UI needs "1,234 results", serve an approximate count from a cached or estimated value, not a COUNT(*) on every page.
• Use cursors for sync endpoints. "Everything changed since X" is keyset on (updated_at, id).

Testing Keyset Pagination

The bugs live at the boundaries: duplicated timestamps, the last page, and data that changes between requests. A good test walks every page by following links.next until it is null, then checks that every row was seen exactly once. Seeding a block of rows with an identical created_at is what catches a missing tiebreaker.

use App\Models\Post;
use Illuminate\Support\Carbon;

it('walks every post exactly once even when timestamps collide', function () {
    $sameMoment = Carbon::parse('2026-10-20 08:00:00');

    Post::factory()->count(30)->create(['status' => 'published', 'created_at' => $sameMoment]);
    Post::factory()->count(25)->create(['status' => 'published']);

    $seen = [];
    $url = '/api/posts?per_page=7';

    while ($url !== null) {
        $response = $this->getJson($url)->assertOk();
        $seen = [...$seen, ...array_column($response->json('data'), 'id')];
        $url = $response->json('links.next');
    }

    expect($seen)->toHaveCount(55)
        ->and(array_unique($seen))->toHaveCount(55)
        ->and($seen)->toEqualCanonicalizing(Post::pluck('id')->all());
});

A second test worth having: load page 1, insert newer posts, load page 2 and assert the two pages share no ids. A per_page of 7 puts page boundaries inside the identical-timestamp group, so removing orderByDesc('id') fails the test at once.

Common Pitfalls

• No unique tiebreaker. The most common bug. Rows silently disappear at page boundaries whenever the sort column has duplicates.
• Index does not match the order. Keyset is only fast if the database can seek. Check EXPLAIN: you want a range access on your composite index, not filesort.
• Nullable sort columns. NULL breaks comparisons. Use COALESCE into a sentinel and index that expression, or exclude NULL rows, or sort by a non-null column.
• Mutable sort keys. If you sort by updated_at and a row is updated while someone is paging, it can jump ahead of the cursor and be seen twice, or jump behind it and be missed. For sync jobs that is usually what you want; for feeds, sort by something immutable.
• Expecting "jump to page 57". Keyset only knows next and previous. If the product needs numbered pages, keep offset for that screen.
• Filtering after fetching. If you drop rows in PHP after the query (permission checks, soft visibility rules), pages come out short. Push those conditions into SQL.

When to Use Offset and When to Use Keyset

Use offset (paginate() or simplePaginate()) when:

• the data set is small or users never go beyond a few pages, like an admin table with filters;
• the UI needs page numbers, a total count, or "jump to page N";
• the sort order is arbitrary and user-chosen across many columns, and you cannot index every combination.

Use keyset (cursorPaginate() or a hand-written cursor) when:

• the table is large and people or jobs go deep: infinite scroll, activity feeds, notifications, chat history;
• you export, sync or backfill a whole table in batches. For one-off jobs inside Laravel, lazyById() and chunkById() already use keyset internally;
• rows are inserted or deleted while clients are paging and duplicates or gaps are unacceptable;
• the API is public and you want predictable latency regardless of how deep a client goes.

A common middle ground: admin screens keep offset with numbered pages, while the public API and every background job use cursors. The query that took 2.8 seconds on page 4,000 becomes the same 15 ms seek as page 1, and the export stops losing orders.

Password storage is one of the few places where "fast" is a bug. The fix is not complicated: a slow, salted, memory-hard password hash, a cost you actually tuned, and a login flow that silently upgrades old hashes. Here is each piece in PHP 8.4 and Laravel 13, plus migrating an existing user base.

Why MD5, SHA-1 and SHA-256 Are the Wrong Tool

General-purpose hashes are designed to be fast. That is exactly what you want for checksums and HMACs, and exactly what an attacker wants when guessing passwords offline. Once the hashes leak, the attacker no longer talks to your rate limiter or your lockout policy. They run guesses on their own hardware as fast as the algorithm allows: tens of billions of MD5 guesses per second on one GPU, versus thousands for bcrypt.

Adding a salt (sha256($salt . $password)) stops precomputed rainbow tables and forces per-user work, but it does nothing about raw speed. Running SHA-256 a few thousand times in a loop is better, and that is basically what PBKDF2 does, but GPUs still parallelise it beautifully because it needs almost no memory.

A password hash has three jobs: a unique random salt per password, a tunable work factor so you can keep up with hardware, and ideally memory hardness so GPUs and ASICs cannot run thousands of guesses in parallel cheaply. bcrypt covers the first two. Argon2id covers all three.

bcrypt vs Argon2id

bcrypt (1999) is the boring, battle-tested default. It is PASSWORD_DEFAULT in PHP and the default driver in Laravel. Its work factor is a cost exponent: cost 12 means 2^12 rounds of the expensive key setup, and every +1 doubles the time. PHP 8.4 raised the default bcrypt cost from 10 to 12, and Laravel's BCRYPT_ROUNDS default is also 12. bcrypt uses about 4 KiB of memory, which is small enough that GPUs can still attack it, just slowly.

bcrypt has one sharp edge: it only uses the first 72 bytes of the input. Two passphrases that share the first 72 bytes produce the same hash. For normal passwords that does not matter. It does matter if you pre-concatenate things such as a username or a long pepper in front of the password, and it matters for very long UTF-8 passphrases where 72 bytes can be fewer than 30 characters.

Argon2id won the Password Hashing Competition in 2015 and is the current OWASP first choice. You tune three knobs: memory (memory_cost, in KiB), iterations (time_cost) and parallelism (threads). Because every guess needs its own block of memory, an attacker with a GPU runs out of memory bandwidth long before running out of cores. It has no 72-byte limit.

The practical rule: for a new project where you control the servers, Argon2id with at least 19 MiB of memory (OWASP's minimum) is the better choice, and 64 MiB is a sensible default if your login traffic allows it. bcrypt at cost 12 or higher is still perfectly acceptable, and much better than anything fast. Do not use plain PBKDF2 unless a compliance regime such as FIPS forces it, and then use a high iteration count (OWASP suggests 600,000 for PBKDF2-HMAC-SHA256).

The Verify-and-Rehash Flow

The key idea that makes upgrades painless: you can only re-hash a password when you have the plaintext, and the only time you have it is during a successful login. So every successful login is a chance to check whether the stored hash still matches your current policy and replace it if not.

The legacy branch handles hashes from before your migration. The normal branch handles cost changes and algorithm changes (bcrypt to Argon2id) with exactly the same code, because the hash string itself records the algorithm and its parameters.

Doing It in Plain PHP 8.4

PHP's password API does the heavy lifting. Never call crypt() directly, never generate your own salt, and never compare hashes with ===.

// Registration: let PHP pick the algorithm, salt and encoding.
$hash = password_hash($plainPassword, PASSWORD_DEFAULT);

// Store $hash in a VARCHAR(255) column. It looks like:
// $2y$12$<22 chars of salt><31 chars of hash>

// Login: never compare hashes yourself.
if (password_verify($plainPassword, $hash)) {
    if (password_needs_rehash($hash, PASSWORD_DEFAULT)) {
        $hash = password_hash($plainPassword, PASSWORD_DEFAULT);
        // persist the new $hash for this user
    }
    // log the user in
}

password_needs_rehash() returns true if the stored hash uses a different algorithm or different options than the ones you pass. Raise the cost, deploy, and every user is upgraded the next time they log in.

How high should the cost be? The honest answer is "as high as your login latency and CPU budget allow". A good target is roughly 250 to 500 ms per hash on your production hardware. Measure instead of guessing:

// Run this on production-like hardware, not on your laptop.
$timeTarget = 0.25; // seconds per hash you are willing to spend
$cost = 9;

do {
    $cost++;
    $start = microtime(true);
    password_hash('benchmark-password', PASSWORD_BCRYPT, ['cost' => $cost]);
    $elapsed = microtime(true) - $start;
} while ($elapsed < $timeTarget && $cost < 16);

printf("Use cost %d (%.3f s per hash)%s", $cost, $elapsed, PHP_EOL);

Pair a high cost with rate limiting (Laravel's RateLimiter or throttle middleware) so password hashing does not become a cheap way to burn your CPU.

Argon2id goes through the same API:

if (! defined('PASSWORD_ARGON2ID')) {
    throw new RuntimeException('PHP was built without Argon2 support.');
}

$options = [
    'memory_cost' => 65536, // KiB, so 64 MiB per hash
    'time_cost' => 4,       // passes over that memory
    'threads' => 1,         // libsodium builds only support 1
];

$hash = password_hash($plainPassword, PASSWORD_ARGON2ID, $options);
// $argon2id$v=19$m=65536,t=4,p=1$<salt>$<hash>

$valid = password_verify($plainPassword, $hash);
$stale = password_needs_rehash($hash, PASSWORD_ARGON2ID, $options);

PASSWORD_ARGON2ID only exists if PHP was compiled with libargon2 or libsodium. Official Docker images and most distro packages have it, but check in CI rather than finding out in production. Memory cost is per hash, so 64 MiB times 50 concurrent logins is 3.2 GiB. Size your PHP-FPM workers accordingly.

Laravel 13: Hash Facade, Config and Rehash on Login

Laravel wraps the same functions behind the Hash facade and reads its policy from config/hashing.php. Publish it with php artisan config:publish hashing if your app does not have it yet.

// config/hashing.php (trimmed)
return [
    'driver' => env('HASH_DRIVER', 'bcrypt'), // or 'argon2id'

    'bcrypt' => [
        'rounds' => env('BCRYPT_ROUNDS', 12),
        'verify' => env('HASH_VERIFY', true),
    ],

    'argon' => [
        'memory' => env('ARGON_MEMORY', 65536),
        'threads' => env('ARGON_THREADS', 1),
        'time' => env('ARGON_TIME', 4),
        'verify' => env('HASH_VERIFY', true),
    ],

    'rehash_on_login' => true,
];

Switching HASH_DRIVER to argon2id does not break existing users: Laravel can still verify old bcrypt hashes, and rehash_on_login upgrades them as people log in.

The default User model casts password to hashed, so assigning a plaintext value hashes it automatically and assigning an existing hash leaves it alone. Since Laravel 11, Auth::attempt() calls the user provider's rehashPasswordIfRequired() after a successful check, so cost and driver upgrades need zero code from you. If you wrote a custom UserProvider, implement that method or the upgrade silently never happens.

What Laravel cannot do for you is migrate hashes it does not understand, like the raw MD5 column from the intro. Do it in two steps. First, a one-off command wraps every MD5 value in bcrypt, so no fast hash stays at rest even for users who never log in again:

namespace App\Console\Commands;

use App\Models\User;
use Illuminate\Console\Command;
use Illuminate\Support\Collection;
use Illuminate\Support\Facades\Hash;

final class WrapLegacyPasswords extends Command
{
    protected $signature = 'passwords:wrap-legacy';

    protected $description = 'Replace raw MD5 hashes with bcrypt(md5) so no fast hash stays at rest';

    public function handle(): int
    {
        User::query()
            ->whereNotNull('legacy_md5')
            ->chunkById(500, function (Collection $users): void {
                foreach ($users as $user) {
                    $user->forceFill([
                        'password' => Hash::make($user->legacy_md5),
                        'password_is_wrapped' => true,
                        'legacy_md5' => null,
                    ])->save();
                }
            });

        $this->info('Legacy hashes wrapped.');

        return self::SUCCESS;
    }
}

Then, at login, users with a wrapped hash are checked against bcrypt(md5(password)) and unwrapped into a normal hash:

namespace App\Http\Controllers\Auth;

use App\Models\User;
use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;
use Illuminate\Support\Facades\Hash;
use Illuminate\Validation\ValidationException;

final class LoginController
{
    public function __invoke(Request $request): RedirectResponse
    {
        $credentials = $request->validate([
            'email' => ['required', 'email'],
            'password' => ['required', 'string'],
        ]);

        $this->unwrapLegacyHash($credentials['email'], $credentials['password']);

        // Auth::attempt() verifies the hash and, with rehash_on_login enabled,
        // re-hashes it when the cost or algorithm in config/hashing.php changed.
        if (! Auth::attempt($credentials, $request->boolean('remember'))) {
            throw ValidationException::withMessages([
                'email' => __('auth.failed'),
            ]);
        }

        $request->session()->regenerate();

        return redirect()->intended('/dashboard');
    }

    private function unwrapLegacyHash(string $email, string $password): void
    {
        $user = User::query()->where('email', $email)->first();

        if ($user === null || ! $user->password_is_wrapped) {
            return;
        }

        // Stored value is bcrypt(md5(password)) from the one-time migration.
        if (Hash::check(md5($password), $user->password)) {
            $user->forceFill([
                'password' => $password, // the 'hashed' cast hashes it
                'password_is_wrapped' => false,
            ])->save();
        }
    }
}

Testing the Upgrade Path

Test the behaviour that matters: users can still log in after a migration, the stored hash actually changes, and failed logins change nothing. Keep tests fast with a low cost: the Laravel skeleton's phpunit.xml already sets BCRYPT_ROUNDS=4.

use App\Models\User;
use Illuminate\Support\Facades\Hash;

it('unwraps a legacy md5 password on the first successful login', function () {
    $user = User::factory()->create([
        'password' => Hash::make(md5('old-secret-123')),
        'password_is_wrapped' => true,
    ]);

    $this->post('/login', ['email' => $user->email, 'password' => 'old-secret-123'])
        ->assertRedirect('/dashboard');

    $user->refresh();

    expect($user->password_is_wrapped)->toBeFalse()
        ->and(Hash::check('old-secret-123', $user->password))->toBeTrue()
        ->and(Hash::check(md5('old-secret-123'), $user->password))->toBeFalse();

    $this->assertAuthenticatedAs($user);
});

it('rehashes on login after the bcrypt cost goes up', function () {
    $user = User::factory()->create([
        'password' => password_hash('secret-pass-1', PASSWORD_BCRYPT, ['cost' => 4]),
    ]);

    config(['hashing.bcrypt.rounds' => 5]);
    Hash::forgetDrivers();

    $this->post('/login', ['email' => $user->email, 'password' => 'secret-pass-1'])
        ->assertRedirect('/dashboard');

    expect(Hash::info($user->refresh()->password)['options']['cost'])->toBe(5);
});

Hash::forgetDrivers() clears the cached hasher so the new rounds value is picked up within the same test. The second test is the one that protects you from a custom provider quietly breaking rehash-on-login.

Common Pitfalls

• Comparing hashes with == or ===. Use password_verify() or Hash::check(). For legacy MD5 comparisons, use hash_equals() so the comparison is constant-time, and never use ==, which treats strings like "0e123..." as numbers.
• Too-short columns. bcrypt is 60 characters and Argon2id hashes are around 97 with default options and grow with the parameters. Use VARCHAR(255) so a future algorithm does not get truncated.
• Hashing on the client. If the browser sends sha256(password), that hash is the password from the server's point of view. Use HTTPS and hash on the server.
• Peppers that break bcrypt. Prepending a long secret pushes the real password past 72 bytes. If you want a pepper, apply it as hash_hmac('sha256', $password, $pepper) and base64-encode the output before bcrypt, and plan for pepper rotation.
• Forgetting the cost in tests. Without BCRYPT_ROUNDS=4, a test suite that creates thousands of users spends minutes hashing.
• Leaving MD5 values at rest. A lazy "upgrade on login" migration keeps fast hashes forever for inactive users. Wrap them all immediately, as shown above.

When to Use What (and When Not To)

• New Laravel app: keep the default bcrypt at cost 12 or move to Argon2id if PHP has it and you have the memory. Either way, leave rehash_on_login on.
• High-traffic login or tight memory: bcrypt is predictable and cheap on RAM. Raise the cost over time instead of switching algorithms.
• Inheriting MD5/SHA-1 hashes: wrap them in bcrypt now, unwrap on login, and force resets for whatever is left after a few months.
• API keys and long random tokens: do not use a password hash. They already have high entropy, so a single SHA-256 is fine, which is exactly how Sanctum stores personal access tokens. Slow hashes are for low-entropy secrets humans choose.

The short version: never store anything fast, let the platform pick salts and encodings, tune the cost on real hardware, and treat every successful login as a free migration step.

The culprit is the event loop. The refactor turned one long synchronous task into hundreds of thousands of chained microtasks, and in JavaScript microtasks always run before the loop is allowed to look at timers, sockets or the next HTTP request. If you understand exactly what runs when, bugs like this become obvious and output-order interview puzzles become boring. Here is the model I use.

One Thread, One Call Stack

JavaScript runs your code on a single thread with a single call stack. When you call a function, a frame is pushed; when it returns, the frame is popped. While that stack is non-empty, nothing else can run: no timer callback, no promise reaction, no click handler, no incoming request in Node. Every "concurrent" thing in JavaScript is really a queue of callbacks waiting for the stack to be empty.

The host (the browser or Node's libuv) does the actual waiting for timers, sockets and files on other threads or in the kernel. When something finishes, the host does not interrupt your code. It puts a callback into a queue. The event loop is just the policy that decides which queue gets served next once the stack is empty.

There are two families of queues that matter:

• Macrotasks (the spec just calls them tasks): setTimeout, setInterval, setImmediate (Node), I/O callbacks, MessageChannel messages, UI events. The loop takes one of these per turn.
• Microtasks: promise reactions (.then, .catch, .finally, and the continuation after await), queueMicrotask, and MutationObserver callbacks in browsers. After every macrotask, and after the initial script, the loop drains all of them, including microtasks queued while draining.

Node adds one more queue in front: process.nextTick callbacks, which are drained before promise microtasks.

How the Loop Picks the Next Callback

This is the whole algorithm, simplified enough to predict output and accurate enough to debug production:

The key asymmetry is in steps C and D versus step F. Microtasks are drained until the queue is empty. Macrotasks are taken one at a time, with a full microtask drain after each. Browsers get a chance to render only between macrotasks, never in the middle of a microtask drain.

In Node, step F is more detailed because libuv cycles through phases (timers, pending callbacks, poll for I/O, check for setImmediate, close callbacks), but since Node 11 the rule that matters matches browsers: after each individual timer or immediate callback, Node drains nextTick and then the microtask queue.

Predicting Output Order

With that model, the classic puzzles are mechanical. Walk the script top to bottom, write sync output immediately, and put every callback in its queue.

console.log('A');

setTimeout(() => console.log('B'), 0);

Promise.resolve().then(() => console.log('C'));

queueMicrotask(() => console.log('D'));

console.log('E');

// Output: A E C D B

A and E are synchronous. C and D are microtasks, queued in that order, so they run in that order as soon as the script finishes. B is a macrotask and has to wait for the microtask queue to be empty, even with a delay of 0 (Node clamps it to 1 ms anyway, and browsers clamp deeply nested timers to at least 4 ms).

async/await is just promises with nicer syntax. The body of an async function runs synchronously until the first await. Everything after the await is scheduled as a microtask once the awaited value settles:

async function load() {
  console.log(1);
  await null;            // everything below becomes a microtask
  console.log(2);
}

console.log(0);
load();
Promise.resolve().then(() => console.log(3));
console.log(4);

// Output: 0 1 4 2 3

1 prints synchronously inside load(). await null wraps null in a resolved promise and queues the continuation. Then .then queues 3. 4 prints, the stack empties, and the microtasks run in FIFO order: 2, then 3. Before V8 7.2 an await on a native promise took three microtask ticks instead of one, so very old Node versions could print 3 before 2. If code correctness depends on that kind of tick counting, the code is wrong, not the engine.

The third rule people miss: microtasks queued inside a macrotask run before the next macrotask.

setTimeout(() => {
  console.log('t1');
  Promise.resolve().then(() => console.log('p1'));
}, 0);

setTimeout(() => console.log('t2'), 0);

// Output (Node 11+ and browsers): t1 p1 t2

Node versions before 11 ran all expired timers first and drained microtasks afterwards, printing t1 t2 p1. That changed to match browsers, and it is one more reason to never write logic that depends on how many timers fire per phase.

Finally, Node's own queues:

// main.cjs (CommonJS)
Promise.resolve().then(() => console.log('promise'));
process.nextTick(() => console.log('nextTick'));
setImmediate(() => console.log('immediate'));
setTimeout(() => console.log('timeout'), 0);

// Typical output: nextTick promise timeout immediate
// (timeout vs immediate order is NOT guaranteed in the main module)

nextTick beats promises because Node drains the tick queue first. setTimeout(fn, 0) versus setImmediate from the main module depends on how long process startup took relative to the 1 ms timer threshold, so it can flip between runs. Inside an I/O callback, setImmediate always fires first because the check phase comes right after poll. Also note: in an ES module, the top-level code itself runs as part of a promise job, so the promise vs nextTick order you observe there can differ from CommonJS. Another reason not to rely on it.

Starving the Loop

Because the microtask queue is drained until empty, a microtask that keeps scheduling microtasks blocks the loop forever, even though each individual callback is tiny:

// This never lets the timer fire: the microtask queue is never empty.
setTimeout(() => console.log('you will never see me'), 0);

function spin() {
  Promise.resolve().then(spin);
}
spin();

The call stack never grows, so you do not get a RangeError: Maximum call stack size exceeded. You just get a frozen tab or a Node process that stops answering requests while CPU sits at 100% on one core. Recursive process.nextTick does the same thing, even more aggressively, because it starves promises too.

The production incident from the intro is the softer version of this. Each await on an already-resolved value costs one microtask. A loop of 200k awaited helpers is 200k+ microtasks drained back to back, and from the event loop's point of view that is one enormous uninterruptible block. The fix is not "add more await". This does nothing for fairness:

// Looks like yielding, but is NOT: await on a resolved promise is a microtask,
// so the loop never reaches the timers or poll phase.
for (const row of hugeArray) {
  transform(row);
  await Promise.resolve();
}

To let the rest of the world run, you must yield a macrotask: setImmediate in Node, setTimeout(0) or MessageChannel in browsers, or scheduler.yield() where it is supported (Chromium-based browsers today).

Implementation: Time-Sliced Processing

The pattern I reach for is time slicing: do work until a budget is spent, then yield a macrotask so the loop can serve timers, I/O and requests, then continue. The clock is injectable so the behaviour is testable without real timing.

const { setImmediate: yieldToLoop } = require('node:timers/promises');

/**
 * Process a large array without blocking the event loop.
 * Runs `fn` on items until `budgetMs` is spent, then yields a macrotask
 * so timers, I/O callbacks and incoming requests get a turn.
 */
async function processInChunks(items, fn, { budgetMs = 10, now = () => performance.now() } = {}) {
  const results = [];
  let sliceStart = now();

  for (let i = 0; i < items.length; i++) {
    results.push(fn(items[i], i));

    if (now() - sliceStart >= budgetMs) {
      await yieldToLoop();   // a real macrotask, not a microtask
      sliceStart = now();
    }
  }

  return results;
}

module.exports = { processInChunks };

A budget of 5 to 15 ms per slice is a good starting point for a Node API server; it keeps per-request latency bounded while still doing real work per slice. In browsers aim for well under 16 ms so you do not drop frames, and consider moving truly heavy work to a Worker instead, where it cannot block the UI at all.

For CPU-bound jobs that take seconds, slicing is a band-aid. Use worker_threads in Node or a Web Worker in the browser, or push the job to a queue. Slicing shines for the middle ground: work that takes 50 to 500 ms and must stay on the main thread because it touches main-thread state.

Testing Event Loop Behaviour

You can test ordering with the built-in node:test runner. Record events into an array and assert on the sequence after giving the loop a real macrotask to finish. The second test proves that processInChunks really yields: a timer scheduled before the work must fire in the middle of the work, not after it. A fake clock makes the slice boundaries deterministic.

// event-loop.test.cjs  ->  node --test
const { test } = require('node:test');
const assert = require('node:assert/strict');
const { processInChunks } = require('./process-in-chunks.cjs');

const tick = () => new Promise((resolve) => setTimeout(resolve, 5));

test('microtasks drain before the next timer', async () => {
  const log = [];
  setTimeout(() => log.push('timeout'), 0);
  Promise.resolve().then(() => log.push('promise'));
  queueMicrotask(() => log.push('microtask'));
  log.push('sync');

  await tick();
  assert.deepEqual(log, ['sync', 'promise', 'microtask', 'timeout']);
});

test('processInChunks lets a timer run in the middle of the work', async () => {
  const log = [];
  setTimeout(() => log.push('timer'), 0);

  let fakeTime = 0;
  const now = () => fakeTime;
  const items = Array.from({ length: 6 }, (_, i) => i);

  const out = await processInChunks(items, (x) => {
    fakeTime += 5;            // pretend each item costs 5 ms
    log.push(`item${x}`);
    return x * 2;
  }, { budgetMs: 10, now });

  assert.deepEqual(out, [0, 2, 4, 6, 8, 10]);
  const timerAt = log.indexOf('timer');
  assert.ok(timerAt > 0 && timerAt < log.length - 1, `timer ran at ${timerAt}`);
});

If someone replaces yieldToLoop() with await Promise.resolve(), the second test fails, because the timer would only run after all items are processed. That is exactly the regression you want caught in CI rather than in production.

Common Pitfalls

• Assuming setTimeout(fn, 0) means "now". It means "after the current task, after all microtasks, and after at least 1 ms (4 ms when nested in browsers)". In an inactive browser tab it can be throttled to once per second or worse.
• Using await as a yield point. Awaiting a resolved promise, a sync function, or null is a microtask. It never lets timers, I/O or rendering run.
• Recursive process.nextTick or promise chains for "async recursion". They starve I/O. Use setImmediate for recursion that should be fair.
• Expecting async functions to run in the background. The body runs synchronously until the first await. An async function with a CPU-heavy loop and no await blocks just as hard as a normal function.
• Relying on cross-queue order like setTimeout vs setImmediate, or nextTick vs promises across module types. Express the dependency explicitly with await or callbacks instead.
• Unhandled rejections in microtasks. A rejected promise without a handler surfaces as unhandledRejection, which crashes Node by default since v15. Microtask scheduling does not make errors disappear.
• Measuring the wrong thing. Event loop lag is visible with perf_hooks.monitorEventLoopDelay(). If p99 delay is in the hundreds of milliseconds, look for long synchronous work or long microtask chains before blaming the database.

When to Care and When Not To

Care about the details when:

• a Node service shows latency spikes on cheap endpoints while one expensive endpoint is running;
• you write libraries that schedule callbacks (emitters, caches, stream adapters) and need a consistent "always async" contract (queueMicrotask is the right tool for that);
• you process large in-memory datasets on the main thread, in Node or in the browser;
• you debug flaky tests that pass or fail depending on timer timing.

Do not over-engineer when:

• the work is I/O-bound and naturally awaits the network or disk; the loop is already free while waiting;
• the job is truly CPU-heavy; move it to a worker or a queue instead of tuning slice sizes;
• you are tempted to depend on exact tick counts. Write code whose correctness holds for any interleaving and use the event-loop model only to reason about latency and fairness.

The short version to keep in your head: sync code first, then all microtasks, then one macrotask, repeat. If something can schedule work faster than it finishes, it will starve everything behind it.

Laravel has two tools for this, and they answer different questions. Bus::chain runs jobs one after another and stops at the first failure. Bus::batch runs jobs in parallel and tracks them as a group, with progress and lifecycle callbacks. Picking the wrong one is how you end up with half-charged orders or imports that never report completion.

Chain vs Batch: The Core Difference

A chain is a sequence. Job B is only pushed to the queue after job A succeeds. If A fails permanently (after its retries), B and C are discarded and the chain's catch callback runs. Use it when each step depends on the previous one: reserve stock, then charge the card, then send the receipt.

A batch is a group. All jobs are pushed at once and any number of workers can pick them up. Laravel stores a row in the job_batches table with counters (total_jobs, pending_jobs, failed_jobs) and updates them atomically as each job finishes. Use it when the jobs are independent and you care about the group outcome: import chunks, thumbnail generation, sending a newsletter in slices.

The lifecycle of a batch is where most of the confusion lives:

Three rules to memorize:

• then runs only if every job succeeded. One permanent failure and then never fires, even with allowFailures().
• catch runs once, on the first job that fails for good (after it has used up its $tries). Later failures do not trigger it again.
• finally runs when every job has run, whatever the outcome. This is where cleanup and "import finished" notifications belong.

Setting Up Batches

Batches need the job_batches table. Laravel ships a generator for its migration:

php artisan make:queue-batches-table
php artisan migrate

Every job you put in a batch must use the Batchable trait. It gives the job $this->batch(), which returns the Batch instance so a job can check whether the batch was cancelled or add more jobs to it. The cleanest way to stop work after cancellation is the SkipIfBatchCancelled job middleware:

namespace App\Jobs;

use App\Services\CustomerCsv;
use Illuminate\Bus\Batchable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Queue\Queueable;
use Illuminate\Queue\Middleware\SkipIfBatchCancelled;

final class ImportCustomerChunk implements ShouldQueue
{
    use Batchable, Queueable;

    public int $tries = 3;

    public function __construct(
        public readonly int $importId,
        public readonly int $offset,
        public readonly int $limit,
    ) {}

    /** Skip the work entirely once the batch has been cancelled. */
    public function middleware(): array
    {
        return [new SkipIfBatchCancelled()];
    }

    public function handle(CustomerCsv $csv): void
    {
        foreach ($csv->rows($this->importId, $this->offset, $this->limit) as $row) {
            $csv->upsertCustomer($row);
        }
    }

    /** @return list<int> */
    public function backoff(): array
    {
        return [10, 60];
    }
}

Note that a job skipped by the middleware still counts as processed. That matters for progress bars: a cancelled batch can reach 100% "progress" while doing almost no work.

Chains for Dependent Steps

Checkout is the classic chain. Charging the card before stock is reserved is a bug, and sending a receipt for a failed charge is worse:

use App\Jobs\ChargePayment;
use App\Jobs\ReleaseStock;
use App\Jobs\ReserveStock;
use App\Jobs\SendReceipt;
use Illuminate\Support\Facades\Bus;

$orderId = $order->id;

Bus::chain([
    new ReserveStock($orderId),
    new ChargePayment($orderId),
    new SendReceipt($orderId),
])
    ->onQueue('orders')
    ->catch(function (Throwable $e) use ($orderId): void {
        // Runs once, when a job in the chain fails for good.
        // The jobs after the failed one are never executed.
        ReleaseStock::dispatch($orderId);
        logger()->error('Checkout chain failed', ['order_id' => $orderId, 'error' => $e->getMessage()]);
    })
    ->dispatch();

The catch closure is serialized and stored with the chain, so capture plain values like $orderId, never $this or a big model graph. If ChargePayment throws on its last attempt, SendReceipt is never queued and the compensation job releases the stock.

Batches for Parallel Work With Progress

Here is the import, split into chunks, with all four callbacks wired to a CustomerImport record that the UI polls:

namespace App\Services;

use App\Jobs\ImportCustomerChunk;
use App\Models\CustomerImport;
use Illuminate\Bus\Batch;
use Illuminate\Support\Facades\Bus;
use Throwable;

final class CustomerImporter
{
    public function start(int $importId, int $rows, int $chunkSize = 1000): Batch
    {
        $jobs = [];

        for ($offset = 0; $offset < $rows; $offset += $chunkSize) {
            $jobs[] = new ImportCustomerChunk($importId, $offset, $chunkSize);
        }

        return Bus::batch($jobs)
            ->name("customer-import-{$importId}")
            ->onQueue('imports')
            ->allowFailures()
            ->progress(function (Batch $batch) use ($importId): void {
                CustomerImport::whereKey($importId)->update(['progress' => $batch->progress()]);
            })
            ->then(function (Batch $batch) use ($importId): void {
                // Only when EVERY job succeeded.
                CustomerImport::whereKey($importId)->update(['status' => 'completed']);
            })
            ->catch(function (Batch $batch, Throwable $e) use ($importId): void {
                // Only for the FIRST job that failed for good.
                CustomerImport::whereKey($importId)->update(['status' => 'has_errors']);
            })
            ->finally(function (Batch $batch) use ($importId): void {
                // When every job has run, success or not.
                CustomerImport::whereKey($importId)->update([
                    'finished_at' => now(),
                    'failed_chunks' => $batch->failedJobs,
                ]);
            })
            ->dispatch();
    }
}

Why allowFailures() here? Without it, the first permanently failed chunk cancels the batch, and every chunk still in the queue is skipped by the middleware. For a checkout-style "all or nothing" job that is what you want. For an import, losing 1 chunk out of 250 should not throw away the other 249; you would rather finish, report failed_chunks, and let support retry the failures with php artisan queue:retry-batch {id}.

The progress callback fires after each successful job. It does a small write, which is fine at a few hundred jobs. At tens of thousands of jobs, throttle it (only write when the integer percentage changes) or drop it and let the UI read the batch directly:

use Illuminate\Support\Facades\Bus;
use Illuminate\Support\Facades\Route;

Route::get('/imports/batches/{batchId}', function (string $batchId) {
    $batch = Bus::findBatch($batchId);

    abort_if($batch === null, 404);

    return [
        'name' => $batch->name,
        'progress' => $batch->progress(),
        'total' => $batch->totalJobs,
        'pending' => $batch->pendingJobs,
        'failed' => $batch->failedJobs,
        'finished' => $batch->finished(),
        'cancelled' => $batch->cancelled(),
    ];
})->middleware('auth');

Bus::findBatch() reads the job_batches row, so this endpoint is cheap and always consistent with what the workers have recorded. Keep it behind auth: a batch ID is not a secret token.

Mixing Chains and Batches

Real workflows are rarely pure. Laravel lets you nest them both ways. An array inside a batch is a chain; a batch inside a chain is a step that waits for the whole batch:

use App\Jobs\BuildSearchIndex;
use App\Jobs\ExportInvoices;
use App\Jobs\ExportPayments;
use App\Jobs\NotifyFinanceTeam;
use App\Jobs\ZipExports;
use Illuminate\Support\Facades\Bus;

// A batch whose items are chains: each region runs its two steps in order,
// while the regions run in parallel with each other.
Bus::batch([
    [new ExportInvoices('eu'), new ExportPayments('eu')],
    [new ExportInvoices('us'), new ExportPayments('us')],
    [new ExportInvoices('apac'), new ExportPayments('apac')],
])->name('month-end-exports')->dispatch();

// A chain that contains a batch: the zip step waits for the whole batch.
Bus::chain([
    Bus::batch([
        new ExportInvoices('eu'),
        new ExportInvoices('us'),
    ]),
    new ZipExports(),
    new NotifyFinanceTeam(),
])->dispatch();

// A running job can also grow its own batch.
// Inside a Batchable job's handle():
// $this->batch()->add([new BuildSearchIndex($this->importId)]);

The second form replaces a common hack where the batch's then callback dispatches the next job. With the batch as a chain step, the dependency is visible at the dispatch site instead of being hidden in a callback.

Testing Batches and Chains

You rarely want real workers in a feature test. Bus::fake() records what was dispatched and gives you assertions for both shapes:

use App\Jobs\ChargePayment;
use App\Jobs\ImportCustomerChunk;
use App\Jobs\ReserveStock;
use App\Jobs\SendReceipt;
use App\Models\Order;
use App\Services\CheckoutService;
use App\Services\CustomerImporter;
use Illuminate\Bus\PendingBatch;
use Illuminate\Support\Facades\Bus;

it('dispatches one batch job per chunk and tolerates failures', function () {
    Bus::fake();

    app(CustomerImporter::class)->start(importId: 42, rows: 2500, chunkSize: 1000);

    Bus::assertBatched(function (PendingBatch $batch): bool {
        return $batch->name === 'customer-import-42'
            && $batch->jobs->count() === 3
            && $batch->jobs->every(fn ($job) => $job instanceof ImportCustomerChunk)
            && $batch->allowsFailures();
    });
});

it('runs checkout as an ordered chain', function () {
    Bus::fake();

    $order = Order::factory()->create();
    app(CheckoutService::class)->checkout($order);

    Bus::assertChained([
        ReserveStock::class,
        ChargePayment::class,
        SendReceipt::class,
    ]);
});

These tests check the wiring: the right number of chunks, the right order, allowFailures switched on. The jobs themselves deserve separate unit tests that call handle() directly with fake dependencies. For the callbacks, extract their bodies into small invokable classes or service methods so you can test them without a queue.

Common Pitfalls

• Expecting then after partial failure. With allowFailures(), the batch keeps going, but then still only fires when everything succeeded. Put "import done" logic in finally and read $batch->failedJobs there.
• Capturing $this or models in callbacks. Callbacks are serialized into the job_batches row. Capture IDs and re-query inside the closure.
• Forgetting the batch was cancelled. Without SkipIfBatchCancelled or a manual if ($this->batch()?->cancelled()) return;, queued jobs keep doing real work after a failure cancelled the batch.
• Retries vs failures. A job that throws but has tries left is not a batch failure yet. catch only fires after the final attempt. Set $tries and backoff() deliberately.
• Unbounded job_batches table. Every batch leaves a row. Schedule pruning:

use Illuminate\Support\Facades\Schedule;

// routes/console.php
Schedule::command('queue:prune-batches --hours=48 --unfinished=72 --cancelled=72')->daily();

• Dispatching inside a DB transaction. If you create the CustomerImport row and dispatch the batch in the same transaction, workers can start before the commit and not find the row. Use afterCommit() on the jobs or dispatch after the transaction.

When to Use Which, and When Not To

Use a chain when steps must run in order and later steps make no sense if an earlier one failed. Keep chains short; a 15-step chain is a workflow engine in disguise and is hard to resume halfway.

Use a batch when the work is a set of independent units and you need group-level answers: how far along, did anything fail, run something exactly once at the end.

Do not use either when one job is enough. If a task finishes in seconds, splitting it adds a database round trip per job for bookkeeping. And do not use batches as a long-lived state machine for business processes that span days; model that state in your own tables and let jobs be the small, retryable steps that move it forward.

The Three States

A circuit breaker wraps calls to a dependency and tracks how they go. It lives in one of three states:

• Closed: normal operation. Calls go through, failures are counted. A success resets the counter.
• Open: the threshold was hit. Calls fail immediately with no network round trip, so your workers are freed in microseconds instead of seconds.
• Half-Open: the cooldown has passed. One trial call is allowed through. If it succeeds, the circuit closes; if it fails, it opens again for another cooldown.

Implementation

The clock is injected so the breaker can be tested without sleeping.

final class CircuitOpenException extends RuntimeException {}

final class CircuitBreaker
{
    private string $state = 'closed';
    private int $failures = 0;
    private ?float $openedAt = null;

    public function __construct(
        private int $failureThreshold = 5,
        private float $cooldownSeconds = 30.0,
        private ?Closure $clock = null,
    ) {
        $this->clock ??= fn (): float => microtime(true);
    }

    public function call(callable $operation): mixed
    {
        if ($this->state === 'open') {
            if (($this->clock)() - $this->openedAt < $this->cooldownSeconds) {
                throw new CircuitOpenException('Circuit is open, failing fast.');
            }

            $this->state = 'half_open';
        }

        try {
            $result = $operation();
        } catch (Throwable $e) {
            $this->recordFailure();

            throw $e;
        }

        $this->reset();

        return $result;
    }

    public function state(): string
    {
        return $this->state;
    }

    private function recordFailure(): void
    {
        $this->failures++;

        if ($this->state === 'half_open' || $this->failures >= $this->failureThreshold) {
            $this->state = 'open';
            $this->openedAt = ($this->clock)();
        }
    }

    private function reset(): void
    {
        $this->state = 'closed';
        $this->failures = 0;
        $this->openedAt = null;
    }
}

import time
from typing import Callable


class CircuitOpenError(Exception):
    pass


class CircuitBreaker:
    def __init__(
        self,
        failure_threshold: int = 5,
        cooldown_seconds: float = 30.0,
        clock: Callable[[], float] = time.monotonic,
    ) -> None:
        self.failure_threshold = failure_threshold
        self.cooldown_seconds = cooldown_seconds
        self.clock = clock
        self.state = "closed"
        self.failures = 0
        self.opened_at: float | None = None

    def call[T](self, operation: Callable[[], T]) -> T:
        if self.state == "open":
            if self.clock() - self.opened_at < self.cooldown_seconds:
                raise CircuitOpenError("Circuit is open, failing fast.")
            self.state = "half_open"

        try:
            result = operation()
        except Exception:
            self._record_failure()
            raise

        self._reset()
        return result

    def _record_failure(self) -> None:
        self.failures += 1
        if self.state == "half_open" or self.failures >= self.failure_threshold:
            self.state = "open"
            self.opened_at = self.clock()

    def _reset(self) -> None:
        self.state = "closed"
        self.failures = 0
        self.opened_at = None

Sharing State in Laravel

The class above keeps its state in memory. In a long-running Python worker that is fine, but under PHP-FPM every request starts with a fresh object, so the breaker never remembers a single failure. In Laravel, keep the state in a shared cache (Redis) instead:

use Illuminate\Support\Facades\Cache;

final class CachedCircuitBreaker
{
    public function __construct(
        private string $name,
        private int $failureThreshold = 5,
        private int $cooldownSeconds = 30,
        private int $failureWindowSeconds = 60,
    ) {}

    public function call(callable $operation): mixed
    {
        $openKey = "circuit:{$this->name}:open";
        $failKey = "circuit:{$this->name}:failures";

        if (Cache::has($openKey)) {
            throw new CircuitOpenException("Circuit {$this->name} is open.");
        }

        try {
            $result = $operation();
        } catch (Throwable $e) {
            Cache::add($failKey, 0, $this->failureWindowSeconds);

            if (Cache::increment($failKey) >= $this->failureThreshold) {
                Cache::put($openKey, true, $this->cooldownSeconds);
                Cache::forget($failKey);
            }

            throw $e;
        }

        Cache::forget($failKey);

        return $result;
    }
}

$breaker = new CachedCircuitBreaker('payment-gateway', failureThreshold: 5, cooldownSeconds: 30);

try {
    $response = $breaker->call(
        fn () => Http::timeout(3)->post($url, $payload)->throw()
    );
} catch (CircuitOpenException) {
    return response()->json([
        'message' => 'The payment provider is unavailable, please try again shortly.',
    ], 503);
}

This shared version is simpler than the in-memory one: when the open key expires, all traffic flows again instead of a single trial call. For most apps that is good enough. If the dependency is fragile, add a short Cache::lock() so only one request makes the trial call.

Testing the Breaker

Because the clock is injected, you can move time forward instead of sleeping:

it('opens after the threshold and recovers after the cooldown', function () {
    $now = 1000.0;
    $breaker = new CircuitBreaker(3, 30, function () use (&$now) { return $now; });
    $fail = fn () => throw new RuntimeException('down');

    foreach (range(1, 3) as $_) {
        try { $breaker->call($fail); } catch (RuntimeException) {}
    }

    expect($breaker->state())->toBe('open')
        ->and(fn () => $breaker->call(fn () => 'ok'))->toThrow(CircuitOpenException::class);

    $now += 31;

    expect($breaker->call(fn () => 'ok'))->toBe('ok')
        ->and($breaker->state())->toBe('closed');
});

Choosing the Thresholds

• Failure threshold: 5 failures is a common start. Too low and one hiccup trips the breaker; too high and you keep hammering a dead service.
• Cooldown: 15 to 60 seconds. Long enough for the dependency to restart or scale, short enough that users do not wait minutes after it recovers.
• Timeouts: a breaker only helps if calls fail fast. Always set a client timeout (Http::timeout(3)); a 30-second default timeout means 30 seconds of blocked workers per call.

Common Pitfalls

• Counting the wrong errors. A 422 Validation failed is the caller's fault, not a sign the service is down. Only count timeouts, connection errors and 5xx responses.
• One breaker for everything. Use one breaker per dependency (payment-gateway, sms-provider), so an SMS outage does not block payments.
• No fallback. Decide what the user sees when the circuit is open: a cached value, a queued job to retry later, or a clear 503 message.
• Retrying inside the breaker without limits. Put backoff retries inside the operation and keep them small, or the breaker sees one failure for what was actually five slow calls.

When to Reach for This

Use a circuit breaker around any remote dependency that can be slow or down and that sits on a hot path: payment gateways, SMS and email providers, third-party APIs, even an internal microservice. Pair it with exponential backoff: backoff handles short blips, the breaker handles real outages.

Exponential backoff spaces retries further apart each time (200ms, 400ms, 800ms...), but on its own it still leaves every client synchronized to the same schedule. Jitter fixes that by randomizing the delay, so retries spread out instead of arriving in lockstep.

The Retry Timeline

Each hop roughly doubles the base delay, capped at some maximum, with a random component layered on top so no two clients retry at exactly the same instant.

Fixed vs Exponential vs Jittered

A fixed delay (always wait 1s) is simple but synchronizes every client that failed at the same time. Plain exponential backoff (200ms, 400ms, 800ms, 1600ms) spreads attempts further apart over time, but clients that failed together are still retrying together at each step. Adding jitter — picking a random delay instead of the fixed exponential value — breaks that synchronization entirely.

Full Jitter

The full jitter strategy (used internally by AWS's own SDKs) computes the exponential delay as a ceiling, then picks a uniformly random value between zero and that ceiling:

delay = random_between(0, min(cap, base * 2^attempt))

This is simpler than "equal jitter" or "decorrelated jitter" variants and performs well in practice: it spreads retries across the full window instead of just adding a small amount of noise around the exponential value.

Implementation

function calculateBackoff(int $attempt, int $baseDelayMs = 200, int $maxDelayMs = 30000): int
{
    $exponential = $baseDelayMs * (2 ** $attempt);
    $capped = min($exponential, $maxDelayMs);

    return random_int(0, $capped);
}

function retryWithBackoff(callable $operation, int $maxAttempts = 5, int $baseDelayMs = 200, int $maxDelayMs = 30000)
{
    $attempt = 0;

    while (true) {
        try {
            return $operation();
        } catch (\Throwable $e) {
            $attempt++;

            if ($attempt >= $maxAttempts) {
                throw $e;
            }

            $delayMs = calculateBackoff($attempt, $baseDelayMs, $maxDelayMs);
            usleep($delayMs * 1000);
        }
    }
}

import random
import time
from typing import Callable, TypeVar

T = TypeVar("T")


def calculate_backoff(attempt: int, base_delay_ms: int = 200, max_delay_ms: int = 30000) -> int:
    exponential = base_delay_ms * (2 ** attempt)
    capped = min(exponential, max_delay_ms)

    return random.randint(0, capped)


def retry_with_backoff(
    operation: Callable[[], T],
    max_attempts: int = 5,
    base_delay_ms: int = 200,
    max_delay_ms: int = 30000,
) -> T:
    attempt = 0

    while True:
        try:
            return operation()
        except Exception:
            attempt += 1

            if attempt >= max_attempts:
                raise

            delay_ms = calculate_backoff(attempt, base_delay_ms, max_delay_ms)
            time.sleep(delay_ms / 1000)

Choosing the Parameters

baseDelayMs should roughly match how fast the downstream service actually recovers from a blip — too low and you're retrying into a still-failing service, too high and users wait needlessly on transient errors. maxDelayMs caps the worst case so a client doesn't end up waiting minutes between attempts. maxAttempts should be low enough that a genuinely broken dependency fails fast instead of hanging the caller for a long chain of doubling delays.

Common Pitfalls

Retrying without any cap on the delay means a client can end up waiting minutes for an attempt that will just fail again. Retrying without jitter defeats the entire purpose — synchronized clients stay synchronized no matter how far apart the delays get. Retrying on every kind of error, including 4xx client errors that will never succeed, wastes the retry budget on failures that a delay can't fix. And retrying indefinitely with no maxAttempts turns a transient blip into a request that never gives up and never surfaces an error to the caller.

When to Reach for This

Any call to a dependency that can fail transiently and recover on its own: HTTP calls to another service, database connections during a failover, queue consumers hitting a rate-limited API. If failures are rarely transient — a malformed request, a missing resource — backoff and retries just delay an error that was never going to succeed.

Consistent hashing fixes this by mapping both nodes and keys onto the same ring, so a topology change only remaps the keys between the changed node and its neighbor.

The Ring

Each node is hashed onto the ring (often multiple times — see "Virtual Nodes" below). To find which node owns a key, hash the key and walk clockwise until you hit the first node.

Adding or Removing a Node

When node B leaves, only the keys that were mapped to B move — to B's clockwise neighbor. Every other key stays exactly where it was. That's the whole point: roughly 1/N of the keyspace moves per topology change, not the whole keyspace.

Virtual Nodes (Replicas)

Hashing raw node names onto the ring directly creates hot spots — some nodes end up owning much bigger arcs than others. The fix: hash each node multiple times, e.g. node-A#0, node-A#1, ..., node-A#149 (150 virtual nodes is a common default). More virtual nodes means smoother distribution, at the cost of a bigger in-memory ring.

Implementation

class ConsistentHash
{
    private array $ring = [];
    private array $sortedKeys = [];
    private int $replicas;

    public function __construct(int $replicas = 150)
    {
        $this->replicas = $replicas;
    }

    public function addNode(string $node): void
    {
        for ($i = 0; $i < $this->replicas; $i++) {
            $this->ring[$this->hash("$node#$i")] = $node;
        }
        $this->sortedKeys = $this->sortedRingKeys();
    }

    public function getNode(string $key): ?string
    {
        if (empty($this->sortedKeys)) {
            return null;
        }

        $hash = $this->hash($key);
        foreach ($this->sortedKeys as $ringKey) {
            if ($ringKey >= $hash) {
                return $this->ring[$ringKey];
            }
        }

        return $this->ring[$this->sortedKeys[0]];
    }

    private function sortedRingKeys(): array
    {
        $keys = array_keys($this->ring);
        sort($keys);
        return $keys;
    }

    private function hash(string $value): int
    {
        return crc32($value);
    }
}

import bisect
import zlib


class ConsistentHash:
    def __init__(self, replicas: int = 150):
        self.replicas = replicas
        self.ring: dict[int, str] = {}
        self.sorted_keys: list[int] = []

    def add_node(self, node: str) -> None:
        for i in range(self.replicas):
            self.ring[self._hash(f"{node}#{i}")] = node
        self.sorted_keys = sorted(self.ring.keys())

    def get_node(self, key: str) -> str | None:
        if not self.sorted_keys:
            return None

        h = self._hash(key)
        index = bisect.bisect_left(self.sorted_keys, h)
        if index == len(self.sorted_keys):
            index = 0

        return self.ring[self.sorted_keys[index]]

    @staticmethod
    def _hash(value: str) -> int:
        return zlib.crc32(value.encode())

Common Pitfalls

Too few virtual nodes leads to uneven load, with hot spots on a handful of physical nodes. Using a weak or poorly-distributed hash function makes the same problem worse — prefer something like CRC32 or xxHash over a naive sum-of-bytes hash. Forgetting to remove all of a node's virtual nodes on removal leaves ghost entries that route traffic to a dead server. And rehashing the entire keyspace on every topology change defeats the whole purpose — only the ring should change, not every key's mapping.

When to Reach for This

Distributed caches doing client-side sharding, CDN edge selection, distributed hash tables, sharded databases, and load balancers that need session affinity without a central coordinator. If your cluster size is fixed and rarely changes, plain modulo hashing is simpler and perfectly fine.

The naive approach — an array you scan for the oldest entry — is O(n) per operation. The trick to O(1) is combining two structures: a hash map for O(1) lookup, and a doubly linked list for O(1) reordering.

The Structure

Every node lives in the linked list AND has a pointer stored in the hash map. head is a sentinel pointing to the most recently used node; tail is a sentinel pointing to the least recently used one, which is the eviction candidate.

The Two Operations

get(key): hash map lookup finds the node in O(1). If found, unlink it from its current position and relink it right after head (it's now the most recently used), then return its value. If not found, return null/miss.

put(key, value): if the key already exists, update its value and move it to the front, same as get. If it's new and capacity is full, remove the node just before tail (the least recently used) from both the list and the hash map, then insert the new node at the front.

Both operations only ever touch a constant number of pointers — no scanning required.

PHP Implementation

class Node
{
    public function __construct(
        public string $key,
        public mixed $value,
        public ?Node $prev = null,
        public ?Node $next = null,
    ) {}
}

class LRUCache
{
    private array $map = [];
    private Node $head;
    private Node $tail;
    private int $capacity;

    public function __construct(int $capacity)
    {
        $this->capacity = $capacity;
        $this->head = new Node('', null);
        $this->tail = new Node('', null);
        $this->head->next = $this->tail;
        $this->tail->prev = $this->head;
    }

    public function get(string $key): mixed
    {
        if (!isset($this->map[$key])) {
            return null;
        }

        $node = $this->map[$key];
        $this->detach($node);
        $this->attachToFront($node);

        return $node->value;
    }

    public function put(string $key, mixed $value): void
    {
        if (isset($this->map[$key])) {
            $node = $this->map[$key];
            $node->value = $value;
            $this->detach($node);
            $this->attachToFront($node);
            return;
        }

        if (count($this->map) >= $this->capacity) {
            $lru = $this->tail->prev;
            $this->detach($lru);
            unset($this->map[$lru->key]);
        }

        $node = new Node($key, $value);
        $this->map[$key] = $node;
        $this->attachToFront($node);
    }

    private function detach(Node $node): void
    {
        $node->prev->next = $node->next;
        $node->next->prev = $node->prev;
    }

    private function attachToFront(Node $node): void
    {
        $node->next = $this->head->next;
        $node->prev = $this->head;
        $this->head->next->prev = $node;
        $this->head->next = $node;
    }
}

The two sentinel nodes (head and tail) exist purely to avoid null checks at the boundaries — every real node always has a valid prev and next to work with.

Common Pitfalls

Forgetting to update the hash map on eviction. If you remove a node from the linked list but leave its entry in $map, the next get() for that key returns a dangling node instead of a miss.

Off-by-one on capacity checks. Check count($this->map) >= $this->capacity before inserting the new node, not after — otherwise the cache temporarily holds capacity + 1 items.

Treating get() as read-only. A cache hit still mutates state — it moves the node to the front. Skipping that step turns your LRU into a plain FIFO cache.

Using an array and array_shift() as the "queue." array_shift() is O(n) because PHP reindexes the array. This defeats the entire point of the exercise — the doubly linked list is what makes eviction O(1).

When to Reach for a Real Implementation

Don't hand-roll this for production unless you have a specific reason (embedding the cache inside a single PHP process with no external dependency, for instance). For anything shared across requests or processes, Redis's own eviction policies (allkeys-lru, volatile-lru) or a library like symfony/cache already solve this correctly and durably. The value of building it yourself is understanding why O(1) requires both structures together — neither one alone gets you there.

The Problem

Client -> POST /charge {amount: 5000} -> Server processes charge, DB write succeeds
Client -> (times out waiting for response, retries)
Client -> POST /charge {amount: 5000} -> Server processes AGAIN -> customer charged twice

The client never knows if the first request failed before or after the side effect happened. Without idempotency, a naive retry strategy silently causes double charges, duplicate emails, duplicate orders.

The Fix: Idempotency Keys

The client generates a unique key (usually a UUID) per logical operation and sends it in a header:

POST /api/v1/charges
Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7
{ "amount": 5000, "currency": "USD" }

The server stores the key alongside the result of the first successful execution. On retry with the same key, it returns the stored result without re-executing the side effect.

Implementation with a Database-Backed Store

function handleCharge(Request $request) {
    $key = $request->header('Idempotency-Key');
    if (!$key) {
        abort(400, 'Idempotency-Key header required');
    }

    return DB::transaction(function () use ($key, $request) {
        $existing = IdempotencyKey::where('key', $key)->lockForUpdate()->first();

        if ($existing) {
            if ($existing->status === 'processing') {
                abort(409, 'Request with this key is already being processed');
            }
            return response($existing->response_body, $existing->response_status);
        }

        IdempotencyKey::create([
            'key' => $key,
            'status' => 'processing',
            'request_hash' => hash('sha256', $request->getContent()),
        ]);

        $result = processCharge($request->all());

        IdempotencyKey::where('key', $key)->update([
            'status' => 'completed',
            'response_status' => 200,
            'response_body' => json_encode($result),
        ]);

        return response()->json($result);
    });
}

The row-level lock (lockForUpdate) inside the transaction is what prevents two concurrent requests with the same key from both slipping past the "does it exist" check — this is the race condition most naive implementations miss.

Sequence of a Safe Retry

Common Pitfalls

Not hashing the request body. If a client reuses a key with a different payload (different amount, say), returning the cached response silently applies the wrong charge to the wrong intent. Store a hash of the request body with the key and reject mismatches with a 422.

No expiration. Idempotency keys should expire (24-48 hours is typical for payment APIs). Keeping them forever bloats the table and risks legitimate reuse of a UUID being blocked incorrectly, however unlikely.

Treating "processing" as "not found." If a second request arrives while the first is still mid-flight (not a retry after failure, but genuine concurrency), returning 409 (Conflict) or making the client poll is safer than letting both proceed.

Scoping keys per-endpoint, not globally. The same key sent to two different endpoints should not collide. Compose the lookup on (key, endpoint) or (key, account_id), not just key alone.

Only applying this to POST. PUT and PATCH can double-apply too if not naturally idempotent (e.g., "increment balance by 100" instead of "set balance to 100"). Prefer absolute updates over relative ones where money is involved, and use idempotency keys for both.

When You Don't Need This

Truly idempotent operations by construction (a PUT that sets absolute state, a GET, a DELETE by ID) don't need a key — retrying them is already safe. Idempotency keys matter specifically when an operation has a side effect that isn't naturally safe to repeat: charging money, sending an email, decrementing inventory, creating a resource with server-generated side effects.

Rule of thumb: any endpoint that moves money, sends a notification, or creates a resource that shouldn't be duplicated needs an idempotency key. Everything else, question whether you're overengineering.

The Classic Deadlock

Two transactions, two rows, opposite order:

-- Transaction A
BEGIN;
UPDATE accounts SET balance = balance - 100 WHERE id = 1;
-- ... pauses ...
UPDATE accounts SET balance = balance + 100 WHERE id = 2;
COMMIT;

-- Transaction B (running concurrently)
BEGIN;
UPDATE accounts SET balance = balance - 50 WHERE id = 2;
-- ... pauses ...
UPDATE accounts SET balance = balance + 50 WHERE id = 1;
COMMIT;

If A locks row 1 and B locks row 2 at nearly the same time, A's second statement waits for B to release row 2, while B's second statement waits for A to release row 1. Neither can ever proceed.

Wait-For Graphs: How Databases Detect This

Most databases (PostgreSQL, MySQL/InnoDB, SQL Server) model lock waits as a directed graph: each transaction is a node, and an edge from T1 to T2 means "T1 is waiting on a lock held by T2." A deadlock exists exactly when this graph contains a cycle.

Periodically (or on every new lock wait, depending on the engine), the database walks this graph looking for cycles. When it finds one, it picks a victim — usually the transaction that has done the least work, or holds the fewest locks — and rolls it back, releasing its locks so the other transaction can continue.

What the Error Actually Looks Like

ERROR: deadlock detected
DETAIL: Process 1234 waits for ShareLock on transaction 5678; blocked by process 5678.
Process 5678 waits for ShareLock on transaction 1234; blocked by process 1234.
HINT: See server log for query details.

The application's job is to catch this specific error and retry the transaction — a deadlock victim is not a bug, it's the database correctly resolving an unavoidable conflict.

import time

def run_with_retry(fn, max_attempts=3):
    for attempt in range(max_attempts):
        try:
            return fn()
        except DeadlockDetected:
            if attempt == max_attempts - 1:
                raise
            time.sleep(0.05 * (2 ** attempt))  # exponential backoff

Deadlocks vs. Ordinary Lock Waits

An ordinary lock wait resolves itself once the holding transaction commits or rolls back — no cycle, no error, just a delay. A deadlock is fundamentally different: without intervention, it never resolves on its own, because every party in the cycle is waiting on another party in the same cycle. This is why detection has to be active (scanning for cycles), not passive (just waiting things out).

Prevention: Consistent Lock Ordering

The single most effective prevention technique is to always acquire locks in the same order across every transaction that touches the same set of resources. If both transactions above had updated row 1 before row 2, the second one to arrive would simply wait for the first to finish — no cycle possible.

-- Both transactions now lock in ascending id order — no deadlock possible
UPDATE accounts SET balance = balance - 100 WHERE id = LEAST(1, 2);
UPDATE accounts SET balance = balance + 100 WHERE id = GREATEST(1, 2);

In practice this often means sorting rows by primary key before issuing a batch of updates, or centralizing the lock-acquisition order in a single code path rather than leaving it to each caller.

Prevention: Keep Transactions Short

Long-running transactions hold locks longer, which widens the window during which a conflicting transaction can show up and create a cycle. Moving non-essential work (sending emails, calling external APIs, heavy computation) outside the transaction boundary shrinks that window significantly.

Prevention: Lower Isolation Where Safe

Higher isolation levels take more locks for longer. SERIALIZABLE is the most deadlock-prone; READ COMMITTED takes fewer, shorter-held locks. Not every operation needs the strongest guarantee — evaluate whether a lower isolation level is safe for a given transaction before defaulting to the strictest one everywhere.

Prevention: Smaller Lock Footprint

Locking an entire table when you only need a few rows multiplies the chance of collision. Use indexed WHERE clauses so the database can take row-level (not table-level) locks, and avoid SELECT ... FOR UPDATE over more rows than the transaction actually intends to modify.

Diagnosing Recurring Deadlocks

When deadlocks show up repeatedly in production, look at the database's deadlock log (PostgreSQL logs full lock and query detail when log_lock_waits is on; MySQL exposes SHOW ENGINE INNODB STATUS). The recurring pattern is almost always the same two code paths acquiring the same two resources in opposite order — find those two call sites and fix the ordering, rather than just adding retry logic and hoping.

Common Pitfalls

Treating deadlocks purely as something to retry around, without ever fixing the underlying lock-order conflict, just moves the cost to increased latency and wasted work under load. Assuming an ORM's default query patterns are deadlock-safe is risky — many ORMs issue related updates in whatever order model associations happen to be traversed, which can vary between requests. And forgetting to add retry logic entirely means a deadlock becomes a user-facing error instead of an invisible, automatically-recovered hiccup.

A deadlock isn't a failure of the database — it's the database correctly refusing to let two transactions wait on each other forever. The fix lives in your application's lock ordering, not in disabling detection.

This is genuinely advanced material — understanding it requires comfort with distributed systems failure modes, not just Redis commands.

Why a Single Redis Lock Isn't Enough

A basic lock looks simple:

SET resource:order-42 my-random-value NX PX 30000

This sets the key only if it doesn't exist (NX), with a 30-second expiry (PX) so a crashed client doesn't hold the lock forever. The problem is that this single Redis node is a single point of failure. If it goes down before replicating the write to a replica, and the replica gets promoted to master, another client can acquire the "same" lock — because the new master never saw the key.

The Redlock Algorithm

Redlock solves this by using N independent Redis masters (the reference implementation uses 5), with no replication or coordination between them. A client wanting the lock does the following:

1. Get the current time in milliseconds.
2. Try to acquire the lock on all N instances sequentially, using the same key and a random value, with a small timeout per instance so a down node doesn't stall the whole process.
3. Compute elapsed time. The lock is considered acquired only if the client got the lock on a majority (N/2 + 1) of instances, and the total elapsed time is less than the lock's validity time.
4. If acquired, the effective validity time is the original TTL minus the elapsed time and clock drift.
5. If the lock wasn't acquired, release it on every instance immediately, whether or not that instance thought it succeeded.

Why Majority Matters

Requiring a majority (not all N) means Redlock tolerates the failure of a minority of nodes — with 5 nodes, up to 2 can be down or unreachable and the lock still works correctly, the same fault-tolerance principle behind Raft and Paxos-based systems. It also prevents split-brain: two clients can't both get a majority of 5 nodes simultaneously, because any two majorities of 5 must overlap by at least one node.

The Random Value and Safe Release

Each client generates a unique random value for its lock attempt (not just any placeholder). Releasing the lock must check that the stored value still matches before deleting it, done atomically via a Lua script:

if redis.call("get", KEYS[1]) == ARGV[1] then
    return redis.call("del", KEYS[1])
else
    return 0
end

Without this check, a client could accidentally delete a lock it no longer owns — for example, if its own lock expired and a different client acquired it in the meantime.

Clock Drift: The Real Weakness

Redlock's correctness assumes clocks across the N nodes don't drift too far apart relative to the lock's TTL. If a node's clock jumps forward unexpectedly (a bad NTP sync, a VM pause-and-resume, manual clock changes), that node might expire a lock much earlier than the others believe, opening a window where two clients think they hold the lock simultaneously. This is the core of Martin Kleppmann's well-known critique of Redlock: it depends on real-time clock behavior in ways that are hard to fully guarantee.

Fencing Tokens: The Practical Fix

Even with Redlock done correctly, a paused client (GC pause, VM suspend, network partition) can wake up after its lock has expired and still act as if it holds it — writing to a shared resource after another client has already acquired the lock and moved on. The standard mitigation is a fencing token: a monotonically increasing number returned every time a lock is granted.

Client A acquires lock, gets token 33
Client A pauses (GC, network delay...)
Client A's lock expires
Client B acquires lock, gets token 34
Client B writes to storage, tagging the write with token 34
Client A wakes up, tries to write with token 33
Storage rejects it: 33 < 34 (already saw a higher token)

The protected resource itself — a database, a file store, an API — must be the one enforcing the token check. Redlock alone cannot make this guarantee; it can only reduce the likelihood of two clients believing they hold the lock at once.

When to Use Redlock (and When Not To)

Redlock is a reasonable choice for efficiency locks — cases where a duplicate execution is wasteful but not catastrophic, like preventing the same cron-triggered job from running twice, or coalescing duplicate cache-rebuild requests. It is a risky choice for correctness locks — cases where a duplicate execution corrupts data, like coordinating writes to a financial ledger. For those, use a system with strong consistency guarantees (a consensus-based lock service like ZooKeeper or etcd) combined with fencing tokens enforced by the resource itself, not just Redis.

Common Pitfalls

Using an even number of nodes defeats the majority-quorum logic that makes Redlock resilient — always use an odd number so a majority is unambiguous. Setting per-node acquisition timeouts too high means a single slow node can blow past your lock's TTL before you've even finished the acquisition phase. And treating Redlock as a strict correctness guarantee, rather than a best-effort mutual exclusion mechanism, is the mistake that leads to production incidents — pair it with fencing tokens whenever the operation it protects actually matters.

Redlock reduces the probability of a broken lock; it does not eliminate it. Design your protected operations to survive the case where the lock briefly fails.

Why Clean History Matters

A pull request's commit history isn't just a log — it's documentation. Future developers (including you, in six months) will use git blame and git log to understand why a change was made. A history full of noise makes that archaeology painful.

A clean commit history is a gift to your future self and your reviewers.

The Basic Command

git rebase -i HEAD~5

This opens your last 5 commits in an editor, each prefixed with pick. From here you can reorder lines, or swap pick for one of several rebase commands.

The Rebase Commands

How It Works Under the Hood

Rebase doesn't move commits — it replays them. Git walks your branch's commits one at a time, applying each as a patch on top of the new base, and builds brand-new commit objects (with new SHAs) along the way.

A Real Example

Say your branch has this history before opening a PR:

a1b2c3d WIP
e4f5g6h fix typo
h7i8j9k actually add the feature
k0l1m2n oops forgot a file

Run git rebase -i HEAD~4, then change the plan to:

pick h7i8j9k actually add the feature
fixup k0l1m2n oops forgot a file
fixup a1b2c3d WIP
fixup e4f5g6h fix typo

Save and exit — Git squashes all four into a single, well-described commit.

Editing a Commit Message Mid-Rebase

Mark a commit reword, and after saving the plan, Git will stop and open your editor just for that commit's message:

git rebase -i HEAD~3
# change 'pick' to 'reword' on the line you want to rename
# Git opens your editor — update the message, save, close
# rebase continues automatically

Splitting or Amending a Commit

Mark a commit edit to pause the rebase right after it's applied:

git rebase -i HEAD~3
# mark the target commit as 'edit'

# rebase pauses here — make your changes
git add <file>
git commit --amend

# then continue
git rebase --continue

Handling Conflicts

Since rebase replays commits one by one, conflicts can surface at any step:

# fix the conflicting files
git add <resolved-files>
git rebase --continue

# or bail out entirely and go back to where you started
git rebase --abort

Pushing Rebased History

Because rebase rewrites commit SHAs, a normal git push will be rejected. You need a force push — but use the safer variant:

git push --force-with-lease

--force-with-lease refuses to overwrite the remote branch if someone else has pushed to it since your last fetch, protecting teammates from losing work — unlike a plain --force.

When to Use Which

Use squash when a commit's changes belong with the previous one but the message itself still adds context worth keeping. Use fixup for pure "oops" commits where the message adds nothing. Use reword when the code is fine but the message is misleading or too terse. Use drop for commits that turned out to be dead ends, like an experiment you abandoned.

Common Pitfalls

Never rebase commits that other people have already pulled and built on top of — you'll rewrite history out from under them and create painful merge conflicts on their end. Rebase is for local or PR-branch cleanup before merge, not for branches already shared and built upon. Also double-check your rebase plan before saving; a misplaced drop silently deletes a commit's changes, though git reflog can usually recover it if you catch the mistake quickly.

Interactive rebase rewrites history — that's exactly why it's powerful, and exactly why it should stay confined to branches only you (or your PR) are working on.

Cache-Aside (Lazy Loading)

In cache-aside, the application talks to the cache directly, and the cache stays passive. On a read, the app checks Redis first; on a miss, it loads from the database and populates the cache. Writes go straight to the database, and the cache entry is invalidated (or updated) afterward.

def get_user(user_id):
    cached = redis.get(f"user:{user_id}")
    if cached:
        return json.loads(cached)

    user = db.query("SELECT * FROM users WHERE id = %s", user_id)
    redis.setex(f"user:{user_id}", 3600, json.dumps(user))
    return user

def update_user(user_id, data):
    db.execute("UPDATE users SET ... WHERE id = %s", user_id)
    redis.delete(f"user:{user_id}")  # invalidate, don't update

Write-Through

In write-through, the cache sits in front of the database and owns the write path. Every write goes to the cache first, which synchronously writes through to the database before returning. Reads always come from the cache since it's guaranteed to be up to date.

def update_user(user_id, data):
    db.execute("UPDATE users SET ... WHERE id = %s", user_id)
    redis.setex(f"user:{user_id}", 3600, json.dumps(data))  # update, not invalidate
    return data

How the Two Patterns Differ

Consistency Trade-offs

Cache-aside has a small window where the cache can serve stale data: if two requests race between the database write and the cache invalidation, a reader might get an old value. Write-through avoids this because the cache and database are updated together in the same operation — but that comes at the cost of every write now waiting on two systems instead of one.

Cache-aside optimizes for read throughput and simplicity. Write-through optimizes for consistency at the cost of write latency.

TTL Strategy

Even with write-through, set a TTL as a safety net — bugs, race conditions, and out-of-band database writes (migrations, admin scripts) can all leave the cache holding stale data indefinitely without one.

CACHE_TTL_SECONDS = 3600  # 1 hour

redis.setex(key, CACHE_TTL_SECONDS, value)

A short TTL (minutes) suits volatile data like inventory counts or session state. A longer TTL (hours) suits data that changes rarely, like user profiles or product catalogs.

Handling Cache Stampedes

When a hot key expires, dozens of concurrent requests can all miss the cache at once and hammer the database simultaneously. A simple mitigation is a short-lived lock so only one request repopulates the cache while the rest wait:

def get_user(user_id):
    cached = redis.get(f"user:{user_id}")
    if cached:
        return json.loads(cached)

    lock = redis.set(f"lock:user:{user_id}", "1", nx=True, ex=5)
    if lock:
        user = db.query("SELECT * FROM users WHERE id = %s", user_id)
        redis.setex(f"user:{user_id}", 3600, json.dumps(user))
        redis.delete(f"lock:user:{user_id}")
        return user
    else:
        time.sleep(0.05)
        return get_user(user_id)  # retry, likely a hit now

Write-Behind: A Third Option

Worth knowing, though outside this tip's main comparison: write-behind (write-back) caching writes to Redis immediately and asynchronously flushes to the database later. It gives the lowest write latency but risks data loss if the cache crashes before flushing — generally reserved for high-throughput analytics or logging pipelines, not systems of record.

When to Use Which

Reach for cache-aside when reads vastly outnumber writes and brief staleness is acceptable — product listings, user profiles, configuration data. Reach for write-through when correctness matters more than write speed and you can't tolerate cache/database drift — pricing data, inventory levels, anything downstream systems depend on being accurate.

Common Pitfalls

Forgetting to invalidate the cache on delete, not just update, leaves ghost entries that outlive the data they represent. Using a single global TTL for wildly different data types wastes memory on rarely-changing data and creates stampedes on frequently-changing data with the same expiry window. And treating Redis as a source of truth instead of a cache is a design smell — if losing the cache would lose data, it isn't a cache anymore.

The right caching strategy is the one whose failure mode you can live with: cache-aside fails toward staleness, write-through fails toward latency. Pick based on what your system can actually tolerate.

Every API needs a slightly different shape of the same data: the full User, a public-safe User without the password hash, a form that only updates two fields. Copy-pasting the interface for each case means they drift apart the moment one gets updated. TypeScript's built-in utility types solve this by deriving new types from one source of truth.

The Problem

interface User {
  id: string
  name: string
  email: string
  passwordHash: string
  createdAt: Date
}

// Duplicated, drifts out of sync with User over time
interface PublicUser {
  id: string
  name: string
  email: string
  createdAt: Date
}

Every time User changes, someone has to remember to update PublicUser too. They won't.

Partial<T>: Make Every Field Optional

Perfect for update payloads, where the caller only sends the fields that changed.

function updateUser(id: string, changes: Partial<User>) {
  // changes might be { name: 'New Name' } or { email: '...' }
  return db.users.update(id, changes)
}

Pick<T, K>: Select a Subset of Fields

Use it when you only need a few fields from a larger type — a preview card, a dropdown option.

type UserPreview = Pick<User, 'id' | 'name'>
// { id: string; name: string }

Omit<T, K>: Exclude Specific Fields

The mirror image of Pick — keep everything except what you list. Ideal for stripping sensitive fields before sending a response.

type PublicUser = Omit<User, 'passwordHash'>
// { id: string; name: string; email: string; createdAt: Date }

Now PublicUser always tracks User automatically. Add a field to User, and it shows up in PublicUser without touching this line.

Combining Them

Utility types compose. A "rename form" that only lets you edit the name:

type RenameForm = Partial<Pick<User, 'name'>>
// { name?: string }

How the Types Derive From One Source

When to Use Which

• Partial<T>: PATCH/update payloads, optional config objects, form state before submission.
• Pick<T, K>: previews, dropdown options, anywhere you need a deliberately small, explicit subset.
• Omit<T, K>: stripping sensitive or internal fields (passwords, internal IDs) while keeping everything else in sync automatically.

Common Pitfalls

• Omit with a renamed/removed key silently succeeds — TypeScript won't error if you omit a key that was already removed from the base type, so typos in the key list can go unnoticed. Double-check the literal keys against the source type.
• Partial hides genuinely required fields — a Partial<User> update function can't tell "the caller forgot id" from "the caller doesn't want to change id." Keep required identifiers (like id) outside the Partial wrapper: { id: string } & Partial<Omit<User, 'id'>>.
• Reaching for Record<string, unknown> instead of Pick/Omit throws away type safety entirely — utility types keep the connection to the original shape, a loose Record doesn't.

Derive, don't duplicate. If two types describe the same entity, one of them should be built from the other with Pick, Omit, or Partial — not maintained by hand.

Without rate limiting, one noisy client can degrade an API for everyone else. But the naive approach to rate limiting has a nasty boundary bug that most teams don't discover until production.

The Problem: Fixed Window Counter

The simplest approach counts requests in a fixed time box and resets the counter every period:

// Naive fixed window with Redis
async function isAllowed(userId) {
  const key = `rl:${userId}:${Math.floor(Date.now() / 60000)}` // per-minute bucket
  const count = await redis.incr(key)
  await redis.expire(key, 60)
  return count <= 100 // 100 req/min
}

This looks fine until a client sends 100 requests at 0:59 and another 100 at 1:00 — 200 requests in two seconds, twice the intended limit, simply because they straddle the window boundary.

Token Bucket

A bucket holds up to N tokens. Tokens refill at a fixed rate. Every request consumes one token; if the bucket is empty, the request is rejected. This allows short bursts (up to the bucket size) while still enforcing a strict average rate over time — it's what Stripe and AWS API Gateway use under the hood.

class TokenBucket {
  constructor(capacity, refillPerSecond) {
    this.capacity = capacity
    this.tokens = capacity
    this.refillPerSecond = refillPerSecond
    this.lastRefill = Date.now()
  }

  tryConsume() {
    this.refill()
    if (this.tokens < 1) return false
    this.tokens -= 1
    return true
  }

  refill() {
    const now = Date.now()
    const elapsedSeconds = (now - this.lastRefill) / 1000
    this.tokens = Math.min(this.capacity, this.tokens + elapsedSeconds * this.refillPerSecond)
    this.lastRefill = now
  }
}

Sliding Window Counter

A cheaper alternative to a full sliding log: weight the previous window's count by how much of it still "overlaps" the current moment.

// weighted average of previous + current fixed windows
const weight = 1 - (elapsedInCurrentWindow / windowSize)
const estimatedCount = previousWindowCount * weight + currentWindowCount

This smooths out the boundary burst problem without the memory cost of storing a timestamp per request.

How a Rate-Limited Request Flows

When to Use Which

• Fixed window: simplest to implement, fine for coarse per-day/per-hour limits where bursts don't matter.
• Token bucket: the default choice for public APIs — allows reasonable bursts while holding a strict average rate.
• Sliding window: most accurate under sustained load, worth the extra complexity for strict SLAs or billing-sensitive limits.

Common Pitfalls

• Limiting by IP alone breaks for users behind shared NAT or corporate proxies — key on API key or user ID as well as IP.
• Skipping rate-limit headers (X-RateLimit-Remaining, Retry-After) forces clients to guess when they can retry, causing thundering-herd retries.
• Per-instance in-memory counters in a multi-server deployment mean each instance enforces the limit independently — a client can get N times the intended limit by hitting N different instances. Always back the counter with a shared store like Redis.
• Not rate-limiting authentication endpoints separately — login/signup routes need tighter limits than general API traffic to slow down credential stuffing.

Start with a token bucket backed by Redis. It's simple to reason about, allows reasonable bursts, and the same primitive scales from a single endpoint to a full API gateway.

In the Next.js App Router (13+), every component is a Server Component by default. This is a big shift from the old Pages Router, and it's the single most misunderstood part of modern Next.js.

The Problem

Most developers coming from Create React App or the Pages Router slap 'use client' at the top of every file "just in case." That defeats the purpose of Server Components: you end up shipping the same amount of JavaScript to the browser as before, just with extra steps.

Server Components (the default)

Server Components render only on the server. No JS for them is sent to the browser. They can await data directly, touch a database, or use secrets safely, because that code never leaves the server.

// app/products/page.tsx
export default async function ProductsPage() {
  const res = await fetch('https://api.example.com/products', {
    next: { revalidate: 60 },
  })
  const products = await res.json()

  return (
    <ul>
      {products.map((p: { id: string; name: string }) => (
        <li key={p.id}>{p.name}</li>
      ))}
    </ul>
  )
}

No useState, no useEffect, no event handlers here — and no client-side fetch waterfall either.

Client Components ('use client')

Client Components are needed for interactivity: hooks, event listeners, browser-only APIs (window, localStorage), or third-party libraries that rely on the DOM.

'use client'

import { useState } from 'react'

export default function LikeButton() {
  const [liked, setLiked] = useState(false)

  return (
    <button onClick={() => setLiked(!liked)}>
      {liked ? 'Liked' : 'Like'}
    </button>
  )
}

The 'use client' directive marks the boundary — everything imported below it also ships to the browser, so keep these components small and push them to the leaves of the tree.

How Rendering Actually Flows

On every request, the flow looks like this:

Two things happen in parallel once the response lands: the static HTML paints right away (fast first contentful paint), and only the Client Component "islands" get hydrated with JS. The Server Component output is never re-executed or hydrated in the browser.

When to Use Which

• Server Component (default): fetching data, reading from a database, using API keys/secrets, rendering static or mostly-static UI, reducing bundle size.
• Client Component ('use client'): useState/useReducer, useEffect, event handlers (onClick, onChange), browser APIs, context providers, third-party UI libraries that touch the DOM.

Common Pitfalls

• Marking a whole page 'use client' because of one interactive button — push 'use client' down to that button only, not the entire page.
• Importing a Server Component into a Client Component doesn't work the way you'd expect — pass the Server Component in as children or a prop instead of importing it directly.
• Fetching secrets inside a Client Component leaks them into the browser bundle. Keep API keys and DB calls in Server Components only.
• Forgetting next: { revalidate } on fetch calls, which silently opts routes into fully static rendering when you actually wanted fresh data.

Default to Server Components everywhere. Only add 'use client' at the smallest leaf component that truly needs interactivity — your bundle size (and your users) will thank you.

Debounce: wait until the storm passes

A debounced function delays running until events stop coming for a set period. Every new event resets the timer, so it fires only once, after things go quiet.

Use it when you only care about the final state:

• Search-as-you-type (call the API after the user stops typing)
• Validating a field after the user finishes editing
• Autosaving a draft once edits pause

function debounce(fn, delay = 300) {
  let timer;
  return (...args) => {
    clearTimeout(timer);
    timer = setTimeout(() => fn.apply(this, args), delay);
  };
}

const search = debounce((q) => fetch(`/api/search?q=${q}`), 300);
input.addEventListener('input', (e) => search(e.target.value));

Type "laravel" quickly and only one request goes out — 300 ms after the last keystroke.

Throttle: run at a steady rate

A throttled function runs at most once per interval, no matter how many events fire. It doesn't wait for quiet — it guarantees a regular cadence.

Use it when you want periodic updates during a continuous stream:

• Updating a scroll-progress bar
• Recomputing layout on resize
• Rate-limiting rapid clicks

function throttle(fn, interval = 200) {
  let last = 0;
  return (...args) => {
    const now = Date.now();
    if (now - last >= interval) {
      last = now;
      fn.apply(this, args);
    }
  };
}

const onScroll = throttle(() => updateProgressBar(), 200);
window.addEventListener('scroll', onScroll);

Scroll for 3 seconds and the bar updates ~15 times (every 200 ms), not on all 100+ scroll events.

Which one do you need?

Ask yourself: do you want the result after activity settles, or during it?

• "After it settles" → debounce (search, autosave, validation).
• "At a steady rate while it happens" → throttle (scroll, resize, drag).

In production, reach for a battle-tested implementation like lodash.debounce / lodash.throttle — they handle leading/trailing edges, cancellation, and maxWait for you.

A query that feels instant on 1,000 rows can crawl on 1,000,000. The usual reason: the database is doing a full table scan — reading every row to find the few you asked for. An index fixes that.

Without an index: a full table scan

SELECT * FROM users WHERE email = 'ann@example.com';

With no index on email, the engine reads every row and compares email. On a large table that is O(n) work.

With an index: a lookup

CREATE INDEX idx_users_email ON users (email);

An index is a sorted structure (usually a B-tree). The engine now navigates straight to the matching rows in about O(log n) — a handful of reads instead of millions.

Read the plan with EXPLAIN

EXPLAIN SELECT * FROM users WHERE email = 'ann@example.com';

• type = ALL (and "Using where") means a full scan — slow.
• type = ref or const with a key listed means the index is used — good.

Composite indexes follow a left-to-right rule

CREATE INDEX idx_orders_user_status ON orders (user_id, status);

This helps WHERE user_id = ? and WHERE user_id = ? AND status = ?, but not WHERE status = ? on its own — a query must use a left prefix of the indexed columns.

When an index does NOT help

• WHERE YEAR(created_at) = 2026 — wrapping the column in a function defeats the index. Use a range instead: created_at >= '2026-01-01' AND created_at < '2027-01-01'.
• LIKE '%term' with a leading wildcard cannot use a normal index.
• Very low-selectivity columns (like a boolean) — a scan is sometimes cheaper than the index.

Key takeaways

• No index means a full scan (O(n)); the right index means a lookup (O(log n)).
• Index the columns you filter, join and sort on — not every column (indexes cost writes and storage).
• Use EXPLAIN to confirm the index is actually used.
• Keep filters sargable: never wrap an indexed column in a function.

SQL injection is one of the most dangerous security vulnerabilities. Here's how to prevent it.

❌ Never Do This

// VULNERABLE CODE - DO NOT USE!
$userId = $_GET['id'];
$query = "SELECT * FROM users WHERE id = $userId";
$result = mysqli_query($conn, $query);

An attacker can inject: ?id=1 OR 1=1 to access all records!

✅ Use Prepared Statements (MySQLi)

$userId = $_GET['id'];
$stmt = $conn->prepare("SELECT * FROM users WHERE id = ?");
$stmt->bind_param("i", $userId);
$stmt->execute();
$result = $stmt->get_result();

✅ Use PDO with Prepared Statements

$userId = $_GET['id'];
$stmt = $pdo->prepare("SELECT * FROM users WHERE id = :id");
$stmt->execute(['id' => $userId]);
$user = $stmt->fetch();

✅ Laravel Query Builder (Automatic Protection)

$userId = request('id');
$user = DB::table('users')->where('id', $userId)->first();
// or
$user = User::find($userId);

Warning: Raw Queries

Even in Laravel, be careful with raw queries:

// ❌ Still vulnerable
DB::select("SELECT * FROM users WHERE id = " . $userId);

// ✅ Use bindings
DB::select("SELECT * FROM users WHERE id = ?", [$userId]);

Best Practices

1. Always use parameterized queries
2. Never concatenate user input into SQL
3. Use ORM/Query builders when possible
4. Validate and sanitize input
5. Apply principle of least privilege to database users

Real-World Impact

In 2023, SQL injection attacks accounted for 30% of all web application breaches.

Don't be a statistic - protect your applications!

Multi-stage builds allow you to create smaller, more secure Docker images by separating build and runtime environments.

The Problem

Traditional Dockerfile includes build tools in the final image:

FROM node:18
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build
CMD ["node", "dist/index.js"]

Result: ~1GB image with unnecessary build dependencies!

The Solution: Multi-Stage Build

# Build stage
FROM node:18 AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# Production stage
FROM node:18-alpine
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
CMD ["node", "dist/index.js"]

Result: ~200MB image with only runtime dependencies!

Benefits

• Smaller images: 5-10x size reduction
• Faster deployments: Less data to transfer
• Better security: Fewer attack surfaces
• Cleaner production: No build tools in production

For Laravel Applications

# Composer dependencies
FROM composer:2 AS composer
WORKDIR /app
COPY composer.* ./
RUN composer install --no-dev --optimize-autoloader

# Node assets
FROM node:18 AS node
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# Production
FROM php:8.3-fpm-alpine
WORKDIR /var/www
COPY --from=composer /app/vendor ./vendor
COPY --from=node /app/public/build ./public/build
COPY . .

Flow Diagram

Multi-stage builds are a Docker best practice that every developer should use!

PHP 8.4 introduces property hooks, a powerful feature that allows you to add custom logic when getting or setting properties.

Basic Example

class User
{
    public string $name {
        get => strtoupper($this->name);
        set => ucfirst($value);
    }
}

$user = new User();
$user->name = 'john doe';
echo $user->name; // Output: JOHN DOE

Computed Properties

Create virtual properties without backing storage:

class Rectangle
{
    public function __construct(
        public float $width,
        public float $height
    ) {}

    public float $area {
        get => $this->width * $this->height;
    }
}

Validation in Setters

class Product
{
    private float $_price;

    public float $price {
        get => $this->_price;
        set {
            if ($value < 0) {
                throw new InvalidArgumentException('Price must be positive');
            }
            $this->_price = $value;
        }
    }
}

Benefits

• ✅ Cleaner than __get() and __set() magic methods
• ✅ Better IDE support and static analysis
• ✅ More explicit and readable code
• ✅ Type-safe property access

Property hooks make PHP objects more powerful while maintaining backward compatibility!

When working with Laravel's Eloquent ORM, one of the most common performance killers is the N+1 query problem. It appears the moment you load a collection of models and then touch a relationship inside a loop.

The N+1 problem

$posts = Post::all();            // 1 query

foreach ($posts as $post) {
    echo $post->author->name;    // +1 query PER post
}

Load 50 posts and you fire 51 queries: one for the posts, plus one for every author. It is invisible in code review but deadly under load.

The fix: eager loading with with()

$posts = Post::with('author')->get();   // 2 queries total

foreach ($posts as $post) {
    echo $post->author->name;            // no extra queries
}

Laravel runs one query for posts and a single WHERE author_id IN (...) for all authors - 2 queries no matter how many posts.

Nested & multiple relationships

// Multiple relations
$posts = Post::with(['author', 'comments'])->get();

// Nested relations (dot notation)
$posts = Post::with('comments.user')->get();

// Constrain a relation with a closure
$posts = Post::with(['comments' => fn ($q) => $q->latest()->limit(5)])->get();

Load only the columns you need

$posts = Post::with('author:id,name')->get();

Selecting id,name keeps the payload small - just always include the foreign key (id) or the relation will not match.

Eager load after the fact

Already have the collection? Load relationships afterwards with load():

$posts = Post::all();
$posts->load('author');

Catch N+1 automatically

Enable strict mode in a service provider so lazy loading throws during development:

use Illuminate\Database\Eloquent\Model;

Model::preventLazyLoading(! app()->isProduction());

Key takeaways

• with() eager-loads upfront (2 queries); load() eager-loads an existing collection.
• Always eager-load any relationship you touch inside a loop.
• Use column selection and closures to load only what you need.
• Turn on preventLazyLoading in dev to catch N+1 before it ships.

Modern JavaScript uses async/await for handling asynchronous operations. Here are the best practices:

1. Always Handle Errors

async function fetchUserData(userId) {
    try {
        const response = await fetch(`/api/users/${userId}`);
        const data = await response.json();
        return data;
    } catch (error) {
        console.error('Failed to fetch user:', error);
        throw error;
    }
}

2. Parallel Execution

Don't await in sequence when you can run in parallel:

// ❌ Slow - Sequential
const user = await fetchUser();
const posts = await fetchPosts();
const comments = await fetchComments();

// ✅ Fast - Parallel
const [user, posts, comments] = await Promise.all([
    fetchUser(),
    fetchPosts(),
    fetchComments()
]);

3. Promise.allSettled for Independent Operations

const results = await Promise.allSettled([
    fetchUser(),
    fetchPosts(),
    fetchComments()
]);

results.forEach(result => {
    if (result.status === 'fulfilled') {
        console.log('Success:', result.value);
    } else {
        console.log('Error:', result.reason);
    }
});

4. Avoid Async in Loops

// ❌ Bad
for (const id of userIds) {
    await processUser(id);
}

// ✅ Good
await Promise.all(userIds.map(id => processUser(id)));

Key Takeaways

• Always use try/catch for error handling
• Use Promise.all() for parallel operations
• Consider Promise.allSettled() for independent tasks
• Avoid awaiting inside loops

Async/await makes asynchronous code look synchronous, but understanding Promises is still crucial!