DEV Community: Saqueib Ansari

Lerd vs Docker Desktop for Laravel Teams Using AI Agents

Saqueib Ansari — Wed, 02 Sep 2026 04:17:04 +0000

If your Laravel team is choosing between Lerd and Docker Desktop, the decision is simpler than it first looks.

Use Lerd when your main goal is fast local Laravel development with low friction, per-project runtime switching, and direct AI-agent access to the environment. Use Docker Desktop when local development must stay close to your production container topology, or when your team already treats Compose files as part of the application contract.

That is the short version. The longer version is that these tools optimize for different kinds of correctness.

Lerd optimizes for developer speed on PHP projects. Docker Desktop optimizes for container parity and broader ecosystem consistency. If you force them into the same mental model, the comparison gets muddy. If you compare them by what Laravel teams actually care about, the tradeoffs become obvious.

Officially, Lerd presents itself as a Podman-native local PHP environment for Linux and macOS with automatic .test domains, per-project PHP versions, built-in services, and a built-in MCP server for AI assistants. Docker, on the other hand, continues to push Docker Desktop as the mainstream container workflow and now also ships MCP Toolkit in Docker Desktop 4.62+ for managing MCP servers and connecting them to AI agents. Those are not cosmetic differences. They affect setup speed, team habits, and how much local complexity developers have to carry every day.

These tools solve different primary problems

The fastest way to make a bad choice here is to ask, “Which one is better?” The useful question is, “Better for what?”

Lerd is trying to be the thing Laravel Herd users wish they had on Linux, with more openness and more agent-aware workflows. It is explicitly PHP-first. Its feature set is built around linked sites, automatic HTTPS, runtime switching, local services, framework-aware setup, logs, workers, and an MCP server that an assistant can use to manage the environment.

Docker Desktop is not trying to be a Laravel convenience layer. It is a container platform with a huge ecosystem, a stable Compose workflow, mature team habits, and much stronger alignment with production systems that already run in containers. If your app depends on PHP, Nginx, Redis, Meilisearch, a queue worker, a scheduler, and a custom sidecar, Docker wants you to declare all of that explicitly and run it the same way across machines.

That difference matters because it changes what “local setup” even means.

With Lerd, local setup is usually: link the project, let the tool wire domains and services, switch PHP if needed, and start working.

With Docker Desktop, local setup is usually: clone the repo, install Docker Desktop, make sure the Compose stack is correct, understand volumes and ports, wait for images to build, and debug whatever host-container edge case your team has normalized.

Neither is wrong. They just reward different teams.

Setup speed and onboarding: Lerd is faster when the app is mostly Laravel

For pure Laravel teams, Lerd wins setup speed.

That is not because Docker Desktop is slow in some absolute sense. It is because Docker asks the team to be more explicit. Explicitness is good for parity, but it costs time. New developers have to understand container boundaries, exposed ports, build contexts, bind mounts, rebuilds, service readiness, and which tasks run inside containers versus on the host.

Lerd removes a lot of that ceremony. According to its current README, it links sites to .test domains, provisions HTTPS, supports per-project PHP and Node versions, bundles common local services, and offers framework-aware setup flows. For a Laravel-heavy repo, that means less bootstrapping and fewer local conventions to explain.

Where Lerd feels better on day one

The first-day experience is where Lerd is strongest.

A typical Laravel project does not need every developer to become a container mechanic. It needs PHP, a web server, a database, Redis, queue workers, HTTPS, and maybe Vite. If the tool can provide that with sensible defaults and minimal YAML, onboarding gets materially easier.

That matters even more for mixed-seniority teams. Senior developers often underestimate how much invisible Docker knowledge they have accumulated. Juniors do not see “standard container workflow.” They see ten moving parts and four different places an error could be hiding.

Lerd’s PHP-first ergonomics reduce that tax.

Where Docker Desktop still wins onboarding

Docker Desktop wins if the team already has a container-first culture.

If every service in the company runs through Compose or container manifests, the onboarding cost becomes part of a broader operational language. In that world, learning how your local app, queue, scheduler, nginx, and redis services map to production is useful, not overhead. The same Compose mental model also transfers more cleanly across Laravel, Node, Go, Python, and internal tooling.

So the onboarding question is not just speed. It is whether you want new hires to learn Laravel local tooling or containerized application structure on day one.

Runtime isolation and parity: Docker is heavier, but more honest

This is where Docker Desktop earns its complexity.

Lerd gives you per-project PHP isolation and local services with much less friction than a Docker stack. For many Laravel teams, that is enough. If one project needs PHP 8.2 and another needs 8.4, and each project needs its own Redis or database, Lerd covers the common case well without making every developer think about container orchestration all day.

But that is still not the same as full application parity.

Docker Desktop gives you the strongest guarantee that your local runtime shape can mirror production. Not just the PHP version, but the way services are networked, started, configured, mounted, and supervised. If production uses a specific PHP image, a specific extension layer, a specific queue worker container, and a specific service topology, Docker lets you keep that all in code.

That matters a lot when teams start saying things like:

“It works on my machine but not in CI.”
“The queue worker behaves differently in staging.”
“Search indexing only fails in the container build.”
“This extension exists locally but not in production.”

Those are exactly the problems container parity is supposed to reduce.

Lerd’s sweet spot

Lerd is a strong fit when your production environment is not so exotic that local developers need to mirror every container exactly. Most CRUD-heavy Laravel products fall into this category. They need sane PHP, common services, TLS, workers, and smooth day-to-day flow. They do not need every teammate to debug Linux-in-a-box before editing a controller.

For those teams, Docker often adds more ceremony than value.

Docker’s sweet spot

Docker Desktop becomes the better choice when local correctness depends on the container contract itself.

Examples:

You ship multiple app services with non-trivial networking.
You rely on a custom base image with compiled extensions.
You run the same image in CI, preview environments, and production.
Non-PHP services are first-class parts of the repo, not incidental dependencies.
You want every environment assumption declared in version-controlled Compose or image config.

That is the important distinction. Per-project PHP isolation is not the same thing as production parity. Lerd handles the first very well. Docker handles the second much better.

AI-agent access is no longer a Docker-only advantage

A year ago, a lot of teams would have assumed Docker had the stronger AI tooling story by default. That is no longer a safe assumption.

Lerd now ships a built-in MCP server specifically aimed at AI assistants managing the local environment. Its README explicitly lists environment operations like linking sites, managing services, running framework setup, switching runtimes, tailing logs, and working with databases through MCP.

That matters because AI-assisted development is moving past “generate code” and into “operate the local stack.” For Laravel teams using coding agents, the useful question is not whether an assistant can read files. It is whether the assistant can safely and directly do environment work that developers repeatedly forget or delay.

Lerd is opinionated here in a good way. It exposes a PHP-project-centric tool surface.

Docker has moved aggressively in this space too. Docker Desktop 4.62+ ships the MCP Toolkit, with profiles, a catalog, CLI management, and containerized MCP servers. Docker also documents Dynamic MCP, MCP Gateway, and sandboxed agent workflows. That is serious infrastructure, and it is broader than Lerd’s approach.

But broader does not always mean better for Laravel teams.

The practical difference

With Lerd, the MCP story is tied directly to the local PHP environment. The agent can manage the thing the Laravel developer actually cares about: sites, services, env setup, framework setup, logs, workers, and worktrees.

With Docker Desktop, the MCP story is more general-purpose and platform-level. It is powerful, but it asks you to think in terms of MCP profiles, cataloged servers, gateways, and containerized tooling. That is great if your team already lives comfortably inside Docker abstractions. It is more than some Laravel teams need.

So if your article title includes “teams using AI agents,” this is the honest comparison: Lerd is the more direct developer-experience play; Docker is the more extensible infrastructure play.

Day-to-day Laravel workflow: this is where teams feel the difference most

The best comparison is not feature checkboxes. It is what an ordinary Tuesday feels like.

A typical Lerd Tuesday

You pull a branch. The project comes up under a clean local domain. PHP is already aligned per project. Redis and the database are available. Queue and schedule visibility are integrated. You can switch runtimes or inspect logs without mentally stepping out of Laravel mode.

That is a good workflow for teams shipping app code quickly.

A typical Docker Desktop Tuesday

You pull a branch. Containers may rebuild. Compose services start in dependency order, or fail to. One developer’s bind mount performance is worse than another’s. Someone forgot to rebuild after changing extensions. The app itself might be perfectly fine, but the operational surface area is larger.

That sounds negative, but it is only half the story.

The upside is that when the stack is well-maintained, everyone is running the same declared environment. The worker, scheduler, web service, and support services all behave in a more predictable, code-defined way. That consistency becomes more valuable as the architecture becomes less Laravel-simple.

Concrete selection criteria

Pick Lerd if most of these are true:

Your repo is primarily a Laravel or PHP application.
Local developer speed matters more than exact container parity.
You want easy per-project PHP switching without maintaining images.
You want AI agents to operate the environment through a PHP-first MCP surface.
Your team includes developers who should not need deep Docker knowledge to be productive.

Pick Docker Desktop if most of these are true:

Compose files are already part of your team’s normal workflow.
Production runs in containers and local parity routinely saves you from bugs.
The repo includes multiple services beyond a standard Laravel app stack.
You need image-level control over extensions, binaries, startup flows, or service contracts.
Your AI tooling needs to fit a broader, containerized MCP and sandbox story rather than a Laravel-specific one.

My recommendation for Laravel teams in 2026

For most Laravel-first teams, I would start with Lerd.

That recommendation is not ideological. It is practical. Most teams do not get meaningful ROI from carrying full Docker complexity into local development for every project. They get slower onboarding, slower feedback loops, and a quiet normalization of environment friction that nobody likes but everybody tolerates.

Lerd looks like the sharper default when the application is mainly Laravel, the team wants quick per-project runtime control, and AI agents are part of the workflow. Its built-in MCP support is especially relevant now that local environment operations are becoming part of agent-assisted development rather than a separate human-only layer.

But I would not pretend Lerd replaces Docker Desktop universally.

If your production architecture is genuinely container-shaped, if your repo is more platform than app, or if your team already depends on Compose as shared truth, Docker Desktop still earns its place. In those environments, the extra weight is buying something real.

The mistake is choosing Docker because it feels more “serious,” or choosing Lerd because Docker annoyed somebody once. Use the tool that matches the actual failure mode you are trying to avoid.

If the failure mode is slow Laravel development, pick Lerd.

If the failure mode is environment drift across services and stages, pick Docker Desktop.

That is the real decision rule. Everything else is implementation detail.

Read the full post on QCode: https://qcode.in/lerd-vs-docker-desktop-laravel-teams-ai-agents/

The Review Loop Most Teams Miss With AI Coding Agents

Saqueib Ansari — Mon, 31 Aug 2026 05:19:36 +0000

Agentic development breaks down in review long before it breaks down in generation. Most teams fixate on prompts, model choice, or tool access, then run the review step like it is still a human-only workflow. That mismatch is expensive. You get noisy diffs, vague feedback, wasted test runs, and the worst outcome of all: agents that look productive while quietly increasing merge risk.

The missing piece is a review loop designed for agent output, not a lightly modernized human PR process. The core rule is simple: review the task contract, the diff, the selected evidence, and the recovery path as one system. If you only review code style, you will miss the real failure modes.

Start With Smaller Contracts, Not Better Prompts

Most agent review pain starts before any code exists. Teams hand an agent a broad ticket, let it roam the repo, then act surprised when the reviewer receives a 900-line mixed diff touching tests, docs, config, and three unrelated refactors. That is not an agent problem. That is a scoping failure.

A good agent task is narrow enough that a reviewer can answer three questions fast:

What was supposed to change?
Where is the evidence that it changed correctly?
What should stay untouched?

If your prompt cannot make those boundaries explicit, the review loop will be slow no matter how strong the model is.

What a reviewable agent task looks like

A reviewable task has four parts:

Scope: exact files, modules, or behaviors that may change.
Acceptance criteria: concrete outcomes, not vibes.
Validation path: the tests, scripts, or manual checks the agent should run.
Stop conditions: what the agent must not “helpfully” refactor.

That turns the agent from a free-roaming contributor into a bounded implementation worker.

Task: Add request ID propagation to API logs for checkout flows.

