DEV Community: Saqueib Ansari

When pagination becomes infrastructure, the simple defaults stop working

Saqueib Ansari — Sat, 25 Apr 2026 08:29:12 +0000

Pagination looks trivial when all you need is page=3&per_page=20 in a CRUD screen. It stops being trivial the moment the same dataset starts serving customer search, CSV exports, background sync jobs, and admin tooling with different correctness requirements.

That is when a list endpoint quietly turns into infrastructure.

The problem is not pagination itself. The problem is pretending one pagination strategy can satisfy every consumer equally well. It cannot. Offset pagination, cursor pagination, keyset pagination, snapshot exports, and bulk traversal each solve different problems. If you force one model across all of them, you usually end up with slow queries, duplicate rows, missing rows, broken exports, or admin screens that feel inconsistent under load.

The practical rule is simple: paginate by product need, not by frontend habit.

If a list is customer-facing and needs numbered pages, optimize for navigation clarity. If a job needs to walk millions of rows safely, optimize for traversal stability. If an export must reflect a coherent slice of data, optimize for snapshot semantics. Treating those as the same problem is how “simple pagination” becomes a source of recurring bugs.

The first decision is not page size. It is consistency model

Most teams start pagination discussions with UI concerns: page count, next/previous links, infinite scroll, visible totals. Those matter, but they are downstream from a more important question:

What kind of correctness does this consumer expect while the dataset is changing?

That question immediately separates your use cases.

Customer browsing usually wants navigability

A customer looking through products, invoices, or posts usually cares about:

predictable sorting
reasonable page-to-page movement
stable enough results for a short session
visible counts or progress markers

They do not usually need perfect traversal of a mutating dataset. They need a good browsing experience.

Background jobs want traversal safety

A sync worker or batch processor cares about different things:

never skipping rows
never reprocessing rows accidentally unless idempotent
surviving inserts and deletes during traversal
avoiding deep offset scans

That is not a browsing problem. It is a data movement problem.

Exports want snapshot-like behavior

Exports are even stricter. Users usually assume “export the results I am looking at” means a coherent dataset, not a moving target assembled over several minutes while records keep changing underneath it.

Admin tools sit awkwardly in the middle

Admin screens often want both:

human-friendly navigation
filters and search
stable enough views to investigate issues
the ability to bulk act on rows safely

That mixed requirement is why admin tooling is where weak pagination design gets exposed fastest.

Offset pagination is fine until it becomes your default hammer

Offset pagination is the first thing most teams ship because it is easy to reason about.

SELECT id, name, created_at
FROM users
ORDER BY created_at DESC, id DESC
LIMIT 50 OFFSET 100;

It works well for simple interfaces where users want page numbers, total counts, and arbitrary jumps.

Where offset pagination wins

Offset is still the best fit when you need:

numbered pages
direct jumps to page N
compatibility with common UI table patterns
relatively small or moderately sized datasets
simple mental models for internal tools

That is why it stays popular. For many backoffice screens, it is good enough.

Where offset pagination starts failing

The weaknesses show up when the dataset is large or actively changing.

Deep offsets get expensive

Databases still have to walk past earlier rows to reach the requested offset. On large datasets, page 1 is cheap and page 10,000 is not.

Changing data causes drift

If new rows are inserted at the top between page requests, offset-based browsing can produce duplicates or gaps.

A user sees rows 1 to 50, moves to the next page, and now sees some overlapping records because the whole result set shifted.

Exports built on offsets are especially fragile

If you implement export by repeatedly calling the same offset-based list endpoint, you are asking for silent inconsistency under concurrent writes.

That is the point many teams miss: offset pagination is a navigation tool, not a reliable dataset traversal strategy.

Use offset where it belongs

Use offset for human navigation when:

page numbers matter
absolute traversal correctness does not
the dataset is not huge
filters are reasonably selective

Do not stretch it into batch infrastructure just because the endpoint already exists.

Cursor and keyset pagination are better when the list must survive change

Once you care about stable traversal under inserts and deletes, cursor-style pagination becomes the better tool.

In practice, most production-safe cursor pagination is a form of keyset pagination: “give me the next rows after this ordered position.”

SELECT id, created_at, email
FROM users
WHERE (created_at, id) < ('2026-04-24T12:30:00Z', 98421)
ORDER BY created_at DESC, id DESC
LIMIT 50;

This pattern is dramatically more stable than offset because it does not ask the database to skip an arbitrary number of rows. It asks for rows after a known boundary in a stable sort order.

Why keyset pagination survives production better

It has three big strengths:

It scales better for deep traversal.
It behaves more predictably while new rows are inserted.
It maps naturally to APIs and infinite scroll.

If you are building public APIs, activity feeds, large search result sets, or internal tools that may be traversed deeply, cursor-based pagination is usually the better default.

But cursor pagination is not a free upgrade

It has real tradeoffs.

You need a stable sort key

The order must be deterministic. Sorting only by created_at is not enough if multiple rows share the same timestamp. Add a tiebreaker like id.

Arbitrary page jumps become awkward

Cursor pagination is great for “next” and “previous.” It is bad for “jump to page 87.” If your UI truly depends on numbered navigation, forcing cursors into that experience can make the product worse.

Cursors need careful encoding

Do not expose raw assumptions loosely. Encode the cursor cleanly, usually as an opaque token.

{
  "data": [...],
  "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wNC0yNFQxMjozMDowMFoiLCJpZCI6OTg0MjF9"
}

That gives you flexibility to evolve internals later without breaking clients.

A solid full-stack pattern for search APIs

If a search page supports filters, sorting, and “load more,” cursor pagination is usually the right choice.

Backend response shape:

{
  "items": [
    {"id": 98421, "name": "Aarav", "created_at": "2026-04-24T12:30:00Z"},
    {"id": 98420, "name": "Sara", "created_at": "2026-04-24T12:29:58Z"}
  ],
  "page_info": {
    "has_next_page": true,
    "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wNC0yNFQxMjozMDo1OFoiLCJpZCI6OTg0MjB9"
  }
}

Frontend usage stays simple: keep filters and sort params stable, pass the cursor forward, append results, and reset the cursor when the query changes.

That is a better long-term pattern than pretending infinite scroll is just offset pagination with a nicer UI.

Exports should almost never reuse the live paginated browsing flow

This is one of the most common production mistakes.

A team already has a list endpoint, so they build CSV export by iterating over its pages until no more results remain. It feels efficient because the endpoint already exists.

It is also usually wrong.

Exports have different semantics from browsing.

Why live pagination is a bad export foundation

If the export takes time and rows are changing underneath it, a live page-by-page export can:

miss rows inserted after earlier pages were read
duplicate rows when sorting shifts
export data with mixed timestamps or inconsistent state
create confusing mismatches between on-screen counts and exported totals

That is not a pagination bug in isolation. It is a contract bug.

Better export patterns

Pattern 1: export from a fixed filter snapshot

At export start, persist the exact filter and sort configuration plus a cutoff boundary.

For example:

status = active
created_at <= export_started_at
sort by id asc

Then run the export job against that frozen definition, not against the evolving UI query.

Pattern 2: export by ID materialization

For stricter correctness, materialize the matching IDs first, then process them in chunks.

INSERT INTO export_items (export_id, record_id)
SELECT :export_id, users.id
FROM users
WHERE status = 'active'
  AND created_at <= :snapshot_time;

Then stream the export off export_items in chunked passes.

This costs more upfront, but it gives you a stable export contract and clean retry semantics.

Pattern 3: export from a replica or warehouse when latency is acceptable

For analytics-heavy or operationally expensive exports, moving the concern away from the transactional app database is often the right call.

The important idea is this: exports are batch jobs with consistency expectations, not just large paginated reads.

Admin tools need dual-mode pagination, not one-size-fits-all purity

Admin systems are where pagination design gets political. People want page numbers, total counts, fast filters, bulk actions, and safe processing across large datasets.

You will not satisfy all of that with one primitive.

The better approach is to separate admin use cases by intent.

Mode 1: human inspection

For analysts, support staff, or operators browsing a filtered table, offset pagination may still be the right answer.

Why? Because admins often want:

page numbers
visible totals
direct page jumps
familiar data-table behavior

That is a UI problem first.

Mode 2: bulk operations

The moment an admin selects “apply action to all matching records,” you are no longer in simple browsing mode.

Now you need bulk traversal semantics. That usually means:

snapshotting the matching set
materializing IDs
processing in chunks or keyset order
making the action idempotent

Do not run bulk operations by replaying the visible page structure. The paginated table is just the discovery layer.

A clean admin architecture

A strong pattern looks like this:

GET /admin/users uses offset or cursor pagination for browsing
POST /admin/users/export creates a snapshot-backed export job
POST /admin/users/bulk-disable creates a bulk operation from a frozen filter or materialized ID set

That split avoids the classic anti-pattern where the admin table endpoint quietly becomes the source of truth for every downstream workflow.

Search changes pagination more than most teams expect

Search is where naive pagination contracts start breaking because relevance ranking is not always stable in the same way as relational sorting.

If your search backend is Elasticsearch, Meilisearch, Typesense, or a hybrid database search layer, pagination behavior depends heavily on ranking stability and index refresh timing.

Why search results are trickier

Search datasets can change because of:

new documents being indexed
ranking signals changing
typo tolerance or synonym behavior
filter changes
personalization layers

That means “page 2” may not be a fixed slice of reality in the same way as a table sorted by id.

Good pattern: separate search pagination from database pagination

Do not force your application DB pagination assumptions directly onto search results.

If search is the source of ranking truth, paginate within the search engine’s model and then hydrate records from the database as needed.

That often means cursor-like or engine-specific continuation tokens are more correct than page/offset semantics.

Bad pattern: search IDs first, then re-sort in SQL

Teams sometimes fetch IDs from search, then run a SQL query that reorders the results differently. That breaks pagination consistency immediately.

Pick the source of ordering truth and keep it consistent through the response.

Search plus exports needs an explicit contract

If users can export search results, define what that means:

export the currently matching results at export start?
export a capped relevance window?
export all records matching the current filters, ignoring ranking drift after snapshot?

If that contract is vague, pagination bugs will show up as product confusion.

The safest production design is usually three separate patterns

Most mature systems converge on a split like this, whether they admit it or not.

Pattern 1: browsing pagination

Use offset or cursor depending on the UX.

Best for:

customer lists
dashboards
admin inspection tables
public APIs with next/previous navigation

Pattern 2: traversal pagination

Use keyset pagination or chunk-by-ID for workers, syncs, and batch jobs.

Best for:

backfills
data sync jobs
email campaign recipient traversal
background reconciliation
bulk reprocessing

A simple example in application code:

$lastId = 0;

while (true) {
    $rows = DB::table('orders')
        ->where('id', '>', $lastId)
        ->orderBy('id')
        ->limit(1000)
        ->get();

    if ($rows->isEmpty()) {
        break;
    }

    foreach ($rows as $row) {
        processOrder($row);
        $lastId = $row->id;
    }
}

This is not flashy, but it is far safer than looping over OFFSET across a large, changing table.

Pattern 3: snapshot pagination

Use frozen filters, materialized IDs, or export manifests for workflows that need coherence.

Best for:

CSV and Excel exports
compliance reports
admin bulk actions with audit requirements
cross-system syncs that must be retryable

These patterns should be different because the guarantees are different.

What to standardize across the stack

Even if you use multiple pagination patterns, you still want consistency in how the stack expresses them.

Standardize response metadata by intent

For browsing endpoints, expose a predictable shape:

items
page_info
total only when it is truly supported and affordable
next_cursor or page metadata depending on strategy

For batch and export flows, do not pretend they are normal paginated reads. Expose job resources instead:

job_id
status
snapshot_time
download_url
processed_count

That distinction keeps clients honest.

Standardize sort rules

Every paginated endpoint should have:

an explicit default sort
a deterministic tiebreaker
documented allowed sort fields
a clear statement of whether pagination is stable under concurrent writes

A shocking number of production bugs come from undocumented sort ambiguity, not from the pagination primitive itself.

Standardize frontend expectations

Frontend teams should know whether an endpoint supports:

direct page jumps
infinite scroll
stable totals
export of current filters
background bulk action handoff

If the UI assumes all list endpoints behave alike, backend pagination differences will leak as weird product behavior.

The practical rule of thumb

Pagination is not one problem. It is at least three:

navigation for humans
traversal for systems
snapshotting for exports and bulk workflows

Treating all three as limit + offset is how simple list endpoints become fragile product infrastructure.

If you want a durable production rule, use this one:

Use offset for navigation, keyset for traversal, and snapshots for exports.

You can bend that rule in specific cases, but if your stack has customer search, admin tables, exports, and background jobs all touching the same data, that baseline split will save you from a lot of quiet bugs.

The real maturity move is not finding one pagination pattern that does everything. It is admitting the dataset now serves different consumers with different correctness needs, and designing each path accordingly.

Read the full post on QCode: https://qcode.in/full-stack-pagination-patterns-that-survive-exports-search-and-admin-tools-2/

Pagination stops being simple when one list endpoint has to do five jobs

Saqueib Ansari — Sat, 25 Apr 2026 08:28:18 +0000

That is when a list endpoint quietly turns into infrastructure.

The practical rule is simple: paginate by product need, not by frontend habit.

The first decision is not page size. It is consistency model

Most teams start pagination discussions with UI concerns: page count, next/previous links, infinite scroll, visible totals. Those matter, but they are downstream from a more important question:

What kind of correctness does this consumer expect while the dataset is changing?

That question immediately separates your use cases.

Customer browsing usually wants navigability

A customer looking through products, invoices, or posts usually cares about:

predictable sorting
reasonable page-to-page movement
stable enough results for a short session
visible counts or progress markers

They do not usually need perfect traversal of a mutating dataset. They need a good browsing experience.

Background jobs want traversal safety

A sync worker or batch processor cares about different things:

never skipping rows
never reprocessing rows accidentally unless idempotent
surviving inserts and deletes during traversal
avoiding deep offset scans

That is not a browsing problem. It is a data movement problem.

Exports want snapshot-like behavior

Admin tools sit awkwardly in the middle

Admin screens often want both:

human-friendly navigation
filters and search
stable enough views to investigate issues
the ability to bulk act on rows safely

That mixed requirement is why admin tooling is where weak pagination design gets exposed fastest.

Offset pagination is fine until it becomes your default hammer

Offset pagination is the first thing most teams ship because it is easy to reason about.

SELECT id, name, created_at
FROM users
ORDER BY created_at DESC, id DESC
LIMIT 50 OFFSET 100;

It works well for simple interfaces where users want page numbers, total counts, and arbitrary jumps.

Where offset pagination wins

Offset is still the best fit when you need:

numbered pages
direct jumps to page N
compatibility with common UI table patterns
relatively small or moderately sized datasets
simple mental models for internal tools

That is why it stays popular. For many backoffice screens, it is good enough.

Where offset pagination starts failing

The weaknesses show up when the dataset is large or actively changing.

Deep offsets get expensive

Databases still have to walk past earlier rows to reach the requested offset. On large datasets, page 1 is cheap and page 10,000 is not.

Changing data causes drift

If new rows are inserted at the top between page requests, offset-based browsing can produce duplicates or gaps.

A user sees rows 1 to 50, moves to the next page, and now sees some overlapping records because the whole result set shifted.

Exports built on offsets are especially fragile

If you implement export by repeatedly calling the same offset-based list endpoint, you are asking for silent inconsistency under concurrent writes.

That is the point many teams miss: offset pagination is a navigation tool, not a reliable dataset traversal strategy.

Use offset where it belongs

Use offset for human navigation when:

page numbers matter
absolute traversal correctness does not
the dataset is not huge
filters are reasonably selective

Do not stretch it into batch infrastructure just because the endpoint already exists.

Cursor and keyset pagination are better when the list must survive change

Once you care about stable traversal under inserts and deletes, cursor-style pagination becomes the better tool.

In practice, most production-safe cursor pagination is a form of keyset pagination: “give me the next rows after this ordered position.”

SELECT id, created_at, email
FROM users
WHERE (created_at, id) < ('2026-04-24T12:30:00Z', 98421)
ORDER BY created_at DESC, id DESC
LIMIT 50;

This pattern is dramatically more stable than offset because it does not ask the database to skip an arbitrary number of rows. It asks for rows after a known boundary in a stable sort order.

Why keyset pagination survives production better

It has three big strengths:

It scales better for deep traversal.
It behaves more predictably while new rows are inserted.
It maps naturally to APIs and infinite scroll.

If you are building public APIs, activity feeds, large search result sets, or internal tools that may be traversed deeply, cursor-based pagination is usually the better default.

But cursor pagination is not a free upgrade

It has real tradeoffs.

You need a stable sort key

The order must be deterministic. Sorting only by created_at is not enough if multiple rows share the same timestamp. Add a tiebreaker like id.

Arbitrary page jumps become awkward

Cursors need careful encoding

Do not expose raw assumptions loosely. Encode the cursor cleanly, usually as an opaque token.

{
  "data": [...],
  "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wNC0yNFQxMjozMDowMFoiLCJpZCI6OTg0MjF9"
}

That gives you flexibility to evolve internals later without breaking clients.

A solid full-stack pattern for search APIs

If a search page supports filters, sorting, and “load more,” cursor pagination is usually the right choice.

Backend response shape:

{
  "items": [
    {"id": 98421, "name": "Aarav", "created_at": "2026-04-24T12:30:00Z"},
    {"id": 98420, "name": "Sara", "created_at": "2026-04-24T12:29:58Z"}
  ],
  "page_info": {
    "has_next_page": true,
    "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wNC0yNFQxMjozMDo1OFoiLCJpZCI6OTg0MjB9"
  }
}

Frontend usage stays simple: keep filters and sort params stable, pass the cursor forward, append results, and reset the cursor when the query changes.

That is a better long-term pattern than pretending infinite scroll is just offset pagination with a nicer UI.

Exports should almost never reuse the live paginated browsing flow

This is one of the most common production mistakes.

A team already has a list endpoint, so they build CSV export by iterating over its pages until no more results remain. It feels efficient because the endpoint already exists.

It is also usually wrong.

Exports have different semantics from browsing.

Why live pagination is a bad export foundation

If the export takes time and rows are changing underneath it, a live page-by-page export can:

miss rows inserted after earlier pages were read
duplicate rows when sorting shifts
export data with mixed timestamps or inconsistent state
create confusing mismatches between on-screen counts and exported totals

That is not a pagination bug in isolation. It is a contract bug.

Better export patterns