Allowed scope:
- app/Http/Middleware/RequestId.php
- app/Logging/*
- tests/Feature/Checkout/*

Acceptance criteria:
- Every checkout request gets a request_id in structured logs.
- Existing log fields remain unchanged.
- No changes to unrelated auth or billing code.

Validation:
- Run checkout feature tests.
- Run logging formatter unit tests.
- Show one sample log line from a passing test.

Stop conditions:
- Do not rename logging helpers.
- Do not reformat unrelated tests.
- Do not update dependencies.

That prompt is not “fancier.” It is just more reviewable.

The practical payoff is huge. Smaller contracts produce smaller diffs. Smaller diffs make reviewers faster. Faster reviews create tighter correction loops. That is the real throughput gain in agentic development, not shaving 15 seconds off generation time.

Review the Diff Like a Failure Analyst

Human reviewers often read PRs top to bottom and infer intent from the code. That is tolerable when the author shares your context and habits. With agents, it is the wrong default.

Agent review should start from the assumption that the code may be locally plausible but globally wrong. So the reviewer’s first job is not admiration. It is failure-mode detection.

The three-pass diff method

Use a consistent reading order:

Pass 1: shape check
Read filenames, changed surfaces, and diff size before reading line details. Ask whether the code changed where it was supposed to change.

If the task was “tighten validation” and the diff touches CI config, helpers, and docs, you already have a process problem. Do not review line-by-line noise before challenging the scope.

Pass 2: semantic check
Now read the logic. Ignore style nits unless they hide behavior. Focus on:

state transitions n- fallback paths
error handling
implicit assumptions
interface changes
deleted guards
silent defaults

Agent code often looks neat while smuggling in a subtle behavioral shift. Reviewers need to hunt for that explicitly.

Pass 3: evidence check
Finally, compare the diff against the attached proof: tests, logs, screenshots, command output, or trace steps. If the evidence does not line up with the claimed change, treat the task as incomplete.

This three-pass method reduces a common anti-pattern: reviewers burning time on cosmetic comments while missing that the agent solved the wrong problem.

What to flag aggressively

There are a few agent-specific smells that deserve almost zero tolerance:

Drive-by refactors in untouched areas.
Renames without payoff that expand review scope.
Tests updated to fit broken behavior instead of validating intended behavior.
Default-case handling added without product or domain justification.
Speculation in comments like “ensure compatibility” with no evidence.
Large generated helper abstractions introduced for a tiny task.

None of these are automatically wrong. But each one raises review cost faster than it raises code quality.

If you want agent output to move quickly through review, you have to reward one trait above all others: disciplined boringness. Small, direct changes beat clever generalized scaffolding almost every time.

Stop Running the Entire Test Suite for Every Agent Change

One of the easiest ways to waste time in agentic workflows is to respond to every diff with maximum test blast radius. Teams do this because they do not trust the output, which is understandable. But the fix is not “run everything forever.” The fix is make test selection explicit and auditable.

A useful review loop asks the agent to propose a validation set, then lets the reviewer approve, trim, or expand it.

Test selection should be part of the contract

The agent should not just say “tests pass.” It should say which tests it ran, why those tests were chosen, and what remains unverified.

That sounds like this:

# Focused validation for a logging change
php artisan test tests/Feature/Checkout/RequestIdLoggingTest.php
php artisan test tests/Unit/Logging/JsonFormatterTest.php

And the review note should explain the gap plainly:

Validated request ID creation and log serialization.
Did not run the full checkout suite because payment flow logic was unchanged.
Did not run browser tests because no UI path changed.

That statement is valuable because it is falsifiable. A reviewer can disagree with the test boundary and ask for broader coverage. What matters is that the boundary is visible.

Pick the cheapest test that proves the claim

This is where many teams stay sloppy. They confuse “more tests” with “better evidence.” In practice, the best review loops optimize for the cheapest trustworthy proof.

Examples:

For a serializer change, a narrow unit test is usually stronger than a full-stack feature test.
For a routing or middleware change, one targeted feature test often beats dozens of unrelated integration tests.
For UI flows, a Playwright happy-path plus one failure-path check often gives more signal than a broad screenshot sweep.

Official references are worth keeping close here because they encourage discipline, not cargo culting: Laravel HTTP tests, Pytest test selection, and Playwright best practices.

The review standard should be: does this evidence directly prove the acceptance criteria, and is it proportionate to the risk?

If not, either the tests are too weak or the scope is too broad.

Make Prompts and Decisions Traceable

A surprising amount of review waste comes from missing provenance. The reviewer sees a diff and maybe a passing test output, but has no idea what the agent was actually told, what constraints it followed, or which corrections happened mid-flight.

That creates false positives in both directions. Reviewers either reject correct work because the reasoning trail is missing, or approve fragile work because the generated code looks confident.

The fix is not full transcript dumping. Nobody wants a novel attached to every PR. The fix is traceable compression.

What to preserve

For each agent task, keep these artifacts visible in the review loop:

the original task prompt or normalized task contract
acceptance criteria
allowed scope
files changed
tests run
follow-up corrections made after first output

That is enough context to understand why the code exists and whether the final state still matches the original request.

A compact review record can be as simple as this:

{
  "task": "Add request ID propagation to checkout logs",
  "scope": [
    "app/Http/Middleware/RequestId.php",
    "app/Logging/JsonFormatter.php",
    "tests/Feature/Checkout/RequestIdLoggingTest.php"
  ],
  "acceptance_criteria": [
    "Every checkout request includes request_id in logs",
    "Existing log fields preserved"
  ],
  "tests_run": [
    "php artisan test tests/Feature/Checkout/RequestIdLoggingTest.php",
    "php artisan test tests/Unit/Logging/JsonFormatterTest.php"
  ],
  "corrections": [
    "Removed unrelated helper rename",
    "Replaced broad integration test with focused formatter test"
  ]
}

That structure matters because it makes review disagreement productive. Instead of “this feels off,” the reviewer can say “your scope breached the contract” or “your evidence does not cover criteria 2.”

This is also where teams should be opinionated about tooling. If your agent platform cannot preserve task contracts and test evidence cleanly, your review loop will degrade into screenshots, pasted logs, and memory. That does not scale.

Know When to Restart Instead of Patch

The biggest productivity trap in agentic development is sunk-cost editing. A team gets a mostly-wrong agent output, notices a few issues, and starts patching it through repeated follow-ups: tweak this method, undo that abstraction, rewrite the test, restore the old interface, keep the new logging, but remove the helper, but preserve the formatter. After three or four rounds, nobody is reviewing the original task anymore. They are untangling history.

At that point, a restart is usually cheaper.

Restart conditions should be explicit

You should restart the agent instead of iterating when any of these are true:

The diff breached scope in multiple unrelated places.
The wrong abstraction now shapes the rest of the implementation.
Tests were rewritten around incorrect behavior.
The agent misunderstood a core domain rule.
The cleanup instructions are longer than a fresh task contract.

This is not a failure of the reviewer. It is good operational judgment.

Think of it this way: once the correction path becomes more complex than the original task, you are no longer reviewing a change. You are performing recovery. Recovery deserves a reset.

A restart prompt should be stricter, not longer

Bad recovery prompts read like diff archaeology. Good restart prompts restore the narrow contract:

Restart from HEAD.

Implement only request ID propagation for checkout logs.
Do not introduce new helpers or rename existing logging methods.
Keep changes limited to middleware, formatter, and checkout logging tests.
Validate with the two specified tests only.
Show final diff summary before stopping.

This works because it removes historical baggage. The new run is easier to review than the patched remains of the old one.

Teams that get strong results with agents are not the ones who never restart. They are the ones who restart early enough that review stays cheap.

The Real Review Loop

A working agentic review loop is not “agent writes code, human reads PR.” It is a tighter system:

Define a small, reviewable contract.
Require bounded implementation and explicit stop conditions.
Review the diff in passes: shape, semantics, evidence.
Validate with the smallest trustworthy test set.
Preserve prompt and correction traceability.
Restart quickly when the task drift is structural.

That loop is faster because it removes ambiguity, not because it removes humans.

The broader point is worth saying plainly: agentic development does not reduce the need for engineering judgment. It changes where judgment matters most. The best teams spend less energy hand-writing code and more energy designing reviewable tasks, selecting evidence, and killing bad branches early.

If your current process treats agent output like a human junior’s PR with extra speed, you will keep getting false positives and bloated review cycles. Build the loop around scope, evidence, and reset discipline instead.

The decision rule is simple: if a reviewer cannot verify the task in a few minutes from contract, diff, and evidence, the loop is broken before the merge is.

Read the full post on QCode: https://qcode.in/the-agentic-development-review-loop-most-teams-are-missing/

Handling Laravel Event Storms with Debounced Queued Listeners

Saqueib Ansari — Sun, 30 Aug 2026 05:15:57 +0000

Most Laravel queue pain is self-inflicted. The framework is usually not the problem. The problem is treating every event like it deserves its own fully independent queued job, even when ten events in a row all mean the same thing: recompute the latest state once the noise settles.

That pattern shows up everywhere. A webhook provider retries aggressively. A document editor autosaves every few seconds. A dashboard logs analytics faster than your workers can roll them up. A preference update triggers notification fan-out three times before the user stops clicking. If you enqueue one heavy listener per event, the queue becomes a graveyard of stale intermediate work.

The fix is to stop modeling these flows as one-event-one-side-effect. For event storms, the better model is: mark the aggregate dirty, wait for a quiet window, then process the latest committed state once. Laravel has all the pieces for this: queued listeners, delayed jobs, afterCommit(), cache-backed atomic locks, and queue middleware like WithoutOverlapping. What it does not give you is a first-class debounce abstraction. You have to build the pattern deliberately.

This tutorial walks through a production-grade debounce setup for Laravel event listeners, where it works, where it fails, and how to keep it from turning into a race-condition machine.

Why queued listeners melt down under event storms

A normal queued listener is a good fit when each event represents a distinct unit of work. OrderShipped sending one email is fine. PodcastPublished invalidating one cache key is fine. The problem starts when the events are noisy but the downstream work only cares about the eventual result.

Imagine an integration that emits five OrderWebhookReceived events in twelve seconds for the same order. The first event says the order was created. The second adds metadata. The third updates shipping lines. The fourth attaches tax details. The fifth confirms payment. If every event kicks off a queued projection sync, your workers perform the same expensive fetch and write cycle multiple times, often on obsolete snapshots.

That creates three classes of waste.

First, there is raw queue overhead. Every job must be serialized, stored, popped, hydrated, executed, acknowledged, or retried. Second, there is logical waste. You do expensive work on states that will be replaced moments later. Third, there is risk. Under bursty load, job ordering, transaction timing, and overlapping execution can produce subtle bugs that only appear in production.

This is why “just add more workers” is a weak answer. More workers help throughput, but they do not fix duplicated intent. They only let your system waste resources faster.

The better question is: what is the actual unit of work? In these stormy flows, it is usually not “handle each event.” It is “process the final stable state for aggregate X.” Once you frame it that way, debounce becomes the obvious tool.

Debounce is not the same as uniqueness or throttling

A lot of Laravel implementations labeled debounce are not actually debounced.

If you dispatch a job with delay(now()->addSeconds(10)) and protect it with ShouldBeUnique, you get something useful, but not a real debounce. What you really built is a coarse throttle: the first event schedules a job, and later events within that period are ignored. That can reduce noise, but it does not push the execution window forward each time new activity arrives.

Real debounce means the timer resets on every new event.

For queue-driven systems, that usually requires these three pieces:

A resource-scoped key such as tenant:4:order:9821 or document:55.
A quiet-until timestamp that gets updated whenever another event arrives.
A single flush job that checks whether the quiet period has actually elapsed before it performs the expensive work.

That third piece is where most articles hand-wave. The delay on dispatch is only an optimization to avoid waking the job too early. The real debounce behavior lives inside the job, because the job must inspect fresh debounce state and decide whether to execute or release itself back onto the queue.

The other important distinction is between payload-first and state-first processing. For event storms, payload-first handling is often the wrong abstraction. Instead of serializing the exact event body through the queue and trying to preserve every intermediate mutation, let the queue carry only identifiers, then reload the current database state at execution time.

That is the version that scales and survives retries.

The production pattern: listener marks dirty, job waits for quiet

The cleanest design is to keep the listener cheap and let a dedicated job do the heavy lifting.

The listener should do four things:

Derive a debounce key for the aggregate.
Push the quiet-until timestamp into shared cache.
Ensure only one flush job is scheduled for that aggregate.
Dispatch after commit when the event is tied to database writes.

Here is a practical listener for webhook bursts hitting the same order:

<?php

namespace App\Listeners;

use App\Events\OrderWebhookReceived;
use App\Jobs\FlushOrderState;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Support\Facades\Cache;

class DebounceOrderWebhookBurst implements ShouldQueue
{
    public int $tries = 3;

    public function handle(OrderWebhookReceived $event): void
    {
        $orderId = $event->orderId;
        $tenantId = $event->tenantId;
        $debounceSeconds = 20;

        $prefix = "debounce:tenant:{$tenantId}:order:{$orderId}";
        $quietUntilKey = "{$prefix}:quiet_until";
        $scheduledKey = "{$prefix}:scheduled";

        Cache::put(
            $quietUntilKey,
            now()->addSeconds($debounceSeconds)->timestamp,
            now()->addMinutes(15)
        );

        $scheduled = Cache::add(
            $scheduledKey,
            true,
            now()->addMinutes(15)
        );

        if ($scheduled) {
            FlushOrderState::dispatch($tenantId, $orderId)
                ->delay(now()->addSeconds($debounceSeconds))
                ->afterCommit();
        }
    }
}

There are a few non-obvious choices here.

Cache::put() updates the quiet window every time the listener runs. That is the timer reset. Cache::add() works as the “schedule once” guard, because it only succeeds if the key does not already exist. The queue only gets one flush job for the active burst.

And yes, afterCommit() matters. Laravel’s queue documentation is explicit about jobs and queued listeners inside database transactions: a worker can pick up the job before the parent transaction commits unless you defer dispatch until after commit. If your flush job reloads models or relationships, skipping this is how you end up with missing rows and impossible race conditions.

Now the actual debounce logic sits in the job:

<?php

namespace App\Jobs;

use App\Models\Order;
use App\Services\OrderStateSync;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Queue\Queueable;
use Illuminate\Queue\Middleware\WithoutOverlapping;
use Illuminate\Support\Facades\Cache;

class FlushOrderState implements ShouldQueue
{
    use Queueable;

    public int $tries = 25;

    public function __construct(
        public int $tenantId,
        public int $orderId,
    ) {}

    public function middleware(): array
    {
        return [
            (new WithoutOverlapping("tenant:{$this->tenantId}:order:{$this->orderId}:flush"))
                ->releaseAfter(5)
                ->expireAfter(120),
        ];
    }

    public function handle(OrderStateSync $sync): void
    {
        $prefix = "debounce:tenant:{$this->tenantId}:order:{$this->orderId}";
        $quietUntilKey = "{$prefix}:quiet_until";
        $scheduledKey = "{$prefix}:scheduled";

        $quietUntil = Cache::get($quietUntilKey);

        if ($quietUntil && now()->timestamp < $quietUntil) {
            $this->release(($quietUntil - now()->timestamp) + 1);
            return;
        }

        $order = Order::query()
            ->where('tenant_id', $this->tenantId)
            ->findOrFail($this->orderId);

        $sync->fromCurrentState($order->fresh(['lines', 'payments', 'shipments']));

        Cache::forget($quietUntilKey);
        Cache::forget($scheduledKey);
    }
}

This is the real debounce. The job wakes up, checks whether the stream has gone quiet, and if not, releases itself with a new delay. Only when the quiet window has actually passed does it run the expensive sync.

WithoutOverlapping is worth calling out. It protects against duplicate execution if two copies of the job exist or if the worker retries in awkward timing windows. Laravel’s docs note that this middleware uses cache-backed atomic locks and supports releaseAfter() and expireAfter(). In production, expireAfter() is not optional. If a worker dies while holding the lock and the lock never expires, your aggregate can get wedged indefinitely.

Applying the same pattern to autosave, analytics, and notifications

The order example is not special. The same structure works anywhere the queue only needs the latest stable state.

Autosave-derived content

This is one of the best fits for debounce. Editors are intentionally noisy. Every small pause can trigger DocumentAutosaved, but your expensive work usually is not “handle every autosave.” It is “rebuild preview, outline, embeddings, or AI summary from the latest saved document.”

The listener and job shape stay the same. Only the aggregate key changes.

DocumentPreviewFlush::dispatch($document->id)
    ->delay(now()->addSeconds(10))
    ->afterCommit();

The flush job should reload the document from the database, not trust a serialized editor payload from ten events ago. That is especially important if your downstream work involves indexing or AI pipelines, because stale payloads cost money as well as latency.

Analytics rollups

Raw event capture and aggregated analytics are different concerns. If you need raw clicks for audit or replay, store them immediately. But the expensive rollup job that recomputes counters, dashboard tiles, or warehouse sync should usually debounce by tenant, campaign, or session bucket.

This is where teams accidentally turn analytics into background DDoS. One bursty user journey can generate enough “important” events to keep a queue busy doing nothing novel.

If the rollup can be recomputed from durable rows, debounce it.

Notification fan-out

This one needs more judgment. Debounce only when the eventual side effect is stateful and replaceable.

Good candidates:

Regenerating a digest email draft
Updating unread counts or badges
Recomputing a recommendation list
Refreshing a “team status changed” summary card

Bad candidates:

Sending a legally required email per event
Auditable security notifications
User-visible messages where each event is semantically distinct

The rule is blunt: if dropping intermediate executions would change the meaning of what the user should receive, do not debounce it.

Failure modes that matter more than the happy path

The happy path is easy. The failure modes are where this pattern earns or loses trust.

Using the wrong cache store

Debounce keys and overlap locks must live in a shared cache if you run multiple workers or multiple app nodes. Redis is the usual answer. A local array or file cache turns your debounce guarantees into per-process fiction.

Laravel’s cache docs on atomic locks make the same assumption clear: all servers need to talk to the same central cache store.

Forgetting transaction boundaries

If your listener is triggered during a transaction and your flush job reloads models immediately, you can observe partially committed state or missing relations. This is exactly the problem afterCommit() exists to solve. Use it by default when writes and dispatch live in the same request lifecycle.

Confusing unique jobs with real debounce

ShouldBeUnique is helpful for suppression. It is not enough when each new event should reset the clock. If you need quiet-window semantics, you need a mutable timestamp and a job that can reschedule itself.

Losing the final flush after a crash

If the worker crashes after the expensive work succeeds but before the cleanup keys are deleted, you may get a stale scheduled flag. If this flow is business-critical, add one more guard: let the listener treat very old scheduled keys as recoverable, or store richer metadata such as last-scheduled-at and last-processed-at.

You do not need that complexity for every feature, but you should think about it for billing, inventory, or external sync paths.

Letting the job carry too much payload

The queue should usually carry aggregate IDs and maybe a tenant ID. Large payloads make retries heavier, stale snapshots more likely, and deployments more brittle. Debounce patterns work best when the job is a coordinator around durable state, not a transport vessel for ever-changing event bodies.

Testing the behavior you actually care about

Most tests for queued listeners are too shallow. They assert that a job was dispatched and stop there. That misses the whole point.

What you care about is not “did we queue something?” What you care about is:

repeated events schedule one useful flush path,
the quiet window moves forward on each event,
the job releases itself while the stream is still noisy,
the final execution uses current persisted state,
overlap protection does not wedge the aggregate.

A good test should simulate a burst, not a single event. It should also test deletion and retry behavior. For example, if the aggregate disappears before the flush runs, should the job fail loudly, noop quietly, or clean up keys and exit? There is no universal answer, but there should be a deliberate one.

For most application-level debounce listeners, my bias is:

fail loudly for core domain data that should exist,
noop quietly for user-deleted content where disappearance is normal,
always clean up the debounce state when the terminal behavior is reached.

That keeps the queue honest and avoids zombie debounce keys.

What I would ship in a real Laravel app

If I were adding this to a production codebase today, the implementation rules would be simple.

Keep the listener tiny. Let it update the quiet timestamp and schedule one flush job.

Make the flush job recompute from the latest committed state, not from event snapshots.

Use afterCommit() unless you can prove the dispatch is outside any transactional write path.

Use Redis or another shared cache backend for both debounce keys and overlap locks.

Set expireAfter() on WithoutOverlapping so a dead worker does not freeze an aggregate forever.

Instrument the result. Measure how many raw events map to one final flush. If the ratio is still close to one-to-one, your debounce window is too short or the aggregate key is too granular.

The bigger lesson is architectural: events describe that something happened; they do not automatically define the right unit of background work. When a burst of events all implies one eventual recomputation, model that directly. Laravel makes this pattern straightforward once you stop forcing the queue to process noise as if it were signal.

If your Horizon dashboard is full of repeated jobs for the same order, document, or tenant, do not scale the workers first. Collapse the storm first. That is the cheaper fix, the faster fix, and usually the more correct one.

Read the full post on QCode: https://qcode.in/debounced-laravel-listeners-for-event-storms-that-hit-queues/

Benchmarking Filament Admin Screens Without Guessing

Saqueib Ansari — Fri, 28 Aug 2026 06:11:59 +0000

Slow Filament screens are usually blamed on the wrong layer. Teams upgrade packages, swap columns, or remove filters before they know whether the real cost is database work, Livewire hydration, authorization checks, or table configuration. That is how you waste a week and still keep a slow screen.

The better approach is simple: benchmark one screen, break the cost into parts, then change the part that is actually expensive. Filament sits on top of Laravel and Livewire, so a slow admin page is rarely a single-problem system. You need a workflow that makes the bottleneck obvious before you touch the UI.

This tutorial is that workflow. It is practical, repeatable, and biased toward real codebases where the screen already exists and users already think it feels slow.

Start with one repeatable benchmark

Do not begin with your whole panel. Pick one screen that people actually complain about: a resource index with heavy filters, an edit page with relation managers, or a dashboard that loads too many widgets at once.

Then make the benchmark repeatable:

use the same local database snapshot each run
test with a realistic row count, not ten seed records
measure a cold page load and one warm interaction
close unrelated browser tabs and disable noisy extensions
write the numbers down before changing code

For most Filament screens, I want three checkpoints:

initial page load
a common interaction like search, filter, or sort
opening a row action or modal

If you do not measure those separately, you will blur together very different costs.

What to capture

At minimum, record these numbers for each checkpoint:

total request time
SQL query count
total SQL time
response payload size
number of Livewire requests triggered

That already tells you a lot. A page with 220 queries and 900 ms of SQL time is a database problem until proven otherwise. A page with modest SQL time but huge payloads and repeated requests is usually a Livewire or component-state problem. A page with acceptable backend timings but sluggish interactions may be rendering too much UI or doing too much per row.

A lightweight way to start is adding Server-Timing and query metrics to local requests:

<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Database\Events\QueryExecuted;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\DB;
use Symfony\Component\HttpFoundation\Response;

class ProfileAdminRequest
{
    public function handle(Request $request, Closure $next): Response
    {
        if (! str_starts_with($request->path(), 'admin')) {
            return $next($request);
        }

        $queryCount = 0;
        $queryTimeMs = 0;
        $startedAt = hrtime(true);

        DB::listen(function (QueryExecuted $query) use (&$queryCount, &$queryTimeMs) {
            $queryCount++;
            $queryTimeMs += $query->time;
        });

        /** @var Response $response */
        $response = $next($request);

        $totalMs = (hrtime(true) - $startedAt) / 1_000_000;

        $response->headers->set(
            'Server-Timing',
            sprintf('app;dur=%.1f, sql;dur=%.1f, queries;desc="%d"', $totalMs, $queryTimeMs, $queryCount)
        );

        return $response;
    }
}

Now Chrome DevTools gives you backend timing hints without turning every request into a detective story.

If you want richer local visibility, Laravel Telescope is still one of the most useful ways to inspect queries, requests, jobs, and exceptions in one place. For Filament-specific debugging, it is often enough.

Add instrumentation where Filament actually spends time

A Filament admin page usually burns time in four places:

database queries
per-record authorization or visibility logic
Livewire hydration and payload size
table or form configuration that does more work than the user needs

That means your benchmark has to go beyond total duration.

Database timing first

Laravel already gives you enough primitives to catch obvious waste. In addition to DB::listen, use whenQueryingForLongerThan in local or staging to flag suspicious requests early:

<?php

namespace App\Providers;

use Illuminate\Database\Connection;
use Illuminate\Database\Events\QueryExecuted;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\ServiceProvider;
use Illuminate\Support\Facades\Log;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        DB::whenQueryingForLongerThan(250, function (Connection $connection, QueryExecuted $event) {
            Log::warning('Slow query threshold exceeded', [
                'sql' => $event->sql,
                'time_ms' => $event->time,
                'connection' => $connection->getName(),
            ]);
        });
    }
}

That will not replace profiling, but it quickly exposes screens where a table interaction is quietly executing a pile of avoidable work.

Watch request shape, not just runtime

Livewire pages can feel slow even when SQL looks fine. Two common reasons are oversized component state and too many requests for small UI changes.

Livewire’s current docs explicitly warn that storing large Eloquent collections as component properties can hurt performance because hydration re-executes work on subsequent requests. That is why a Filament page with "helpful" preloaded collections often degrades over time instead of getting better.

Also watch how many requests a single interaction triggers. Search fields, reactive filters, dependent selects, and polling widgets can stack together in ugly ways.

Separate initial render from interaction cost

This is where teams often misdiagnose the problem.

A screen may load fine at first, then feel terrible when users search or change filters. That usually points to table search, per-row closures, or repeated Livewire updates. Filament’s table docs note that global search term splitting can hurt performance on large datasets, and that is exactly the kind of detail that matters only after you have measured the slow interaction path.

So benchmark both:

first render of the page
first search request
first filter request
first modal open

Do not assume the same fix helps all four.

Read the usual bottlenecks correctly

Once you have timings, the next step is classification. Most slow Filament screens fall into a few predictable buckets.

Database-heavy tables

This is the classic case: relation columns, badge counts, computed summaries, and searchable fields all pile onto one index page. The query count spikes, SQL time dominates the request, and every sort or filter makes it worse.

Typical causes:

missing eager loading for related columns
per-row count() or aggregate calls inside closures
global search across too many text columns
filters that build expensive subqueries
options() lists loading huge tables on every request

This is where Filament table configuration matters more than package upgrades. If a table is asking the database to do the wrong work, a faster Filament release will only make the wrong work happen a bit more efficiently.

Authorization-heavy rows and actions

Filament makes it easy to add visible(), hidden(), disabled(), and policy-based actions everywhere. That is good ergonomically and dangerous operationally.

If each row action or badge checks permissions through expensive closures, you can end up paying authorization cost hundreds of times on one table render. The page still looks like a "UI problem," but the real issue is repeated decision logic.

A useful smell test is this: if reducing page size from 50 records to 10 dramatically improves the screen even when SQL is already reasonable, per-row logic is probably part of the problem.

Livewire state and request churn

A different pattern is moderate SQL time but clumsy interactions. Search feels sticky. Filter changes trigger multiple requests. Opening a modal rehydrates more state than expected.

That usually means too much data lives in the component, too many fields are reactive by default, or several components are bundled into one slow request path.

Livewire gives you tools here, but they are not magic. #[Isolate] helps when one component is expensive and independent. Lazy loading helps when widgets do not need to block first paint. Computed properties help when you were previously carrying around heavy collections as public state. The point is to shrink work per interaction, not to sprinkle attributes at random.

Production-only slowness

If local numbers look acceptable and production feels worse, stop tuning the screen first and check deployment posture.

Filament’s deployment docs recommend php artisan filament:optimize, which wraps component and icon caching, and Laravel still benefits from the usual production optimizations like php artisan optimize and correct OPcache setup. Those are not substitutes for bad screen design, but they absolutely matter once the screen is otherwise healthy.

Fix the bottleneck you measured

This is the part that should feel boring. Good performance work is usually a series of targeted, unsurprising fixes.

Tighten the table query before touching the UI

If the benchmark says the table query is the bottleneck, change the query first:

use Filament\Tables;
use Filament\Tables\Table;
use Illuminate\Database\Eloquent\Builder;

public static function table(Table $table): Table
{
    return $table
        ->modifyQueryUsing(fn (Builder $query) => $query
            ->select(['id', 'customer_id', 'status', 'total', 'created_at'])
            ->with(['customer:id,name'])
            ->withCount('items'))
        ->columns([
            Tables\Columns\TextColumn::make('customer.name')->searchable(),
            Tables\Columns\TextColumn::make('items_count'),
            Tables\Columns\TextColumn::make('status')->badge(),
            Tables\Columns\TextColumn::make('total')->money('USD'),
            Tables\Columns\TextColumn::make('created_at')->dateTime(),
        ])
        ->defaultPaginationPageOption(25)
        ->splitSearchTerms(false);
}

Three things are happening here:

the base select is narrower
relations and counts are loaded intentionally
search behavior is made cheaper for large datasets

That is a much better starting point than deleting columns until the page stops hurting.

Stop doing expensive work per row

If per-record closures are the issue, move repeated logic up a level.

Bad pattern:

action visibility closures that hit services or policies for every record
badge or description closures that trigger relation access lazily
ad hoc formatting that performs database lookups inside the column callback

Better pattern:

preload the data the UI needs
compute coarse permissions once per request where possible
reserve per-row checks for cases that are truly record-specific

This is also where reducing visual ambition helps. Admin tables do not need to be miniature dashboards. If each row shows three badges, two counts, a derived status, and four action buttons, you are paying for that complexity every render.

Shrink Livewire work on interaction

When interactions are the main problem, focus on state and request frequency.

Useful moves:

replace large public collections with computed lookups or paginated queries
avoid making fields reactive unless the user genuinely needs instant feedback
lazy-load widgets that are not needed for first paint
isolate an expensive widget only if it does not need to coordinate with the rest of the page

Be careful here: request bundling in Livewire often helps overall performance. Isolating components is for targeted cases, not a default style.

Use upgrades as a measured final step

Filament and Livewire releases do ship real performance work. Newer versions have improved rendering paths, component handling, and request behavior. But the right order is still:

measure the screen
fix obvious query and state issues
upgrade if the version gap is meaningful
rerun the same benchmark

Otherwise you never learn whether the upgrade solved your problem or merely shifted it.

Turn one benchmark into a guardrail

A single successful tuning pass is useful. A repeatable performance habit is better.

Once you make one Filament screen faster, keep the process:

store the before and after timings in the PR description
keep one realistic local dataset for admin profiling
add a short checklist for new heavy resources
rerun the same benchmark after package upgrades

A checklist can be brutally small:

does the table eager load displayed relations?
are counts and aggregates precomputed sensibly?
is search scoped narrowly enough?
are actions or badges doing expensive per-row work?
is Livewire carrying more state than the screen needs?

That is enough to stop most regressions.

If you want useful official references while working through this, keep these close:

Filament table docs: filamentphp.com/docs/5.x/tables/overview
Filament deployment and optimization: filamentphp.com/docs/4.x/deployment
Livewire properties and hydration guidance: livewire.laravel.com/docs/4.x/properties
Livewire isolation for expensive independent components: livewire.laravel.com/docs/4.x/attribute-isolate
Laravel Telescope: laravel.com/docs/13.x/telescope

The practical rule is simple: do not optimize Filament screens by taste. Measure one screen, separate SQL from hydration from UI logic, fix the dominant cost, and rerun the same benchmark. That is how you make an admin panel faster without guessing.

Read the full post on QCode: https://qcode.in/benchmark-filament-admin-screens-without-guesswork/

When Laravel Checkout Flows Outgrow Job Chains

Saqueib Ansari — Tue, 25 Aug 2026 04:52:32 +0000

Most Laravel teams start checkout flows with job chains because they feel clean, native, and cheap to ship. That works right up until checkout stops being one thing. The moment payment capture, inventory reservation, license provisioning, welcome email, analytics, and rollback logic start pulling on each other, a plain chain turns into a fragile story told across too many queue jobs.

The practical recommendation is simple: use job chains for short, mostly linear flows with low rollback cost. Use saga-style workflows when your checkout crosses service boundaries, needs compensation, or must survive partial success without guessing what happened. If your team is debating this too late, that usually means the chain already outgrew its shape.

Job Chains Win Early Because They Hide Complexity

Laravel job chains are attractive for good reasons. They are built into the framework, easy to read, and good enough for a surprising amount of business logic. For a simple paid flow, a chain can express the happy path clearly:

Bus::chain([
    new ChargeCustomer($checkoutId),
    new CreateOrder($checkoutId),
    new SendReceipt($checkoutId),
])->dispatch();

That is hard to argue with. The intent is obvious. The code stays close to Laravel’s queue model. You do not need extra infrastructure, workflow state, or orchestration concepts just to move money and send an email.

This approach stays healthy when three conditions hold:

The steps are mostly linear.
Failure handling is local, not cross-cutting.
A failed step can usually be retried without inventing rollback semantics.

That last point matters more than most teams admit. Retry is easy when the side effect is harmless. Retry is dangerous when the job already captured a payment, already created a subscription, or already called a third-party API with no clean undo.

The hidden cost of job chains is that they make the happy path obvious and the failure path implicit. Early on, that feels efficient. Later, it becomes the reason the system is hard to reason about.

Where Checkout Flows Break the Job Chain Model

Checkout is not one transaction. It is a collection of side effects pretending to be one transaction.

A realistic flow might do all of this:

authorize or capture payment
create the order record
allocate inventory or credits
provision a workspace or subscription
send email
emit events to analytics and CRM
roll back selected steps if something later fails

A job chain can execute those steps in order, but it does not give you a strong model for state transitions, partial completion, or compensation. Once you care about those things, your chain logic usually leaks into several places at once.

The first failure mode: side effects succeed before the chain fails

Suppose payment succeeds, order creation succeeds, but workspace provisioning fails because the downstream service is degraded. A plain chain can stop, retry, or send an alert. What it cannot do cleanly is answer the business question: what should the system do now?

If you refund immediately, you may create duplicate refunds under retries unless you designed idempotency correctly.
If you do nothing, the customer may be charged without receiving the product.
If you retry indefinitely, support inherits the ambiguity.

The problem is not that Laravel chains are bad. The problem is that the chain abstraction is too thin for workflows that need explicit recovery policy.

The second failure mode: rollback gets scattered

Teams usually patch this with ad hoc rollback code inside failed() handlers, listeners, or follow-up jobs:

class ProvisionWorkspace implements ShouldQueue
{
    public function handle(Provisioner $provisioner): void
    {
        $provisioner->createForCheckout($this->checkoutId);
    }

    public function failed(Throwable $e): void
    {
        RefundPayment::dispatch($this->checkoutId);
        ReleaseReservedCredits::dispatch($this->checkoutId);
        MarkCheckoutForReview::dispatch($this->checkoutId, $e->getMessage());
    }
}

This is where a chain starts lying to you. The flow is no longer linear. Recovery is now distributed across job classes, queue retries, manual support rules, and sometimes cron-based cleanup. You still have “a chain,” but operationally you have a workflow engine you built by accident.

The third failure mode: nobody can answer “what state is this checkout in?”

This is the big one. During incidents, the real question is rarely “did job X fail?” It is usually:

Was the customer charged?
Was the subscription created?
Should we retry, compensate, or wait?
Is this safe to replay?

Job chains are execution plumbing. They are not a great domain model for these answers unless you add a lot of extra state tracking around them.

What Saga-Style Workflows Actually Buy You

A saga-style workflow is not magic. It is just a more honest model for long-running, multi-step processes with compensating actions.

Instead of treating the flow as “run these jobs in order,” you treat it as a durable state machine with explicit forward steps and explicit undo behavior. Each step knows what success means, what failure means, and whether compensation is required.

That changes the design conversation in useful ways.

You stop pretending rollback is a database transaction

A checkout flow involving Stripe, email, provisioning, and internal records is not one atomic transaction. A saga accepts that reality. Each step commits independently, and the workflow defines what to do if a later step fails.

Typical compensations look like this:

reverse payment capture or issue refund
release inventory or reserved credits
disable a partially created subscription
cancel downstream provisioning requests

That is much cleaner than burying recovery behavior in random failed() methods.

You get durable workflow state

A proper saga keeps state like pending_payment, payment_captured, subscription_provisioned, compensating, or completed. That sounds boring until a production issue hits. Then it becomes the difference between support guessing and support knowing.

A minimal Laravel-oriented representation might look like this:

final class CheckoutWorkflowData
{
    public function __construct(
        public string $checkoutId,
        public ?string $paymentIntentId = null,
        public ?string $subscriptionId = null,
        public string $status = 'started',
    ) {}
}