Pattern 1: export from a fixed filter snapshot

At export start, persist the exact filter and sort configuration plus a cutoff boundary.

For example:

status = active
created_at <= export_started_at
sort by id asc

Then run the export job against that frozen definition, not against the evolving UI query.

Pattern 2: export by ID materialization

For stricter correctness, materialize the matching IDs first, then process them in chunks.

INSERT INTO export_items (export_id, record_id)
SELECT :export_id, users.id
FROM users
WHERE status = 'active'
  AND created_at <= :snapshot_time;

Then stream the export off export_items in chunked passes.

This costs more upfront, but it gives you a stable export contract and clean retry semantics.

Pattern 3: export from a replica or warehouse when latency is acceptable

For analytics-heavy or operationally expensive exports, moving the concern away from the transactional app database is often the right call.

The important idea is this: exports are batch jobs with consistency expectations, not just large paginated reads.

Admin tools need dual-mode pagination, not one-size-fits-all purity

Admin systems are where pagination design gets political. People want page numbers, total counts, fast filters, bulk actions, and safe processing across large datasets.

You will not satisfy all of that with one primitive.

The better approach is to separate admin use cases by intent.

Mode 1: human inspection

For analysts, support staff, or operators browsing a filtered table, offset pagination may still be the right answer.

Why? Because admins often want:

page numbers
visible totals
direct page jumps
familiar data-table behavior

That is a UI problem first.

Mode 2: bulk operations

The moment an admin selects “apply action to all matching records,” you are no longer in simple browsing mode.

Now you need bulk traversal semantics. That usually means:

snapshotting the matching set
materializing IDs
processing in chunks or keyset order
making the action idempotent

Do not run bulk operations by replaying the visible page structure. The paginated table is just the discovery layer.

A clean admin architecture

A strong pattern looks like this:

GET /admin/users uses offset or cursor pagination for browsing
POST /admin/users/export creates a snapshot-backed export job
POST /admin/users/bulk-disable creates a bulk operation from a frozen filter or materialized ID set

That split avoids the classic anti-pattern where the admin table endpoint quietly becomes the source of truth for every downstream workflow.

Search changes pagination more than most teams expect

Search is where naive pagination contracts start breaking because relevance ranking is not always stable in the same way as relational sorting.

If your search backend is Elasticsearch, Meilisearch, Typesense, or a hybrid database search layer, pagination behavior depends heavily on ranking stability and index refresh timing.

Why search results are trickier

Search datasets can change because of:

new documents being indexed
ranking signals changing
typo tolerance or synonym behavior
filter changes
personalization layers

That means “page 2” may not be a fixed slice of reality in the same way as a table sorted by id.

Good pattern: separate search pagination from database pagination

Do not force your application DB pagination assumptions directly onto search results.

If search is the source of ranking truth, paginate within the search engine’s model and then hydrate records from the database as needed.

That often means cursor-like or engine-specific continuation tokens are more correct than page/offset semantics.

Bad pattern: search IDs first, then re-sort in SQL

Teams sometimes fetch IDs from search, then run a SQL query that reorders the results differently. That breaks pagination consistency immediately.

Pick the source of ordering truth and keep it consistent through the response.

Search plus exports needs an explicit contract

If users can export search results, define what that means:

export the currently matching results at export start?
export a capped relevance window?
export all records matching the current filters, ignoring ranking drift after snapshot?

If that contract is vague, pagination bugs will show up as product confusion.

The safest production design is usually three separate patterns

Most mature systems converge on a split like this, whether they admit it or not.

Pattern 1: browsing pagination

Use offset or cursor depending on the UX.

Best for:

customer lists
dashboards
admin inspection tables
public APIs with next/previous navigation

Pattern 2: traversal pagination

Use keyset pagination or chunk-by-ID for workers, syncs, and batch jobs.

Best for:

backfills
data sync jobs
email campaign recipient traversal
background reconciliation
bulk reprocessing

A simple example in application code:

$lastId = 0;

while (true) {
    $rows = DB::table('orders')
        ->where('id', '>', $lastId)
        ->orderBy('id')
        ->limit(1000)
        ->get();

    if ($rows->isEmpty()) {
        break;
    }

    foreach ($rows as $row) {
        processOrder($row);
        $lastId = $row->id;
    }
}

This is not flashy, but it is far safer than looping over OFFSET across a large, changing table.

Pattern 3: snapshot pagination

Use frozen filters, materialized IDs, or export manifests for workflows that need coherence.

Best for:

CSV and Excel exports
compliance reports
admin bulk actions with audit requirements
cross-system syncs that must be retryable

These patterns should be different because the guarantees are different.

What to standardize across the stack

Even if you use multiple pagination patterns, you still want consistency in how the stack expresses them.

Standardize response metadata by intent

For browsing endpoints, expose a predictable shape:

items
page_info
total only when it is truly supported and affordable
next_cursor or page metadata depending on strategy

For batch and export flows, do not pretend they are normal paginated reads. Expose job resources instead:

job_id
status
snapshot_time
download_url
processed_count

That distinction keeps clients honest.

Standardize sort rules

Every paginated endpoint should have:

an explicit default sort
a deterministic tiebreaker
documented allowed sort fields
a clear statement of whether pagination is stable under concurrent writes

A shocking number of production bugs come from undocumented sort ambiguity, not from the pagination primitive itself.

Standardize frontend expectations

Frontend teams should know whether an endpoint supports:

direct page jumps
infinite scroll
stable totals
export of current filters
background bulk action handoff

If the UI assumes all list endpoints behave alike, backend pagination differences will leak as weird product behavior.

The practical rule of thumb

Pagination is not one problem. It is at least three:

navigation for humans
traversal for systems
snapshotting for exports and bulk workflows

Treating all three as limit + offset is how simple list endpoints become fragile product infrastructure.

If you want a durable production rule, use this one:

Use offset for navigation, keyset for traversal, and snapshots for exports.

Read the full post on QCode: https://qcode.in/full-stack-pagination-patterns-that-survive-exports-search-and-admin-tools/

Laravel job debouncing works better when urgency has its own lane

Saqueib Ansari — Fri, 24 Apr 2026 16:10:15 +0000

Laravel debounced jobs are great when the newest state is all you care about. They are dangerous when you use them to collapse events that only look similar from far away.

That distinction is where most teams get burned.

If a user edits a draft title six times in ten seconds, debouncing the search reindex is smart. If a payment capture, fraud flag, and fulfillment trigger all happen inside the same debounce window and your app treats them as one “order update,” you did not reduce noise. You blurred urgency.

That is the rule to keep in your head through this entire tutorial: debounce replaceable work, not meaningful intent.

Laravel’s queue system makes it easy to smooth out noisy background activity. The hard part is not the API. The hard part is deciding which events are safe to merge, which ones must remain sharp, and how to encode that distinction in job boundaries, keys, and dispatch flow.

This is where teams usually go wrong. They debounce by model, controller, or aggregate because that is the easiest thing to key. But business urgency does not map neatly to user:42 or order:123. Real systems contain mixed urgency. If your debounce strategy ignores that, it will eventually delay the exact event a user expected to happen now.

Step 1: Separate convergent work from event-significant work

Before you write a debounced job, classify the work correctly.

Some tasks are convergent. They only care about the latest useful state. Intermediate triggers are disposable because the final output replaces them.

Other tasks are event-significant. They care that a specific thing happened, at a specific time, with a specific meaning.

If you mix those two categories under one debounce key, the architecture is already wrong.

What convergent work looks like

These are usually safe candidates for debouncing:

rebuilding a search index after repeated edits
refreshing a cached summary
syncing a profile snapshot to a CRM
regenerating a preview
recalculating analytics rollups
rebuilding a read model used for non-critical UI

In all of those cases, the latest state usually wins. You are not preserving a moment. You are producing a current representation.

What event-significant work looks like

These are usually bad candidates for shared debouncing:

payment capture or refund transitions
password changes and session invalidation
fraud or security alerts
shipment progression
audit or compliance logging
notifications tied to immediate user expectations

These are not just state updates. They are business events with timing and consequence.

The question that prevents bad debounce design

Ask this before you debounce anything:

If two triggers happen 500 milliseconds apart, is it correct for one of them to disappear?

If the answer is not an easy yes, do not debounce them together.

That one question is more useful than any framework feature. Most teams answer a weaker question instead: “Would it be nice to do less work?” That is how urgency gets misclassified.

Step 2: Start with the boring version before adding debounce

A lot of Laravel apps do not need debounced jobs first. They need better job boundaries and idempotent handlers.

If you have not measured actual waste, queue churn, or downstream API pressure, the safest move is to keep the job simple.

class SyncUserPreferences implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public function __construct(public int $userId) {}

    public function handle(PreferenceSyncService $service): void
    {
        $service->syncLatestState($this->userId);
    }
}

This may run multiple times during a burst. That is not automatically a problem.

If the job is cheap and safe to repeat, plain queuing is often the better default. Teams get into trouble when they add debounce because duplicate work feels inelegant, not because they have proved it is harmful.

When debounce actually earns its keep

Debounce starts making sense when duplicate scheduling creates a real cost, such as:

expensive third-party API calls
CPU-heavy rebuilds
queue backlog during burst traffic
repeated work that adds no user value
downstream systems that only need the latest snapshot

Once you know that is the actual problem, debounce the replaceable effect, not the entire workflow.

class RebuildPreferenceSummary implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public function __construct(public int $userId) {}

    public function debounceKey(): string
    {
        return "preference-summary:{$this->userId}";
    }

    public function debounceFor(): int
    {
        return 5;
    }

    public function handle(PreferenceSummaryBuilder $builder): void
    {
        $builder->rebuildForUser($this->userId);
    }
}

That key works because it describes a narrow, replaceable outcome. Rebuilding a summary is not the same thing as “everything that happened to the user.”

The anti-pattern to avoid

This is the kind of job that looks tidy and behaves badly:

class SyncOrder implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public function __construct(public int $orderId) {}

    public function debounceKey(): string
    {
        return "order:{$this->orderId}";
    }

    public function debounceFor(): int
    {
        return 10;
    }

    public function handle(OrderSyncService $sync): void
    {
        $sync->run($this->orderId);
    }
}

The problem is not just the code. It is the assumption behind the key.

That key says every meaningful thing that happens to an order is safely mergeable. Address edits, customer notes, payment transitions, risk checks, and shipping state all become “order noise.” In a real application, that is false.

Step 3: Split the workflow into an urgent lane and a convergent lane

If a workflow contains both critical and replaceable side effects, do not force one job to represent both. Build a two-lane pipeline.

This is the pattern that holds up in production.

Lane 1: immediate business actions

These jobs protect correctness, trust, and business timing. They may still run on a queue, but they should not be debounced with softer follow-up work.

Typical examples:

charge capture workflows
fraud screening triggers
audit event recording
session invalidation after password change
time-sensitive notifications
fulfillment progression

Lane 2: eventual convergence work

These jobs can safely collapse into the latest useful version.

Typical examples:

search indexing
CRM sync
read model refreshes
analytics fan-out
preview generation
derived dashboard summaries

The point is not that one lane is synchronous and the other is queued. The point is that one lane must preserve event meaning and the other can converge on state.

A Laravel controller flow that makes the split explicit

final class UpdateOrderController
{
    public function __invoke(UpdateOrderRequest $request, Order $order)
    {
        $oldPaymentStatus = $order->payment_status;

        $order->fill($request->validated());
        $order->save();

        if ($oldPaymentStatus !== 'captured' && $order->payment_status === 'captured') {
            ProcessCapturedPayment::dispatch($order->payment_id, $order->id);
        }

        if ($order->wasChanged(['shipping_address', 'customer_note', 'items'])) {
            RefreshOrderReadModel::dispatch($order->id);
            SyncOrderSnapshotToCrm::dispatch($order->id);
        }

        return response()->json(['ok' => true]);
    }
}

This shape is much safer than a single catch-all job.

Payment capture remains sharp. The read model and CRM sync can converge. The code now reflects business urgency instead of hiding it inside a generic “order sync.”

Why this matters for user experience

Debounce windows leak directly into product behavior.

A five-second delay on a search index update is usually invisible or acceptable. A five-second delay on a just-paid invoice, a revoked session, or an urgent fraud review is not. If the user expects the result now, your debounce window is part of UX whether you planned for that or not.

That is why debouncing cannot be treated as a pure infrastructure optimization. It is product behavior expressed through queue design.

Step 4: Design debounce keys around replaceable outcomes

Most debounce bugs are key-design bugs.

A broad key collapses meaning. A narrow key protects it.

Weak keys

These are usually too coarse to be safe:

user:42
order:123
account:9
project:77

They describe the entity being touched, not the kind of work being replaced.

Stronger keys

These are safer because they describe the specific convergent effect:

search-index:post:123
crm-profile-sync:user:42
read-model:order:123
usage-summary:account:9
preview-render:document:77

The naming matters more than it looks.

A good debounce key forces you to answer the real architectural question: what exactly is safe to replace with newer state?

A simple review rule for pull requests

When reviewing a debounced job, look at the key and ask:

Can two different business meanings land on this same key?

If yes, the key is probably too broad.

This is a very practical code-review filter because the danger often hides in innocent-looking strings.

Step 5: Use idempotency and tests to make debounce safe

Debounce does not remove the need for correctness safeguards. It only reduces redundant scheduling.

That is why strong Laravel queue design combines debounce with idempotency.

Debounce and idempotency solve different problems

Debounce says: “do not schedule every burst trigger if the work is replaceable.”
Idempotency says: “if this job runs more than once anyway, the result stays correct.”

You usually want both.

Even urgent jobs that should never be debounced still need protection against retries, duplicate delivery, or weird provider-side behavior.

class ProcessCapturedPayment implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

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

    public function handle(PaymentWorkflow $workflow): void
    {
        if ($workflow->alreadyCaptured($this->paymentId)) {
            return;
        }

        $workflow->capture($this->paymentId, $this->orderId);
    }
}

That guard is doing a different job than debounce. It protects execution correctness if retries or duplicates still occur.

Fetch current safe state in convergent jobs

For debounced jobs, it is usually better to load the latest state in the handler than to trust an old payload too much.

That is the whole point of convergence work.

class RefreshOrderReadModel implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public function __construct(public int $orderId) {}

    public function debounceKey(): string
    {
        return "read-model:order:{$this->orderId}";
    }

    public function debounceFor(): int
    {
        return 3;
    }

    public function handle(OrderProjectionBuilder $builder): void
    {
        $builder->rebuild($this->orderId);
    }
}

This job does not need every intermediate detail from every trigger. It needs the current source of truth.

Test classification, not just dispatch

A lot of queue tests are too shallow for this kind of logic. They assert that a job was pushed and stop there.

That misses the real risk.

What you need to test is whether mixed-urgency changes dispatch into the right lanes.

it('keeps payment capture immediate while allowing projection work to converge', function () {
    Queue::fake();

    $order = Order::factory()->create([
        'payment_status' => 'pending',
        'customer_note' => 'old note',
    ]);

    $this->patchJson("/orders/{$order->id}", [
        'payment_status' => 'captured',
        'customer_note' => 'leave at reception',
    ])->assertOk();

    Queue::assertPushed(ProcessCapturedPayment::class, 1);
    Queue::assertPushed(RefreshOrderReadModel::class, 1);
    Queue::assertPushed(SyncOrderSnapshotToCrm::class, 1);
});

That test protects the architectural rule. It is far more valuable than a test that only proves “some job got dispatched.”

Step 6: Use a practical rollout checklist in real Laravel codebases

If you are adding debounced jobs to an existing app, do it in a strict order. This is where the tutorial angle matters, because teams often try to jump straight to implementation.

1. Inventory bursty workflows

Look at the places where repeated events are common:

autosave-heavy forms
profile and settings screens
webhook consumers
checkout and billing flows
admin dashboards with rapid edits
AI or third-party sync pipelines

Do not guess. Find the flows where duplicate work actually exists.

2. Classify each queued side effect

For every job fired from those flows, tag it mentally as one of these:

exact and urgent
important but retry-safe
replaceable by newer state

If a job spans multiple categories, that is a sign it is too broad.

3. Split catch-all jobs before adding debounce

If you have classes like these, stop and refactor first:

HandleAccountUpdate
ProcessUserChange
SyncOrder
HandleProjectMutation

Those names are architecture smells. They invite wide keys and mixed urgency.

Replace them with explicit outcomes instead:

TriggerInvoicePaidWorkflow
InvalidateSessionsAfterPasswordReset
RefreshCustomerDashboardProjection
SyncContactSnapshotToHubSpot

Specific names lead to specific debounce boundaries.

4. Keep debounce windows short unless you can defend longer ones

A long debounce window is easy to justify in theory and painful to explain in production.

Short windows are usually safer because they reduce redundant scheduling without turning the app sluggish. If you are reaching for 10, 20, or 30 seconds, that should be a conscious decision backed by real cost or throughput constraints.

5. Observe real outcomes after rollout

The success metric is not just fewer jobs.

Watch for:

lower redundant queue volume
stable downstream API usage
no delayed critical user flows
no missing or softened audit behavior
no “why did this happen late?” product bugs

If queue savings come with support tickets or subtle timing failures, the debounce boundary is too broad.

Laravel’s official queue docs are still the right place for queue mechanics, retry behavior, middleware, and job lifecycle details: https://laravel.com/docs/queues. Use the framework docs to understand the tool. Use your own architecture to decide what the tool is allowed to merge.

The rule that survives production pressure

Use Laravel debounced jobs for convergence work where the latest useful state can safely replace earlier triggers.

Do not use them for meaningful events where the exact trigger, timing, or business consequence matters.

If you want one practical decision rule, use this:

Never let one debounce key group together both “nice to delay” and “must happen now.”

The moment that happens, the design is already broken.

Split the workflow. Keep urgent events sharp. Let only truly replaceable background work blur together. That is how you get the benefits of debouncing without quietly teaching your system to ignore urgency.

Read the full post on QCode: https://qcode.in/laravel-debounced-jobs-are-great-until-urgency-gets-misclassified/

Blade gets slow when your views keep doing the same work

Saqueib Ansari — Wed, 22 Apr 2026 02:31:48 +0000

Most Laravel Blade performance optimization work starts in the wrong place.

Teams blame Blade when pages feel slow, but Blade is usually just exposing bigger architectural habits: too much conditional rendering, too many nested components, repeated partial evaluation, and data shaping that happens far too late. The fix is rarely a clever micro-optimization. It is usually about rendering less, preparing data earlier, and being more selective about what the view layer is responsible for.