final class CheckoutSaga
{
    public function run(CheckoutWorkflowData $data): void
    {
        $data->paymentIntentId = $this->capturePayment($data);
        $data->status = 'payment_captured';

        try {
            $data->subscriptionId = $this->provisionSubscription($data);
            $data->status = 'subscription_provisioned';

            $this->sendReceipt($data);
            $data->status = 'completed';
        } catch (Throwable $e) {
            $data->status = 'compensating';

            if ($data->subscriptionId) {
                $this->cancelSubscription($data->subscriptionId);
            }

            if ($data->paymentIntentId) {
                $this->refundPayment($data->paymentIntentId);
            }

            $data->status = 'failed';

            throw $e;
        }
    }
}

This is still simplified, but the shape is already better. The system now has a memory of what happened, not just a queue of what was supposed to happen.

You can make retry policy step-specific

Not every failure deserves the same response. Email can usually retry. Payment capture needs idempotency and stricter safeguards. Provisioning may need bounded retries before compensation kicks in.

Saga-style workflows let you say that clearly. That is the real value: not more abstraction, but better failure semantics.

The Right Choice Depends on Your Failure Cost

This is where teams should be more opinionated.

If your checkout flow is a single application writing to one database and sending one or two non-critical side effects, job chains are usually the correct choice. Adding a workflow layer too early is architecture cosplay.

If your checkout touches money, entitlements, and third-party systems, the question is no longer “can a chain run this?” The question is “what does failure mean, and can we explain recovery without hand-waving?”

Choose job chains when:

the flow has 3-5 mostly linear steps
failures are either retryable or cheap to repair manually
no step requires formal compensation beyond simple cleanup
support rarely needs a per-checkout execution timeline
idempotency is straightforward and already enforced

Choose saga workflows when:

payment and product delivery can diverge
rollback spans multiple services or vendors
some steps are slow, asynchronous, or externally acknowledged later
support and ops need workflow state, not just failed jobs
duplicate execution would be expensive or embarrassing
you are already writing custom recovery logic in multiple places

That last bullet is the tell. If your team has a spreadsheet of “what to do when step 4 fails after step 2 succeeded,” you do not have a simple chain anymore.

A Laravel Team’s Migration Path Should Be Boring

The mistake is treating this as a binary rewrite. You do not need to replace every queue flow with a grand workflow platform. Start with the one path that hurts: usually paid checkout, subscription activation, or account onboarding with entitlements.

Stage 1: keep jobs, add explicit workflow state

Before adopting a full saga engine, add a workflow record that tracks state transitions explicitly. Even if the execution still uses jobs under the hood, this gives you observability and a stable place for decision logic.

At minimum, track:

workflow id or checkout id
current status
completed steps
compensations run
last error
next retry time or terminal disposition

This alone will improve incident handling more than many teams expect.

Stage 2: pull compensation out of `failed()` handlers

failed() is fine for local cleanup. It is a poor home for business-critical compensation policy. Move rollback decisions into an orchestration layer where the whole workflow state is visible.

That can still be Laravel-native. You do not need to import complexity just to become explicit.

Stage 3: adopt a durable workflow runtime only where it pays rent

If the flow becomes long-running or highly asynchronous, a durable workflow system starts earning its cost. That might be an internal saga package, a Laravel-oriented workflow library, or an external engine if your scale and complexity justify it.

The evaluation criteria should be boring and practical:

Can it persist workflow state durably?
Can it replay safely?
Can it model compensation cleanly?
Can support inspect execution without reading queue internals?
Can developers test failure branches without building rituals?

Official Laravel queue docs are still the baseline here: https://laravel.com/docs/queues. Read them first, then decide whether you need more than queues.

The Real Tradeoff Is Cognitive Load, Not Just Infrastructure

Sagas are better for complex checkout flows, but they are not free. They introduce workflow concepts, explicit state modeling, and more up-front design work. That is worthwhile only when the business flow is already complex enough to deserve it.

A plain job chain keeps code smaller when the domain is simple. A saga keeps incidents smaller when the domain is not.

That is the comparison that matters.

The wrong move is staying on job chains because they are familiar after the workflow has already become compensation-heavy. The second wrong move is adopting a heavyweight workflow abstraction before the team has a real failure-handling problem.

My rule of thumb is blunt: if a failed checkout can leave money captured but value undelivered, model the flow as a saga. If failure mostly means “retry this later,” keep the chain.

That one decision line will save most Laravel teams from both under-engineering and workflow theater.

For adjacent reading, Laravel’s bus and queue primitives remain useful even in a saga-oriented design because jobs still make good execution units. The difference is that they stop being the source of truth for the business process.

Build the chain first when the flow is genuinely small. The moment recovery becomes a first-class requirement, stop stretching the chain abstraction past its limit and promote the flow into a workflow with explicit state and compensation.

Read the full post on QCode: https://qcode.in/saga-workflows-vs-job-chains-laravel-checkout-flows/

A Better AI Learning Workflow for Engineers Who Need Shipping Context

Saqueib Ansari — Sat, 22 Aug 2026 05:21:18 +0000

Most engineers do not have a learning problem. They have a translation problem. An LLM can explain a concept in five seconds, but that does not tell you what breaks in your codebase, what tradeoff matters under real traffic, or what test you should write before merging.

If your goal is to ship, the right AI learning workflow is not summary-first. It is decision-first. You use the model to compress research into implementation pressure: constraints, failure modes, interface changes, migration risk, and testable claims. That is the difference between "I understand the topic" and "I can make the next production decision with confidence."

Start With Shipping Questions, Not Topic Questions

A weak workflow starts with prompts like "teach me X" or "summarize Y." That creates polished understanding and poor execution. You get vocabulary, broad concepts, and clean explanations, but not the details that actually move a codebase forward.

A stronger workflow starts by anchoring the learning to a concrete engineering surface:

a feature you need to build
a system you need to change
a bug class you need to eliminate
an architectural choice you need to make

That changes the prompt shape immediately. Instead of asking what a concept is, ask where it will collide with your system.

For example, if you are learning retrieval pipelines, the useful question is not "what is RAG?" It is: where does retrieval introduce latency, stale context, ranking failure, and observability debt in my stack?

If you are learning background job orchestration, the useful question is not "how do queues work?" It is: what consistency guarantees do I actually need, and what happens when retries meet non-idempotent side effects?

This framing matters because most implementation failures come from the edges:

state transitions
partial failures
schema drift
rate limits
concurrency
human maintenance cost

LLMs are much more useful when you force them to talk about those edges early.

Build Notes Around Decisions, Not Facts

The output of AI-assisted learning should not be a generic summary document. It should be a working note that helps you decide what to do next. That means your notes need a different structure.

A good engineering note usually needs five things:

What problem are we actually solving?
What assumptions are true in our codebase?
What are the main options and their tradeoffs?
What can fail in production?
What should we implement, test, and monitor?

That sounds obvious, but most AI-generated notes skip at least three of them. They overproduce explanation and underproduce operational guidance.

A better note template

Use a template that forces implementation consequences to the surface:

Topic:
Current use case:
Decision we need to make:

What changes in code:
- modules touched
- new interfaces or abstractions
- schema/config changes
- deployment impact

Tradeoffs:
- latency
- cost
- complexity
- debuggability
- vendor lock-in

Failure modes:
- what breaks first
- what is silent vs obvious
- rollback strategy

Validation plan:
- unit tests
- integration tests
- load checks
- metrics/logging

Recommendation:
- choose X because...
- reject Y because...

This structure does two useful things. First, it turns the model into a design sparring partner instead of a summarizer. Second, it gives you a note that can evolve into an ADR, implementation ticket, or PR checklist.

For engineers working in Laravel, Node, or mixed full-stack systems, this is especially valuable because the risk is rarely in the idea itself. The risk is in the seams between app code, background work, storage, and third-party APIs.

The Workflow That Produces Shipping Context

The practical workflow is simple. The discipline is not.

Step 1: Gather raw material aggressively

Pull in the docs, code snippets, architecture notes, issue threads, and your own current implementation context. If you are learning from a concept page or official docs, pair that with your local constraints immediately.

Useful official references are usually the boring ones: framework docs, API docs, protocol specs, and vendor guides. For AI-heavy work, that often means starting with pages like the OpenAI docs or the Model Context Protocol introduction, then forcing the model to map those ideas into your application boundaries.

Step 2: Ask for contradictions and pressure points

Do not ask the model to explain the material back to you. Ask it where the clean explanation stops being enough.

Good prompts here sound like this:

I am evaluating this for a production app.
Given these constraints:
- Laravel API backend
- queue workers for async tasks
- per-request latency budget under 1.5s
- users can retry actions
- external model/API calls may fail or rate limit

Tell me:
1. which assumptions in the docs break first in production
2. what design mistakes engineers usually make on first implementation
3. what has to be idempotent
4. what should be synchronous vs queued
5. what should be measured from day one

That prompt shape is powerful because it asks for stress, not explanation. You are trying to extract where reality pushes back.

Step 3: Convert learning into code-level consequences

This is where most people stop too early. They now "understand" the topic and move on. That is exactly where you should get more specific.

Ask the model to translate the concept into concrete code impacts:

which classes or services likely change
where boundaries should move
what config needs to exist
which invariants must hold
what test matrix becomes necessary

For example, if you are adopting AI-assisted content enrichment in a publishing pipeline, the real questions are not about prompting style. They are about job retries, duplicate writes, content review states, and auditability of generated output.

Step 4: Produce implementation artifacts immediately

The best learning session ends with something your team could actually use. That can be:

an ADR draft
a migration plan
a risk register
a PR breakdown
a test plan
an observability checklist

If the conversation does not end in an artifact, it probably stayed too abstract.

Example: Learning an AI Feature the Wrong Way vs the Right Way

Suppose you want to add automatic article-tag suggestions to a CMS.

The weak workflow is predictable. You ask for a summary of classification models, embedding-based tagging, and prompt-based extraction. You get a clean answer, feel informed, then start coding. Two days later you discover inconsistent tags, slow moderation screens, duplicated retries, and no way to audit why a tag was assigned.

The stronger workflow starts from the shipping constraints.

Wrong question

"What are the best ways to generate tags from article text?"

That produces a taxonomy lesson.

Better question

"We need draft-time tag suggestions inside an editorial CMS. Editors must be able to override suggestions. Suggestions should not block publishing. We need deterministic enough behavior to avoid tag drift over time. What architecture gives us acceptable latency, auditability, and maintainability?"

Now the model can actually help. It may push you toward a queued enrichment job, a versioned suggestion policy, and a persisted explanation field so editors can see why a suggestion appeared.

A useful implementation sketch might look like this:

final class GenerateTagSuggestions
{
    public function handle(Article $article): void
    {
        if (! $article->isDraft()) {
            return;
        }

        $result = $this->taggingService->suggest(
            articleId: $article->id,
            title: $article->title,
            body: $article->body,
        );

        SuggestedTagSet::updateOrCreate(
            ['article_id' => $article->id, 'policy_version' => $result->policyVersion],
            [
                'tags' => $result->tags,
                'rationale' => $result->rationale,
                'generated_at' => now(),
            ]
        );
    }
}

Notice what matters here. The interesting part is not "call model, get tags." The interesting part is policy versioning, non-blocking execution, and persistence of rationale. That is shipping context.

From there, your notes should immediately capture questions like:

Should editors see stale suggestions or none at all during failures?
Do we overwrite prior suggestions or store history?
What causes a re-generation?
How do we prevent model drift from polluting taxonomy quality?

That is a much better learning outcome than a polished explanation of prompt engineering.

Turn Learning Into Tests Before You Trust It

A useful rule: if the topic can affect production behavior, your learning workflow should end with tests or at least a test plan.

This is where AI can be genuinely effective. Once you have a candidate design, ask the model to generate the test matrix from the failure modes you already identified.

Example test prompts

Ask for tests like an engineer, not like a student:

Given this service and job flow, generate the test cases that protect against:
- duplicate retries
- partial external API failures
- stale cached outputs
- invalid editor overrides
- regression when taxonomy rules change

Return them grouped into unit, integration, and queue/retry scenarios.

That often gets you to a stronger suite faster than starting from a blank file.

A Laravel-style test outline might end up looking like this:

it('does not create duplicate suggestion records on retry', function () {
    Queue::fake();

    $article = Article::factory()->draft()->create();

    app(GenerateTagSuggestions::class)->handle($article);
    app(GenerateTagSuggestions::class)->handle($article);

    expect(SuggestedTagSet::count())->toBe(1);
});

it('keeps publishing path independent from tag suggestion failure', function () {
    $service = Mockery::mock(TaggingService::class);
    $service->shouldReceive('suggest')->andThrow(new RuntimeException('rate limited'));
    app()->instance(TaggingService::class, $service);

    $article = Article::factory()->draft()->create();

    expect(fn () => PublishArticle::run($article))->not->toThrow(Exception::class);
});

The point is not that the model writes perfect tests. It usually does not. The point is that it can help you enumerate failure surfaces quickly, which is exactly what good learning should produce.

Where LLM Learning Workflows Fail

The biggest failure mode is false closure. The model sounds organized, so the engineer stops digging.

You should assume these weaknesses unless proven otherwise:

It hides uncertainty behind fluent prose.
It smooths over important edge cases.
It underestimates operational burden.
It gives symmetrical tradeoffs where a stronger recommendation is warranted.

That means your workflow needs explicit guardrails.

Three guardrails that matter

First, separate source capture from decision output. Keep the raw notes distinct from the final recommendation. Otherwise you lose track of what came from docs, what came from inference, and what came from your own architecture constraints.

Second, force the model to state what it does not know from the provided context. Missing constraints are often more important than the explanation itself.

Third, require a recommendation with a rejection reason. If the output ends with "it depends," you probably asked the wrong question or gave no real constraints.

A strong final prompt often looks like this:

Based on everything above, make a recommendation for this codebase.
Choose one default approach.
Then list:
- what we are intentionally not optimizing for
- what could make this decision wrong in 6 months
- what we should measure after rollout

That forces a more senior shape of answer.

The Practical Rule: Learn Toward the Next Commit

The best AI learning workflow for engineers is not a reading workflow. It is a commit-preparation workflow.

Use the model to get from vague topic knowledge to the next set of concrete moves:

what to change
what to avoid
what to test
what to monitor
what decision to document

If your notes do not help you open a PR, write an ADR, or tighten a test suite, they are probably still too academic.

That is the real standard. Not "did the model explain it well?" but did the workflow reduce uncertainty at the code and system level?

For engineers shipping real systems, that is the only kind of learning that compounds. Use AI to compress research, but force it to end in architecture pressure, implementation artifacts, and testable decisions. Anything less is just smarter procrastination.

Read the full post on QCode: https://qcode.in/ai-learning-workflows-engineers-shipping-context/

Using Test Impact Analysis on Slow Laravel Test Suites Without Losing Trust

Saqueib Ansari — Wed, 19 Aug 2026 05:19:05 +0000

If your Laravel suite is slow enough that developers hesitate before running it, you do not really have a fast feedback loop. You have a compliance ritual. That becomes a bigger problem once agents enter the workflow, because agents amplify whatever loop you give them. If verification takes twelve minutes, the agent either waits uselessly, skips checks, or pushes too much uncertainty downstream.

The practical answer for most PHP teams is test impact analysis locally, full-suite verification in CI, and explicit rules for when selective execution is too risky. That gives you a fast inner loop without lying to yourself about what counts as real confidence.

For Laravel teams, this is now a serious option. Pest 5 introduced built-in test impact analysis through --tia, and Laravel’s testing stack already gives you the parallel execution hooks you need to keep fallback runs sane. The hard part is not turning the feature on. The hard part is designing a workflow that stays trustworthy when the codebase, the team, and the suite get messy.

The Real Problem Is Not Just Runtime

A slow suite hurts in more than one way.

The obvious cost is wall-clock time. A developer changes one policy, one listener, or one validation rule, then waits minutes for a result. That is annoying, but it is still the shallow version of the problem.

The deeper cost is behavioral. Once the suite becomes expensive, people stop using it as a steering mechanism. They batch unrelated edits together. They verify less often. They defer broad checks until the end of the branch. Agents do the same thing even faster. Instead of validating each change in small increments, they accumulate risk and hope the next big run explains what broke.

That is why Laravel test impact analysis matters. It is not only about making tests faster. It is about restoring a development rhythm where verification can happen after small, frequent changes.

Pest’s TIA model is appealing for exactly this reason. The first run builds a dependency graph from coverage data, using a driver such as PCOV or Xdebug. Later runs look at what changed, rerun the tests that depend on those files, and replay cached results for the rest. Pest’s own release docs position this as a local development feature, not as a substitute for full CI verification, and that framing is correct.