So here is the recommendation up front: treat Blade like a thin rendering layer, not a mini application runtime. The more logic, branching, and repeated work you push into templates, the more large pages will drag as your app grows.

This article takes a tutorial-style path because that is the most useful shape for this topic. Start with the simple baseline, identify where over-rendering actually comes from, then tighten the view layer step by step until Blade becomes cheap again.

Start by fixing the real cause: over-rendering is usually repeated work in disguise

When developers say a Blade page is slow, they often mean one of three things.

The first is that the page executes too much logic while deciding what to show. The second is that it repeats expensive partials or components many times in loops. The third is that the data is not shaped properly before it reaches the template, so the template keeps doing tiny bits of work across a large tree.

That is why large apps feel this problem more than small apps. A few @if branches are harmless. A few Blade components are harmless. A partial inside a loop is harmless. But once you mix all three across dashboards, admin tables, notifications, sidebars, modals, and role-based UI fragments, the view layer stops being a thin presentation concern and starts acting like a low-visibility execution engine.

A simple Blade file can quietly become the place where you:

branch on permissions repeatedly
inspect relationships repeatedly
render nested components hundreds of times
compute state labels and CSS classes repeatedly
include partials that include other partials that include other partials

That is not a Blade feature problem. It is a rendering-discipline problem.

A bad baseline often looks like this:

@foreach ($users as $user)
    <x-user-row :user="$user">
        @if($user->team && $user->team->is_active)
            <x-badge color="green">Active Team</x-badge>
        @endif

        @if($user->orders->count() > 10)
            <x-badge color="blue">VIP</x-badge>
        @endif

        @can('impersonate', $user)
            @include('admin.users.actions.impersonate', ['user' => $user])
        @endcan
    </x-user-row>
@endforeach

This reads nicely. It can still perform badly in a large list because it combines relationship access, policy checks, nested components, and partial includes at per-row scale.

The first fix is not “rewrite Blade.” It is reduce repeated decisions inside the template.

Move view decisions upstream before you optimize syntax

The biggest improvement in large Blade codebases usually comes from one habit: precomputing view state before the template renders.

A Blade template should not be figuring out business meaning row by row if the controller, action class, view model, or resource transformer can do it once.

Instead of asking Blade to decide whether a user is VIP, has an active team, or can be impersonated on every pass through a loop, shape that state in advance.

For example:

$users = $users->map(function ($user) use ($currentAdmin) {
    return [
        'id' => $user->id,
        'name' => $user->name,
        'team_name' => $user->team?->name,
        'has_active_team' => (bool) $user->team?->is_active,
        'is_vip' => $user->orders_count > 10,
        'can_impersonate' => $currentAdmin->can('impersonate', $user),
    ];
});

return view('admin.users.index', compact('users'));

Then the Blade becomes much flatter:

@foreach ($users as $user)
    <x-user-row :user="$user">
        @if($user['has_active_team'])
            <x-badge color="green">Active Team</x-badge>
        @endif

        @if($user['is_vip'])
            <x-badge color="blue">VIP</x-badge>
        @endif

        @if($user['can_impersonate'])
            @include('admin.users.actions.impersonate', ['user' => $user])
        @endif
    </x-user-row>
@endforeach

This does not just make the page faster. It makes it easier to reason about.

That tradeoff is worth calling out. Some developers resist this pattern because it feels like “moving presentation logic out of the view.” Good. In large apps, that is usually the right move. Blade should decide how to present prepared state, not rediscover that state at render time.

If you want structure around this, view models or small presenter-style classes are often a better long-term choice than stuffing more logic into controllers.

Components help until they become a rendering tax

Blade components are great for consistency, but they are not free.

This is where large Laravel apps get into trouble. Teams rightly standardize on components, then start nesting them everywhere because the ergonomics feel good. A table row becomes a component. Each cell becomes a component. Status becomes a component. Dropdown actions become a component. Empty wrappers become components. Eventually one index page is made from hundreds or thousands of component instances.

That cost is real.

A useful rule is this: use components for design-system consistency and composability, not for every tiny fragment of markup.

A component is usually worth it when:

it centralizes repeated UI behavior
it wraps meaningful rendering logic
it enforces consistency across the app
it would otherwise create duplicated, fragile markup

A component is often not worth it when:

it is just one div with two classes
it is rendered hundreds of times per request
it adds another level of nesting without real reuse value
it mostly forwards props to another component

For example, this is usually fine:

<x-alert type="warning" :dismissible="true">
    Billing details are incomplete.
</x-alert>

This is where things start getting silly in large loops:

<x-table.row>
    <x-table.cell>
        <x-text.muted>{{ $user->email }}</x-text.muted>
    </x-table.cell>
</x-table.row>

If that pattern repeats across 500 rows with nested conditional content, you are paying a rendering tax for abstraction purity.

My recommendation is opinionated here: for dense, repeated UI like tables, audit whether some components should collapse back into direct Blade or a simpler partial. Design-system discipline is good. Component maximalism is not.

Laravel’s official Blade docs are worth revisiting because the framework gives you several rendering primitives, not just one style of componentization: https://laravel.com/docs/blade

Cache fragments where the page is structurally repetitive

Once you have reduced repeated logic and trimmed unnecessary component depth, the next lever is selective caching.

This is where teams often hesitate because they imagine stale UI bugs. That fear is reasonable, but it should not stop you from caching obviously stable fragments.

Not everything on a page changes at the same rate.

A large admin layout may have:

a mostly static sidebar
role-scoped navigation that changes rarely
summary cards that change every minute or five minutes
a table body that changes frequently
small status badges that are cheap enough not to care about

Treating the whole page as equally dynamic is wasteful.

A good pattern is to cache stable fragments aggressively and leave the volatile parts uncached.

For example:

@php
    $navCacheKey = 'admin.nav.'.auth()->id().'.'.app()->getLocale();
@endphp

@cache($navCacheKey, now()->addMinutes(10))
    @include('admin.partials.sidebar-nav')
@endcache

Or for role-based dashboards:

@cache('dashboard.summary.'.auth()->user()->role, now()->addMinutes(2))
    @include('dashboard.partials.summary-cards', ['stats' => $stats])
@endcache

The exact syntax depends on how you structure fragment caching in your app or package stack, but the principle is stable: cache repeated view work where staleness tolerance is acceptable.

The failure mode to avoid is caching before you understand invalidation. If the UI is permission-sensitive, tenant-sensitive, or locale-sensitive, your cache key must reflect that. Otherwise you trade render cost for correctness bugs, which is not an upgrade.

A simple decision rule helps:

if the fragment is expensive and changes slowly, cache it
if it is cheap and highly dynamic, render it directly
if it is expensive and highly dynamic, redesign the page shape or data flow

Nested conditionals are often a sign the page wants view states, not more Blade

One of the most common sources of Blade sprawl in large apps is conditional branching that grows organically over time.

A view starts with one @if. Then another for role checks. Then a branch for feature flags. Then a branch for tenant rules. Then an empty state. Then a loading or syncing banner. Soon the template is full of nested decisions that are technically correct and painful to maintain.

This kind of code is a warning sign:

@if($user->is_admin)
    @if(feature('advanced-billing'))
        @if($account->hasActiveSubscription())
            @include('billing.partials.admin-active')
        @else
            @include('billing.partials.admin-inactive')
        @endif
    @endif
@endif

The problem is not just readability. Branch-heavy Blade often means the page is trying to encode a state machine informally.

A better approach is to surface explicit view states earlier.

$billingView = match (true) {
    ! $user->is_admin => 'hidden',
    ! feature('advanced-billing') => 'hidden',
    $account->hasActiveSubscription() => 'admin_active',
    default => 'admin_inactive',
};

return view('settings.billing', compact('billingView', 'account'));

Then Blade becomes much cleaner:

@if($billingView === 'admin_active')
    @include('billing.partials.admin-active')
@elseif($billingView === 'admin_inactive')
    @include('billing.partials.admin-inactive')
@endif

This pattern is especially useful in large settings pages, dashboards, and tenant-aware admin surfaces where conditional sprawl accumulates fast.

The key idea is simple: if the view has too many branches, the state is under-modeled.

Large loops need cheaper rendering primitives and better data contracts

The places where Blade performance hurts most are usually predictable:

index tables
activity feeds
audit logs
nested navigation trees
comment threads
permission-heavy admin grids

These are the places where tiny inefficiencies multiply. A per-item policy check, a nested component, an included partial, or a relationship access that felt harmless at 20 rows becomes expensive at 500.

This is where you need to be practical.

First, trim the data contract. Do not pass full models with a dozen relationships into a dense loop if the template only needs six fields and two booleans.

Second, prefer simpler rendering primitives in repeated UI. Not everything needs to be a component.

Third, avoid performing authorization, formatting, or business classification repeatedly inside the loop if you can precompute it once.

A good “dense list” preparation pattern often looks like this:

$rows = User::query()
    ->select(['id', 'name', 'email', 'status', 'last_login_at'])
    ->withCount('orders')
    ->get()
    ->map(fn ($user) => [
        'name' => $user->name,
        'email' => $user->email,
        'status_label' => $user->status === 'active' ? 'Active' : 'Disabled',
        'is_vip' => $user->orders_count > 10,
        'last_login_human' => optional($user->last_login_at)?->diffForHumans(),
    ]);

Then the Blade loop can stay boring, which is exactly what you want.

There is a tradeoff here. Some teams worry this approach moves too much formatting out of Blade. That concern is valid if you go too far. But large apps benefit from data prepared for rendering rather than raw objects dumped into the template and left to fend for themselves.

What to change in a real codebase this week

If you want practical progress instead of abstract advice, audit one slow Blade-heavy page using this order.

Start by asking where the repeated work is happening. Look for nested components, deep includes, relationship access in loops, repeated policy checks, and conditionals that branch three or four layers deep.

Then make changes in this sequence:

Move repeated decisions upstream into prepared view state.
Flatten overly nested components in dense repeated UI.
Replace branch-heavy templates with explicit state mapping.
Cache stable fragments with keys that include role, tenant, locale, or other relevant scope.
Reduce the amount of raw model data flowing into large loops.

You do not need a giant rewrite to see improvement. Large Blade pages often get noticeably faster from just a few disciplined changes.

The practical decision rule is simple: if a Blade file keeps making the same decision or building the same structure hundreds of times, that work probably belongs somewhere else.

Blade is at its best when it is boring. When the template becomes a maze of components, includes, conditionals, and repeated state checks, performance is usually only one of the problems. The bigger issue is that the rendering layer has taken on too much responsibility.

Fix that, and page speed usually improves along with maintainability.

Read the full post on QCode: https://qcode.in/laravel-blade-performance-hacks-avoiding-over-rendering-in-large-apps/

Auth migrations break on session strategy, not login screens

Saqueib Ansari — Tue, 21 Apr 2026 02:32:07 +0000

Most auth migrations do not fail because the new provider is weak. They fail because teams treat authentication like an identity project and ignore that it is also a session-behavior project.

That sounds less exciting than debating providers, passkeys, JWTs, or SSO standards, which is probably why teams keep skipping it. But users do not feel your identity architecture. They feel whether they got logged out unexpectedly, whether one tab still works while another does not, whether their trusted device suddenly is not trusted, and whether support can explain what happened.

So the practical recommendation comes first: plan the session lifecycle before you plan the migration launch. If you cannot explain how sessions are issued, refreshed, downgraded, revoked, and retired across web, API, mobile, and admin surfaces, your auth migration strategy is incomplete.

The risky part starts after a successful login

Most teams anchor on the visible surface of auth:

the login page
the provider choice
SSO support
MFA setup
token format
social login or enterprise login paths

Those things matter, but they are rarely what breaks the rollout.

The real damage usually begins after authentication technically succeeds.

That is where session behavior starts colliding with production reality. Existing browser sessions keep living. Mobile apps lag behind release schedules. Old cookies continue to exist. API clients cache stale assumptions. Admin tooling relies on ancient session fields nobody wanted to touch during the migration.

This is why staging is often misleading. A clean login on a clean browser proves almost nothing. Real users arrive with history. They already have cookies, remembered devices, old tokens, multiple tabs, multiple products, saved sessions, password-reset links, and in some cases mobile clients that are a week behind your backend rollout.

That is the environment your migration has to survive.

The questions that actually matter are blunt:

What happens to users already signed in on other devices?
What does logout mean now, exactly?
Can old sessions still access new APIs?
Can new sessions coexist safely with old cookies?
What happens to remembered-device trust?
What gets revoked on password reset, email change, or permission downgrade?

If those are fuzzy, the migration is underdesigned no matter how polished the login flow looks.

Session strategy is the real migration contract

The cleanest way to think about an auth migration is that identity proves who the user is, while session strategy defines how that truth behaves over time.

That second part is where production reliability lives.

A good session migration contract should make six areas explicit:

Area	What needs to be defined
Session model	Server sessions, stateless tokens, or hybrid behavior
Revocation model	Current device logout, global logout, per-device revoke
Cookie scope	Domain, subdomain, path, SameSite, secure flags
Trust semantics	Remembered devices, MFA grace windows, step-up rules
Compatibility window	How old and new artifacts coexist during rollout
Recovery behavior	Password resets, email verify, suspicious login, lockouts

What trips teams up is that these are not just security details. They are product behaviors.

If your old system allowed long-lived browser continuity but the new system starts forcing frequent re-authentication, users notice. If the old system revoked everything on password reset and the new one only revokes some clients, that is not a backend nuance. That is a real change in security posture. If logout from one app now logs users out of three others, that is not implementation trivia either. That is product behavior with support consequences.

This is why auth migration strategy should be written more like an operational contract than a provider integration checklist.

Mixed-mode rollout is where auth migrations become unstable

The nastiest auth bugs almost never show up in the clean final state. They show up in the in-between state, when some traffic is old, some is new, and everyone is pretending that temporary compatibility will be simple.

It rarely is.

A very common production shape looks like this: the main web app still trusts a server-backed session, the new API layer expects access and refresh tokens, the admin panel checks legacy session data for roles, and the mobile app is only partially updated. Add shared subdomains or legacy cookies to that mix and you have a system where “authenticated” can mean different things depending on where the request lands.

That is how you get the most frustrating class of migration bug: a user looks signed in from one perspective and signed out from another.

One route works. Another redirects to login. The UI claims the session expired while API calls keep succeeding. Password reset kills the browser session but not the mobile token. Support cannot reproduce it consistently because browser state, rollout state, and app version all matter.

This is not an edge case. This is the default failure pattern when rollout modes are not made explicit.

A safer approach is to name the migration states and make every service honor them.

enum AuthRolloutMode: string
{
    case LegacyOnly = 'legacy_only';
    case DualAccept = 'dual_accept';
    case DualWrite = 'dual_write';
    case NewPrimary = 'new_primary';
    case LegacyRetired = 'legacy_retired';
}

The enum itself is not the point. The discipline is.

Each mode should answer practical questions like these:

Which session artifacts are valid?
Which cookies are still accepted?
Which services trust both formats?
Does login write one session artifact or two?
What event ends the compatibility window?

If those answers only exist in someone’s head or in a sprint board comment from two weeks ago, the rollout is already riskier than it needs to be.

My recommendation here is opinionated: keep dual-mode periods short. Teams often stretch them because they fear forcing re-authentication. In practice, a short, clearly communicated re-login is usually cheaper than months of ambiguous mixed-session behavior.

Cookie scope and logout semantics cause more pain than token debates

The most boring migration details are often the most destructive.

Cookie scope is a good example. Teams spend enormous energy on token standards and provider capabilities, then get blindsided by one old cookie on .example.com that collides with a new flow on auth.example.com, or by a SameSite setting that looked fine in testing and behaves differently once cross-subdomain redirects enter the picture.

Legacy systems accumulate strange assumptions over time:

a shared cookie for multiple apps
a path-scoped cookie left over from an older admin route
CSRF behavior coupled to one specific session cookie
inconsistent secure flags across environments
an old app reading auth state from a cookie name nobody wants to retire yet

Then the migration changes one of those pieces and suddenly the rollout looks haunted. Users hit login loops. One browser seems fine, another does not. Logout clears one layer but not another. Session refresh works until a redirect crosses subdomains and resets the wrong cookie.

A simple compatibility table saves a lot of pain here:

Cookie           Old Scope         New Scope            Transitional Rule
legacy_session   .example.com      retired              accepted in dual mode only
app_session      app.example.com   app.example.com      primary browser session
refresh_token    auth.example.com  auth.example.com     httpOnly, secure, narrow path
device_trust     .example.com      app.example.com      used only for low-risk MFA grace

That table is not glamorous. It is operationally useful.

The same goes for logout semantics. Many systems treat “logout” as a single action when there are really several:

log out of the current browser session
log out of the current app only
log out of all apps on all devices
revoke all sessions after password reset
revoke only high-risk sessions after suspicious-login detection

If product, backend, and support are not aligned on which one exists where, users will feel the inconsistency immediately.

Device trust is where migrations quietly damage both UX and security

One of the least discussed parts of auth migration is device trust, which is strange because it is where users often feel the migration most directly.

If your old system had “remember this device” semantics, MFA grace periods, or step-up rules for sensitive actions, the new system needs to do more than authenticate successfully. It needs to preserve or intentionally redefine those trust boundaries.

This is where teams often drift into trouble.

Sometimes the new system becomes accidentally weaker. Trust state does not migrate cleanly, but nobody notices because sign-in still works.

Sometimes the new system becomes accidentally harsher. Users on previously trusted devices suddenly get repeated MFA challenges or step-up prompts in workflows that used to be stable.

Neither is a good outcome.

You need explicit answers to questions like:

Does remembered-device state migrate or reset?
Is device trust scoped per browser, per app, or per identity provider?
Which actions still require step-up auth even with a valid session?
Does changing email or password revoke trusted-device status?
How does suspicious-login review affect active sessions?

If the answer is “the new provider probably handles that,” that is a warning sign. Providers handle mechanisms. They do not automatically preserve your product’s old trust model.

In practice, I would rather see a migration be explicit and slightly conservative than artificially seamless and internally inconsistent. If trusted-device portability is messy, say so, reset it once, and make the recovery path clear. That is usually better than pretending continuity exists while leaving users in a half-migrated trust state.

Example: migrating a Laravel app from classic sessions to SPA and API auth

This is one of the most common full stack migration paths.