If you ignore that framing, you create a false sense of safety. If you respect it, you get a much better developer loop.

What a healthy loop should feel like

A healthy Laravel testing workflow should make these things cheap:

rerunning a narrow slice after a small refactor
verifying a bug fix before moving to the next file
letting an agent validate each patch instead of dumping one giant speculative change
widening the scope when the blast radius starts to grow

That last point matters most. Good teams do not ask one testing mode to solve everything. They use different levels of verification for different kinds of uncertainty.

Where Test Impact Analysis Actually Wins

The biggest win is not the first-run benchmark. It is the reduction in friction after the first run.

Once the dependency graph exists, your team can stop treating the whole suite as the default response to every tiny edit. A small change to a controller, request object, or service class should not force the same verification cost as a migration rewrite or authentication refactor.

That sounds obvious, but many Laravel codebases still behave as if every touched file deserves a full ceremonial run. That habit survives because tooling used to make the alternative awkward. It is less defensible now.

Best-fit projects

Test impact analysis works especially well in Laravel projects with these properties:

a real separation between unit and feature tests
request flows that are tested by intent, not by giant catch-all files
factories and fixtures with predictable side effects
limited hidden state in shared helpers or global bootstrapping
developers who work in small batches instead of all-day mega-branches

In those codebases, TIA becomes a force multiplier. It keeps local checks cheap while preserving enough relevance that the result is useful.

Why this matters for agent-assisted development

Agents are not patient engineers. They are throughput machines. If you give them a ten-minute verification cycle, they will either use it badly or avoid it. If you give them a three-second impacted run plus a clear escalation rule for wider checks, they become much more useful.

That is the real opportunity here. TIA turns verification from an end-of-branch event into an every-few-minutes event. That is exactly the cadence agents need.

A realistic local command set

Do not overcomplicate the first rollout. Three commands are enough for most teams:

{
  "scripts": {
    "test:impact": "./vendor/bin/pest --parallel --tia",
    "test:quick": "php artisan test --parallel --stop-on-failure",
    "test:full": "php artisan test --parallel --recreate-databases"
  }
}

This is intentionally boring.

test:impact is the default inner loop. test:quick is the broader local check before a push when the change touches meaningful app behavior. test:full is the expensive reset when the branch has become wide enough that you want a fresh, broad pass with recreated databases.

You can add more scripts later, but the bigger mistake is starting with a clever matrix of commands nobody remembers.

The Trust Boundary Has To Be Explicit

The most common failure with selective testing is not a bug in the tool. It is a bug in the team’s interpretation of green.

If you do not define this clearly, people start treating a fast impacted run as equivalent to a branch-wide verification result. It is not.

The safest rule is brutally simple:

impacted green means the recent change is probably safe to continue
broader local green means the branch is likely stable enough to push
full-suite CI green means the branch is ready to trust

Those three signals are related, but they are not interchangeable.

Why CI should stay conservative

Pest’s official guidance says TIA is for local development and that CI should run the full suite against a clean checkout. That is the right architectural line.

There are good reasons for that:

CI should not depend on a developer’s local cache state
protected-branch verification should be deterministic and boring
cross-cutting failures often emerge only in a clean environment
replayed results are valuable for iteration, but full-system trust belongs to a fresh run

Laravel’s parallel testing support is strong enough that full-suite CI does not have to be painfully slow if the suite is structured competently. Use php artisan test --parallel, tune process count, and shard later only if you actually need it.

A sane CI shape

A straightforward GitHub Actions job is enough to enforce the trust boundary:

name: test

on:
  pull_request:
  push:
    branches: [main]

jobs:
  suite:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: shivammathur/setup-php@v2
        with:
          php-version: '8.4'
          coverage: pcov
      - run: composer install --no-interaction --prefer-dist
      - run: php artisan test --parallel

That is not glamorous, but that is the point. Local verification can be clever. CI should be dependable.

If you want to go further, a useful pattern is to refresh the TIA baseline on merges to main so developers pull fresh mapping data locally. That supports fast replay behavior without turning CI itself into a selective-execution system of record.

The High-Risk Changes Where Impacted-Only Is Not Enough

This is where teams need judgment instead of slogans.

Selective execution is strongest when the change is narrow and the dependency graph tells a clear story. It becomes weaker when the edit changes shared behavior, bootstrapping, or infrastructure that many tests rely on indirectly.

I would treat these as default escalation zones:

service providers and container bindings
authentication, authorization, policies, and middleware wiring
framework and package upgrades
global config changes and env-dependent behavior
migrations that alter heavily used tables or indexes
changes to base test classes, custom assertions, traits, or shared helpers
factories, seeders, and fixtures with broad reuse
queue, cache, event, broadcast, and notification infrastructure

These are not cases where TIA is useless. They are cases where TIA should be the first signal, not the last one.

Migration changes are especially deceptive

A schema change often looks narrower than it really is.

Suppose you rename a column on a commonly queried table, tweak a foreign key, or change default values that influence model state. The immediate impacted set may be small enough to look comforting. The real application blast radius may not be.

For that class of change, I would use a two-step rule:

run impacted tests immediately for fast feedback
widen to a broader parallel run before you trust the branch

That keeps the inner loop fast without mistaking local confidence for system-wide certainty.

Shared test infrastructure is another danger zone

If you change a custom test trait, base TestCase, helper that signs users in, or a fixture factory used across dozens of flows, the suite can fail in surprising places. Some of those failures may be obvious dependencies. Others are just side effects hiding behind convenience code.

That is also why test architecture quality still matters. TIA can reduce the runtime cost of a messy suite, but it cannot magically make a highly coupled suite easy to reason about.

Parallel Testing Is What Makes the Safety Net Practical

Impact analysis gets most of the attention because it is the shiny feature. For Laravel teams, parallel testing is what keeps the whole strategy honest.

If your fallback full run is still unbearable, people will avoid it. Then the workflow collapses into impacted-only by habit, even if nobody says that out loud.

Laravel’s official testing docs already give you the baseline: php artisan test --parallel, automatic per-process test databases, and hooks for process and database setup. Use them properly.

Resource isolation is where many teams fail

A lot of "parallel is flaky" complaints are not actually about parallelism. They are about shared resources that were never made safe for concurrency.

Typical offenders include:

cache prefixes shared across processes
temp files written to one global path
seeded data that assumes singleton state
external service doubles that reuse global ports or files
SQLite file contention when tests write concurrently

Laravel gives you the hooks to isolate this cleanly:

<?php

use Illuminate\Support\Facades\Artisan;
use Illuminate\Support\Facades\ParallelTesting;
use PHPUnit\Framework\TestCase;

ParallelTesting::setUpProcess(function (int $token) {
    config()->set('cache.prefix', 'tests_'.$token);
    config()->set('filesystems.disks.local.root', storage_path('framework/testing/'.$token));
});

ParallelTesting::setUpTestDatabase(function (string $database, int $token) {
    Artisan::call('db:seed', ['--class' => 'RequiredTestSeeder']);
});

ParallelTesting::setUpTestCase(function (int $token, TestCase $testCase) {
    // Per-test-case setup when specific shared resources need token isolation.
});

That is the sort of implementation detail teams skip when they want the speedup without the engineering work. Then they conclude that the tool is unreliable. Usually the problem is that the suite was relying on hidden global state.

Profile before you over-engineer

Before inventing new layers, run Pest with --profile and look at the slowest tests. In many Laravel suites, a small number of pathological tests dominate total runtime.

Typical causes:

repeated full-database seeding inside unrelated tests
expensive external process setup
feature tests that cover too much workflow in one file
chatty factories creating large object graphs for trivial assertions
browser or integration tests mixed into the same default loop

Impact analysis helps with selection. It does not excuse waste inside the selected tests. Fixing the slowest ten often matters more than adding another clever test command.

What a Production-Ready Workflow Looks Like

The best rollout is not "turn on TIA and trust the magic." It is a layered workflow with escalation points.

Here is the version I would recommend to most PHP teams.

1. Default to impacted runs during active development

When a developer or agent is changing one service, one request class, one controller, or one policy, test:impact should be the default response. It keeps the inner loop tight and makes frequent verification realistic.

2. Widen the scope when the branch stops being narrow

Once the work touches shared infrastructure, data shape, or multiple bounded areas, run test:quick. That broader parallel pass catches issues the narrow loop was never meant to certify.

3. Keep full-suite CI as the merge truth

Protected branches should still rely on a full run from a clean checkout. If you blur that line, you lose the only signal everyone can trust equally.

4. Write the escalation rules down

Do not leave this to intuition alone. Put it in CONTRIBUTING.md or the team handbook.

Something this short is enough:

Use `test:impact` for local iteration on narrow changes.
Run `test:quick` before pushing changes that touch shared app behavior.
Run `test:full` locally after risky refactors, migrations, or shared test infrastructure changes.
CI remains the source of truth and always runs the full suite.

That documentation matters because it preserves meaning. Fast green stays useful without becoming sloppy green.

5. Split categories if your suite is structurally mixed

If unit, feature, browser, and contract tests all live in one verification habit, selective testing still helps, but your team will keep mixing very different confidence levels together.

A better model is often:

unit and feature tests in the fast daily loop
browser or end-to-end tests as a separate, less frequent layer
heavy cross-service contract checks reserved for CI or targeted pre-merge runs

The point is not to produce a pretty pyramid diagram. The point is to stop asking one command to carry every kind of certainty.

The Decision Rule That Actually Works

If your Laravel suite is too slow, do not pick between "run everything" and "run less." That framing is weak.

The stronger approach is this:

use impact analysis to make local iteration fast enough to be habitual
use parallel broader runs to absorb uncertainty when the blast radius grows
use full-suite CI to protect the branch with a deterministic signal
treat cross-cutting changes as escalation cases, not normal cases

That is the decision rule I would give any PHP team building with agents, frequent refactors, or simply a codebase large enough that the old full-suite-only habit has become a drag.

Pest 5’s release notes are worth reading for the TIA model, and Laravel’s testing documentation remains the practical reference for parallel setup and database behavior. Pest’s CLI reference is also useful once you start tuning the workflow.

The memorable version is short: selective locally, exhaustive in CI, and skeptical whenever the change smells global.

That is how you get faster feedback without lowering the bar.

Read the full post on QCode: https://qcode.in/laravel-test-impact-analysis-for-slow-suites/

Pest 5 Makes Agent Verification Feel Like a Real Testing Workflow

Saqueib Ansari — Thu, 13 Aug 2026 05:23:40 +0000

If your team is experimenting with coding agents, Pest 5 changes the conversation in a useful way. It stops agent safety from being a vague review culture problem and turns it into a verification design problem. That is the right frame. Agents will keep producing plausible code quickly. The only durable answer is to make correctness cheap to prove.

For Laravel and PHP teams, the practical stack is now much clearer: use Pest tests for hard business truth, static analysis for structural correctness, evals for fuzzy behavior, and human review for judgment calls. Pest 5 matters because it gives these pieces a workflow shape that actually fits agent-assisted development instead of treating AI as a separate novelty lane.

The mistake to avoid is simple: do not bolt an agent onto a weak codebase and expect code review to absorb the risk. If the rules that matter are not encoded already, the agent did not create your problem. It exposed it.

The Shift: Verification First, Agent Second

Most teams still evaluate agent output backward. They start with the generated diff, then ask a reviewer to mentally simulate whether it is safe. That does not scale. It did not scale before AI either, but agents make the failure obvious because they can produce ten reviewable changes in the time a human properly reasons through one.

Pest 5 pushes a better operating model. Its current release and docs position the framework around faster feedback loops, test impact analysis, an agent verification command, browser testing, and eval-oriented workflows for AI-heavy applications. The important part is not the feature checklist. The important part is what that checklist implies: verification should be the product boundary for agent-written code.

That means you need a clear split of responsibilities:

Unit and feature tests own business rules and regression checks.
Static analysis owns type discipline, framework misuse, and structural drift.
Evals own broader output quality where exact equality is the wrong assertion model.
Human review owns architecture, scope discipline, naming, and product intent.

If you keep those boundaries fuzzy, agents become a source of anxiety. If you make them explicit, agents become another producer feeding a strong acceptance pipeline.

This is why I think the real value of Pest 5 is not "AI support." It is that Pest is finally treating verification as something that can be shaped around agent workflows without turning the test suite into theater.

Step 1: Put Non-Negotiable Rules in Tests

If a broken rule would create money loss, permission leaks, bad state transitions, or user-visible corruption, it belongs in a normal test. Not in a prompt. Not in a reviewer checklist. Not in tribal knowledge.

This is the first thing to fix in a Laravel codebase before you let agents touch meaningful flows. The suite has to answer, in executable form, what must never change.

What should live in Pest tests

In practice, these categories almost always belong there:

Pricing and tax calculations
Authorization and policy outcomes
State machine transitions
Validation invariants
Idempotency behavior for jobs, webhooks, and retries
Data transformation rules used by downstream systems

Those are not "nice to have" tests. Those are the contract that makes agent iteration safe.

Example: pricing logic the agent cannot negotiate with

Suppose an agent refactors a checkout service to reduce duplication. The code might look cleaner and still be wrong in exactly the place that matters. This is where a narrow, explicit Pest suite earns its keep.

use App\Domain\Billing\Cart;
use App\Domain\Billing\Money;
use App\Domain\Billing\PercentageDiscount;

it('never drops below zero when discounts exceed subtotal', function () {
    $cart = new Cart(subtotal: Money::fromInt(5000));

    $total = $cart
        ->applyDiscount(new PercentageDiscount(150))
        ->total();

    expect($total->toInt())->toBe(0);
});

it('applies store credit after discount rules without producing negative totals', function () {
    $cart = new Cart(subtotal: Money::fromInt(8000));

    $total = $cart
        ->applyDiscount(new PercentageDiscount(25))
        ->applyStoreCredit(Money::fromInt(9000))
        ->total();

    expect($total->toInt())->toBe(0);
});

it('keeps cents precise across discount math', function () {
    $cart = new Cart(subtotal: Money::fromInt(1999));

    $total = $cart
        ->applyDiscount(new PercentageDiscount(10))
        ->total();

    expect($total->toInt())->toBe(1799);
});

These tests are not interesting in a literary sense. Good. They should be boring and merciless. An agent can refactor the service, swap collaborators, rename classes, or optimize internals. What it cannot do is silently break the money rules without a visible failure.

Keep the suite sharp, not bloated

A common overreaction is to compensate for AI with giant end-to-end coverage everywhere. That usually makes the feedback loop worse.

What you want is a layered suite with different response times:

Small unit tests for hard domain rules
Focused feature tests for Laravel request and policy flows
A limited number of integration tests for database, queues, mail, or external boundaries
Browser tests only where UI behavior really matters

If every rule is validated only through a slow browser or full-stack flow, test impact analysis becomes less useful and agents lose the speed advantage you wanted in the first place.

The test suite should be opinionated about cost. Cheap tests should guard expensive mistakes.

Step 2: Use Static Analysis to Catch Structural Drift Early

Tests catch behavior. They do not reliably catch a service returning the wrong shape, a nullable leak creeping through a boundary, a collection changing element type, or a helper method becoming a soft-typed dumping ground. Agents are especially good at creating those kinds of problems because the code still looks plausible.

That is why static analysis needs to be part of agent verification, not a separate quality initiative you keep postponing.

Pest 5’s broader ecosystem message matters here too. The official release material ties Pest to a stronger toolchain around verification, not just test syntax. That matches reality: Laravel teams need Pest plus PHPStan plus Larastan, not Pest alone.

Make contracts explicit where agents touch them

Application services, data mappers, and domain actions benefit a lot from explicit shapes. Once you document the return contract tightly, both humans and tools get less room to lie to themselves.

<?php

namespace App\Actions\Orders;

use App\Models\Order;

final class BuildOrderSummary
{
    /**
     * @return array{
     *     id: int,
     *     customer_email: string,
     *     currency: string,
     *     lines: list<array{
     *         sku: string,
     *         name: string,
     *         quantity: int,
     *         total_cents: int
     *     }>,
     *     total_cents: int
     * }
     */
    public function handle(Order $order): array
    {
        return [
            'id' => $order->id,
            'customer_email' => $order->customer_email,
            'currency' => $order->currency,
            'lines' => $order->items
                ->map(fn ($item) => [
                    'sku' => $item->sku,
                    'name' => $item->name,
                    'quantity' => $item->quantity,
                    'total_cents' => $item->total_cents,
                ])
                ->values()
                ->all(),
            'total_cents' => $order->total_cents,
        ];
    }
}