A Laravel app starts with session-based auth and server-rendered pages. Then the team adds a SPA, mobile clients, or third-party integrations. The conversation quickly turns into a package debate around Sanctum, Passport, bearer tokens, refresh flows, and API guards.

That debate is often premature.

The better starting question is not “Which auth stack should we standardize on?” It is “What session behavior must remain coherent while browser, API, and mobile clients coexist?”

A reasonable phased design might look like this:

// Phase 1
// Browser remains session-primary.
// Same-origin API calls can still rely on the existing session.

// Phase 2
// Mobile and external clients adopt token-based auth.
// Revocation is coupled across session and token layers.

// Phase 3
// Sensitive actions require step-up auth.
// Users gain visibility into active sessions and devices.

// Phase 4
// Legacy guards and compatibility branches are retired.

The important part is not that this is the only correct sequence. The important part is that revocation, session visibility, logout, and reset behavior stay coherent while the architecture changes.

A common Laravel-specific failure mode here is ending up with two separate truths:

the browser thinks server session state is authoritative
the API layer thinks tokens are authoritative

That is how users end up “logged out” in one surface while still effectively active in another. If you are migrating to hybrid auth, tie revocation semantics together early or you will spend the rollout explaining contradictions.

Example: cross-subdomain SSO migrations fail when revocation stays fuzzy

Now take a broader full stack setup:

app.example.com for the product
admin.example.com for internal tools
billing.example.com for account management
auth.example.com as the new central identity service

On paper, centralizing auth seems like a straightforward improvement. In practice, sign-in federation is usually the easy part. Logout and revocation are where things get messy.

Before rollout, you need exact answers to questions like:

Does logging out from one app end sessions in all apps?
Is local logout still allowed anywhere?
How are revoke events propagated?
What happens if one app temporarily loses contact with the central auth service?
When do old app-specific cookies stop being honored?

A simple event-driven model is often safer than letting every app interpret central auth state differently.

{
  "events": [
    "auth.session.revoked",
    "auth.password.changed",
    "auth.mfa.reset",
    "auth.account.locked"
  ]
}

Each app can respond predictably to those events and translate them into local behavior. That is much better than having every product area invent its own meaning for “session revoked.”

The key point is that SSO migrations are not primarily a token-minting problem. They are a shared-session-semantics problem.

What to test before rollout, and what to stop assuming

Most auth migration test plans are too shallow. They prove that login works and then move on.

That is not enough.

A serious migration test surface should exercise session lifecycle behavior: login, refresh, logout, revoke, password reset, email verification, MFA challenge, step-up auth, and suspicious-login handling. It should also test compatibility behavior: old sessions hitting new routes, new sessions hitting old services, browsers carrying both old and new cookies, mixed-version mobile clients, and cross-subdomain redirects.

Risk testing matters too. What happens when permissions change mid-session? What happens if an admin impersonation session ends while another tab is open? What if a user resets their password from mobile while a browser session remains active? Those are the cases that determine whether the migration is robust or just cosmetically successful.

More importantly, stop assuming these things are “probably fine”:

logout means the same thing everywhere
one browser equals one session
mobile clients will update fast enough
device trust state will migrate cleanly
provider defaults match your existing product behavior
token-based auth automatically simplifies revocation

Most of the time, none of that is safely true by default.

What most teams should do first

If you are planning an auth migration, do not start with brand-new login screens or provider marketing checklists.

Start by writing down the current session model honestly. Define how sessions die, not just how they start. Document cookie scope across every relevant app surface. Decide how old and new artifacts coexist during rollout, and decide when that compatibility ends. Make device-trust and MFA semantics explicit. Then test revocation and recovery flows harder than login.

That order is boring, which is exactly why it works.

The practical decision rule is simple: if you cannot explain how a session starts, survives, escalates, downgrades, and dies across every client in your stack, your auth migration strategy is not finished.

Teams love debating auth at the identity layer because that part looks architectural. Users judge auth at the session layer because that part feels real. Ignore that difference and the migration will remind you the hard way.

Read the full post on QCode: https://qcode.in/full-stack-auth-migrations-fail-because-session-strategy-gets-ignored/

Your Laravel app is probably slower because of query shape, not Eloquent itself

Saqueib Ansari — Mon, 20 Apr 2026 10:32:15 +0000

Most Laravel Eloquent query bottlenecks are not caused by Eloquent being inherently slow. They happen because Eloquent makes expensive database behavior feel cheap.

That is the trap.

A relationship property looks like normal object access. A nested whereHas() reads like clean business logic. A big with() call feels like a safe optimization. Then traffic rises, queue workers back up, database CPU climbs, and suddenly the slowest part of your app is the code that looked the most elegant in review.

The practical takeaway is simple: treat query shape as part of endpoint design. If a route is hot, the SQL it generates is part of the feature, not an implementation detail you can ignore until production hurts.

The first bottleneck is usually query multiplication

Most Laravel apps do not fall over because of one absurd query. They slow down because one request quietly runs too many “reasonable” ones.

The classic example still matters because it keeps happening:

$posts = Post::latest()->take(20)->get();

foreach ($posts as $post) {
    echo $post->author->name;
    echo $post->category->title;
    echo $post->comments->count();
}

That code is readable. It is also expensive.

You start with one query for posts, then trigger more queries for authors, categories, and comments. That is the familiar N+1 query problem, but the real production version is usually broader. Query multiplication leaks into places teams forget to inspect:

Blade templates
API resources
model accessors
policies and gates
collection transforms
helper methods touching relations indirectly
notification builders

That is why “we fixed the controller” often does not fix the route.

A better baseline is to shape the data intentionally:

$posts = Post::query()
    ->select(['id', 'title', 'author_id', 'category_id', 'published_at'])
    ->with([
        'author:id,name',
        'category:id,title',
    ])
    ->withCount('comments')
    ->latest()
    ->take(20)
    ->get();

That change improves performance in three direct ways:

narrower selected columns
intentional relationship loading
SQL-side counting instead of hydrating full collections

These are small-looking changes in PHP and meaningful changes under load.

Make lazy loading fail early

Laravel already gives you a solid guardrail here, and most teams should enable it outside production. The official relationship docs are here: https://laravel.com/docs/eloquent-relationships.

use Illuminate\Database\Eloquent\Model;

public function boot(): void
{
    Model::preventLazyLoading(! app()->isProduction());
}

This will not solve every performance problem. It will catch a lot of accidental query creep before traffic does it for you.

Eager loading fixes one problem and often creates another

A lot of Laravel advice stops at “use eager loading.” That advice is incomplete.

Yes, eager loading fixes many N+1 issues. But blind eager loading often replaces query-count waste with data-volume waste.

This is a common overcorrection:

$orders = Order::with([
    'user',
    'items.product.images',
    'coupon',
    'shippingAddress',
    'billingAddress',
    'payments',
    'refunds',
    'events',
])->latest()->paginate(50);

The query count may improve. The endpoint can still be slow because it is loading far more data than the request actually needs.

That creates a different failure profile:

Symptom	What is actually happening
high memory usage	too many related models hydrated into PHP
slow API serialization	resources walking oversized object graphs
database pressure	relation fetches are wider than the screen needs
weak throughput	each request carries too much unnecessary data

This is where teams need a stricter rule: list views are not detail views.

If the endpoint is an orders index, the UI probably needs:

order id
customer name
status
total
maybe an item count

It probably does not need full refund history, deep product image trees, payment logs, and event timelines for every row.

A healthier list query usually looks more like this:

$orders = Order::query()
    ->select(['id', 'user_id', 'status', 'total', 'created_at'])
    ->with(['user:id,name'])
    ->withCount('items')
    ->latest()
    ->paginate(50);

That is not premature optimization. It is basic endpoint discipline.

My recommendation is blunt because teams delay this too long: make query shape endpoint-specific by default. Reusing one oversized relation graph across pages, APIs, exports, and dashboards is convenient for developers and expensive for the system.

The worst slowdowns are usually SQL-shape problems disguised as elegant Eloquent

Once your app grows beyond simple CRUD, the nastiest bottlenecks are often not classic N+1 cases. They are expressive Eloquent queries that generate expensive SQL plans.

The usual suspects are predictable:

nested whereHas() chains
broad orWhereHas() filters
sorting by related-table columns
polymorphic filters on large tables
repeated aggregate subqueries in paginated endpoints
dashboards built directly on transactional tables

For example:

$users = User::query()
    ->whereHas('orders.items.product', function ($query) {
        $query->where('is_active', true);
    })
    ->whereHas('subscriptions', function ($query) {
        $query->where('status', 'active');
    })
    ->latest()
    ->paginate(25);

In PHP, this looks elegant. In SQL, it may be far more expensive than it appears.

This is one of the biggest ORM traps in Laravel. Because Eloquent can express something cleanly, teams assume the database can execute it efficiently. That assumption fails all the time.

When query logic gets deep, stop reasoning from the PHP outward. Inspect the real SQL and the real execution plan.

Useful tools include:

Laravel Telescope for query visibility: https://laravel.com/docs/telescope
Laravel Debugbar in development
slow query logs
EXPLAIN or EXPLAIN ANALYZE
APM traces if you have them

Sometimes the fix is still an Eloquent refactor. Sometimes it is a join. Sometimes it is a summary table or a dedicated read model. If the endpoint behaves like reporting, stop pretending it is ordinary CRUD.

Example: when the view quietly becomes the query planner

Suppose an admin dashboard shows recent invoices with:

customer name
item count
latest payment status
overdue state

A typical first version looks like this:

$invoices = Invoice::latest()->take(100)->get();

return view('dashboard', compact('invoices'));

Then the Blade template does this:

{{ $invoice->customer->name }}
{{ $invoice->items->count() }}
{{ optional($invoice->payments->last())->status }}
{{ $invoice->due_date->isPast() ? 'Overdue' : 'On time' }}

Readable, yes. Efficient, no.

This is exactly how query cost gets hidden in mature Laravel apps. The view is now implicitly deciding the workload.

A better version makes the data contract explicit:

$invoices = Invoice::query()
    ->select(['id', 'customer_id', 'due_date', 'created_at'])
    ->with(['customer:id,name'])
    ->withCount('items')
    ->with(['latestPayment:id,invoice_id,status,created_at'])
    ->latest()
    ->take(100)
    ->get();

And define a targeted relationship on the model:

public function latestPayment()
{
    return $this->hasOne(Payment::class)->latestOfMany();
}

That is the pattern worth repeating. The view should consume shaped data, not accidentally define database work.

Counts, sums, and existence checks are quiet performance killers

Another common Eloquent bottleneck is loading full relation collections just to answer tiny questions.

This happens everywhere because it is convenient and often slips through code review without comment.

Bad:

$projects = Project::with('tasks')->get();

foreach ($projects as $project) {
    echo $project->tasks->count();
}

Better:

$projects = Project::withCount('tasks')->get();

Bad:

if ($user->orders->count() > 0) {
    // ...
}

Better:

if ($user->orders()->exists()) {
    // ...
}

Bad:

$total = $user->payments->sum('amount');

Better:

$total = $user->payments()->sum('amount');

The rule is easy to remember: if you need a boolean, count, sum, or latest row, do that work in SQL.

Hydrating full collections just to derive a tiny answer is self-inflicted load, and on hot endpoints it adds up quickly.

Many Eloquent bottlenecks are really indexing problems

A surprising amount of slowness blamed on Eloquent is actually weak schema support.

The query may be logically fine. The database still struggles because there is no efficient access path.

This usually shows up in ordinary access patterns:

filtering by workspace_id or tenant_id
filtering by status
sorting by created_at
joining on foreign keys
excluding soft-deleted rows
scoping by ownership and recency

Take this query:

Order::query()
    ->where('workspace_id', $workspaceId)
    ->where('status', 'paid')
    ->latest()
    ->paginate(50);

A lot of teams add separate indexes on workspace_id, status, and created_at, then wonder why the endpoint still drags.

Because real workloads often want a composite index aligned with the actual filter-plus-sort path, not a pile of unrelated single-column indexes.

A few blunt rules help:

heavily used foreign keys should be indexed
repeated filter combinations usually deserve composite indexes
sort order matters when designing index structure
soft-delete columns matter more than teams expect on hot tables

And do not guess. Use EXPLAIN.

If the execution plan is bad, no amount of elegant Eloquent will rescue it.

Example: when the next fix belongs in the schema, not the controller

Suppose a multi-tenant billing screen repeatedly filters invoices by workspace, status, and recency. The team trims columns and narrows eager loading, but performance still degrades as the table grows.

That often means the next real fix is one of these:

a composite index like (workspace_id, status, created_at)
moving archived rows out of the hot table
replacing deep offset pagination on very large datasets
introducing a summary table for dashboard metrics

That is why experienced teams stop treating Eloquent tuning as purely application-code work. Database design is part of the performance contract.

Batch jobs and reporting paths need different query discipline

Another place Laravel apps get hurt is background processing.

Queue jobs, exports, and sync workers are often written like oversized controllers. That works until the dataset becomes large enough to punish memory and runtime.

This is dangerous on a large table:

User::where('is_active', true)->get()->each(function ($user) {
    // sync work
});

For larger workloads, use chunking or cursors.

User::query()
    ->where('is_active', true)
    ->chunkById(1000, function ($users) {
        foreach ($users as $user) {
            // sync work
        }
    });

Or:

foreach (User::where('is_active', true)->cursor() as $user) {
    // process incrementally
}

Each pattern has tradeoffs:

Pattern	Best for	Main risk
`get()`	small datasets	memory blowups
`paginate()`	user-facing lists	deep offset cost on large tables
`chunkById()`	jobs, exports, migrations	depends on stable ordered keys
`cursor()`	low-memory iteration	longer runtime, long-lived cursor

And if the workload is effectively analytical, stop forcing it through hydrated models. Laravel’s query builder is often the better fit for reporting-style queries: https://laravel.com/docs/queries.

$rows = DB::table('orders')
    ->join('users', 'users.id', '=', 'orders.user_id')
    ->selectRaw('users.plan, COUNT(*) as order_count, SUM(orders.total) as revenue')
    ->where('orders.status', 'paid')
    ->groupBy('users.plan')
    ->get();

That is not anti-Eloquent. It is just honest about workload shape.

What to fix first in a real production app

If your Laravel app is already slow under load, do not start with random micro-optimizations. Start with the highest-leverage sequence.

Measure query count and cumulative query time on hot routes.
Enable lazy-loading protection outside production.
Remove hidden relationship access from views, resources, accessors, and policies.
Replace collection-based counts, sums, and existence checks with SQL-side operations.
Narrow eager loading to exactly what each endpoint needs.
Inspect deep whereHas() chains and aggregate-heavy queries with EXPLAIN.
Add composite indexes for real filter-and-sort paths.
Move reporting-style endpoints to query builder, raw SQL, or dedicated read models when appropriate.

That order works because it attacks the biggest sources of waste first.

The decision rule is simple: if a route is hot, treat its query shape as part of the endpoint contract. Decide exactly what the screen or API needs, keep relationships narrow, make SQL do aggregation work, and support the access pattern with the right indexes.

Eloquent is still one of Laravel’s biggest strengths. But under load, convenience without query discipline becomes a tax. The teams that scale well are the ones that stop admiring elegant model code and start respecting the database underneath it.

Read the full post on QCode: https://qcode.in/why-your-laravel-eloquent-queries-bottleneck-under-load-and-how-to-fix-them/

Why AI feature rollouts fail before the model does

Saqueib Ansari — Mon, 20 Apr 2026 02:32:05 +0000

If your AI feature rollout can only succeed when everything goes right, it is not ready for production.

That is the core mistake. Teams treat AI launch like a feature flag exercise, when it is really a trust management problem. They watch latency, track usage, celebrate activation, and miss the thing that matters most: users are deciding whether your product is dependable.

Once they decide it is not, recovery is slow.

A flaky CRUD screen is annoying. A flaky AI feature is corrosive. Users stop trusting the output, then they stop trusting the workflow around it, then they stop trusting your judgment for shipping it in the first place.

So here is the practical takeaway up front: ship AI features narrowly, instrument them for user harm, and design the fallback before the rollout starts. If you do not have those three, you do not have a rollout plan. You have a demo with traffic.

Most rollout dashboards are measuring activity, not trust

A lot of teams track the wrong metrics because the easy metrics are already there.

They monitor things like:

request volume
response latency
cost per generation
acceptance rate
thumbs up and thumbs down
error rate

None of that is useless. It is just incomplete.

An AI feature can look healthy in those charts while quietly making the product worse.

Take an AI support reply assistant. Maybe usage is high. Maybe latency is good. Maybe agents accept the draft often enough. That still does not tell you whether the system is helping.

What if agents are accepting drafts because they are under pressure, then fixing tone, policy mistakes, and factual drift manually before sending? What if the AI is reducing writing time by 20 percent but increasing review time by 35 percent? What if it creates just enough confidence to cause more subtle mistakes?

That is the trap. AI feature rollout failure modes often start with shallow telemetry.

You need metrics tied to real product outcomes. At minimum, every AI rollout should track three categories:

1. Trust metrics

These tell you whether users are gaining confidence or quietly backing away.

Examples:

repeat usage after first exposure
voluntary re-engagement in later sessions
percentage of users who keep the feature enabled
reduction in repeated prompt retries for the same task

2. Harm metrics

These tell you whether the feature is creating downstream work or risk.

Examples:

correction time
human override rate
revert rate
support escalations
policy violations
moderation review volume

3. Fallback metrics

These tell you whether users are escaping the feature instead of benefiting from it.

Examples:

switch-to-manual rate
abandonment after generation
“regenerate” loops
copy-without-send or draft-without-publish behavior

If you are not measuring all three, your dashboard is missing the point.

The biggest rollout mistake is weak kill switch design

A lot of teams say they have a kill switch. Usually they mean one feature flag or one provider toggle.

That is not enough.

A real AI kill switch is not just “turn the model off.” It is “degrade the product safely when the model becomes unreliable.” Those are different capabilities.

If your only failure response is total shutdown, you have two bad choices:

leave a broken experience live too long
remove the feature so aggressively that users lose useful workflows too

The better approach is layered control.

Here is what mature rollout control usually needs:

Layer	What it controls	Why it matters
Provider switch	Stop or reroute model calls	Handles infra or vendor failures
Feature switch	Disable one AI capability	Limits blast radius
Scenario switch	Turn off risky use cases only	Keeps low-risk value alive
UX fallback switch	Replace AI with deterministic flow	Preserves task completion
Review threshold switch	Increase human oversight	Buys safety without full rollback

For example, imagine an AI reply assistant in a customer support tool. If quality degrades, the safest response is often not “hide the whole panel.” It is something like this:

disable generation for refunds and billing disputes
keep canned response templates visible
require review before send
show a short status notice inside the workflow
preserve existing non-AI tooling

That is a product-grade fallback.

A configuration model can reflect that clearly:

{
  "ai_features": {
    "reply_assistant": {
      "enabled": true,
      "scenarios": {
        "billing": false,
        "refunds": false,
        "shipping": true
      },
      "mode": "suggestion_only",
      "fallback": "templates",
      "review_required": true,
      "max_latency_ms": 4000
    }
  }
}

The point is not sophistication for its own sake. The point is control under stress.

Users forgive limited AI faster than inconsistent AI

This is where product teams often make the wrong tradeoff.

They worry a narrow launch will feel underwhelming, so they broaden the surface area too early. More tasks, more contexts, more input types, more autonomy.

That usually backfires.

Users will tolerate a feature that is clearly scoped and consistently useful. They will not tolerate one that feels magical one day and reckless the next.

So if you are rolling out an AI feature, constrain it harder than your demo suggests.

A smart first release often means limiting one or more of these dimensions:

user cohorts
languages
content lengths
workflow types
regulatory or compliance-sensitive use cases
autonomy level

For example, if you are building AI-generated product descriptions for an ecommerce admin panel, the first release should probably not be “generate anything for any catalog item.”

A much better rollout looks like this:

only short descriptions
only for categories with structured attributes
only in one language
only as suggestions, not auto-publish output
only for users already doing manual content review

That version is less flashy. It is also much more likely to earn trust.

Consistency is a better growth strategy than ambition during rollout.

Offline evaluation is necessary, but it is not enough

Teams often run evals before launch and then switch to normal product monitoring. That is not good enough for AI systems.

The problem is behavioral drift.

Users do not interact with AI features the way your test cases do. They push them into edge cases, start relying on them in new workflows, paste in weirder inputs, and gradually discover where the feature is fragile. That means the system that passed pre-launch evaluation may be operating in a very different reality two weeks later.

So you need ongoing evaluation in production, not just pre-launch scoring.

A useful rollout evaluation model has three lanes.

Fixed regression suite

This is your stable benchmark set. It catches obvious prompt regressions, provider changes, parser breakage, and policy failures.

Live traffic sampling

This uses real sanitized production examples so you can test what users are actually doing now.

Incident-triggered review

This is the most important lane and the one many teams skip.

Some failures are statistically small but trust-destroying:

hallucinated policy guidance
false certainty in sensitive workflows
misleading summaries that sound polished
unsafe tone in customer-facing output

These deserve manual review and specific rollback thresholds, even if the aggregate numbers look fine.

A rollout checklist for evaluation might look like this:

regression suite pass rate above threshold
daily live sampling on real usage slices
incident class definitions agreed before launch
rollback triggers tied to business risk, not just model score
reviewer workflow for high-trust-impact failures

That is a lot closer to production discipline than “we watched thumbs down.”

Example: why a writing assistant rollout fails even when adoption looks good

Let us make this concrete.

Suppose you ship an AI writing assistant inside a CMS for a content team. Leadership sees strong usage in week one. The feature looks like a success.

But underneath that, the rollout may be failing.

What the dashboard says

68 percent of eligible users tried the feature
average generation time is 2.3 seconds
copy-to-editor rate is high
explicit negative feedback is low

What the product reality says

editors now spend more time fixing tone drift
brand voice inconsistency increases review load
the AI invents details in product-heavy articles often enough to create distrust
users keep generating because they hope the next draft is better, not because the current one is useful

That is a classic rollout illusion.

If you only look at invocation and copy rate, the feature appears healthy. If you measure editorial correction time and second-pass review load, it may be doing net harm.

A better rollout design would include:

narrower launch for low-risk content types first
structured prompt templates for approved article shapes
required human review before publish
sampled factuality audits
brand voice deviation checks
rollback trigger based on correction burden, not just low ratings

The lesson is simple: usage is not proof of trust. Sometimes it is proof of user hope.

Example: what a survivable AI analytics rollout looks like

Now take a different feature, an AI insights panel inside an analytics dashboard.

The bad rollout plan looks like this:

enable for 20 percent of users
one global feature flag
no scenario segmentation
no confidence gating
generic error fallback
monitor latency and usage only

That rollout is fragile because misleading summaries will do more damage than obvious failures. Users remember confident nonsense.

A survivable plan looks more like this.

Scope the surface

Only enable AI insights for dashboards with enough underlying data and simple query shapes.

Gate confidence

If the system cannot support the claim reliably, do not generate a polished paragraph. Fall back to guided prompts or structured comparisons.

Preserve the manual workflow

The dashboard should still work cleanly without AI. The AI layer should help, not hijack the experience.

Sample for factual review

Check generated summaries against actual query results on a recurring basis.

Define rollback triggers early

For example:

feature: ai-insights
rollback_if:
  misleading_summary_rate_24h: "> 2%"
  repeated_user_reprompt_rate: "> 25%"
  manual_dismissal_rate: "> 35%"
  confidence_validation_failure: "> 5%"

This is not glamorous. It is what keeps the rollout honest.

Rollout controls should not depend on engineers waking up

One more failure mode shows up in real companies all the time: only engineers can intervene safely.

Product notices output drift. Support sees angry users. Operations wants the risky path disabled. But the real controls live in code, infra dashboards, or internal scripts that only a small group understands.

That delay matters. Trust damage compounds while the org debates what to do.

For high-impact AI features, non-engineering operators should have access to a limited, safe control surface. Not raw infrastructure access, but product-level controls such as:

pause new user exposure
disable risky scenarios
switch from autonomous mode to suggestion mode
increase human review thresholds
activate deterministic fallback UX

The interface for that should be boring and explicit.

Good control copy says:

Disable AI replies for billing cases
Require approval before send
Pause rollout beyond current cohort
Use template fallback for region X

Bad control copy says things only the model team understands.

When something goes wrong, your operators should not need to think about token windows, model routing, or inference settings. They should be able to reduce user harm quickly.

What most teams should do before the next AI launch

If your rollout process is mostly “feature flag plus model monitoring,” fix that before you ship the next thing.

Start here:

Define one trust metric, one harm metric, and one fallback metric for the feature.
Build kill switches at scenario and UX level, not just infrastructure level.
Launch a narrower version than the team wants.
Keep post-launch evaluation running on live traffic samples.
Give operators safe controls for reducing risk without waiting on engineering.

And ask one uncomfortable question before launch: what would trust erosion look like in this product, specifically?

Not in theory. In concrete terms.

Would users stop accepting drafts? Start double-checking everything manually? Avoid the feature for sensitive tasks? Open more support tickets? Quietly revert to the old workflow?

If you cannot name the trust failure pattern, you probably cannot detect it early enough.

The decision rule is straightforward: do not ship an AI feature unless you can measure user harm, degrade it safely, and reduce scope faster than users can lose confidence. If any of those are missing, the rollout is not mature yet.

Read the full post on QCode: https://qcode.in/why-your-ai-powered-feature-rollouts-fail-and-how-to-avoid-user-trust-erosion/

Better agent memory often starts with a smaller task

Saqueib Ansari — Sun, 19 Apr 2026 10:32:12 +0000

Most teams reach for agent memory too early.

They see an agent forget a decision, lose track of context, or repeat work, then conclude the fix is more memory. So they add a memory layer, then retrieval, then summaries, then long-term notes, then per-user state, then conversation compaction, then “reflection.” The agent starts to look smarter, but the system usually gets harder to debug, more expensive to run, and less trustworthy in practice.

A lot of the time, the real problem is simpler and less glamorous: the task boundary is bad.

If an agent needs to remember fifteen moving pieces across a long messy workflow, there is a decent chance you did not design one task, you designed four tasks and forced one runtime to pretend otherwise. Memory then becomes a patch over workflow sprawl.

That does not mean memory is useless. Some classes of work absolutely need it. User preferences, durable project facts, prior decisions that should survive sessions, and retrieval over large knowledge bases are all real use cases. But teams keep treating memory as the first design move, when it should often be the fallback after you have tightened the task shape.

My default recommendation is blunt: before adding another memory mechanism, try making the agent responsible for less. Smaller, sharper tasks usually improve cost, debuggability, reliability, and reviewer trust faster than another layer of recall ever will.

Memory often compensates for unclear ownership

When people say an agent “needs memory,” they often mean one of three different things.

First, they mean the agent needs durable facts. For example, the user prefers Laravel over Symfony, the project uses PostgreSQL 16, the deployment target is Fly.io, or the team has already rejected a Redis-based design. That is genuine memory.

Second, they mean the agent needs working context across a long run. It must remember what step it already completed, which files it changed, which outputs were intermediate, and what still remains. That might be memory, but it is often really workflow state.

Third, they mean the agent keeps getting lost inside a broad, ambiguous assignment. “Build the onboarding system,” “clean up the dashboard,” or “improve our AI workflow” all sound like single tasks but are actually bundles of decisions, sub-problems, review points, and competing constraints.

That third category is where teams get into trouble. They interpret confusion as a memory deficiency when it is actually a task design deficiency.

If an agent must constantly recover the same context just to stay on track, ask a more uncomfortable question: why is the task wide enough that staying on track is hard in the first place?

This matters because memory is not free. Every added layer creates failure modes:

stale retrieval returning old decisions
summary drift that quietly changes meaning
irrelevant recalls polluting the prompt
hidden coupling between unrelated tasks
increased latency and token cost
harder incident analysis when output quality drops

A bad task boundary with good memory still tends to feel unstable. A good task boundary with modest memory often feels surprisingly solid.

Tight task boundaries reduce the amount of remembering required

The best agent workflows do not ask the model to be universally persistent. They shape the work so the required context is obvious and local.

A good task boundary has a few traits.

It has a clear input contract. It has a narrow success condition. It can be reviewed independently. It produces an output that another step can consume without reloading the entire world. Most importantly, it does not require the agent to carry a giant mental backpack between unrelated decisions.

Think about the difference between these two assignments.

Bad boundary:

“Take our docs, analyze user complaints, redesign the onboarding flow, update the Laravel backend, rewrite the React UI, improve copy, and make sure analytics still work.”

Better boundaries:

Identify the top three onboarding failures from support and product notes.
Propose one recommended onboarding flow change with tradeoffs.
Implement backend changes for the approved flow.
Implement frontend states for the approved flow.
Add tracking events for the new path.
Validate success, error, and empty states.

The second version does not eliminate context, but it localizes it. Each step needs less memory because each step owns less ambiguity.

This is the key contrarian point: better task decomposition acts like memory compression without the retrieval bugs.

Instead of asking the agent to remember every decision in real time, you externalize important decisions as artifacts between steps. That can be a JSON payload, a short approval note, a generated spec, a checklist, or a patch. The handoff becomes the memory.

That is usually healthier than letting a model keep fuzzy internal continuity across a sprawling run.

The hidden cost of memory-heavy agent design

Memory-heavy systems look sophisticated on architecture diagrams because they have a lot of boxes. In production, those boxes create friction.

The first cost is token and latency overhead. Even good retrieval has a price. Every call to fetch prior summaries, user state, semantic matches, or project facts adds work. Sometimes that work is worth it. Often it is compensating for a task that should have been split at the orchestration layer instead.

The second cost is debuggability. If an agent gives a bad answer, you want to know why quickly. With a narrow task, the causes are usually visible: bad input, weak instructions, poor tool result, or bad model judgment. With layered memory, you now have more suspects. Did retrieval miss the right fact? Did it fetch an outdated summary? Did compaction lose nuance? Did an old preference override a newer one? Did two memory stores disagree?

The third cost is trust. Engineers trust systems they can reason about. A task pipeline with explicit boundaries is inspectable. A memory-rich agent that “usually remembers the right thing” is much harder to trust for critical operations because its behavior is less legible.

Here is the tradeoff teams underestimate: memory can make demos feel smoother while making operations feel shakier.

A memory-rich agent may impress people by recalling an earlier preference. But if it also occasionally applies stale assumptions to code changes, billing logic, or deployment tasks, the magic wears off fast.

That is why I would rather have an agent that remembers less but fails in crisp, understandable ways than one that remembers more and fails opaquely.

Example one: code review workflows usually need better segmentation, not more recall

Take a common engineering workflow. A team wants an agent to handle code review end to end:

read the issue
inspect the repo
understand prior architecture decisions
implement the fix
run tests
update docs
write the PR description
respond to review feedback

The first instinct is to build a powerful memory system so the agent can carry context across the whole lifecycle.

That works up to a point. But it also creates predictable problems. The same memory store now has to support implementation context, review discussion, prior design rationale, test outcomes, and documentation decisions. Very quickly, retrieval quality becomes a core dependency.

A cleaner design is to break the flow into explicit phases with artifacts.

For example:

Step 1: issue-analysis
Input: issue text, related files, recent failures
Output: recommended fix plan as structured JSON

Step 2: implementation
Input: approved fix plan JSON
Output: patch + changed files + implementation notes

Step 3: validation
Input: patch + test commands
Output: pass/fail summary + risk notes

Step 4: PR packaging
Input: issue text + implementation notes + validation summary
Output: PR description and reviewer checklist

In that design, each stage only needs a small slice of state. You can still store durable project facts separately, but you stop asking one long-running agent to be historian, implementer, tester, and release coordinator at the same time.

That change usually improves four things immediately.

First, reruns get cheaper. If validation fails, rerun validation, not the entire memory-rich workflow.

Second, human review gets cleaner. A reviewer can approve the fix plan before any code is touched.

Third, failures localize. If the PR description is weak, that is a packaging problem, not a mystery involving months of memory.

Fourth, prompts become simpler. Simpler prompts tend to be more robust.

That is not a theoretical advantage. It is a day-to-day operational one.

Example two: UI agents often use “memory” to survive missing product boundaries

Frontend agent workflows are where this problem gets especially obvious.

A team says the agent needs memory because it keeps making inconsistent UI decisions. But inconsistency in UI generation is often not about forgetting. It is about being asked to infer too much across too many hidden rules.

Suppose the assignment is:

“Build the new billing dashboard, match our design patterns, support mobile, handle edge cases, and make the UX intuitive.”

That task is doing almost no real constraint work. So the team adds memory. It stores prior UI conventions, recent design discussions, component examples, and old tickets about edge cases. The agent starts retrieving all of that, and sometimes it helps.

But the better fix is usually to split the work and make the boundaries explicit.

A better flow looks like this:

Task A: define screen states
Output: loading, empty, partial failure, success, permission-limited, and stale-data behavior

Task B: define layout archetype
Output: page structure, responsive rules, CTA hierarchy, forbidden patterns

Task C: implement backend data contract
Output: stable API response and error semantics

Task D: implement frontend from approved constraints
Output: UI code only

Now the agent is not leaning on memory to reconstruct product intent from scraps. It is working from task-local artifacts with clear ownership.

This is one of the most useful design rules in agent systems: if memory is regularly being used to recover decisions that should have been formalized as inputs, your pipeline is under-specified.

Use artifacts as memory whenever possible

A strong workflow artifact is better than vague remembered context.

By artifact, I mean something explicit that survives a task boundary in a predictable form:

a structured plan
an approved schema
a state matrix
a diff summary
a risk checklist
a test report
a short decision record

Artifacts are boring in a good way. They do not need semantic ranking. They do not need summarization heuristics. They do not mutate silently. They are visible, reviewable, and easy to feed into the next step.

This is especially useful when you need multi-step agent workflows in Laravel, PHP, or full stack environments where backend, frontend, and deployment concerns mix. The more disciplines overlap, the more dangerous implicit continuity becomes.

A practical pattern is to keep durable memory narrow and let artifacts carry workflow state.

For example:

durable_memory:
  - repository conventions
  - deployment environment facts
  - user preferences
  - long-lived architectural decisions

workflow_artifacts:
  - task plan
  - approved implementation choice
  - generated patch summary
  - validation results
  - release notes draft

That split matters. Durable memory tells the system what remains true over time. Artifacts tell the next step what just happened. Mixing those two is where agents become confusing.

If you store everything as memory, you flatten time. Temporary workflow details start competing with durable facts. That makes retrieval noisier and mistakes more likely.

When more memory actually is the right answer

This is the part contrarian takes often skip. Sometimes the answer really is more memory.

If the agent must personalize behavior across sessions, memory helps.

If the agent works over a large changing knowledge base and retrieval determines usefulness, memory helps.

If the workflow depends on past decisions that are not practical to restate every time, memory helps.

If the environment is conversational by nature, with long-running context and repeated references, memory helps.

But even here, the design question should be precise: what kind of memory, for what duration, under what freshness rules, and with what override behavior?

Good memory design is narrow. Bad memory design is aspirational.

A few healthy uses of memory look like this:

user preference memory with explicit recency handling
project fact retrieval with source references
summarized session recall with a freshness check
durable decision records tied to dates or revisions

Unhealthy uses look like this:

stuffing every intermediate result into one semantic store
assuming summaries preserve operational nuance
letting stale decisions outrank current instructions
using memory as a substitute for orchestration and task design

My rule of thumb is simple. Use memory for facts worth remembering. Use task boundaries and artifacts for work worth structuring.

A practical decision test for teams building agent workflows

Before adding another memory layer, ask these questions.

Does the agent truly need durable recall, or is it just being asked to do too much in one run?

Can this workflow be split into stages with explicit outputs?

Would a reviewer rather inspect an artifact than trust retrieved context?

If this task fails, do we want to debug retrieval quality or a specific stage contract?

Can we rerun only the failed part if we decompose it properly?

If your honest answers point toward decomposition, do that first.

Here is the practical recommendation I would give most teams right now.

Start with the smallest memory model that can preserve real long-lived facts. Then spend your design energy on tighter task boundaries, better artifacts, and cleaner handoffs. Only add more memory when a specific workflow still fails after that redesign.

That order matters because memory is seductive. It feels like general intelligence infrastructure. Task boundaries feel like plumbing. But plumbing is what keeps systems reliable.

The memorable takeaway is this: if your agent seems forgetful, do not assume it needs a bigger brain. It may just need a smaller job.

Read the full post on QCode: https://qcode.in/the-best-agent-memory-is-often-a-better-task-boundary/

Claude Code needs product constraints before it edits your UI

Saqueib Ansari — Sun, 19 Apr 2026 05:16:00 +0000