That docblock is not decorative. It gives PHPStan and Larastan something strong enough to reason about when an agent starts "cleaning up" a serializer or changing a downstream consumer.

Without those contracts, the typical failure mode looks like this:

Agent swaps an integer for a float because it feels convenient.
A collection becomes lazy where an eager array was assumed.
A nullable property leaks into mail or queue payload logic.
The code passes casual review because the diff feels tidy.

Static analysis is the right place to kill those changes fast.

A sane Laravel baseline for agent work

If you want a practical bar, this is a good starting point:

Run PHPStan and Larastan in CI on every agent-authored change.
Treat new ignores as debt that needs explanation, not as routine cleanup.
Add return types, generic collections, and array shapes to application services first.
Tighten hot paths before edge paths. Orders, billing, auth, webhooks, and exports usually deserve the earliest attention.

The point is not to reach some abstract purity level. The point is to shrink the space where an agent can introduce quiet structural decay and still look productive.

Official references are worth linking where readers want to go deeper: Pest 5 announcement, Agent plugin docs, PHPStan, and Larastan.

Step 3: Use Agent Verification for Fast Probes, Not Permanent Coverage

The Pest agent plugin is one of the more practical pieces in this release because it acknowledges a real workflow need: sometimes the agent does not need a new permanent test yet. It needs a one-off proof that the change works inside the real test environment.

That is a very different thing from saying "the agent should just click around and hope." The plugin’s current docs describe a single verification command that can exercise backend behavior directly and, with browser tooling installed, drive real UI flows as well. That is useful precisely because it stays inside the verification boundary instead of inventing a separate AI sandbox.

Good uses for one-off agent verification

This is where I think it fits best:

Route still returns 200 after a controller refactor
Policy still blocks a user class correctly
Dashboard still renders after a Livewire or Blade change
Queue side effect still happens after an event wiring change
Form flow still works before you decide whether it deserves a permanent browser test

Bad uses for one-off agent verification

This is where teams will misuse it:

Replacing durable tests with ad hoc probes
Treating a successful one-off check as proof of broad correctness
Letting the agent invent vague success criteria on the fly
Skipping normal feature tests because the probe was "good enough"

The rule should be strict: agent verification probes are temporary evidence, not long-term coverage. If a behavior matters repeatedly, promote it into a real test.

Example: one-off probe after a dashboard access change

The official docs show the shape of this pattern with a --agent command. In practice, a Laravel team might use it like this after an authorization or rendering change:

./vendor/bin/pest --agent='$user = \\App\\Models\\User::factory()->create(); $this->actingAs($user)->get("/dashboard")->assertOk();'

That is useful because it checks the actual application boundary quickly. But if the dashboard access rule is business-critical, stop there only once. The second time that flow matters, turn it into a committed feature test.

This is the right mental model:

Probe once to unblock local iteration
Promote repeated or risky behavior into the suite
Never confuse fast evidence with durable coverage

That distinction will save your team from creating a pile of unverifiable agent folklore.

Step 4: Treat Evals as Behavioral Sweeps, Not Truth Machines

Evals are the most misunderstood part of this stack because teams tend to swing between two bad extremes. Either they avoid them because they sound fuzzy, or they overuse them because they sound modern.

The right use is narrower and more valuable: evals are great for broad behavioral assessment when exact string equality or a single assertion is the wrong testing model.

That matters a lot for teams building AI features into Laravel apps, but it also matters for agent-driven code changes where you want to validate classes of behavior across many cases.

What belongs in evals

Good candidates include:

Prompt-driven summarization quality
Classification consistency across datasets
Whether generated content follows policy constraints
Whether a support assistant refuses unsafe requests correctly
Whether a code transformation preserved behavior across a bank of fixtures

What does not belong there:

Refund arithmetic n- Role-based authorization truth
Validation rules with deterministic outcomes
Anything you can express cleanly as a direct assertion

If the outcome is exact and deterministic, use a normal test. Evals are not a fashionable replacement for good engineering.

Example: evaluating a support assistant policy boundary

A Laravel team shipping an internal or customer-facing assistant might use dataset-style cases to test refusal and escalation behavior. Pest’s eval tooling makes sense here because "correct" is often about policy adherence across varied prompts, not one exact sentence.

it('handles refund policy scenarios consistently', function (string $message, string $expectedLabel) {
    $reply = app(SupportAgent::class)->respond($message);

    $label = app(ResponsePolicyClassifier::class)->classify($reply);

    expect($label)->toBe($expectedLabel);
})->with([
    ['I want a refund for an order placed 5 minutes ago', 'allow_refund_path'],
    ['Refund me for a non-refundable item from 8 months ago', 'deny_with_policy_reason'],
    ['Can you refund my friend\'s order if I know their email?', 'deny_identity_mismatch'],
    ['I was charged twice, what should I do?', 'route_to_human_or_duplicate_charge_flow'],
]);

That example still looks test-like because it should. The important shift is conceptual: you are validating behavior quality across a realistic set of cases, not pretending one string comparison will capture the whole policy surface.

For AI-heavy products, this is the missing layer between deterministic tests and manual spot checks. It gives teams a way to keep agent and model behavior under pressure without faking precision they do not actually have.

Step 5: Make Test Impact Analysis Serve the Loop, Not Replace the Gate

Test impact analysis is the feature that will probably change team behavior fastest, because feedback speed is where most agent workflows fall apart. The official Pest 5 announcement positions the TIA engine as a way to rerun only affected tests after changes. If that works well in your codebase, it is a big operational win.

But there is a trap here too. Teams will be tempted to treat changed-area test selection as if it were the whole safety model. That is wrong.

Use test impact analysis to accelerate local verification and agent iteration. Do not use it as an excuse to weaken merge gates.

What the workflow should look like

A strong Laravel pipeline for agent-authored work usually wants three speeds:

Fast local loop

This is what the agent or developer runs repeatedly during implementation:

vendor/bin/pest --dirty
vendor/bin/phpstan analyse

The goal here is cheap confidence. The changed-area rerun should answer, "did this edit obviously break the things it touches?"

Risk-targeted checks

If the change touches policies, serialization, or UI flows, run the extra layer that matches the risk:

vendor/bin/pest tests/Feature/Auth
vendor/bin/pest --agent='$user = \\App\\Models\\User::factory()->create(); $this->actingAs($user)->get("/settings")->assertOk();'

Now you are validating both the durable contract and the one-off path that mattered during the edit.

Full merge gate

Before merge, the bar still needs to be broad:

vendor/bin/pest
vendor/bin/phpstan analyse
php artisan test --testsuite=Feature

Depending on the codebase, you may also add browser tests, architectural tests, or a targeted eval suite. The point is that the full gate still exists. TIA narrows the inner loop. It does not get to redefine what production confidence means.

Where TIA can mislead you

There are a few failure modes worth calling out:

Coupling is hidden, so the impacted set is smaller than the real risk surface.
The suite is too integration-heavy, so changed-area speedups are weak.
Critical business rules are missing, so fast feedback still misses expensive bugs.
Teams start trusting fast green runs more than the real suite.

That last one is the dangerous cultural bug. Fast feedback is for steering. Full verification is for merging.

Human Review Still Matters, but It Should Move Up the Stack

The better your automated verification gets, the more valuable human review becomes because it stops being wasted on machine-checkable details.

A good reviewer should not spend half their time re-deriving whether a discount can go negative or whether a nullable property escaped into a DTO. If those questions still dominate review, the pipeline is underbuilt.

What humans should own instead:

Is the agent solving the right problem or just the nearest one?
Did the abstraction improve clarity or create another layer for no reason?
Are naming and boundaries getting stronger or weaker?
Did the change increase hidden coupling?
Is there an architectural consequence the local diff hides?

That is the level where senior engineering judgment matters. Everything below that should be pulled downward into tests, analysis, or evals over time.

A useful rule for teams adopting agents is this: if reviewers catch the same class of mistake twice, automate it by the third time. That one rule alone will make your agent workflow materially safer within a month.

Pest 5 does not solve verification for you. It gives PHP teams a better place to anchor it. That is enough to matter.

If you are running Laravel with coding agents today, the recommendation is straightforward. Start small, but make the stack explicit: durable Pest tests for core rules, PHPStan and Larastan for structure, one-off agent verification probes for fast iteration, evals for behavior classes that resist exact assertions, and a full merge gate that does not flinch.

Decision rule: if your confidence in an agent change still depends mostly on a reviewer reading the diff carefully, your verification system is too weak. Fix that before you scale the agent.

Read the full post on QCode: https://qcode.in/pest-5-agent-verification-testing-problem/

AI review can help with Laravel upgrades, but it should not make the decisions

Saqueib Ansari — Wed, 12 Aug 2026 04:53:13 +0000

Laravel upgrades are one of the easiest places to overestimate AI. It looks perfect for the job: large diffs, framework changes, repetitive refactors, and lots of surface area to scan. In practice, AI review is useful, but it is not where the important upgrade decisions get made.

I still use AI during Laravel upgrades, especially as a second pass. It catches renamed methods, outdated config shapes, stale imports, and framework-level inconsistencies faster than most humans want to admit. But the more expensive bugs in a real upgrade are usually not syntax bugs. They are judgment bugs. They come from misunderstanding how this codebase uses queues, middleware, auth, caching, tenancy, validation, or exception handling.

That distinction changed how I run upgrades now: AI helps me audit the change set, but I do not let it pretend to own the migration. The architectural call still needs a human.

Where AI Review Actually Helps

The best use of AI in a Laravel upgrade is narrow and mechanical. Give it a diff, the target Laravel version, and a concrete question. That tends to produce useful output quickly.

In my experience, AI is good at spotting four classes of issues:

Framework API drift: deprecated helpers, signature changes, config keys that moved, middleware registration changes, or updated bootstrapping conventions.
Pattern mismatch: places where half the app uses the new pattern and the other half still uses the old one.
Upgrade guide coverage gaps: areas you skipped because the app still boots, but the framework now expects a cleaner or safer implementation.
Low-level review fatigue: dozens of tiny edits that are individually obvious but easy to miss when you are tired.

That matters because upgrade work creates a lot of noise. If you are moving from one Laravel major version to another, the official upgrade guide is essential, but it does not tell you where your specific codebase is fragile. It tells you what changed in the framework. You still need to map that onto your app.

The official docs are still the anchor here:

AI becomes valuable when you already know the target and want a fast consistency scan. It is much less valuable when you want it to infer business intent from a codebase it met thirty seconds ago.

The Bugs AI Usually Misses

The dangerous part of AI review is not that it is dumb. It is that it is plausible. It often produces the kind of answer that sounds senior enough to pass a quick read, while still being wrong in the places that matter.

During upgrades, the misses usually fall into three buckets.

It does not understand your invariants

Laravel gives you abstractions. Your application gives those abstractions meaning. A queue job in one project is a harmless background sync. In another, it is part of a payment pipeline with strict ordering guarantees. A middleware change can look cosmetic until it silently alters tenant resolution or auth context.

AI can say, "this code should use the newer registration style," and still miss that the current order exists to preserve behavior around impersonation, locale resolution, or request-scoped caching.

That is why upgrade bugs often show up in places that look boring in the diff. The framework changed something generic. Your app depended on the old behavior in a very non-generic way.

It tends to normalize toward framework defaults

This is one of the biggest traps. AI usually assumes your code should look more like the framework docs. Sometimes that is correct. Sometimes your app intentionally deviates because the default is wrong for your domain.

I have seen this show up in exception rendering, validation flow, broadcast auth, guard selection, and database transaction boundaries. The AI recommendation looks clean because it moves the app closer to "standard Laravel." But standard Laravel is not automatically correct Laravel.

It cannot rank risk the way a maintainer can

Upgrade work is not just about correctness. It is about sequencing. Which change is safe now? Which one should be isolated? Which one needs a feature flag? Which one needs product signoff because it changes observable behavior?

AI review is weak at that layer. It can tell you what is different. It usually cannot tell you which difference is worth waking up for at 2 AM.

What Changed in My Upgrade Process

The useful shift was simple: I stopped treating AI as a reviewer of the whole upgrade and started treating it as a reviewer of prepared evidence.

That means I now structure the upgrade before I ask AI to look at anything.

I keep an upgrade notes file

Before changing code, I write down the target version, the official upgrade notes I expect to touch, risky subsystems, and known app-specific deviations. This dramatically improves both human review and AI review, because the work has context.

A stripped-down version looks like this:

## Laravel 12 Upgrade Notes

### Expected framework touchpoints
- bootstrap / app configuration
- exception handling
- middleware registration
- queue + scheduler behavior
- auth / guards
- validation and request objects

### App-specific risk areas
- tenant resolution depends on middleware order
- admin guard differs from default web guard
- payment jobs rely on serialized DTO shape
- API clients retry through custom exception mapping

### Non-goals
- no opportunistic refactors
- no config cleanup unrelated to upgrade
- no auth redesign during this PR

This is not documentation theater. It forces scope control. It also makes bad AI suggestions easier to reject, because you already wrote down the constraints.

I separate mechanical changes from behavior changes

If an upgrade PR mixes signature updates, container changes, config rewrites, auth cleanup, and test rewrites, the review quality collapses. AI becomes noisier and humans become less reliable.

So I split the work.

Mechanical compatibility changes go first.
Behavior-preserving test updates come next.
Architectural changes happen only if the upgrade genuinely requires them.

That separation matters because AI is strongest in the first category and weakest in the third.

Example: A Change That Looks Safe but Is Not

A common upgrade trap is middleware or bootstrap registration. Laravel evolves how the application is configured, and AI will often recommend moving everything to the modern pattern immediately. Sometimes that is fine. Sometimes it breaks assumptions hidden in execution order.

Here is the kind of thing that deserves human attention:

->withMiddleware(function ($middleware) {
    $middleware->alias([
        'tenant' => \App\Http\Middleware\ResolveTenant::class,
        'admin' => \App\Http\Middleware\RequireAdmin::class,
    ]);

    $middleware->appendToGroup('web', [
        \App\Http\Middleware\ResolveTenant::class,
        \App\Http\Middleware\ApplyTenantLocale::class,
    ]);
});

An AI review may say this is fine, or suggest a cleaner registration style. The real question is different: what depends on that order?

If ResolveTenant used to run earlier through a previous kernel arrangement, moving it without checking can break:

tenant-aware route model binding
locale selection before validation messages are built
per-tenant cache prefixes
auth guard resolution for admin subdomains

None of that is obvious from the framework diff alone. You need application context, and you need tests that prove the contract.

The right follow-up is not "does this match the docs?" It is "what user-visible behavior did this ordering previously guarantee?"

Tests Are the Real Counterweight

If you want AI review to be useful during upgrades, give it a codebase with strong regression tests. Otherwise you are asking a language model to do architecture and QA at the same time, which is where the fantasy starts.

I now treat tests as the primary control system and AI as a secondary scanner.

Write tests around the risky edges first

Before or during the upgrade, I want tests around:

request lifecycle assumptions
auth and permission boundaries
queue serialization and retries
exception-to-response mapping
integration points with external services

For example, if your app depends on a custom exception becoming a specific JSON error shape, lock that down explicitly:

it('maps billing exceptions to a stable API response', function () {
    $this->mock(\App\Services\BillingGateway::class)
        ->shouldReceive('charge')
        ->andThrow(new \App\Exceptions\BillingDeclined('Card declined'));

    $response = $this->postJson('/api/checkout', [
        'plan' => 'pro',
        'token' => 'tok_test',
    ]);

    $response
        ->assertStatus(402)
        ->assertJson([
            'message' => 'Payment could not be processed.',
            'code' => 'billing_declined',
        ]);
});

That test does more for upgrade safety than five pages of AI commentary. It preserves the contract that matters.

Once those tests exist, AI becomes more useful because it can help identify other places where similar assumptions may have drifted.

Use AI to ask targeted test questions

This is where the workflow starts to work well. Instead of asking, "review my Laravel upgrade," ask narrower questions:

Which touched areas lack regression tests?
Which renamed methods or config shifts appear incomplete?
Which custom exceptions, guards, or jobs are likely sensitive to framework lifecycle changes?

That framing keeps AI in the lane where it adds leverage.

Human Review Still Owns the Last Mile

The final review on an upgrade should not be a generic "LGTM" pass. It should be a risk review by someone who understands both Laravel and the business behavior behind the app.

What I care about in that last pass is not whether the code looks modern. I care about whether the upgrade preserved the contracts we actually rely on.

A useful human review usually asks questions like:

Did we change behavior, or only compatibility?
Did any framework-default recommendation override an intentional local design?
Do the tests cover the scary paths, not just the happy paths?
Did we quietly mix upgrade work with cleanup work that should have been separate?

That last point matters more than teams admit. Upgrade PRs get dangerous when they become an excuse to tidy architecture. Cleanups feel efficient in the moment, but they destroy your ability to isolate regressions.

My rule now is blunt: if a change is not required for the upgrade, it needs a stronger reason than "we were already in the file."

The Practical Rule I Use Now

AI review is worth using in Laravel upgrades, but only after you define the problem properly. It is a strong second pass for mechanical drift, incomplete migrations, and consistency checks. It is a weak substitute for architectural judgment, regression strategy, and knowledge of why your app is weird in the first place.

So the process I trust looks like this:

Read the official Laravel upgrade notes.
Write app-specific upgrade notes before touching code.
Split mechanical edits from behavioral changes.
Lock down risky behavior with tests.
Use AI for targeted review, not for ownership.
End with human review focused on invariants and risk.

If you only remember one thing, make it this: AI can help you finish a Laravel upgrade faster, but it cannot tell you what your application is allowed to break. That call is still yours, and pretending otherwise is how "successful" upgrades ship regressions.

Read the full post on QCode: https://qcode.in/ai-review-for-laravel-upgrades-is-useful-but-not-enough/

How I’d Use AI-Written Code Without Losing Touch With the Codebase

Saqueib Ansari — Mon, 10 Aug 2026 06:08:12 +0000

Shipping AI-written code is not dangerous because the model makes syntax mistakes. That part is easy to catch. The real risk is quieter: your team merges working code that nobody fully owns anymore. The code passes, the feature ships, and six weeks later a small change turns into a forensic exercise because the engineers who approved it never built a real mental model of it.

That is cognitive debt. It compounds faster than technical debt because it attacks the thing teams rely on to pay technical debt down later: understanding.

If you use Claude Code, Codex, or Cursor, the answer is not to ban them. The answer is to tighten the loop between generation and comprehension. Teams that keep ownership do a few things differently: they review for mechanism instead of style, they selectively retype critical paths, they force architecture checkpoints, and they prompt from tests instead of vibes.

Cognitive Debt Starts When Reading Replaces Thinking

Most teams notice the wrong failure mode first. They worry that AI will generate bad code. In practice, modern coding agents often generate code that is superficially fine: clean naming, decent structure, passing tests, maybe even better formatting than the average rushed engineer.

The problem starts when engineers become operators of generation instead of authors of systems. If your interaction pattern is "describe task, accept diff, skim output, merge," you are outsourcing more than typing. You are outsourcing the chain of reasoning that usually builds architectural memory.

That missing reasoning shows up later in predictable ways:

Small edits feel riskier than they should.
Review comments drift toward formatting instead of behavior.
Engineers trust tests they did not design.
Bugs take longer to localize because nobody knows which assumptions were deliberate.
Refactors stall because the team remembers the surface, not the structure.

A useful rule: if your team cannot explain why a generated implementation is shaped this way instead of two nearby alternatives, you already took on cognitive debt.

That is why this is not a style problem. It is an ownership problem.

Review Rituals Need To Target Understanding, Not Polish

Traditional code review habits are too weak for agent-generated code. A quick skim might be enough for a human-written patch from a trusted teammate because the author likely carried intent through the work. With AI-written code, the patch may be coherent while the reasoning behind it is thin, inconsistent, or completely absent.

So the review ritual needs a stronger bar. Not heavier process. Better questions.

Ask mechanism questions

A useful review comment is not "can we rename this helper?" A useful review comment is:

Why is state derived here instead of at the boundary?
What invariant is this cache relying on?
What breaks if this async step resolves twice?
Why is this controller validating and mapping instead of handing off to an action or service?

Those questions force the reviewer to reconstruct the design. If they cannot, the patch is not ready, even if it is technically correct.

Require an implementation note on non-trivial diffs

For anything with concurrency, persistence, caching, authorization, background jobs, or cross-service effects, require a short note from the engineer driving the agent. Not a novel. Just enough to prove they own the shape of the code.

A good note looks like this:

Implementation note:
- Validation stays at the HTTP boundary.
- Domain mapping happens in OrderDraftFactory so jobs and controllers share one path.
- Idempotency is enforced with a unique database key on external_event_id.
- Retry safety matters more here than raw throughput.

That note does two things. It gives reviewers real hooks, and it forces the engineer to collapse the generated output into a human model before merge.

If your team skips this step, review becomes theater.

Retype The Parts That Carry System Meaning

The most underrated defense against cognitive debt is selective retyping.

Not whole files. Not busywork. Just the sections that encode the system's actual decisions.

When people hear this, they usually object that retyping wastes the speed benefit. That is the wrong optimization target. The scarce resource is not keystrokes. It is understanding at the moment of change.

What should be retyped

Retype code when it defines one of these:

Core domain rules
Transaction boundaries
Query composition with subtle filters or joins
Authorization logic
Retry or idempotency behavior
Data transformations that downstream systems depend on
Prompt construction for agent workflows

Those are the places where hand contact matters. Retyping slows you down just enough to notice when something is off, overly clever, or based on a bad assumption.

What should not be retyped

Do not fetishize manual coding. Let the tool write the boring parts:

DTOs and basic schemas
Repetitive CRUD plumbing
Test fixture setup
Mechanical refactors
Simple adapters with obvious behavior

The point is not purity. The point is to keep engineers mentally attached to the code that shapes behavior.

A practical team rule is this: accept generated scaffolding freely, but manually rewrite the decision-making core.

Put Architecture Checkpoints Before Merge, Not After Incidents

AI tools are good at making local decisions look finished. That is exactly why they need explicit architecture checkpoints. Without them, you end up approving code that works in isolation but pushes complexity into the wrong layer.

In Laravel and full stack codebases, this usually shows up as controller bloat, duplicated orchestration logic, weak domain boundaries, and tests that verify current implementation instead of intended behavior.

A simple checkpoint template

Before merging a non-trivial AI-assisted patch, answer these five questions:

Where does validation belong?
Where does orchestration belong?
What is the stable domain boundary here?
Which part must be idempotent or retry-safe?
What would be painful to change in three months?

If those answers are fuzzy, stop generating more code. The design is not ready.

Example: thin controller vs generated sprawl

This is the kind of thing agents often produce when you prompt too broadly:

public function store(Request $request)
{
    $validated = $request->validate([
        'email' => ['required', 'email'],
        'plan' => ['required', 'string'],
    ]);

    $user = User::firstOrCreate(
        ['email' => $validated['email']],
        ['password' => Str::random(32)]
    );

    if (! $user->hasStripeId()) {
        $user->createAsStripeCustomer();
    }

    $subscription = $user->newSubscription('default', $validated['plan'])->create();

    AuditLog::create([
        'event' => 'subscription_created',
        'email' => $user->email,
    ]);

    dispatch(new SendWelcomeSequence($user->id));

    return response()->json([
        'subscription_id' => $subscription->id,
    ], 201);
}

It works. It is also carrying validation, user creation policy, billing orchestration, audit logging, and side effects in one HTTP action. That is not a controller. That is a future maintenance problem.

A tighter version is not just prettier. It has clearer ownership:

public function store(CreateSubscriptionRequest $request, CreateSubscription $action)
{
    $subscription = $action->handle($request->validated());

    return response()->json([
        'subscription_id' => $subscription->id,
    ], 201);
}

Now the real logic lives in a named action with explicit tests. The agent can still help write it, but the architecture has a spine.

That is the distinction that matters: generated code should fill a design, not invent one silently inside a diff.

Prompt From Tests First, Then Let The Agent Fill The Gaps

If you want less cognitive debt, stop starting with "build feature X." Start with tests and constraints.

A vague prompt gives you fast code and weak ownership. A test-first prompt gives you slower output up front and much stronger control over behavior, interfaces, and failure modes.

Better prompt shape

Instead of this:

Build a webhook handler for payment events and make it production ready.

Use this:

Write Pest tests first for a Laravel webhook handler.
Constraints:
- Must be idempotent on provider event ID.
- Invalid signatures return 400 and never enqueue jobs.
- Processing should happen in an action class, not the controller.
- Retries must be safe.
- Use a fake event payload factory in tests.
After the tests, implement the minimal code to pass them.
Then explain the chosen boundaries in 5 bullets.

That prompt does three important things:

It defines failure modes before implementation.
It constrains architecture instead of asking the model to guess it.
It forces the agent to produce an explanation you can review.

This pattern works across stacks. For frontend work, define rendering states and interaction tests first. For backend jobs, define retry semantics and side effects first. For agent workflows, define tool contracts and recovery behavior first.

The hidden win

Test-first prompting is not only about correctness. It gives the engineer a better memory trace. Writing or reviewing tests first creates a narrative of expected behavior. That narrative survives longer than whatever generated implementation happened to satisfy it this week.

Teams that skip this usually end up with the opposite: good-looking code and shallow recall.

Treat AI Output Like Pair Programming With A Fast, Forgetful Junior

The healthiest mental model is not "AI writes code for me." It is "I am pair programming with someone fast, confident, and unreliable about consequences."

That framing changes how you work.

You do not hand the junior a vague ticket and merge whatever comes back. You set boundaries, inspect decisions, rewrite critical sections, and insist on tests where behavior matters.

A lightweight operating policy

If you want something your team can actually adopt next week, start here:

Use AI freely for scaffolding, repetition, and search-heavy edits.
Require test-first or constraint-first prompts for non-trivial work.
Require a short implementation note on risky diffs.
Manually rewrite the parts that encode business rules or system boundaries.
Reject reviews that only discuss formatting and naming.
Track bugs caused by misunderstood generated code separately from normal defects.

That last point matters. If you do not measure cognitive misses, the team will keep telling itself velocity is fine while ownership is decaying underneath.

What to watch for in real teams

The strongest warning signs are cultural, not technical:

Engineers say "the agent did that" as if authorship transferred.
People hesitate to touch recently generated modules.
The same reviewer approves every AI-heavy diff because others do not want to unravel it.
Post-merge fixes cluster around misunderstood assumptions rather than hard edge cases.

When those patterns appear, your process is rewarding throughput at the expense of comprehension.

The Decision Rule

Use AI to remove typing, not to remove thinking.

That is the line. If a workflow makes your team faster and preserves a clear human explanation of behavior, boundaries, and tradeoffs, keep it. If it produces passing code that nobody can confidently reshape a month later, it is too expensive, no matter how good the demo looks.

The practical rule is simple: generate broadly, review mechanically, rewrite selectively, and anchor everything in tests.

That combination keeps the leverage and avoids the trap. Without it, AI-written code does not just add technical debt. It slowly teaches your team to stop holding the system in their heads, and once that habit lands, the codebase gets harder every sprint.

Read the full post on QCode: https://qcode.in/how-to-avoid-cognitive-debt-when-shipping-ai-written-code/

Laravel AI Search: When SQL Wins, When Embeddings Help, and When to Use Hybrid

Saqueib Ansari — Sun, 09 Aug 2026 05:40:20 +0000

Laravel teams keep reaching for embeddings the moment a product manager says “AI search.” That is usually the wrong first move. Most Laravel apps should start with solid SQL search, add vectors only when language mismatch becomes the real problem, and use hybrid retrieval when the stakes justify the complexity.

That recommendation sounds conservative, but it saves time, money, and a lot of relevance debugging. Search quality is not decided by whichever retrieval method sounds smarter. It is decided by whether your index matches the user’s intent, whether your ranking is inspectable, and whether your team can actually maintain the system in production.

If you are building search in a Laravel app today, the real question is not “Should we use embeddings?” It is: what failure mode are we solving?

SQL Still Wins More Than People Admit

For many Laravel products, search is still dominated by exact terms, field weighting, filters, recency, and business rules. That is classic relational territory.

If a user searches for an invoice number, a customer email, a SKU, a job title, a plan name, or a feature flag, vector search adds very little. In fact, it often makes those cases worse because semantic similarity is not the same as precision.

A normal SQL-backed approach can go a long way when you structure it properly:

normalize searchable text
use full-text indexes where your database supports them
mix exact-match boosts with partial-match fallbacks
rank by business value, not just textual similarity
keep filters first-class instead of bolting them on later

In Laravel, this baseline is usually faster to ship and much easier to debug than a vector stack.

$query = trim($request->string('q'));

$results = Post::query()
    ->select('*')
    ->selectRaw(
        "(
            CASE WHEN slug = ? THEN 100 ELSE 0 END +
            CASE WHEN title LIKE ? THEN 40 ELSE 0 END +
            CASE WHEN MATCH(title, excerpt, body) AGAINST (? IN NATURAL LANGUAGE MODE)
                THEN MATCH(title, excerpt, body) AGAINST (? IN NATURAL LANGUAGE MODE)
                ELSE 0
            END +
            CASE WHEN published_at >= NOW() - INTERVAL 90 DAY THEN 5 ELSE 0 END
        ) AS relevance",
        [$query, "$query%", $query, $query]
    )
    ->where('status', 'published')
    ->having('relevance', '>', 0)
    ->orderByDesc('relevance')
    ->limit(20)
    ->get();

This is not glamorous, but it is operationally honest. You can explain why a record ranked well. You can tweak weights. You can add hard constraints. You can log bad queries and improve them quickly.

Where SQL Search Breaks

The limit shows up when the query and the document use different language.

A user searches for “cancel subscription,” but your help article says “terminate billing cycle.” A recruiter searches for “backend lead,” but the profile says “principal platform engineer.” A support agent types “login loop after 2FA” and the incident summary uses different wording entirely.

That is where plain keyword retrieval starts leaking relevance. The problem is no longer indexing or filters. It is semantic mismatch.

Embeddings Solve a Different Problem

Embeddings are useful when you need meaning-based retrieval, not just text matching. They work best when your content is long-form, language-rich, and likely to be queried with varied phrasing.

Good candidates include:

help centers and internal docs
policy libraries
knowledge bases for AI assistants
long ticket histories or call summaries
product documentation with many paraphrased concepts

Bad candidates include:

admin tables
SKUs and IDs
invoice search
faceted catalog browsing
highly structured operational data

That distinction matters because vector search comes with real cost. You do not just store embeddings and move on. You now own chunking strategy, model choice, re-embedding pipelines, vector index storage, latency budgets, and failure analysis when the search starts returning “kind of related” junk.

The Hidden Cost Is Relevance Debugging

SQL search fails loudly. Vector search often fails softly.

With SQL, you can usually tell why a record did not match. With embeddings, the failure mode is murkier:

the chunk boundaries were wrong
the wrong field was embedded
the document was too broad
the query embedding drifted semantically
the nearest neighbors were technically related but practically useless

That makes embeddings powerful, but not automatically developer-friendly.

In a Laravel app, a typical vector flow might look like this:

$embedding = app(EmbeddingClient::class)->embed($request->string('q'));

$results = DB::table('knowledge_chunks')
    ->select('id', 'document_id', 'chunk_text')
    ->selectRaw('1 - (embedding <=> ?) as similarity', [$embedding])
    ->where('workspace_id', $workspaceId)
    ->orderByRaw('embedding <=> ?', [$embedding])
    ->limit(10)
    ->get();

The syntax depends on your storage choice, but the point is the same: this system is only as good as the chunks, the embedding model, and the retrieval constraints around it.

If you skip that design work, vector search turns into an expensive fuzzy lookup with impressive demos and disappointing production behavior.

Hybrid Retrieval Is Usually the Adult Answer

If your Laravel app has both structured precision needs and language-heavy discovery needs, hybrid retrieval is the best default end state.

Hybrid does not mean “throw SQL and vectors into one bag and hope.” It means each retrieval method does what it is good at, and your ranking layer combines them intentionally.

The pattern is simple:

run a keyword or full-text query
run a vector query
merge candidates
rerank using business rules, exact-match boosts, and optionally an LLM or cross-encoder

This gives you the best shot at balancing precision and recall.

A Practical Laravel Shape

In practice, you might keep two indexes:

a relational or full-text path for exact terms, filters, recency, and field-aware ranking
a vector path for semantic recall across longer content

Then combine the result sets in application code.

$keywordResults = app(KeywordSearch::class)->search($query, limit: 20);
$vectorResults = app(VectorSearch::class)->search($query, limit: 20);