Most teams are giving Claude Code and similar coding agents the wrong kind of guardrails. They define lint rules, component libraries, TypeScript strictness, maybe a PR checklist, then act surprised when the generated UI is technically valid and still completely wrong for the product.

That happens because UI quality is not just a code problem. It is a constraint problem. A coding agent can infer structure from code, but it cannot reliably infer product intent from scattered components, half-documented Figma files, and a designer's unspoken assumptions. If you let it touch your interface without explicit design constraints, it will optimize for the easiest visible pattern, not the right user experience.

The result is familiar. Buttons appear where links should be. Empty states are missing. Error handling is technically present but emotionally tone-deaf. Tables render correctly on desktop and collapse into nonsense on mobile. Forms validate inputs but ignore recovery paths. Loading states flicker, destructive actions look identical to safe ones, and every screen feels slightly off even when nothing is obviously broken.

If you are using Claude Code to build frontends, the fix is not to tell it to “be more careful.” The fix is to encode the rules your product team already uses but has not written down. In practice, that means three things: constrain the design system, constrain state behavior, and constrain interaction decisions.

Why coding agents get UI wrong even when the code looks right

A coding agent is usually operating with strong local context and weak product context.

It can see:

component names n- props
file structure
nearby patterns
tests, if they exist
style tokens, if they are obvious

What it usually cannot see clearly is the reason those patterns exist. It does not know which spacing exception was intentional, which modal pattern caused support tickets last quarter, or which CTA hierarchy was chosen to reduce accidental destructive actions. It sees implementation artifacts, not the product history behind them.

That gap matters more in UI than in backend code. In backend systems, correctness is often binary. A queue either retries or it does not. A database transaction either commits safely or it does not. In interfaces, many failures are product-wrong rather than syntax-wrong. The page compiles. The tests pass. The screen even looks polished. But the user is guided into the wrong action, left without feedback, or blocked in an edge case the system should have anticipated.

This is why “use our component library” is not enough. A component library gives an agent building blocks. It does not tell the agent:

when a modal is forbidden and a drawer is preferred
which actions must always expose undo
what an empty analytics screen should teach the user
how loading, partial data, timeout, and stale-data states differ
when a dense table should become filtered cards on smaller screens
what should happen after a successful action besides showing a toast

Without those rules, the agent fills in the blanks with plausible defaults. Plausible defaults are exactly what create generic SaaS interfaces that look acceptable in a screenshot and fail in production.

Design constraints are product rules, not visual suggestions

A useful way to think about design constraints is this: they are operational rules for interface behavior.

Most teams document design at the wrong abstraction layer. They write token specs, color scales, and typography guidelines, then assume the rest is obvious. It is not. Agents need higher-level constraints that connect presentation to intent.

The best constraint sets usually cover four layers.

1. Structural constraints

These describe how layouts and patterns are allowed to appear.

Examples:

Settings pages use left navigation only when there are 5 or more stable categories.
Primary actions sit at the top-right on desktop, but become bottom-sticky only for task completion flows on mobile.
Use modals only for short confirmation or isolated edit tasks. Anything with navigation, preview, or multiple steps becomes a dedicated page or drawer.
Never place destructive actions next to primary success actions without separation.

These rules prevent the agent from composing random but valid interfaces.

2. State constraints

This is the part most teams skip, and it is where agents fail hardest.

Every meaningful screen has more than one state:

initial loading
refreshing
empty
filtered empty
partial failure
permission denied
offline or timeout
success after mutation
stale data with background refresh

If these states are not specified, the agent will invent them inconsistently. One page gets skeletons, another gets a spinner, another gets nothing. Some errors show inline, others in toasts, others vanish into console.error.

3. Interaction constraints

These define how the product should feel to use.

Examples:

Inline validation should appear on blur, not on every keystroke, except for password strength indicators.
Save operations that complete under 400ms should not show a blocking spinner.
Destructive actions require either confirmation text entry or undo, depending on blast radius.
Search filters should preserve URL state so views are shareable.

These are not styling notes. They are product behavior rules.

4. Content constraints

Agents also make terrible microcopy decisions unless guided.

Examples:

Empty states must explain why the screen is empty and what to do next.
Error copy must be actionable, not apologetic fluff.
Button labels should describe the outcome, not generic verbs like “Submit.”
Success states should confirm what changed and what the user can do next.

That last point matters more than teams admit. A visually correct interface with vague copy is still a broken interface.

What to give Claude Code before it edits a frontend

If you want Claude Code UI constraints to work in practice, do not hand the agent a 60-page brand document and hope for the best. Give it a small, enforceable contract.

A good starting point is a machine-readable or at least agent-readable file that lives near the frontend codebase. Something like docs/ui-constraints.md or docs/product-ui-rules.md works fine. The important part is that it is explicit, current, and opinionated.

Here is a practical structure.

## UI decision rules

- Use existing design system components before creating new primitives.
- Do not introduce new button variants, badge colors, or spacing scales.
- Prefer page layouts over modals for flows with more than one decision.
- All async actions must define loading, success, error, and retry behavior.
- Empty states must include a reason and a next step.
- Destructive actions must be visually separated and require confirmation or undo.
- Filter and sort state must persist in the URL for index/list screens.
- Mobile layouts must preserve key actions without hiding critical information behind hover.

## State patterns

### Tables
- Initial load: skeleton rows
- Empty dataset: educational empty state with CTA
- Empty after filters: compact reset-filters state
- Background refresh: keep stale rows visible, show subtle loading indicator
- Row action failure: inline error at row level, not page-level generic toast

### Forms
- Validate on blur for standard inputs
- Disable submit only for invalid or actively submitting states
- Preserve user input on server validation failure
- Show field errors inline, global errors at top summary
- After success, either redirect with confirmation or update in place, never both

This kind of document does two jobs. First, it narrows the agent's search space. Second, it gives reviewers something concrete to enforce.

The key is specificity. “Make it intuitive” is useless. “For data tables, preserve stale data during refetch instead of blanking the screen” is actionable.

The missing piece: state matrices beat design tokens

If you only do one thing, build state matrices for your important screens.

This sounds boring, which is probably why teams avoid it. But it is the single best way to stop UI drift when coding agents start shipping views quickly.

A state matrix is a compact description of what a screen does across the conditions that matter. Not just how it looks, but how it behaves.

Take a billing page. Most teams specify the happy path: list invoices, show subscription tier, allow payment method updates. That is not enough.

A state matrix forces you to define:

Condition	Required behavior
No invoices yet	Explain why, show expected future behavior
Payment provider timeout	Keep current billing info visible, show retry path
Subscription canceled but active until date	Emphasize remaining access, de-emphasize upgrade CTA
Card update success	Confirm last four digits changed, do not just show generic success toast
User lacks billing permission	Show read-only state with escalation path

An agent can implement this reliably because the ambiguity is gone.

Here is a lightweight JSON version teams can actually keep in a repo.

{
  "screen": "billing-overview",
  "states": {
    "initial_loading": {
      "pattern": "skeleton",
      "preserve_previous_data": false
    },
    "refreshing": {
      "pattern": "background_refresh",
      "preserve_previous_data": true
    },
    "empty": {
      "title": "No invoices yet",
      "body": "Invoices appear here after your first successful billing cycle.",
      "cta": null
    },
    "permission_denied": {
      "pattern": "read_only_notice",
      "action": "contact_workspace_admin"
    },
    "mutation_success": {
      "feedback": "inline_confirmation",
      "message_template": "Payment method updated successfully"
    },
    "provider_timeout": {
      "pattern": "non_blocking_error",
      "retry": true,
      "preserve_previous_data": true
    }
  }
}

This is not over-engineering. It is cheaper than reviewing the same category of mistakes in every generated PR.

My strong recommendation is simple: for any screen that affects money, permissions, publishing, destructive actions, or multi-step workflows, define a state matrix before you let an agent implement it.

A bad prompt produces generic UI, but a bad constraint file produces dangerous UI

A lot of teams focus on prompt engineering here. Prompts matter, but they are not the foundation.

This is weak:

Build a clean billing settings page using our existing components. Make it responsive and user-friendly.

This is much better:

Implement the billing settings page using the design system components already in /components/ui.
Follow docs/product-ui-rules.md and docs/state-matrices/billing-overview.json.

Requirements:
- No modal for card updates, use inline expandable panel
- Preserve visible billing history during background refetch
- Differentiate empty account state from filtered-empty search state
- Permission-limited users must see read-only info with no destructive controls
- Mutation success must appear inline near the changed section, not as toast only
- Mobile layout must keep current plan and payment method visible above invoice history

The difference is not better adjectives. The difference is behavioral specificity.

This becomes even more important when the agent starts making local extrapolations. If your codebase has three modal-heavy flows and one page-based flow, the agent may choose the wrong precedent unless the rule says when each pattern is allowed.

In other words, agents do not just need examples. They need decision boundaries.

Example: constraining a CRUD screen the right way

Let us take a common Laravel or full stack admin scenario: a user management screen.

The naive implementation generated by an agent usually looks fine:

table of users
create button
edit modal
delete confirmation modal
search box
role badge

But production reality is messier. What happens when the current user cannot edit owners? What happens when a user is invited but has not accepted? What happens when the list is filtered and empty? What happens if role changes fail after optimistic UI updates?

Here is a better implementation contract.

export const userManagementConstraints = {
  list: {
    emptyState: {
      noUsers: "Show invite CTA and explain roles are assigned after invitation",
      filteredEmpty: "Show clear filters action, do not repeat invite CTA as primary"
    },
    responsive: {
      mobile: "Switch from table to stacked cards, preserve role and status visibility"
    }
  },
  actions: {
    invite: {
      feedback: "Inline success banner with invited email",
      failure: "Field-level email error when possible"
    },
    roleChange: {
      optimistic: false,
      success: "Update row in place",
      failure: "Inline row error, preserve previous role badge"
    },
    delete: {
      allowedFor: ["non-owner"],
      requiresConfirmation: true,
      confirmationStyle: "modal",
      copy: "Explain this removes workspace access immediately"
    }
  },
  permissions: {
    ownerRows: {
      editRole: false,
      delete: false,
      explanation: "Owners cannot be modified from this screen"
    }
  }
};

Now the agent has enough context to avoid the usual traps. It knows not to optimistically change roles. It knows owner rows are special. It knows filtered empty and first-use empty are different experiences. That is the difference between UI that demos well and UI that survives real users.

Design systems are not enough unless they encode allowed composition

There is another uncomfortable truth here. A lot of design systems are too primitive for agent-driven development.

They expose tokens and components, but they do not encode allowed composition patterns. So the agent can legally combine pieces into interfaces no designer would approve.

For example, if your system exposes Button, Card, Dialog, Tabs, Badge, and Dropdown, but does not say how these should be combined in settings flows, index pages, or destructive action paths, then you do not really have an enforceable system. You have a parts catalog.

Agents make this weakness obvious.

What most teams need is a layer above the component library:

approved page archetypes
state-specific variants
interaction rules by flow type
anti-patterns that should never appear

If you are building internal docs for this, include a blunt “never do this” section. Agents benefit from negative constraints more than humans do.

Examples:

Never hide critical actions behind hover-only controls.
Never use a success toast as the only confirmation for destructive or financial actions.
Never blank a data-rich screen during background refetch.
Never use disabled buttons without adjacent explanation in permission-limited contexts.
Never treat empty, filtered-empty, and error states as one generic placeholder.

Those rules save more review time than another page of color token documentation.

How to wire this into a real frontend workflow

The practical version is not complicated.

First, store your rules where the agent can read them close to the repo. Do not bury them in a design tool or a wiki nobody updates.

Second, reference them explicitly in implementation tasks, prompt templates, and PR review checklists.

Third, validate the behavior, not just the markup.

A reasonable workflow for teams using Claude Code looks like this:

Define ui-constraints.md with global interaction and composition rules.
Add state matrices for critical screens.
Create a small set of page archetypes, such as index page, multi-step form, settings screen, analytics dashboard.
Require implementation prompts to cite the relevant constraints.
Review generated PRs against state behavior and edge cases before visual polish.

If you want to go one step further, turn some of these into tests. Not everything can be unit tested, but a surprising amount can be enforced.

For example:

it('preserves visible rows during background refetch', async () => {
  render(<UsersPage initialData={seedUsers} />);

  expect(screen.getByText('alice@example.com')).toBeInTheDocument();

  triggerRefetch();

  expect(screen.getByText('alice@example.com')).toBeInTheDocument();
  expect(screen.getByTestId('background-loading-indicator')).toBeInTheDocument();
});

it('shows filtered empty state instead of generic empty state', async () => {
  render(<UsersPage initialData={seedUsers} />);

  await userEvent.type(screen.getByLabelText(/search/i), 'nonexistent');

  expect(screen.getByText(/no users match these filters/i)).toBeInTheDocument();
  expect(screen.getByRole('button', { name: /clear filters/i })).toBeInTheDocument();
  expect(screen.queryByText(/invite your first user/i)).not.toBeInTheDocument();
});

These tests are not glamorous, but they pin down product behavior. That is exactly where agents need the most help.

What most teams should do first, and what they should stop doing

If your team is early in agent-assisted UI work, do not try to formalize every pixel. That is a waste of time.

Do this first:

document 10 to 20 global UI decision rules
create state matrices for your 5 most important screens
define empty, loading, error, and success behavior consistently
write down anti-patterns the agent must avoid

Do not do this first:

obsess over prompt wording while product rules remain implicit
assume your component library communicates intent by itself
review only screenshots instead of behavior and edge cases
let the agent invent empty states and validation flows screen by screen

The highest leverage move is not better prompting. It is reducing ambiguity in the parts of UI work that are currently trapped in people's heads.

Here is the rule I would use in a real team: if a screen can cause user confusion, financial mistakes, permission errors, or irreversible actions, the agent should not build it from components alone. It should build it from explicit constraints plus state definitions.

That sounds strict because it should be. Coding agents are fast, and speed magnifies weak product discipline. If your design logic is undocumented, the agent will expose that gap immediately.

The practical takeaway is simple. Before Claude Code touches your UI, give it more than a style system. Give it boundaries. Tell it which patterns are allowed, which states must exist, which edge cases matter, and which interactions are non-negotiable. Otherwise you are not automating frontend work. You are automating product inconsistency.

Read the full post on QCode: https://qcode.in/claude-code-needs-design-constraints-before-it-touches-your-ui/

Why Your Laravel Queue Stops Processing Without Telling You

Saqueib Ansari — Tue, 14 Apr 2026 02:31:51 +0000

Most Laravel queue “bugs” aren’t bugs—they’re missing feedback loops. If a job can fail without paging you (or at least showing up somewhere you actually look), it will. The fix is not “add more retries” or “restart the worker more often”. The fix is to make failure observable, make retries intentional, and make “lost work” impossible to ignore.

This post is a production-focused checklist of the silent failure modes I see most often in Laravel queues, why they happen, and how to harden your setup so you detect, alert, and recover quickly.

The silent failure pattern: your queue is working… until it isn’t

A queue feels healthy when:

queue:work is running
Horizon (or your process manager) shows workers online
jobs are being pushed

But “healthy” is not “reliable”. Silent failure usually looks like one of these:

jobs stop being processed for minutes/hours with no alerts
jobs are processed but do nothing (early returns, swallowed exceptions)
jobs fail and get retried forever (or die) without anyone noticing
jobs are “processed” but side effects don’t happen (DB committed, external API not called, emails not sent)

The root cause is almost always one of:

the worker process is alive but stuck
the job is failing in a way that doesn’t surface
the job is being released/backed off indefinitely
the queue driver semantics are misunderstood

If you only take one recommendation: treat queue health as an SLO with alerting, not as a background implementation detail.

Failure mode 1: the worker is running but not processing (stuck/hung)

The most dangerous state is a worker process that’s alive but not making progress. Your supervisor says it’s “RUNNING”, but jobs pile up.

Common causes:

long-running jobs without timeouts (HTTP calls with no timeout, stuck I/O)
deadlocks or slow queries holding a connection
memory leaks causing swapping / GC thrash
a single job monopolizing the worker

What to do (opinionated)

1) Set hard timeouts at multiple layers:

job-level timeout
worker-level --timeout
HTTP client timeouts

2) Make “no progress” alertable:

alert on queue depth (backlog)
alert on oldest job age
alert on Horizon “wait time” (if using Horizon)

3) Prefer more workers with shorter jobs over fewer workers with long jobs. Long-running jobs are where silent failures breed.

Example: enforce timeouts and fail fast

<?php

namespace App\Jobs;

use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;
use Illuminate\Support\Facades\Http;

class SyncVendorCatalog implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    // Hard stop for the worker
    public int $timeout = 60;

    // Don’t keep retrying forever; make it loud
    public int $tries = 3;

    // Optional: prevent a job from being attempted too long after it was queued
    public int $maxExceptions = 1;

    public function handle(): void
    {
        $response = Http::timeout(10)           // connect+read timeout
            ->retry(2, 200)                     // short retry with backoff
            ->get('https://api.vendor.com/catalog');

        $response->throw();

        // … process payload
    }
}

This does two important things:

the job cannot hang indefinitely
failures become deterministic (you’ll hit failed_jobs after tries)

If you’re using curl directly, Guzzle, S3 clients, etc., set timeouts there too. Laravel can’t kill a job that’s blocked in a syscall unless the worker timeout triggers.

Operational note

If you run workers with php artisan queue:work, use explicit flags:

--timeout=60
--sleep=1
--tries=3

And don’t pretend queue:listen is acceptable in production; it’s slower and easier to misconfigure.

Official docs: Queues https://laravel.com/docs/queues

Failure mode 2: exceptions are swallowed (your job “succeeds” while doing nothing)

This is the classic silent failure: the job finishes without throwing, so the queue driver marks it as done—even though the intended side effect never happened.

Where it happens:

try { ... } catch (\Throwable $e) { /* log? */ } with no rethrow
returning early on invalid state without recording it
“best effort” integrations that ignore non-200 responses

What to do

Be strict: if a job is responsible for a side effect, it should throw when it can’t perform it. “Best effort” should be explicit and observable.

If you truly want to swallow an error (rare), you still need:

a metric increment
an error report (Sentry/Bugsnag)
a dead-letter workflow (manual replay)

Example: don’t swallow; classify

<?php

namespace App\Jobs;

use App\Services\Payments\PaymentGateway;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;
use Throwable;