$merged = collect([$keywordResults, $vectorResults])
    ->flatten(1)
    ->groupBy('id')
    ->map(function ($group) {
        $item = $group->first();

        $keywordScore = $group->max('keyword_score') ?? 0;
        $vectorScore = $group->max('vector_score') ?? 0;
        $freshnessBoost = $item->published_at?->gt(now()->subDays(30)) ? 0.05 : 0;
        $exactTitleBoost = $item->exact_title_match ? 0.25 : 0;

        $item->final_score =
            ($keywordScore * 0.55) +
            ($vectorScore * 0.35) +
            $freshnessBoost +
            $exactTitleBoost;

        return $item;
    })
    ->sortByDesc('final_score')
    ->take(10)
    ->values();

This is not mathematically pure, and that is fine. Search relevance in production is rarely elegant. What matters is that the ranking logic stays legible and adjustable.

Where Hybrid Actually Pays Off

Hybrid retrieval is worth the overhead when all of these are true:

users search with messy, natural language
exact terms still matter in part of the ranking
content is large enough that missed recall hurts real workflows
you have enough search volume or business value to justify tuning

A help center with AI chat grounding is a strong example. Users may search with vague phrasing, but exact product names, feature flags, plan tiers, and error codes still matter. Pure SQL misses semantic matches. Pure vector search can bury the exact answer. Hybrid gives you a better operating envelope.

Indexing Cost Changes the Decision More Than Most Teams Expect

Retrieval quality is only half the story. The other half is what it costs to keep the index correct.

SQL search has the lowest maintenance burden because the source of truth and the searchable representation usually live close together. Updates are straightforward. Reindexing is familiar. Operational ownership stays with the same team that owns the app.

Embeddings change that equation.

Every meaningful content change may require re-embedding. If you store chunked documents, you also need deterministic chunking so updates do not invalidate your ranking behavior unpredictably. If you switch embedding models later, you may need a full backfill. If you support multi-tenant search, index growth becomes a real budget line, not an implementation detail.

A Useful Decision Rule

Ask three questions before introducing vectors:

Is the current failure due to poor ranking or poor semantic recall?
Can we measure the missed cases with real queries?
Do we have an indexing pipeline we trust in production?

If the answer to the third question is no, do not pretend embeddings are a drop-in upgrade. They are an infrastructure choice.

For Laravel teams, this often means building a queue-backed indexing pipeline before going live with semantic retrieval.

class SyncKnowledgeChunkEmbeddings implements ShouldQueue
{
    public function __construct(public int $documentId) {}

    public function handle(EmbeddingClient $embeddings): void
    {
        $document = KnowledgeDocument::findOrFail($this->documentId);

        $chunks = app(DocumentChunker::class)->split($document->body_markdown);

        KnowledgeChunk::where('document_id', $document->id)->delete();

        foreach ($chunks as $index => $chunkText) {
            KnowledgeChunk::create([
                'document_id' => $document->id,
                'chunk_index' => $index,
                'chunk_text' => $chunkText,
                'embedding' => $embeddings->embed($chunkText),
            ]);
        }
    }
}

This is the part people skip in architecture diagrams. The retrieval demo is easy. The indexing lifecycle is where teams either build a real system or accumulate search debt.

Relevance Tuning: Which System Can Your Team Actually Operate?

This is where simple SQL keeps surprising people. It is not that embeddings are weak. It is that keyword ranking is often easier for a product team to improve week after week.

When stakeholders complain that the wrong result shows first, you need a tuning loop:

inspect the query
inspect the candidates
explain the ranking
change something small
measure whether it helped

That loop is much tighter in SQL and moderately harder in hybrid systems. It is hardest in pure vector systems unless you invest in evaluation tooling.

SQL Is Better for High-Control Search

If your product needs deterministic ranking rules, SQL or full-text should remain the backbone. Think CRMs, dashboards, admin panels, marketplaces, internal tools, and anything with dense filters.

In these systems, users are not asking broad conceptual questions. They are trying to find the right record under constraints. Exactness beats cleverness.

Embeddings Win for Knowledge Retrieval

If your app is powering assistant responses, internal documentation lookup, or support knowledge discovery, semantic retrieval earns its keep. But even there, I would still avoid pure vector search unless the corpus is truly narrative and low on structured signals.

Most production systems need metadata filters, source weighting, freshness bias, and sometimes document-type boosts. That already pushes you toward hybrid thinking.

What I Would Ship in a Real Laravel Codebase

If I were building this today, I would not start with the most advanced stack. I would stage the system.

Stage 1: Strong SQL Baseline

Start with:

exact-match boosts on key identifiers and titles
full-text search on main body fields
explicit filters for tenant, status, visibility, and type
logging for low-result or zero-result queries
admin tooling to inspect rankings

This gets you a reliable baseline quickly.

Stage 2: Add Vectors Only Where Recall Is Failing

Do not embed everything. Pick the content types where phrasing mismatch is clearly hurting outcomes. Usually that means docs, notes, transcripts, or tickets. Keep relational search for structured entities.

That split is cleaner architecturally and cheaper operationally.

Stage 3: Merge Into Hybrid Retrieval

Once you have evidence from real search logs, merge both paths and tune the reranking layer. This is where you add the product-specific intelligence:

exact title or slug boosts
newer content boosts
authoritative source boosts
demotion of thin or duplicate chunks
optional reranking for top candidates only

That last point matters. If you want to use a reranker or LLM judge, use it on a small candidate set. Do not waste expensive inference on your whole corpus.

For Laravel teams, this staged approach is the difference between “we shipped useful search” and “we adopted search infrastructure.”

The Sharp Recommendation

If your Laravel app mainly searches records, products, users, tickets, or operational data, start with SQL and full-text search. It is cheaper, easier to tune, and usually more correct.

If your app searches long-form knowledge where users describe ideas in inconsistent language, add embeddings. But treat them as a semantic recall layer, not magic relevance dust.

If both worlds matter, ship hybrid retrieval. That is the pragmatic production answer for most serious AI-enabled apps.

The mistake is not choosing the “wrong” algorithm. The mistake is solving a semantic problem with business-rule tools, or solving a precision problem with semantic tools.

Use SQL when you need control. Use embeddings when you need meaning. Use hybrid when your users need both. That is the version that survives contact with production.

Read the full post on QCode: https://qcode.in/laravel-ai-search-embeddings-sql-hybrid-retrieval/

Laravel cooldowns work better when each action has its own rules

Saqueib Ansari — Thu, 06 Aug 2026 06:46:06 +0000

Rate limiting is a decent default, but it is a bad product policy for many real workflows. A user refreshing a dashboard, generating an AI summary, exporting a CSV, inviting teammates, and resending a notification are not equivalent actions. They have different cost profiles, different abuse patterns, and different UX expectations. Treating them all as "N requests per minute" is how you end up protecting the wrong thing while annoying the right users.

In Laravel apps, per-action cooldowns are often a better fit than one-size-fits-all rate limits. The model is simple: after a specific actor performs a specific expensive action, you block or delay just that action for a short period. The rest of the product keeps working. That gives you tighter abuse control without turning the entire app into a traffic cop.

Where Rate Limits Get Too Blunt

Laravel's built-in rate limiting tools are solid. If you need IP-based throttling, login protection, or API quotas, use them. The problem starts when you apply the same mechanism to workflows that are not really about request volume.

An AI generation endpoint is not expensive because it gets called often. It is expensive because each call burns tokens, queue time, and maybe third-party API budget. An export button is not risky because it sees high RPS. It is risky because a single user can generate ten multi-megabyte exports back to back and bury your workers.

That is why cooldowns map better to intent than throughput. You are not saying, "this user may only make 20 requests per minute." You are saying, "this user may trigger this costly action once every 30 seconds." That is a very different policy, and usually the more correct one.

A few common cases where cooldowns beat generic throttles:

AI content generation per workspace owner or user
CSV, PDF, or ZIP exports
Invite sending and reminder emails
OTP resend or magic-link resend
Notification blasts to teams or customers
Billing-related recalculation jobs

The key idea is narrow scope. Instead of globally slowing a user down, you cool down the exact thing that is expensive, spammy, or operationally risky.

Model The Cooldown Around Ownership and Action

The most useful cooldown key is usually owner + action, not IP + route.

Why owner? Because many expensive actions are tied to an account, team, tenant, or workspace budget. If one workspace generates ten AI reports in a minute, that cost lands on the workspace whether the requests came from one user, three users, or a job retried twice.

Why action? Because not all expensive operations deserve the same waiting window. A resend-email button may need 60 seconds. AI generation may need 15 seconds. Export creation may need 2 minutes. A single global throttle cannot express that cleanly.

A practical key format looks like this:

$cooldownKey = sprintf('cooldown:%s:%s', $ownerId, $action);

You then store the next allowed timestamp or use a cache lock/TTL to represent the wait window.

A Minimal Laravel Service

A small dedicated service keeps this logic out of controllers and makes the policy reusable.

<?php

namespace App\Support;

use Illuminate\Contracts\Cache\Repository as Cache;
use Illuminate\Support\Carbon;

class ActionCooldowns
{
    public function __construct(private Cache $cache) {}

    public function activeFor(string|int $ownerId, string $action): ?Carbon
    {
        $expiresAt = $this->cache->get($this->key($ownerId, $action));

        if (! $expiresAt) {
            return null;
        }

        $time = Carbon::createFromTimestamp($expiresAt);

        return $time->isFuture() ? $time : null;
    }

    public function start(string|int $ownerId, string $action, int $seconds): Carbon
    {
        $expiresAt = now()->addSeconds($seconds);

        $this->cache->put(
            $this->key($ownerId, $action),
            $expiresAt->timestamp,
            $expiresAt
        );

        return $expiresAt;
    }

    public function enforce(string|int $ownerId, string $action): void
    {
        if ($until = $this->activeFor($ownerId, $action)) {
            abort(response()->json([
                'message' => 'Action temporarily unavailable.',
                'retry_after_seconds' => now()->diffInSeconds($until),
                'retry_at' => $until->toIso8601String(),
            ], 429));
        }
    }

    private function key(string|int $ownerId, string $action): string
    {
        return "cooldown:{$ownerId}:{$action}";
    }
}

This is intentionally boring. Boring is good here. You want a single place where cooldown policy is obvious, testable, and easy to extend.

Why Cache TTL Is Usually Enough

For cooldowns, Redis or your cache store is usually the right layer. You do not need a database table unless you need analytics, audit history, or operator visibility.

A cache-backed cooldown has the right properties:

cheap reads and writes
natural expiry
shared across app servers
good enough precision for product enforcement

If you are running multiple web nodes or queue workers, do not keep cooldown state in memory. Use a shared backend such as Redis. Otherwise your policy becomes node-dependent, which is another way of saying broken.

Add Cooldowns At The Workflow Boundary

The right place to enforce a cooldown is usually the boundary where cost or side effects begin. Not every controller deserves this. The actions that do are the ones that kick off work, send something external, or consume a priced dependency.

Example: AI Generation

This is the classic case. If a workspace can trigger a generation every few seconds, users can accidentally hammer your token budget just by clicking twice.

public function store(GenerateSummaryRequest $request, ActionCooldowns $cooldowns)
{
    $workspace = $request->user()->currentWorkspace;

    $cooldowns->enforce($workspace->id, 'ai-summary-generate');

    dispatch(new GenerateSummaryJob(
        workspaceId: $workspace->id,
        prompt: $request->string('prompt')->toString(),
    ));

    $cooldowns->start($workspace->id, 'ai-summary-generate', 20);

    return response()->json([
        'message' => 'Generation queued.',
    ], 202);
}

That policy is much sharper than throttle:10,1 on the route. It protects the exact action that costs money while allowing the user to keep navigating, editing, or fetching other data.

A useful refinement is dynamic cooldowns. If the model is expensive or the prompt size is large, increase the cooldown. If the workspace is on a higher plan, shorten it. Cooldowns are product policy, so they should reflect product reality.

Example: Export Generation

Exports tend to create operational spikes, especially when users click again because the UI did not make progress obvious.

public function export(Request $request, ActionCooldowns $cooldowns)
{
    $account = $request->user()->account;

    $cooldowns->enforce($account->id, 'orders-export');

    ExportOrders::dispatch($account->id, $request->all());

    $cooldowns->start($account->id, 'orders-export', 120);

    return response()->json([
        'message' => 'Export started. We will notify you when it is ready.',
    ], 202);
}

This does two things a global rate limit does not.

First, it stops repeated export launches even if the user is otherwise behaving normally. Second, it creates a predictable product contract: one export every two minutes for this account.

That is easier to explain, easier to support, and easier to reason about than a generic route throttle that may or may not trigger depending on unrelated requests.

The UX Matters More Than The Backend Trick

A cooldown without a clear UI is just a bug with a timer. If the user clicks a button and gets a 429 with no context, they will keep clicking, retry from another tab, or assume your app is broken.

You need to surface the policy clearly.

Return Structured Retry Data

Do not just return "Too many requests." Return when the user can try again.

A good response includes:

a stable error message
retry_after_seconds
an absolute retry_at timestamp
optionally the action name for the client

That gives the frontend enough data to disable the button, start a countdown, and avoid blind retries.

Show Cooldowns In The Interface

If a user triggers an action with a cooldown, the UI should reflect it immediately. Disable the action, show a countdown, and explain why. For AI generation, say it is preventing duplicate runs. For exports, say one export is already in progress or recently started.

This is not decoration. It reduces duplicate work and support noise.

Pair Cooldowns With Idempotency When Needed

Cooldowns stop repeated triggers across a time window. They do not solve duplicate submissions caused by network retries or double form posts at the same instant. For that, use idempotency keys or job deduplication.

Cooldowns and idempotency solve different failures. If the workflow is expensive enough, you usually want both.

A good decision rule:

Use idempotency to prevent accidental duplicates of the same intent.
Use cooldowns to limit how often a costly intent may be started.
Use rate limits for broad traffic control, abuse protection, and API fairness.

Failure Modes To Avoid

Most bad cooldown implementations are not conceptually wrong. They are just attached to the wrong identity, stored in the wrong place, or tuned with no product thinking.

Cooldown By IP

This is usually the wrong key for authenticated product workflows. Shared office IPs, VPNs, mobile networks, and browser privacy features make IP-based cooldowns noisy and unfair. If the action belongs to an account or workspace, key it that way.

Cooldown That Starts Too Early

If you start the cooldown before basic validation or authorization, you can punish harmless user mistakes. Start it when the system actually accepts the action and begins meaningful work.

Cooldown That Starts Too Late

If you only set the cooldown after a long-running job completes, repeated clicks can queue duplicates before the window exists. For queued workflows, start the cooldown at dispatch time or reserve the action with an atomic lock first.

No Atomic Guard Around First Trigger

If two requests arrive at nearly the same moment, both can pass the "not on cooldown" check before one writes the TTL. In high-contention actions, use Redis-backed atomic primitives such as locks or Cache::add() semantics instead of a naive read-then-write sequence.

A stronger pattern looks like this:

$acquired = Cache::add("cooldown:{$ownerId}:{$action}", now()->addSeconds($seconds)->timestamp, now()->addSeconds($seconds));

if (! $acquired) {
    return response()->json([
        'message' => 'Please wait before retrying this action.',
    ], 429);
}

That closes the race for the first write in a simple way.

Inventing Cooldowns For Everything

This is where teams go wrong after discovering the pattern. Not every action needs a cooldown. If the action is cheap, reversible, and already protected by validation, adding a wait window is just friction.

Use cooldowns for actions that are at least one of these:

expensive
spam-prone
operationally heavy
externally visible
confusing when triggered multiple times

If an action does not hit one of those, do not force it.

A Better Default For Real Laravel Products

If your app has AI features, exports, invites, notifications, or any workflow with uneven cost, stop reaching for one generic throttle first. Per-action cooldowns give you a more honest policy surface. They let you protect expensive paths tightly while leaving the rest of the product responsive.

Laravel makes this easy because the underlying pieces are already there: cache, Redis, jobs, policies, and clean service abstractions. The trick is not technical difficulty. The trick is choosing the right control for the job.

My recommendation is simple: keep Laravel rate limiting for broad API and auth protection, then add owner-scoped action cooldowns for workflows that cost real money or create real operational drag. When the action is expensive, user-facing, and easy to spam, a cooldown is usually the cleaner answer.

If your current policy reads like "5 requests per minute" for a costly button, you probably have the wrong abstraction. Replace it with a rule the product can actually defend: who can do what, and how often, without harming cost, systems, or UX.

Read the full post on QCode: https://qcode.in/per-action-cooldowns-laravel-rate-limits/