class CapturePayment implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public int $tries = 5;
    public int $backoff = 30; // seconds

    public function __construct(public int $orderId) {}

    public function handle(PaymentGateway $gateway): void
    {
        try {
            $gateway->capture($this->orderId);
        } catch (Throwable $e) {
            // If it’s transient, rethrow to retry.
            // If it’s permanent, fail fast so it lands in failed_jobs.

            if ($gateway->isPermanentFailure($e)) {
                $this->fail($e); // marks as failed immediately
                return;
            }

            throw $e;
        }
    }
}

Key judgment call: “permanent failure” should not burn retries. You want it to go to failed_jobs quickly so you can handle it (refund, contact user, etc.).

Failure mode 3: misconfigured retries/backoff create infinite limbo

Laravel makes it easy to back off and retry, but it’s also easy to create jobs that never succeed and never fail loudly.

How this happens:

release() is called repeatedly without a cap
backoff grows but tries is high or defaulted
retryUntil() pushes the failure window far out
Horizon auto-balancing hides the fact that one queue is stuck

What to do

Set finite retries ($tries) for most jobs.
Use bounded retry windows for time-sensitive work (retryUntil).
For idempotent tasks that can be replayed later, fail early and rely on a replay mechanism.

A reasonable default for many teams:

$tries = 3 for external API calls
$tries = 1 for non-idempotent side effects unless you’ve built idempotency
$backoff = [10, 60, 300] for transient network issues

If you can’t explain why a job is safe to retry, it probably isn’t.

Failure mode 4: “lost” jobs due to driver semantics and worker restarts

Not all queue drivers behave the same. Silent loss or duplication is often a mismatch between assumptions and reality.

Database driver gotchas

Jobs are stored in a table; workers poll.
Under load, polling delay can look like “stuck”.
Long transactions can block job reservation.

If you’re at the point where queue latency matters, move off database.

Redis driver gotchas

Redis is the default for a reason: it’s fast and supports good semantics. But you still need to understand:

visibility timeout / retry_after: if a worker dies mid-job, the job becomes available again after retry_after.
if retry_after is too small relative to job runtime, you’ll get duplicate processing.

In Laravel, retry_after is configured per connection in config/queue.php.

Rule: set retry_after comfortably above your maximum real job runtime (including worst-case API slowness), and keep job timeouts below it.

Supervisor/systemd gotchas

Workers restart. Deploys happen. Servers reboot.

Silent failure here is often:

workers not restarted after deploy (stale code)
process manager configured to restart too aggressively (thrashing)
logs not captured anywhere useful

If you deploy frequently, prefer Laravel Horizon for Redis-backed queues. It gives you process control, visibility, and per-queue balancing.

Official link: Horizon https://laravel.com/docs/horizon

Failure mode 5: you have “failed jobs”, but nobody sees them

Laravel will happily write to failed_jobs (or Horizon’s failed list) forever while your team never checks it.

This is the most common “silent failure” in real companies: the system is technically recording failure, but it’s not operationally connected to humans.

What to do (minimum viable)

Ensure failed job storage is configured (queue:failed-table migration for DB).
Alert on failed job rate.
Give engineers a one-command way to inspect and replay.

Concrete setup: hook into Queue events and report

Laravel emits queue events you can subscribe to. Use them to send failures to Sentry/Bugsnag and to emit metrics.

<?php

namespace App\Providers;

use Illuminate\Queue\Events\JobFailed;
use Illuminate\Queue\Events\JobProcessed;
use Illuminate\Queue\Events\JobProcessing;
use Illuminate\Support\Facades\Event;
use Illuminate\Support\ServiceProvider;

class QueueObservabilityServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        Event::listen(JobProcessing::class, function (JobProcessing $event) {
            // Example: increment a metric, add trace context, etc.
            // statsd()->increment('queue.job_processing', 1, ['queue' => $event->job->getQueue()]);
        });

        Event::listen(JobProcessed::class, function (JobProcessed $event) {
            // statsd()->increment('queue.job_processed', 1, ['queue' => $event->job->getQueue()]);
        });

        Event::listen(JobFailed::class, function (JobFailed $event) {
            // Send to your error tracker
            if (app()->bound('sentry')) {
                \Sentry\captureException($event->exception);
            }

            // Also log with strong context
            logger()->error('Queue job failed', [
                'connection' => $event->connectionName,
                'queue'      => $event->job->getQueue(),
                'job'        => $event->job->resolveName(),
                'uuid'       => method_exists($event->job, 'uuid') ? $event->job->uuid() : null,
                'message'    => $event->exception->getMessage(),
            ]);
        });
    }
}

This is deliberately boring: make failures impossible to ignore by routing them into the same system that pages you for HTTP 500s.

If you’re using Horizon, also configure its notification hooks for long waits and failures.

Practical alerting targets

Pick alerts that catch “silent” quickly without constant noise:

Queue backlog: jobs waiting > N for > 5 minutes
Oldest job age: oldest pending job > X minutes
Failed jobs rate: > 0 in 10 minutes for critical queues
No processing: processed count = 0 while pending count increases

Don’t overcomplicate it. Two alerts (oldest job age + failed jobs) catch most incidents.

Failure mode 6: duplication and non-idempotent side effects (the “it ran twice” incident)

Some teams call this a “silent failure” because the queue doesn’t error—but users see double emails, double charges, duplicate webhooks.

Duplication happens when:

a worker times out but the side effect already happened
retry_after expires and the job is re-queued while still running
external systems retry webhooks and you enqueue duplicates

What to do

Assume at-least-once delivery. Build idempotency where it matters.

For emails/notifications: store a send record keyed by a deterministic id
For payments: use provider idempotency keys (Stripe supports this) and store request IDs
For “sync” jobs: use upserts and version checks

Example: simple idempotency guard using cache lock

This won’t solve every case, but it’s a strong baseline for “don’t run twice concurrently” and “avoid rapid duplicates”.

<?php

namespace App\Jobs;

use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;
use Illuminate\Support\Facades\Cache;

class SendInvoiceEmail implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public int $tries = 3;

    public function __construct(public int $invoiceId) {}

    public function handle(): void
    {
        $key = "invoice:{$this->invoiceId}:email_sent";

        // 24h idempotency window
        if (Cache::has($key)) {
            return;
        }

        $lock = Cache::lock("lock:{$key}", 30);

        if (! $lock->get()) {
            // Another worker is doing it.
            return;
        }

        try {
            // ... send email

            Cache::put($key, true, now()->addDay());
        } finally {
            optional($lock)->release();
        }
    }
}

Tradeoff: cache-based idempotency is operationally dependent on Redis. For “money moved” side effects, prefer database unique constraints or provider idempotency keys.

What to change in a real Laravel codebase this week

If your queue failures are currently “silent”, don’t start by rewriting jobs. Start by tightening the system around them.

1) Move critical queues to Redis + Horizon if you’re still on the database driver.

2) Set explicit timeouts and retries on every job that touches the network.

3) Wire JobFailed to your error tracker and create one alert: “failed jobs > 0 on critical queue”.

4) Alert on oldest job age (this catches stuck workers even when nothing is failing).

5) Add idempotency to the top 1–2 risky jobs (payments, emails, webhooks). Don’t boil the ocean.

Decision rule to keep you out of trouble

If a queued job triggers an external side effect (email, payment, webhook, data sync), treat it like a mini production service:

it must time out
it must fail loudly (error tracker + alert)
it must be safe to retry (or it must not retry)

When you’re unsure, bias toward: fail fast → land in failed jobs → replay intentionally. Silent “best effort” is how queues rot in production.

Read the full post on QCode: https://qcode.in/why-your-laravel-queue-fails-silently-and-how-to-fix-it/

Laravel Multitenancy: How to Isolate Tenant Databases Without Packages

Saqueib Ansari — Sun, 12 Apr 2026 02:31:40 +0000

Most teams should start with single-database, tenant-scoped rows and only graduate to database-per-tenant when you have a clear reason (regulatory isolation, noisy-neighbor issues, or operational boundaries). But if your goal is database isolation—separate schemas or separate databases per tenant—you don’t need a multitenancy package to do it well in Laravel. You need three things you can own and reason about:

1) a reliable way to resolve the current tenant for every request/job, 2) a safe way to route queries to the tenant database, and 3) guardrails so you don’t accidentally query the landlord database with tenant credentials (or vice versa).

This article shows a production-ready pattern for database-per-tenant isolation using middleware, a tenant resolver, and a small amount of connection plumbing—no third-party multitenancy package. The bias here is intentional: packages are great until you hit an edge-case (queue workers, Octane, migrations, reporting queries, cross-tenant admin) and you realize you don’t understand the magic. Owning the primitives makes those cases boring.

Choose your isolation model (and don’t overbuild)

Before implementing anything, be honest about what you’re optimizing for.

Approach A: shared database + tenant_id scoping (default recommendation)

Pros: simplest ops, easiest reporting, one migration path, fewer connections.

Cons: weaker isolation; a missing where tenant_id = ? can leak data unless you enforce it hard (global scopes + policies + DB constraints).

Approach B: database-per-tenant (what we’re building)

Each tenant has its own database (or schema), and the app switches connections at runtime.

Pros: strong isolation, easier per-tenant backups/restore, per-tenant performance tuning, cleaner “delete tenant” story.

Cons: operational complexity (migrations across N DBs), connection management, cross-tenant reporting becomes a deliberate pipeline instead of a query.

Decision rule

If you’re early-stage or you need analytics-heavy cross-tenant queries, start with Approach A and enforce scoping. If you have clear isolation requirements or tenants big enough to justify their own DB lifecycle, Approach B is worth it.

The rest of this post assumes database-per-tenant.

The core architecture: landlord DB + tenant DB

You’ll typically have:

A landlord (central) database containing tenants, domains, billing, feature flags, and audit metadata.
A tenant database per tenant containing tenant-owned tables (users, projects, orders, etc.).

The application resolves the tenant from the request (domain/subdomain/header), loads tenant connection info from the landlord DB, then sets the current tenant connection for the duration of the request.

Laravel already gives you most of the tools:

Database connections via config/database.php
Middleware for per-request initialization
Model connection selection via $connection or Model::on('connection')
Queue events and job middleware for worker-side initialization

The main thing you must get right: don’t let state leak between requests, especially under Laravel Octane.

Implement tenant resolution (domain-first, explicit, and testable)

Resolve tenants using a dedicated service. Keep it boring, deterministic, and easy to unit test.

Landlord models

In the landlord DB, store tenant connection details (or enough to derive them).

// app/Models/Landlord/Tenant.php
namespace App\Models\Landlord;

use Illuminate\Database\Eloquent\Model;

class Tenant extends Model
{
    protected $connection = 'landlord';

    protected $fillable = [
        'name',
        'slug',
        'db_host',
        'db_port',
        'db_name',
        'db_username',
        'db_password',
        'active',
    ];

    protected $casts = [
        'active' => 'bool',
    ];
}

If you don’t want to store raw passwords, use a secrets manager and store a reference. But don’t pretend you’re “more secure” by base64-encoding it in the DB.

Resolver service

Resolve by host (custom domains or subdomains). You can support multiple strategies, but pick one as primary.

// app/Tenancy/TenantResolver.php
namespace App\Tenancy;

use App\Models\Landlord\Tenant;
use Illuminate\Http\Request;

class TenantResolver
{
    public function resolve(Request $request): ?Tenant
    {
        $host = $request->getHost();

        // Example: tenant1.example.com -> tenant1
        $baseDomain = config('tenancy.base_domain');
        if ($baseDomain && str_ends_with($host, $baseDomain)) {
            $subdomain = rtrim(str_replace('.'.$baseDomain, '', $host), '.');
            if ($subdomain && $subdomain !== 'www') {
                return Tenant::query()
                    ->where('slug', $subdomain)
                    ->where('active', true)
                    ->first();
            }
        }

        // Example: custom domain mapping
        return Tenant::query()
            ->whereHas('domains', fn ($q) => $q->where('host', $host))
            ->where('active', true)
            ->first();
    }
}

This implies a domains relation; if you don’t need it, drop it. The point is: resolution should be explicit and centralized.

Failure mode to design for

If tenant resolution fails, do not silently fall back to a default tenant DB. That’s how cross-tenant leaks happen.

Return a 404/410, or redirect to marketing, or show “Tenant not found”. But don’t proceed with tenant queries.

Switch the database connection safely (without global magic)

Laravel lets you define connections at runtime by mutating config and purging the connection so a new PDO is created.

The pattern that works in production:

Keep a fixed tenant connection name.
On each request, overwrite database.connections.tenant with the resolved tenant credentials.
Call DB::purge('tenant') then DB::reconnect('tenant').
Set a current tenant in a scoped container so your app can access it.

Tenancy manager

// app/Tenancy/TenancyManager.php
namespace App\Tenancy;

use App\Models\Landlord\Tenant;
use Illuminate\Support\Facades\DB;

class TenancyManager
{
    public function initialize(Tenant $tenant): void
    {
        // Build a connection array compatible with config/database.php
        $connection = [
            'driver' => 'mysql',
            'host' => $tenant->db_host,
            'port' => $tenant->db_port ?? 3306,
            'database' => $tenant->db_name,
            'username' => $tenant->db_username,
            'password' => $tenant->db_password,
            'charset' => 'utf8mb4',
            'collation' => 'utf8mb4_unicode_ci',
            'prefix' => '',
            'strict' => true,
            'engine' => null,
            // Consider setting options like SSL here if needed
        ];

        config(['database.connections.tenant' => $connection]);

        // Very important: drop any existing connection state
        DB::purge('tenant');
        DB::reconnect('tenant');

        // Optional: set default connection for the request
        DB::setDefaultConnection('tenant');

        app(CurrentTenant::class)->set($tenant);
    }

    public function end(): void
    {
        // Reset to landlord to avoid accidental tenant queries later
        DB::setDefaultConnection(config('database.default', 'landlord'));

        // Purge tenant connection so Octane/long-running workers don’t reuse it
        DB::purge('tenant');

        app(CurrentTenant::class)->clear();
    }
}

Current tenant holder

Don’t use a static global. Use the container.

// app/Tenancy/CurrentTenant.php
namespace App\Tenancy;

use App\Models\Landlord\Tenant;

class CurrentTenant
{
    private ?Tenant $tenant = null;

    public function set(Tenant $tenant): void
    {
        $this->tenant = $tenant;
    }

    public function get(): Tenant
    {
        if (!$this->tenant) {
            throw new \RuntimeException('No tenant initialized for this context.');
        }

        return $this->tenant;
    }

    public function optional(): ?Tenant
    {
        return $this->tenant;
    }

    public function clear(): void
    {
        $this->tenant = null;
    }
}

// app/Providers/AppServiceProvider.php
use App\Tenancy\CurrentTenant;

public function register(): void
{
    $this->app->singleton(CurrentTenant::class, fn () => new CurrentTenant());
}

Middleware to wire it up

// app/Http/Middleware/InitializeTenancy.php
namespace App\Http\Middleware;

use App\Tenancy\TenantResolver;
use App\Tenancy\TenancyManager;
use Closure;
use Illuminate\Http\Request;

class InitializeTenancy
{
    public function __construct(
        private TenantResolver $resolver,
        private TenancyManager $tenancy
    ) {}

    public function handle(Request $request, Closure $next)
    {
        $tenant = $this->resolver->resolve($request);

        if (!$tenant) {
            abort(404);
        }

        $this->tenancy->initialize($tenant);

        try {
            return $next($request);
        } finally {
            $this->tenancy->end();
        }
    }
}

Apply it to tenant routes only (not your public marketing site, webhooks that aren’t tenant-specific, or landlord admin).

Octane note: the finally block is non-negotiable. Under long-running workers, forgetting to reset state is how tenant A’s connection bleeds into tenant B’s request.

Make models tenant-aware (and prevent accidental landlord access)

Once you set the default connection to tenant, most queries will go to the tenant DB. That’s convenient—and also dangerous if some code path should never touch tenant DB.

The clean approach is to be explicit:

Landlord models always set $connection = 'landlord'.
Tenant models always set $connection = 'tenant'.

Tenant base model

// app/Models/Tenant/TenantModel.php
namespace App\Models\Tenant;

use Illuminate\Database\Eloquent\Model;

abstract class TenantModel extends Model
{
    protected $connection = 'tenant';
}

Then:

// app/Models/Tenant/Project.php
namespace App\Models\Tenant;

class Project extends TenantModel
{
    protected $fillable = ['name'];
}

This removes ambiguity: even if some code accidentally switches the default connection, your tenant models still target tenant.

Guardrail: block tenant queries when not initialized

If you want a hard fail instead of silent misrouting, add a connection “health check” at the model layer.

A pragmatic way is to ensure tenant middleware runs for routes that touch tenant models, and to throw if CurrentTenant is missing in sensitive service methods.

Example:

// app/Services/Projects/CreateProject.php
namespace App\Services\Projects;

use App\Models\Tenant\Project;
use App\Tenancy\CurrentTenant;

class CreateProject
{
    public function __construct(private CurrentTenant $currentTenant) {}

    public function handle(string $name): Project
    {
        // Hard requirement: no tenant, no write
        $this->currentTenant->get();

        return Project::create(['name' => $name]);
    }
}

This is opinionated, but in real systems it prevents “it worked in dev” surprises.

Failure mode: cross-connection joins

Once you’re database-per-tenant, cross-database joins are not a feature, they’re a trap. If you need landlord + tenant data together, fetch them separately and combine in memory or build a reporting pipeline.

Example 1: Tenant-aware migrations without packages

Migrations are where database-per-tenant systems often collapse into ad-hoc scripts.

The pattern that scales: maintain two migration paths.

database/migrations/landlord for central tables
database/migrations/tenant for tenant tables

Then run tenant migrations per tenant.

Configure migration paths

You can keep standard migrations for landlord and add a custom command for tenant.

// app/Console/Commands/TenantsMigrate.php
namespace App\Console\Commands;

use App\Models\Landlord\Tenant;
use Illuminate\Console\Command;
use Illuminate\Support\Facades\Artisan;
use Illuminate\Support\Facades\DB;

class TenantsMigrate extends Command
{
    protected $signature = 'tenants:migrate {--tenant_id=} {--fresh} {--seed}';
    protected $description = 'Run tenant migrations for one or all tenants';

    public function handle(): int
    {
        $query = Tenant::query()->where('active', true);

        if ($id = $this->option('tenant_id')) {
            $query->whereKey($id);
        }

        $tenants = $query->get();

        foreach ($tenants as $tenant) {
            $this->info("Migrating tenant {$tenant->id} ({$tenant->name})...");

            config(['database.connections.tenant' => [
                'driver' => 'mysql',
                'host' => $tenant->db_host,
                'port' => $tenant->db_port ?? 3306,
                'database' => $tenant->db_name,
                'username' => $tenant->db_username,
                'password' => $tenant->db_password,
                'charset' => 'utf8mb4',
                'collation' => 'utf8mb4_unicode_ci',
                'prefix' => '',
                'strict' => true,
            ]]);

            DB::purge('tenant');
            DB::reconnect('tenant');

            if ($this->option('fresh')) {
                Artisan::call('migrate:fresh', [
                    '--database' => 'tenant',
                    '--path' => 'database/migrations/tenant',
                    '--force' => true,
                ]);
            } else {
                Artisan::call('migrate', [
                    '--database' => 'tenant',
                    '--path' => 'database/migrations/tenant',
                    '--force' => true,
                ]);
            }

            if ($this->option('seed')) {
                Artisan::call('db:seed', [
                    '--database' => 'tenant',
                    '--force' => true,
                ]);
            }

            $this->output->write(Artisan::output());
        }

        return self::SUCCESS;
    }
}

This is intentionally straightforward. You can optimize later (batching, parallelization, locking), but first make it correct.

Operational takeaway: if you have hundreds/thousands of tenants, tenant migrations become a deployment step that needs observability. Log per-tenant migration duration and failures, and never run them blindly during peak traffic.

Example 2: Queue jobs and scheduled tasks (where leaks actually happen)

Requests are easy. Workers and schedulers are where “no package” implementations usually fail.

The problem

A job runs later, on a different machine/process. If you don’t serialize tenant identity and re-initialize the connection, the job will run on whatever default connection the worker has.

Pattern: make jobs tenant-aware explicitly

Create a small trait that stores tenant_id and initializes tenancy in handle.

// app/Tenancy/Queue/TenantAware.php
namespace App\Tenancy\Queue;

use App\Models\Landlord\Tenant;
use App\Tenancy\TenancyManager;

trait TenantAware
{
    public int $tenantId;

    public function forTenant(int $tenantId): static
    {
        $this->tenantId = $tenantId;
        return $this;
    }

    public function initializeTenancy(): void
    {
        $tenant = Tenant::query()
            ->whereKey($this->tenantId)
            ->where('active', true)
            ->firstOrFail();

        app(TenancyManager::class)->initialize($tenant);
    }

    public function endTenancy(): void
    {
        app(TenancyManager::class)->end();
    }
}

Use it in a job:

// app/Jobs/RecalculateUsage.php
namespace App\Jobs;

use App\Models\Tenant\Project;
use App\Tenancy\Queue\TenantAware;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;

class RecalculateUsage implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
    use TenantAware;

    public function __construct(int $tenantId)
    {
        $this->tenantId = $tenantId;
    }

    public function handle(): void
    {
        $this->initializeTenancy();

        try {
            // All tenant queries go to the tenant DB
            Project::query()->chunkById(500, function ($projects) {
                foreach ($projects as $project) {
                    // ...recalculate usage...
                }
            });
        } finally {
            $this->endTenancy();
        }
    }
}

Dispatching:

RecalculateUsage::dispatch($tenant->id);

Scheduler

For scheduled commands, do the same thing: iterate tenants and initialize tenancy per tenant, with a try/finally.

Practical takeaway: if you’re using Horizon, add tags like tenant:{id} for visibility. If you’re using Octane + queues, be even more strict about cleanup.

Hard edges: reporting, auth, and performance

Database-per-tenant isn’t hard because of the happy path. It’s hard because of the “one day you need…” path.

Cross-tenant reporting

Don’t fight your isolation model. If you need cross-tenant analytics:

Emit events (orders created, invoice paid) into a central analytics store (landlord DB tables, ClickHouse, BigQuery, etc.).
Or run ETL jobs that aggregate tenant data into landlord tables.

Trying to query N tenant databases on-demand inside a request is a self-inflicted outage.

Authentication and session storage

If your users live in tenant DBs, auth becomes tenant-contextual:

Resolve tenant first.
Then authenticate against tenant DB.

If you use Laravel’s session database driver, decide where sessions live. Most teams put sessions in a shared store (Redis) to avoid per-tenant session tables.

Official docs worth re-reading:

Laravel database config: https://laravel.com/docs/database
Laravel queues: https://laravel.com/docs/queues
Laravel Octane (statefulness concerns): https://laravel.com/docs/octane

Connection churn and pooling

Switching tenant DB per request means more distinct connections. Mitigations:

Use Redis/cache aggressively for landlord lookups (tenant by domain).
Keep tenant credentials stable; avoid generating ephemeral DB users unless you have a strong reason.
If you’re on MySQL/Postgres managed services, watch connection limits. Consider PgBouncer (Postgres) or a proxy/pooler.

Security posture

Database-per-tenant is not automatically secure if your app can still connect to all tenant DBs with the same credentials. The strongest model is:

Each tenant has its own DB user limited to that tenant DB.
The landlord DB holds encrypted credentials or references.

That’s extra ops, but it’s real isolation.

What I would ship first (and what I’d delay)

Here’s the opinionated path that keeps you out of trouble:

1) Ship TenantResolver + TenancyManager + middleware with strict failure behavior (no tenant, no access).
2) Make landlord vs tenant models explicit with $connection properties.
3) Add tenant-aware jobs early, even if you think you “don’t use queues much”. You will.
4) Add tenant migration command and run it in CI/staging with multiple tenants.

Delay until you actually need them:

Fancy cross-tenant query abstractions
Per-tenant read replicas
Automatic tenant provisioning with zero-touch credentials rotation

Rule of thumb to remember

If there is any chance the code runs outside an HTTP request (queues, scheduler, Octane worker), assume tenant context is missing and make initialization explicit. In multitenancy, “implicit defaults” are just bugs waiting for a customer to find them.

Read the full post on QCode: https://qcode.in/laravel-multitenancy-database-isolation-without-packages/

Laravel API Versioning Strategies That Don’t Suck

Saqueib Ansari — Sat, 11 Apr 2026 02:31:51 +0000

Most teams should avoid “v1/ v2” branching the entire Laravel codebase. It looks clean on paper, but it quietly doubles your maintenance surface area and makes backward compatibility harder, not easier. A better default is: keep one codebase, version at the edges, and evolve your API using additive changes, explicit deprecations, and small compatibility shims when you must.

That recommendation holds for the majority of product APIs: mobile apps, SPAs, partner integrations, and internal services that you control. Only reach for hard version splits when you’re forced to break contracts (auth model changes, resource identity changes, or semantic shifts that can’t be expressed as additive fields).

This article is opinionated and practical: how to design Laravel API versioning that keeps clients moving without turning your app into a museum of old controllers.

The failure mode: “/api/v1” everywhere, duplicated controllers, and two realities

Laravel makes it easy to slap a prefix on routes:

Route::prefix('api/v1')->group(function () {
    Route::get('/users/{user}', [V1\UserController::class, 'show']);
});

Route::prefix('api/v2')->group(function () {
    Route::get('/users/{user}', [V2\UserController::class, 'show']);
});

The first month feels productive. Then reality hits:

You fix a bug in v2 and forget v1.
You add a field in v2 and now serializers diverge.
You change validation rules and now you have to reason about “which version is correct”.
You end up with two sets of policies, resources, requests, docs, tests, and support tickets.

The deeper problem is that route prefixes don’t define versioning—contracts do. If the contract is “a user has an id and email”, you can keep that contract stable without cloning controllers. Conversely, if you change the meaning of id or how authorization works, the prefix won’t save you from breaking clients.

So the goal isn’t “have versions”. The goal is:

Backward-compatible evolution by default.
Predictable breaking changes when required.
Minimal overhead in code, docs, and tests.

Choose a versioning strategy based on what you’re actually changing

There are three common strategies for public-ish JSON APIs. In Laravel, all three are viable, but only one is a good default.

URL versioning (e.g., /v1)

When it wins:

You have large, unavoidable breaking changes.
You need to run two contracts for a long time.
You have external clients you can’t force-upgrade.

Where it fails:

Encourages “forked API” thinking.
Creates duplication pressure (controllers, resources, docs).
Makes it tempting to ship breaking changes in v2 instead of designing additive evolution.

Header-based versioning (e.g., Accept: application/vnd…)

Example:

Accept: application/vnd.qcode.users+json; version=2

When it wins:

You want stable URLs and better cache keys in some gateways.
You have a mature API platform and strong client discipline.

Where it fails:

Harder to debug manually.
Some clients and tools are clumsy with custom media types.
If you don’t enforce it consistently, you end up with “hidden versions”.

“No explicit version” + compatibility rules (recommended default)

This is the pragmatic approach for most product teams:

Keep routes stable (/api/users/{id}), no version in the URL.
Make additive changes (new optional fields, new endpoints).
Use feature flags or capabilities when semantics vary.
Deprecate with headers and timelines.

When it wins:

You control most clients (your mobile app, your SPA).
You want minimal code overhead.
You want to avoid long-lived parallel APIs.

Where it fails:

If you truly must break semantics (not just shape).
If you have many third-party integrators with unpredictable upgrade cycles.

If you’re unsure, start with “no explicit version” and design for compatibility. Add explicit versioning only when you hit a real breaking wall.

The Laravel pattern: version at the boundary, not the core

Even if you decide to support multiple versions, the cleanest architecture is:

Domain/services: one set of business logic.
Requests/validation: minimal version-specific differences.
Resources/transformers: where version differences usually belong.
Routes: detect version, then choose the right transformer.

In other words: keep the “truth” in one place, and treat versioning as a presentation concern.

Example 1: Header-based version negotiation + versioned Resources (minimal duplication)

Let’s implement a simple version negotiation layer in Laravel. We’ll support:

Default version: 1
Client can send X-API-Version: 2

Step 1: Middleware to resolve API version

<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;

class ResolveApiVersion
{
    public function handle(Request $request, Closure $next)
    {
        $version = (int) $request->header('X-API-Version', 1);

        // Clamp to supported range
        if ($version < 1) $version = 1;
        if ($version > 2) $version = 2;

        // Make it accessible everywhere
        app()->instance('api.version', $version);

        // Helpful for debugging and support
        $response = $next($request);
        $response->headers->set('X-API-Version', (string) $version);

        return $response;
    }
}

Register it for your API group in app/Http/Kernel.php (Laravel 11 still supports middleware registration patterns; adjust for your app’s structure).

Step 2: One controller, version-aware Resources

Controller stays stable:

<?php

namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use App\Http\Resources\User\UserResourceV1;
use App\Http\Resources\User\UserResourceV2;
use App\Models\User;

class UserController extends Controller
{
    public function show(User $user)
    {
        $version = app('api.version');

        return match ($version) {
            2 => new UserResourceV2($user),
            default => new UserResourceV1($user),
        };
    }
}

Now the version differences live where they belong: the representation.

UserResourceV1:

<?php

namespace App\Http\Resources\User;

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

class UserResourceV1 extends JsonResource
{
    public function toArray(Request $request): array
    {
        return [
            'id' => (string) $this->id,
            'email' => $this->email,
            'name' => $this->name,
        ];
    }
}

UserResourceV2 adds fields and changes naming without breaking v1:

<?php

namespace App\Http\Resources\User;

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

class UserResourceV2 extends JsonResource
{
    public function toArray(Request $request): array
    {
        return [
            'id' => (string) $this->id,
            'email' => $this->email,
            'display_name' => $this->name,
            'avatar_url' => $this->avatar_url,
            'created_at' => $this->created_at?->toISOString(),
        ];
    }
}

Why this is low-overhead:

One route, one controller, one policy.
Versioning is mostly in Resources.
You can backport bug fixes to both versions automatically.

Common failure mode: trying to put version checks everywhere (“if v2 then …”) inside services. That’s how your domain becomes unreadable. Keep version checks at the boundary.

Backward compatibility rules that actually work in production

Versioning is mostly about discipline. These rules prevent 80% of breakage.

Prefer additive changes; treat removals as breaking forever

Adding a new optional field is cheap. Removing or renaming a field is expensive because some client somewhere will keep reading it.

Add: avatar_url (safe)
Add: metadata object (safe)
Remove: name (breaking)
Change type: id from string to int (breaking)

If you want to “remove” something, deprecate it first and keep it available until you have a hard cutoff.

Never change meaning under the same key

Changing semantics is worse than changing shape.

Bad: status used to mean “account status”, now means “subscription status”.

If semantics change, ship a new field (account_status, subscription_status) and deprecate the old one.

Be strict about request validation, but tolerant in responses

For requests:

Validate hard. Reject unknown enum values.
Be explicit about constraints.

For responses:

Clients should ignore unknown fields. Your API should assume they will.

This is why JSON:API and similar specs push predictable patterns, but you don’t need to fully adopt a spec to follow the principle.

Use explicit deprecation signals

If you’re serious about stability, communicate deprecations in-band:

Deprecation: true
Sunset: <http-date> (RFC 8594)
Link: <https://docs.example.com/deprecations/v1>; rel="deprecation"

Laravel makes this easy at the middleware level.

Official reference for the Sunset header: https://datatracker.ietf.org/doc/html/rfc8594

Example 2: “Compatibility shim” for a breaking request change (without forking endpoints)

A common breaking change is request shape. Example: you originally accepted:

{ "name": "Asha", "email": "asha@example.com" }

Later you want:

{ "profile": { "display_name": "Asha" }, "email": "asha@example.com" }

Forking /v2/users is the obvious move. A lower-overhead approach is a request normalization shim that maps old payloads into the new internal shape.

Step 1: Middleware to normalize input based on version

<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;

class NormalizeUserPayload
{
    public function handle(Request $request, Closure $next)
    {
        if (!$request->isMethod('post') || !$request->is('api/users')) {
            return $next($request);
        }

        $version = app('api.version');

        if ($version === 1) {
            // Convert v1 payload to v2 internal contract
            $name = $request->input('name');

            $request->merge([
                'profile' => array_merge(
                    $request->input('profile', []),
                    ['display_name' => $request->input('profile.display_name', $name)]
                ),
            ]);
        }

        return $next($request);
    }
}

Step 2: Validate only the new shape in a Form Request

<?php

namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;

class StoreUserRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            'email' => ['required', 'email'],
            'profile.display_name' => ['required', 'string', 'min:2'],
        ];
    }
}

Step 3: Controller uses the normalized contract

<?php

namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use App\Http\Requests\StoreUserRequest;
use App\Models\User;

class UsersController extends Controller
{
    public function store(StoreUserRequest $request)
    {
        $user = User::create([
            'email' => $request->input('email'),
            'name' => $request->input('profile.display_name'),
        ]);

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

Tradeoff: shims can accumulate if you keep them forever. The point is to buy time for migration, not to preserve every legacy contract indefinitely.

A practical policy:

Shims are allowed only when paired with a Sunset date.
Shims must be isolated to middleware/transformers, not services.

Testing and documentation: where versioning usually collapses

Versioning fails when it isn’t testable and observable.

Contract tests per version (cheap, high leverage)

You don’t need full duplicated test suites. You need a thin set of contract tests for the responses that clients depend on.

In PHPUnit/Pest, test the same endpoint with different headers:

it('returns v1 user shape', function () {
    $user = \App\Models\User::factory()->create(['name' => 'Asha']);

    $this->withHeader('X-API-Version', '1')
        ->getJson("/api/users/{$user->id}")
        ->assertOk()
        ->assertJsonStructure(['id', 'email', 'name'])
        ->assertJsonMissing(['display_name', 'avatar_url']);
});

it('returns v2 user shape', function () {
    $user = \App\Models\User::factory()->create(['name' => 'Asha']);

    $this->withHeader('X-API-Version', '2')
        ->getJson("/api/users/{$user->id}")
        ->assertOk()
        ->assertJsonStructure(['id', 'email', 'display_name', 'created_at']);
});

This catches accidental breakage when someone “cleans up” a resource.

Document deprecations like product decisions, not footnotes

If you have an API docs site (OpenAPI/Swagger), don’t just mark things deprecated and move on. Add:

What replaces it
The cutoff date
The client action required

If you’re using OpenAPI, you can model versioning either as separate specs or as one spec with versioned schemas. Many teams do better with separate specs once they truly diverge—but that’s exactly the point: don’t diverge until you must.

Official OpenAPI spec: https://spec.openapis.org/oas/latest.html

Observability: log version usage before you remove anything

Before you sunset v1:

Log api.version, route name, and client identifier.
Create a dashboard: “Requests by version over time”.

In Laravel, you can attach this to middleware and ship to whatever you use (OpenTelemetry, Sentry, Datadog, ELK). The exact stack matters less than the discipline: if you can’t measure usage, you can’t deprecate safely.

When you truly need a hard v2 (and how to do it without a mess)

Sometimes you must break:

Auth changes (e.g., moving from API keys to OAuth2 scopes)
Resource identity changes (/users/{id} becomes /accounts/{uuid})
Pagination semantics change (offset → cursor)
A field’s meaning changes and can’t be expressed additively

In those cases, do URL versioning, but still avoid duplicating the entire stack.

Practical pattern:

Keep shared domain/services.
Keep shared policies where possible.
Use separate route files: routes/api_v1.php, routes/api_v2.php.
Keep controllers thin; put logic in services.
Version the Resources and Requests more than the business logic.

A clean route setup:

// routes/api.php
Route::middleware(['api', \App\Http\Middleware\ResolveApiVersion::class])
    ->group(function () {
        require base_path('routes/api_shared.php');
    });

// If you truly need hard versions:
Route::prefix('api/v1')->middleware('api')->group(function () {
    require base_path('routes/api_v1.php');
});

Route::prefix('api/v2')->middleware('api')->group(function () {
    require base_path('routes/api_v2.php');
});

The judgment call: if your v2 is “we renamed fields and cleaned up JSON”, you don’t need /v2. Use resources and shims. If your v2 is “the meaning of the workflow changed”, you probably do.

The decision rule most teams should adopt

If you want minimal overhead and long-term stability in a Laravel API, adopt this rule of thumb:

Default: no URL versioning; evolve via additive fields + explicit deprecation headers.
Allow: header-based negotiation when you need different representations.
Escalate to /v2 only when semantics break, not when you merely dislike the old shape.

And one warning that saves teams from years of pain: never let versioning leak into your domain layer. Keep it in middleware, request normalization, and resources. If your services start taking $version arguments, you’re building two products in one codebase—and you’ll pay for it every sprint.

Read the full post on QCode: https://qcode.in/laravel-api-versioning-designing-backward-compatible-apis-with-minimal-overhead/