DEV Community: Saqueib Ansari

Before You Blame Filament, Profile the Screen

Saqueib Ansari — Fri, 17 Jul 2026 05:13:03 +0000

If a Filament admin screen feels slow, the framework is usually not the first thing you should blame. That instinct is understandable because Filament sits at the visible layer. But in real Laravel apps, the slowdown usually comes from query shape, relation loading, policy checks, table configuration, and repeated per-row work. Filament just makes those mistakes more obvious because it gives you powerful abstractions and a lot of interactive surface area.

That is exactly why Filament performance testing matters. Without profiling, teams jump straight to framework-level fixes, Livewire paranoia, or cargo-cult caching. The result is wasted time and a slower codebase that becomes harder to reason about. The better approach is narrower and more boring: profile the specific screen, identify the hot path, and fix the actual bottleneck.

This article is opinionated on purpose. Do not optimize Filament globally. Optimize one screen at a time. If you cannot point to the exact query, callback, policy, widget, or relation manager causing the slowdown, you are not doing performance work yet. You are guessing.

Start With a Single Screen, Not a General Complaint

Most admin performance discussions start too vaguely.

Someone says the panel is slow. Another person blames Livewire. Someone else suggests Redis, queueing, Octane, or server upgrades. All of that is premature if the actual problem is a resource table firing 120 queries because three columns were made searchable across relations.

Filament screens are not uniform. A dashboard widget page, a resource index, an edit form, a relation manager, and a global search interaction each fail differently. If you test them as one system, the signal gets muddy fast.

The first rule is to isolate the problem into a page-level benchmark. Pick one slow screen and answer these questions:

Is the problem on initial load, or only after filters/search/sort?
Is the page slow for every user, or only users with more permissions or larger datasets?
Is the time spent in SQL, authorization, rendering, or repeated component work?
Does the slowdown scale with row count, relation depth, or visible widgets?

That sounds basic, but teams skip it constantly.

A practical profiling pass should test these screens separately:

resource index pages
edit pages with relation managers
dashboard pages with widgets and stats
modal actions and bulk actions
global search results

If one page is slow, do not treat the whole panel as slow. Filament is a container for many performance profiles, not one performance profile.

Build a Simple Local Baseline

You do not need a perfect observability stack to start. You need consistent numbers.

In a Laravel app, the fastest baseline usually comes from Laravel Debugbar, Telescope, query logs, and request timing around the specific Livewire interaction. For local work, that is enough to get to the truth quickly.

A lightweight query/timing baseline can look like this:

use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Log;

DB::flushQueryLog();
DB::enableQueryLog();

$startedAt = microtime(true);

app()->terminating(function () use ($startedAt) {
    $queries = DB::getQueryLog();

    Log::info('filament-screen-profile', [
        'duration_ms' => round((microtime(true) - $startedAt) * 1000, 2),
        'query_count' => count($queries),
        'slowest_queries' => collect($queries)
            ->sortByDesc('time')
            ->take(10)
            ->values()
            ->all(),
    ]);
});

That code is intentionally unglamorous. Good. Performance work should start with facts, not tooling theatre.

When you profile a Filament screen, record these values every time:

total request duration
total query count
slowest queries by time
peak memory if the page loads large collections
row count displayed
which interaction triggered the work

That last point is easy to miss. A Filament page may be acceptable on first render and terrible when sorting by a related column, opening a modal, switching tabs, or loading a relation manager. If you only test the first page hit, you will miss the expensive path that users actually feel.

Most "Filament Is Slow" Problems Are Really Query Problems

The most common cause of a slow Filament page is not rendering. It is bad data loading strategy.

Filament makes it easy to define expressive tables:

relationship-backed columns
counts and badges
computed text
searchable related fields
sortable related fields
tab counts
conditional state based on related models

Every one of those features can be fine. The problem is when they stack without an explicit query strategy.

Here is a pattern that looks clean and often performs badly:

public static function table(Table $table): Table
{
    return $table
        ->columns([
            TextColumn::make('name')->searchable(),
            TextColumn::make('company.name')->searchable()->sortable(),
            TextColumn::make('roles.name')->badge(),
            TextColumn::make('projects_count')->counts('projects'),
            TextColumn::make('latestInvoice.status')->badge(),
            TextColumn::make('owner.email')->toggleable(),
        ]);
}

Nothing here is obviously wrong. That is why teams get trapped.

The hidden problem is that this table definition is also a data access definition. Search across company.name can force joins or subqueries. Rendering roles.name can touch collections that were not eager loaded properly. Sorting on related state can generate ugly SQL. Showing latestInvoice.status may trigger relation access patterns you did not think about.

The fix is not to stop using Filament features. The fix is to make the page query explicit.

Define a Screen-Specific Query Contract

A strong default is to override the resource query and load only what the screen actually needs.

use Illuminate\Database\Eloquent\Builder;

public static function getEloquentQuery(): Builder
{
    return parent::getEloquentQuery()
        ->select([
            'id',
            'name',
            'company_id',
            'owner_id',
            'latest_invoice_id',
            'status',
            'created_at',
        ])
        ->with([
            'company:id,name',
            'owner:id,email',
            'latestInvoice:id,customer_id,status,due_at',
            'roles:id,name',
        ])
        ->withCount('projects');
}

This is not exciting code, but it is the kind of code that makes admin panels fast.

A few practical rules matter here:

Select only the columns the page needs. Pulling full row payloads for every model in an admin table is lazy and expensive.
Narrow eager loads aggressively. with('company') is acceptable when prototyping, not when debugging a slow production screen.
Use withCount(), withExists(), and constrained eager loads deliberately. Let SQL do the aggregation once instead of letting PHP rediscover it row by row.
Avoid hidden relation access in accessors. Accessors that look elegant in models can destroy table performance because they hide expensive reads behind attribute access.

Run `EXPLAIN` Before You Touch Caching

If one query dominates the timeline, inspect the query plan before you add caching or try to "optimize Filament." In a lot of cases, the table is simply revealing schema weaknesses.

Common problems include:

missing indexes on foreign keys used in filters
missing indexes on status or date columns used in sorting
relationship search hitting large unindexed text fields
composite queries that need multi-column indexes but only have single-column indexes

Filament does not create those problems. It just makes them visible because admin tables are query-heavy by nature.

If a slow screen depends on filtering orders by team_id, status, and created_at, and you only indexed team_id, the panel will feel slow no matter how clean the Filament configuration is.

This is why performance testing should stay grounded in database behavior. If the SQL is bad, the UI framework is not the bottleneck.

Table Configuration Can Create Death by a Thousand Cuts

Even when the main query is fine, Filament tables can still feel slow because of repeated per-row work. This is where performance slips from "one obvious bad query" into a more annoying pattern: lots of individually reasonable decisions that add up badly.

Per-row formatting, badge color callbacks, visibility rules, icon logic, and custom state derivation all execute inside the rendering loop. On a 25-row page, maybe that is harmless. On a 100-row page with multiple relation-backed columns, it becomes expensive quickly.

Watch for Queries Inside Column Logic

This pattern is common and usually wrong:

TextColumn::make('status')
    ->badge()
    ->formatStateUsing(function ($state, $record) {
        return $record->latestInvoice?->is_overdue
            ? 'Overdue'
            : ucfirst($state);
    })
    ->color(fn ($record) => $record->orders()
        ->where('priority', 'high')
        ->exists()
            ? 'danger'
            : 'gray');

That exists() call looks tiny. It is not tiny when it runs once per row.

This is the kind of mistake that gets blamed on Livewire diffing or framework overhead when the real issue is simple: you embedded a query decision inside presentation code.

A better pattern is to push the expensive logic into the base query:

public static function getEloquentQuery(): Builder
{
    return parent::getEloquentQuery()
        ->with([
            'latestInvoice:id,customer_id,is_overdue',
        ])
        ->withExists([
            'orders as has_high_priority_orders' => fn ($query) =>
                $query->where('priority', 'high'),
        ]);
}

Then keep the table definition dumb:

TextColumn::make('status')
    ->badge()
    ->formatStateUsing(fn ($state, $record) =>
        $record->latestInvoice?->is_overdue ? 'Overdue' : ucfirst($state)
    )
    ->color(fn ($record) => $record->has_high_priority_orders ? 'danger' : 'gray');

That principle scales well: precompute expensive truth once, render it many times cheaply.

Be Skeptical of Overly Smart Columns

Filament lets you build rich tables quickly. That does not mean every nice-looking column is worth the cost.

These features deserve scrutiny when a screen is slow:

searchable relationship columns
sortable computed columns
badges based on multiple relations
icon and color callbacks that inspect extra state
columns driven by accessors with hidden query reads
wide tables with many toggleable but still computed columns

A recurring production mistake is adding convenience columns that answer interesting questions but are not essential to the first screen. That is a product problem masquerading as a technical problem.

If a column requires complex relation loading and expensive conditional logic, ask a harder question: does this belong on the list page at all, or should it live on the detail page?

Admin UX is not improved by making every row a mini analytics dashboard.

Search and Sort Need Restraint

Search and sort are especially dangerous because they look like low-risk improvements. They are not.

A broad ->searchable() on multiple relationship-backed columns can turn a fast screen into a heavy query generator. Sorting by related state can make the query planner miserable. Searching computed text is often a smell unless that value is persisted or denormalized intentionally.

For most real admin panels, a better pattern is:

search a small set of indexed primary fields
use explicit filters for status, team, owner, or date ranges
denormalize a display field when you know the list screen depends on it
avoid pretending every interesting value should be globally searchable

That approach is less magical and more reliable.

Authorization Often Hurts More Than Teams Expect

Laravel developers usually remember to profile SQL. They often forget to profile policies, gates, and visibility checks.

Filament calls authorization in a lot of places:

page access
navigation visibility
row actions
bulk actions
form field visibility
relation manager visibility
action enable/disable state

If your policy logic performs relationship queries or repeated membership checks, it can dominate a request even when the main table query is reasonable.

The Common Multi-Tenant Trap

Here is a policy shape that is logically fine but dangerous on a busy Filament screen:

public function update(User $user, Project $project): bool
{
    return $user->teams()
        ->whereKey($project->team_id)
        ->wherePivot('role', 'admin')
        ->exists();
}

If that policy is evaluated repeatedly for row actions across a table, the cost compounds quickly. The issue is not that policies are bad. The issue is that per-record authorization that re-queries shared context is wasteful.

Better options include:

preload the current tenant membership context once per request
memoize cheap authorization state in the request lifecycle
avoid duplicating the same expensive logic in visible(), disabled(), and policy checks together
centralize team or tenant role resolution so it does not get rediscovered per row

That does not mean you should bypass policies. It means you should make them cheap.

Profile Authorization Like You Profile Queries

A good local test is brutally simple: temporarily stub or simplify the suspicious policy path and compare request time. If the screen suddenly becomes fast, you found a policy bottleneck.

Another useful tactic is request-scoped memoization for shared checks:

class TeamMembershipService
{
    protected array $cache = [];

    public function isTeamAdmin(int $userId, int $teamId): bool
    {
        $key = "{$userId}:{$teamId}";

        return $this->cache[$key] ??= \DB::table('team_user')
            ->where('user_id', $userId)
            ->where('team_id', $teamId)
            ->where('role', 'admin')
            ->exists();
    }
}

Used carefully, that kind of request-local caching is a real fix because it eliminates redundant work without introducing stale cross-request state.

The larger point is this: authorization logic is part of performance architecture. In admin panels, it is not just a security concern.

Relation Managers, Widgets, and Tabs Multiply Hidden Work

When teams say a Filament edit page feels heavy, the form itself is often not the issue. The actual cost lives in the surrounding page chrome: relation managers, widgets, stat cards, tab badges, and counts sprinkled around the interface.

This is the second big source of framework blame. The main page appears slow, so Filament gets accused. But the page is really acting like a compound dashboard.

Relation Managers Are Easy to Underestimate

Each relation manager is its own data loader, table, action surface, and policy consumer. Add three of them to an edit page and the request lifecycle gets crowded fast.

The problem gets worse when relation managers are visible by default even though the user only needs one at a time. If each manager performs counts, eager loads, and action authorization on first render, the page can feel sluggish before the user touches anything.

When profiling an edit page, test with relation managers disabled one by one. That quickly reveals whether the form is slow or the surrounding components are slow.

Widgets and Badge Counts Are Frequent Offenders

Dashboards and resource pages love metrics. Counts feel cheap. They are often not.

A common anti-pattern looks like this:

a widget counts overdue invoices
a tab badge counts overdue invoices again
a header stat computes the same number with slightly different constraints
a relation manager tab recomputes another near-identical count

The UI looks polished. The backend is doing duplicate work.

If a metric appears in multiple places, centralize how it is loaded. Either compute it once in a dedicated query path or decide that not every surface needs a live count.

This is where product discipline matters. Not every badge is worth a query.

Pagination Is Usually Better Than Table Maximalism

Another quiet performance killer is oversized tables. Teams often assume that showing 100 rows by default is better admin UX than showing 25. In practice, that is usually wrong.

A smaller, faster page with sharp filters is better than a large, sluggish page filled with decorative columns and computed state.

If users complain they need more context per page, the first move should not be increasing pagination blindly. Try this order instead:

remove low-value columns
move expensive detail into the record page
simplify row-level visual logic
add better filters or presets
only then consider raising rows per page

That sequence preserves speed and keeps the table useful.

A Production-Sane Workflow for Filament Performance Testing

Once you stop guessing, the work becomes much more straightforward. Most slow Filament screens can be improved with a disciplined pass through the same layers.

The Order Actually Matters

This is the sequence I would recommend for most Laravel teams:

profile one screen and capture request time plus query count
identify the slowest queries and run EXPLAIN
make the resource query explicit with select(), narrow with(), withCount(), and withExists()
remove query work from column callbacks and per-row presentation logic
inspect policies, action visibility rules, and repeated authorization checks
isolate widgets, relation managers, tab badges, and duplicated metrics
only after that, consider caching, Octane, or deeper infrastructure changes

That order saves time because it forces you to work from the hottest bottleneck outward.

A Realistic Refactor Pattern

Suppose a Filament resource index is slow because it shows customer data, invoice state, and order priority all in one table. A sensible refactor would usually look like this:

restrict the base select list
eager load only the exact relationships needed for visible columns
convert per-row exists() checks into withExists()
replace free-form relationship search with targeted indexed filters
trim low-value columns from the default table state
lower the default page size if the screen is still doing too much

That is not glamorous work. It is effective work.

What Not to Do First

A few things are usually the wrong first move:

adding broad caching before understanding query shape
blaming Livewire for N+1 issues created in your table config
increasing server resources before fixing obvious SQL waste
collapsing everything into one giant index page because it feels convenient
treating accessors as free when they hide expensive relation reads

Those choices make the system harder to debug later.

The Practical Decision Rule

Filament is fast enough for serious Laravel applications. What it does not do is protect you from expensive Eloquent habits, sloppy authorization design, or overly ambitious admin tables.

That is not a weakness. It is just the reality of building rich internal tools on top of expressive abstractions.

If a screen is slow, your job is not to defend the framework or attack it. Your job is to locate the exact cost center. In most cases, you will find one of five things:

the query loads too much data
the table performs too much per-row work
the policy layer repeats shared checks
the page bundles too many widgets or relation managers
the schema is missing indexes for how the admin UI actually queries data

Official docs worth keeping nearby while profiling:

The rule of thumb is simple and worth repeating: do not blame Filament until you can name the exact query, callback, policy, widget, or tab that is slow. If you cannot name it, you have not tested performance yet. You have only felt it.

Read the full post on QCode: https://qcode.in/filament-performance-testing-before-you-blame-framework/

Passwordless Laravel Auth Is Easy to Demo and Harder to Run Well

Saqueib Ansari — Fri, 17 Jul 2026 05:08:37 +0000

Passwordless auth sounds like a simplification until you try to run it in a real Laravel product. The UI gets simpler. The security model does not. You remove the password field, but you still have to prove identity, prevent replay, handle hostile email infrastructure, preserve decent UX across devices, and give support a way to debug failures without turning into a manual override team.

That is why most magic-link examples are fine for prototypes and incomplete for production. They focus on generating a signed URL and calling Auth::login() when it is opened. That is the easy part. The hard part is everything around the click.

My recommendation is blunt: do not implement passwordless auth in Laravel as a “special login link” feature. Implement it as a short-lived authentication workflow with explicit state, single-use consumption, step-up hooks, and support visibility. If you skip those layers, you are not shipping passwordless auth. You are shipping a bearer token in an email and hoping the rest works out.

The first threat is often your user's email security stack

A lot of magic-link writeups quietly assume the first request to the link comes from the human who owns the inbox. In production, that assumption breaks fast.

Enterprise email systems, secure mail gateways, antivirus products, browser preview services, and mobile mail clients often prefetch links. Some do it to scan for malware. Some do it to build previews. Some follow redirects. If your Laravel route performs the login on the first GET, one of those automated actors can consume the credential before the user even sees the email.

That creates a failure mode that feels bizarre to users. They click the email one minute later and see “link expired” or “token already used.” From their perspective, your auth is broken. From your perspective, it worked exactly once, just not for the person you intended.

This is why magic-link login should almost never be consume-on-GET in a serious app.

Use email links to resume a flow, not to finish it

A better pattern is simple:

User requests passwordless sign-in.
You create a login attempt record in the database.
You email a signed URL that identifies that attempt.
The GET request validates the link and renders a confirmation page.
A deliberate POST consumes the attempt and creates the session.

That extra round-trip is not busywork. It is what separates “clickable email token” from “scanner-resistant auth flow.” Automated scanners are very good at issuing GET requests. They are much worse at completing a CSRF-protected browser form in the same session context.

A minimal route shape in Laravel can look like this:

Route::middleware('guest')->group(function () {
    Route::post('/login/passwordless', RequestMagicLinkController::class)
        ->middleware('throttle:5,1')
        ->name('passwordless.request');

    Route::get('/login/passwordless/{attempt}', ShowMagicLinkController::class)
        ->middleware('signed')
        ->name('passwordless.show');

    Route::post('/login/passwordless/{attempt}', ConsumeMagicLinkController::class)
        ->middleware(['signed', 'throttle:6,1'])
        ->name('passwordless.consume');
});

The important design choice is not the route naming. It is the separation of concerns.

The email link proves the user reached the mailbox.
The confirmation POST proves a browser session intentionally completed the flow.
Your application decides whether that is enough for full access or only enough for provisional access.

Signed URLs are useful, but not sufficient

Laravel's signed URL support is absolutely worth using here. It protects query integrity and expiration. But it does not solve the full problem.

A signed URL does not make the underlying login attempt single-use. It does not tell you whether a link was consumed by a scanner. It does not stop a forwarded email from being reused inside its lifetime. It does not decide whether a new device should be trusted.

That distinction matters because teams often mistake “cryptographically signed” for “production-ready.” Those are different claims.

The core object is not the link. It is the login attempt

If you want passwordless auth to survive production, you need a first-class persistence model for the flow. The link should point to a login attempt record, not carry the whole security story inside the URL.

A reasonable schema usually includes:

id
user_id
token_hash
expires_at
consumed_at
requested_ip
requested_user_agent
requested_at
redirect_to
device_label
risk_flags or equivalent JSON metadata

The token itself should be random, short-lived, and stored only as a hash. Treat it the same way you treat reset tokens: the raw secret exists only long enough to email it.

Hash the token and keep the URL boring

You do not need a clever token format. You need an unpredictable one.

use Illuminate\Support\Str;

$plainToken = Str::random(64);

$attempt = MagicLoginAttempt::create([
    'user_id' => $user->id,
    'token_hash' => hash('sha256', $plainToken),
    'expires_at' => now()->addMinutes(15),
    'requested_ip' => request()->ip(),
    'requested_user_agent' => substr((string) request()->userAgent(), 0, 1000),
    'redirect_to' => '/dashboard',
]);

$url = URL::temporarySignedRoute(
    'passwordless.show',
    $attempt->expires_at,
    [
        'attempt' => $attempt->id,
        'token' => $plainToken,
    ]
);

That is enough. Resist the urge to encode user data, device hints, or trust semantics into the token itself. Put state in the database where you can revoke it, inspect it, and reason about it.

One active attempt or many?

This is an architectural choice worth making explicitly.

If a user requests five links in ten minutes, what should happen?

The easy answer is to allow all of them until they expire. The operationally cleaner answer is usually to invalidate older pending attempts when a newer one is issued, especially for low-friction consumer flows. That reduces confusion and gives support a clearer story: “only the latest email works.”

For B2B apps, I prefer one of these two policies:

Single active attempt per user for standard sign-in.
Scoped active attempts when you want parallel flows, such as one for web login and one for privileged action confirmation.

What I would avoid is laissez-faire token issuance with overlapping validity windows. That produces the exact support tickets you do not want.

Replay protection is the part that separates demos from systems

A magic link is a bearer credential. That means whoever presents it first within the allowed window may gain access unless you design the consumption step carefully.

The minimum bar is straightforward:

the token must be single-use
token consumption must be atomic
successful login must rotate the session
second use must fail cleanly, not race unpredictably
old attempts should not remain ambiguously “sort of valid”

Consume with an atomic state transition

The most common bug in homemade passwordless auth is loading a valid attempt, checking it, and then updating it later in a way that allows two near-simultaneous requests to succeed.

The right mental model is not “validate then login.” It is “win the one-time state transition, then login.”

public function __invoke(Request $request, string $attemptId)
{
    $attempt = MagicLoginAttempt::query()
        ->whereKey($attemptId)
        ->where('expires_at', '>', now())
        ->firstOrFail();

    abort_unless(
        hash_equals($attempt->token_hash, hash('sha256', (string) $request->string('token'))),
        403
    );

    $updated = MagicLoginAttempt::query()
        ->whereKey($attempt->id)
        ->whereNull('consumed_at')
        ->where('expires_at', '>', now())
        ->update([
            'consumed_at' => now(),
            'consumed_ip' => $request->ip(),
            'consumed_user_agent' => substr((string) $request->userAgent(), 0, 1000),
        ]);

    abort_if($updated !== 1, 409, 'This sign-in link is no longer valid.');

    Auth::loginUsingId($attempt->user_id, remember: false);
    $request->session()->regenerate();

    return app(PostMagicLoginRedirector::class)->handle($request, $attempt);
}

That update call is doing the real work. Only one request gets to transition the attempt from pending to consumed.

Do not overfit to IP and user agent

A lot of teams see replay risk and immediately try to bind the flow to IP address or browser fingerprint. That sounds strong until real users hit it from mobile networks, privacy-preserving browsers, VPNs, or email apps that hand off to a different browser instance.

My advice is to treat those signals as risk indicators, not absolute truth.

Good uses of those signals:

require extra confirmation if the consume request is materially different from the request that created the attempt
downgrade trust for the resulting session
add audit metadata
trigger step-up auth for sensitive accounts

Bad uses:

hard-block normal device transitions
permanently deny login because the IP changed between request and click
pretend browser fingerprints are stable enough to be identity proof

Passwordless auth gets worse, not better, when you replace passwords with brittle environmental checks.

Expiration should reflect attack window, not developer convenience

Fifteen minutes is a common default because it feels reasonable, and for many apps it is. But do not pick a TTL because it appears in tutorials. Pick it because it matches the risk of the action.

A low-privilege product login can often tolerate a short-lived email token. A billing confirmation or admin access flow should usually have a narrower window and stronger follow-up checks.

The right question is not “what expiry do other apps use?” It is “how much damage can a leaked email link do before it expires?”

Device trust and step-up auth are where the architecture gets real

A lot of teams imagine passwordless as a replacement for the entire auth stack. That is the wrong framing for any app with meaningful account value.

In practice, passwordless auth is usually your primary login factor, not your entire authorization model. Once the user proves inbox access, you still need a policy for new devices, risky sessions, privileged actions, and recovery.

This is where many Laravel apps should stop improvising and let Fortify handle the second-factor layer.

Magic link first, Fortify second

If you already use Laravel Fortify, the clean approach is to keep concerns separate:

passwordless flow establishes baseline identity
Fortify handles TOTP or other second-factor challenge when required
trusted-device state influences whether challenge can be skipped
authorization gates for sensitive actions still check current assurance level

That design matters because it lets you avoid a common anti-pattern: stuffing every security decision into the magic-link controller.

The magic-link flow should answer one question: did this user complete a valid email-based sign-in attempt?

Fortify and your trust policy should answer the next question: is this session strong enough for the thing they are trying to do?

Provisional sessions are underrated

A clean way to integrate the handoff is to create a real authenticated session after successful token consumption, but mark it as provisional until required step-up checks pass.

For example, after Auth::loginUsingId(), you can set session metadata like:

auth_method=passwordless_email
auth_assurance=low
step_up_required=true
trusted_device=false

Then middleware or your redirect layer can decide whether the user goes straight to the dashboard, to the Fortify challenge, or to a limited-access screen.

That gives you a lot more control than treating auth as a binary “logged in or not” state.

Trusted device should be revocable server state

The lazy version of trusted device is a permanent cookie that says “do not ask again.” That is convenient and weak.

A better version is:

a random device token stored as a hashed record server-side
an expires_at
a label the user can understand, like “MacBook Pro, Chrome”
a last_seen_at
a way to revoke all or one device from account settings

That lets you preserve smooth repeat sign-in without making trust irreversible.

The policy should also be narrower than most teams first imagine. Trusted device should usually reduce friction for routine access. It should not silently authorize sensitive actions forever.

A practical policy might look like this:

ordinary product access: allow with passwordless login
new device on admin account: require Fortify challenge
billing change or API key creation: require recent step-up regardless of trusted device
team ownership transfer: require fresh challenge, always

That is the difference between “passwordless login” and “passwordless security theater.”

Support and observability determine whether the system survives launch

The first time passwordless auth fails, support will learn more about your design than your developers did.

Users do not file tickets that say “I suspect your token consumption semantics are vulnerable to prefetch races.” They say things like:

“the link did not work”
“I got logged out and the new email also failed”
“it says already used”
“I’m on a new laptop and now I’m stuck”

If your team cannot reconstruct the flow quickly, they will start inventing manual fixes. That is where insecure operational habits are born.

Log events across the lifecycle

At minimum, emit structured events for:

login attempt created
email dispatch attempted
email dispatch succeeded or failed
landing route viewed
consume requested
consume rejected with reason
session created
Fortify challenge initiated
challenge completed or failed
trusted device granted, refreshed, revoked

The events do not need to be fancy. They need to be correlated.

MagicLinkRequested::dispatch($attempt->id, $user->id);
MagicLinkEmailSent::dispatch($attempt->id, $user->id);
MagicLinkViewed::dispatch($attempt->id, request()->ip());
MagicLinkConsumeRejected::dispatch($attempt->id, 'expired');
MagicLinkConsumed::dispatch($attempt->id, $user->id);
StepUpChallengeRequired::dispatch($user->id, session()->getId());
TrustedDeviceGranted::dispatch($user->id, $device->id);

What matters is that a support engineer or developer can inspect a timeline and answer basic questions without guessing.

Build for common failure stories, not just malicious ones

The most frequent problems are usually operational, not adversarial:

the user clicked the oldest of several emails
the corporate mail gateway prefetched the link
the user opened the email on mobile but expected the desktop browser to be logged in
the device changed and step-up auth was required unexpectedly
the email delivery lag exceeded the token TTL

Your system should be opinionated about these cases.

For example, if you detect that an already-consumed attempt was first viewed by a mail-security user agent before the real browser arrived, your UI can say something useful instead of a generic failure message: “Your email security scanner may have opened this sign-in link. Request a new one.”

That is not just better UX. It reduces pointless support volume.

Recovery policy is part of the auth design

Passwordless auth fails hardest when inbox access is degraded or lost. If the user's email is unavailable and their trusted device is gone, what happens next?

You need that answer before launch.

Good recovery design usually includes:

a clear operator policy for what support may and may not do
audited device revocation and session revocation
strong identity proof requirements before account recovery
explicit separation between “resend login flow” and “override security controls”

What I would avoid is first-line support having the power to casually disable two-factor settings or impersonate users. That turns your help desk into the weakest part of the auth stack.

What I would actually ship in a Laravel app

If I were replacing passwords in a real Laravel product today, I would keep the design deliberately boring.

The implementation would have these properties:

email links resume a flow on GET; they do not log users in directly
login attempts are stored server-side with hashed tokens and explicit lifecycle fields
only the latest standard sign-in attempt remains valid unless there is a clear reason otherwise
token consumption happens on POST with CSRF protection and atomic single-use update
successful consumption regenerates the session immediately
the resulting session carries an assurance level, not just a yes/no login state
Fortify handles step-up auth instead of homemade challenge logic scattered across controllers
trusted-device records are revocable, expiring, and backed by server state
sensitive actions require recent assurance, not just any authenticated session
support can inspect the full event trail without ever seeing raw tokens

That is not the shortest path to “passwordless.” It is the shortest path I would trust.

Magic links are valuable. They remove password reset churn, reduce credential-stuffing exposure, and often improve the first-login experience. Those are real wins. But they are only wins if the surrounding system is tighter than the password flow you replaced.

The decision rule is simple: if your Laravel passwordless auth can be consumed by a scanner, replayed by a second request, trusted forever on the wrong device, or debugged only by guesswork, you have not finished the design. The magic link is not the hard part. The operational model is.

Read the full post on QCode: https://qcode.in/passwordless-laravel-auth-magic-links-are-not-the-hard-part/

Testing Laravel AI features without burning API credits

Saqueib Ansari — Tue, 14 Jul 2026 05:48:24 +0000

The expensive part of testing AI features is not the API bill. It is the false confidence. If your Laravel tests only prove that a controller returns 200, you are not testing AI behavior. You are testing that your app can make a network request.

The fix is simple: treat the model like an external dependency and test your AI layer as a deterministic contract. That means faking model output, faking tool-call payloads, simulating streaming chunks, and forcing ugly failures on purpose.

This is cheaper, but more importantly, it makes AI behavior reviewable before production. That is the real win.

Put a boundary around the model first

If your controller, job, or Livewire component talks to OpenAI directly, your tests get brittle fast. You end up asserting on transport details, not product behavior.

A better shape is to put your AI integration behind one application service. That service can return a small, app-specific result object like AiReply, DraftResult, or SupportAnswer. Your controllers test app behavior. A narrower set of tests covers the provider integration.

That boundary matters because your fake data should match your contract, not the provider's entire payload. Providers change fields. Your app should not care unless the change affects behavior.

Here is a small example:

<?php

namespace App\Services\Ai;

final class ProductCopyService
{
    public function __construct(private OpenAiResponsesClient $client) {}

    public function generate(string $name, string $audience): ProductCopyResult
    {
        $response = $this->client->create([
            'model' => 'gpt-5.4',
            'input' => "Write concise product copy for {$name} aimed at {$audience}.",
        ]);

        return new ProductCopyResult(
            headline: data_get($response, 'output_text', ''),
            tokensUsed: (int) data_get($response, 'usage.total_tokens', 0),
        );
    }
}

Now your app tests do not need to know every provider field. They only need to know what a valid ProductCopyResult looks like.

If you are using Laravel's AI SDK, the same principle still applies. Keep your app-facing behavior behind a boundary and fake at the transport or client seam. Laravel gives you strong testing primitives for this pattern through the HTTP client fake tools and general testing utilities.

Fake model responses, not just success codes

Most teams stop too early. They fake a 200 OK with some text and call it done. That only covers the happy path where the model behaves exactly how you hoped.

You want at least three classes of fake responses:

A valid answer your app should accept.
A structurally valid answer your app should reject or normalize.
A provider error your app should handle cleanly.

For direct HTTP integrations, Http::fake() is enough. The important part is the payload shape. Make the fake look like the real provider format your parser expects.

<?php

use Illuminate\Support\Facades\Http;
use function Pest\Laravel\postJson;

it('stores generated copy without calling the real API', function () {
    Http::fake([
        'api.openai.com/*' => Http::response([
            'output_text' => 'Ship faster with a Laravel-first AI workflow.',
            'usage' => ['total_tokens' => 148],
        ], 200),
    ]);

    $response = postJson('/products/copy', [
        'name' => 'QCode Deploy',
        'audience' => 'Laravel teams',
    ]);

    $response
        ->assertOk()
        ->assertJsonPath('headline', 'Ship faster with a Laravel-first AI workflow.');

    Http::assertSent(function ($request) {
        return str($request->url())->contains('/v1/responses')
            && $request['model'] === 'gpt-5.4';
    });
});

That last assertion matters. It proves your code sent the request you think it sent, without leaking the test into provider internals.

Test malformed-but-plausible output

AI failures are usually not crashes. They are subtly wrong outputs that still look reasonable.

Examples:

JSON returned as text inside Markdown fences.
Missing fields in a structured payload.
Tool-call arguments that are syntactically valid but semantically wrong.
Overlong output that should trigger truncation or validation.

Those are the tests that save you from production cleanup jobs.

it('rejects product copy when the model returns empty content', function () {
    Http::fake([
        'api.openai.com/*' => Http::response([
            'output_text' => '',
            'usage' => ['total_tokens' => 83],
        ], 200),
    ]);

    $response = postJson('/products/copy', [
        'name' => 'QCode Deploy',
        'audience' => 'Laravel teams',
    ]);

    $response
        ->assertStatus(422)
        ->assertJsonPath('message', 'AI returned an unusable result.');
});

That is the mindset shift: test whether your code can judge model output, not whether the model is smart.

Tool calls need contract tests, not vibes

Once your feature uses tool calling, naive tests break down. You are no longer asserting against one blob of output. You are testing a mini workflow: model asks for a tool, your app executes it, and the final answer depends on that result.

If you are on OpenAI's current API shape, the Responses API and its function-calling guide make this explicit. Tool calls and tool outputs are separate items, correlated by call_id. That detail is worth testing because bad correlation bugs are easy to miss in manual demos.

A good pattern is to keep fixtures tiny and intentional. Do not dump entire provider payloads into your test unless you need them. Include only the fields your parsing logic actually uses.

it('executes the stock lookup tool and returns the final answer', function () {
    Http::fakeSequence()
        ->push([
            'output' => [[
                'type' => 'function_call',
                'call_id' => 'call_123',
                'name' => 'lookupInventory',
                'arguments' => json_encode(['sku' => 'QC-DEPLOY']),
            ]],
        ], 200)
        ->push([
            'output_text' => 'QCode Deploy is in stock and ships this week.',
        ], 200);

    $tool = Mockery::mock(InventoryLookup::class);
    $tool->shouldReceive('forSku')
        ->once()
        ->with('QC-DEPLOY')
        ->andReturn(['in_stock' => true, 'eta' => 'this week']);

    $this->app->instance(InventoryLookup::class, $tool);

    $response = $this->postJson('/support/ask', [
        'question' => 'Can I get QCode Deploy this week?',
    ]);

    $response
        ->assertOk()
        ->assertJsonPath('answer', 'QCode Deploy is in stock and ships this week.');
});

What should you assert here?

The tool was called exactly once.
The parsed arguments match your expected schema.
The final user-facing answer reflects tool output, not hallucinated data.
Unexpected tool names or invalid arguments are handled safely.

Failure modes worth forcing

Tool calling tends to fail in boring, expensive ways:

The model requests a tool that no longer exists.
The arguments are missing required keys.
The tool succeeds, but returns data your final formatter cannot handle.
The model loops and keeps asking for the same tool.

Those are not edge cases. They are normal production states. If you do not have tests for them, your AI feature is still a demo.

Streaming tests should validate transcript flow

Streaming is where many Laravel AI tests become theater. Teams assert that a stream started, maybe that the response status was fine, and move on. That misses the real risk: partial content, broken event order, dropped tool updates, and cleanup logic that never runs.

The right mental model is to test transcript flow, not socket magic.

OpenAI's current streaming docs describe semantic event types rather than one opaque stream blob. Laravel's newer AI and response tooling also leans into streaming as a first-class pattern. Your tests should reflect that by asserting against emitted chunks or normalized events.

One clean approach is to normalize incoming stream events into an internal DTO before they hit the UI. Then your tests can fake a short event sequence and assert on the rendered transcript.

it('streams partial output in order', function () {
    $events = [
        ['type' => 'response.created'],
        ['type' => 'response.output_text.delta', 'delta' => 'Ship'],
        ['type' => 'response.output_text.delta', 'delta' => ' faster'],
        ['type' => 'response.output_text.delta', 'delta' => ' with Laravel.'],
        ['type' => 'response.completed'],
    ];

    $stream = new FakeAiEventStream($events);

    $chunks = iterator_to_array(
        app(StreamedAnswerFormatter::class)->toClientChunks($stream)
    );

    expect($chunks)->toBe([
        'Ship',
        ' faster',
        ' with Laravel.',
    ]);
});

This looks almost too simple, which is a good sign. Streaming tests should not require a real SSE connection to be useful. They should prove three things:

chunks arrive in the expected order
partial state is accumulated correctly
terminal events trigger cleanup or persistence

If your app stores transcript messages after stream completion, assert that explicitly. If cancellation should avoid persistence, write that test too.

Do not skip interrupted streams

Interrupted streams are where production bugs hide. Simulate a stream that ends after two deltas and never emits completion. Your app should not mark that run as successful. It should either retry, surface a recoverable error, or store an incomplete state intentionally.

That is the difference between a polished AI feature and a support ticket generator.

Force ugly failures on purpose

You should spend more time testing failure states than model brilliance. AI providers fail in ordinary infrastructure ways and weird AI-specific ways.

The minimum failure set I want in a Laravel codebase is:

timeout
rate limit
provider 500
malformed JSON or missing fields
empty output
tool-call validation failure
stream interruption

Laravel's fake HTTP layer makes most of this straightforward. Use fake sequences when retries matter. Use exceptions when transport failure matters more than response parsing.

use Illuminate\Http\Client\ConnectionException;
use Illuminate\Support\Facades\Http;

it('falls back gracefully when the provider times out', function () {
    Http::fake(function () {
        throw new ConnectionException('Timed out contacting AI provider.');
    });

    $response = $this->postJson('/support/ask', [
        'question' => 'Summarize this order issue',
    ]);

    $response
        ->assertStatus(503)
        ->assertJsonPath('message', 'AI is temporarily unavailable.');
});

it('retries once after a rate limit response', function () {
    Http::fakeSequence()
        ->push(['error' => ['message' => 'Rate limit']], 429)
        ->push(['output_text' => 'Final answer after retry.'], 200);

    $response = $this->postJson('/support/ask', [
        'question' => 'Retry example',
    ]);

    $response
        ->assertOk()
        ->assertJsonPath('answer', 'Final answer after retry.');
});

These tests are not glamorous, but they are where trust comes from. Anyone can demo a good model response. Fewer teams can prove their app behaves well when the provider is slow, inconsistent, or partially broken.

Make AI behavior reviewable

Saving credits is useful. Making AI changes reviewable is what actually improves engineering quality.

A solid team workflow usually looks like this:

Keep canonical fixtures small

Use a few realistic payload fixtures for:

plain text success
structured output success
tool-call round trip
streaming transcript
provider failure

Do not store giant provider dumps unless a parsing bug requires them. Small fixtures are readable in pull requests.

Assert on normalized outputs

Your tests should mostly assert on app-level results:

rendered answer
saved database record
emitted event
retry path
fallback message

That keeps tests stable even if you switch providers later.

Snapshot only after normalization

If you use snapshots, snapshot your own DTO or trimmed JSON shape, not the raw provider payload. Raw payload snapshots turn into noise fast.

Keep one or two live integration tests

I still want a tiny number of opt-in tests that hit the real provider, usually outside the default CI path. Not many. Just enough to catch authentication drift, model deprecations, or a broken request shape.

But your day-to-day suite should run with zero credits and near-zero randomness.

That is the rule of thumb:

Unit and feature tests should prove your application can handle AI deterministically. Real API calls should be rare verification, not the foundation of confidence.

If your Laravel AI tests still depend on a live model to feel meaningful, the problem is not your budget. The problem is that your AI boundary is too loose.

Tighten the boundary, fake the right layers, and test the awkward cases first. That is how you ship AI features without burning credits or trust.

Read the full post on QCode: https://qcode.in/how-to-test-laravel-ai-features-without-burning-api-credits/

PHP Attributes Can Help Your Docs, But They Won’t Save Them

Saqueib Ansari — Sun, 12 Jul 2026 07:25:33 +0000

PHP attributes are a useful documentation tool, but they are a terrible documentation strategy on their own. That is the short version.

The appeal is obvious. Attributes live next to the code. They are structured, machine-readable, and hard to ignore during implementation. For Laravel and PHP teams building APIs, policies, commands, or internal frameworks, that sounds like the perfect answer to documentation drift.

It is not.

Attributes are excellent for capturing metadata close to the code. They are weak at explaining intent, tradeoffs, workflow, and reader context. If you treat them as the whole documentation system, you usually end up with reference output that is technically populated but editorially useless.

My recommendation is simple: use attributes as a source layer, not as the finished docs. They are best when they feed a stronger documentation system that still has structure, narrative, and human judgment.

What attributes are actually good at

PHP attributes were built for structured metadata, not prose. The PHP manual describes them as machine-readable metadata attached to classes, methods, properties, parameters, and more, accessible through reflection: PHP attributes overview.

That makes them very good at things code already knows for sure:

route-level metadata
validation or schema hints
authorization intent
serialization rules
OpenAPI field and response definitions
command signatures or handler registration

In other words, attributes shine when the documentation value is declarative and local.

A basic example looks clean for a reason:

<?php

use OpenApi\Attributes as OA;
use App\Http\Resources\UserResource;
use Illuminate\Http\Request;

#[OA\Get(
    path: '/api/users/{user}',
    summary: 'Fetch a single user',
    tags: ['Users']
)]
#[OA\Parameter(name: 'user', in: 'path', required: true, schema: new OA\Schema(type: 'integer'))]
#[OA\Response(
    response: 200,
    description: 'User returned successfully',
    content: new OA\JsonContent(ref: UserResource::class)
)]
public function show(Request $request, int $user)
{
    // ...
}

That is a good use of attributes because the metadata is tightly coupled to the code surface. The route shape, parameter location, and basic response contract belong close to the handler. If the endpoint changes, the attribute should change with it.

This is also why tools like swagger-php lean hard into attributes now. Its docs treat attributes as a first-class documentation path, and its annotation model is already moving toward deprecation in favor of attributes: swagger-php and attribute reference.

So the pro-attribute case is real. They reduce one kind of drift: the drift between implementation details and machine-readable reference data.

Where attribute-driven docs become a trap

The problem starts when teams confuse structured metadata with useful documentation.

A generated reference can be technically complete and still fail its reader.

That usually happens in three predictable ways.

1. The docs become local but not meaningful

Attributes are great at saying what exists. They are bad at saying why it matters.

A generated API page may tell you an endpoint accepts status, page, and sort, and still never answer the questions developers actually care about:

Which filters are stable API contracts versus convenience helpers?
What combinations are slow or discouraged?
What defaults are business-critical?
What failure cases should clients design around?
When should this endpoint not be used at all?

Attributes do not naturally answer those questions because those answers are not local facts. They are editorial explanations.

2. The reference starts lying through omission

Teams often trust generated docs too much because they look official. But a clean generated page can hide serious gaps:

examples are missing
response semantics are underspecified
auth behavior is implied, not stated
pagination edge cases are absent
business rules live in service code, not in the documented contract

This is the dangerous version of drift. The docs are not obviously stale. They are plausibly incomplete, which is worse because people trust them longer.

3. Attributes accumulate faster than they get curated

Attributes feel cheap to add, so teams add them everywhere. That is fine at first. Then the codebase gets noisy.

A controller method ends up carrying routing metadata, OpenAPI metadata, security metadata, response metadata, and internal framework metadata all in one stack. At that point, you did not create self-documenting code. You created a metadata wall.

That wall has two costs:

developers stop reading it carefully
the generated docs inherit the same lack of focus

The output may still validate. That does not mean it communicates.

The real comparison: attributes versus editorial docs

The useful comparison is not attributes versus no attributes. It is attributes-only docs versus attributes feeding an editorial documentation layer.

Attributes-only documentation wins on:

proximity to code
machine readability
generation speed
lower risk of obvious schema drift
better tooling automation

Editorial documentation wins on:

decision-making context
examples with intent
warning readers about failure modes
explaining patterns across endpoints or modules
helping new developers understand how the system is supposed to be used

That is why attributes are a shortcut and a drift trap at the same time.

If you stay purely manual, the docs drift because humans forget. If you stay purely attribute-driven, the docs drift because the generated output captures only the pieces the generator can see.

The best systems split the job.

Attributes own structured truth that should stay near code.
Generated references expose that truth consistently.
Editorial docs explain how to use the system well.

This is the same pattern that works in Laravel apps generally. Route definitions are not architecture docs. Validation rules are not onboarding docs. Resource classes are not product guidance. They are inputs into a bigger understanding.

Documentation should be designed the same way.

Where attributes help most in Laravel codebases

Laravel teams get the best results from attributes when they use them on contract surfaces, not as a universal writing system.

Good targets include:

API endpoint metadata
request and response schema mapping
policy or permission registration
event, listener, or command discovery
internal package hooks where reflection already exists

Bad targets are usually the places where explanation matters more than declaration.

For example, this is a reasonable attribute shape because it captures local truth:

<?php

#[RequiresPermission('users.view')]
#[AuditAction('user.viewed')]
#[CacheTtl(seconds: 60)]
final class ShowUserAction
{
    public function __invoke(int $userId): UserData
    {
        // ...
    }
}

Those attributes tell your framework or tooling something concrete. They can also be surfaced in generated internal reference material.

But they still do not answer bigger questions:

Why is users.view separated from users.list?
Why is the cache only 60 seconds?
What user states are intentionally hidden?
What audit guarantees should downstream systems expect?

Those answers belong in docs written for humans, not in ever-growing attribute payloads.

A useful rule of thumb

If a fact is:

enforced by code,
introspectable by reflection,
and meaningful as structured metadata,

then an attribute is a good home for it.

If a fact requires:

rationale,
examples,
sequencing,
tradeoff discussion,
or warnings about misuse,

then it should not live only in attributes.

That line saves teams from turning code into a documentation dumping ground.

How to keep generated docs honest

The failure mode is not using attributes. The failure mode is shipping generated output with no editorial contract around it.

The easiest fix is to define a small documentation architecture instead of hoping generators produce finished work.

1. Decide what attributes are allowed to own

Be explicit. Do not let every team invent its own doctrine.

For example:

attributes own route, schema, auth, and response metadata
markdown docs own tutorials, workflows, migration notes, and decision rules
changelogs own release deltas
examples live in tested fixtures or example requests

That sounds obvious, but most teams skip it. Then they wonder why half the documentation lives in controllers and the other half in Confluence gravesites.

2. Generate references, then curate entry points

A generated OpenAPI page is not a developer experience. It is a reference artifact.

You still need curated entry points such as:

“Start here” guides
common workflows
auth setup
pagination and rate-limit behavior
versioning rules
examples that reflect real client use

Generated reference should support those pages, not replace them.

3. Treat examples as first-class documentation

This is where attribute-driven systems are usually weak. They capture schemas well and examples poorly.

If your docs generator supports examples, use them aggressively. If it does not, keep tested examples close to the codebase and pull them into editorial docs. A technically correct schema without one realistic example is far less useful than teams admit.

4. Review attributes like API surface, not like decoration

Attribute changes should be treated as contract changes when they affect external behavior. That means code review should ask questions like:

Did the response contract change?
Is the status code still correct?
Are nullable fields still truthful?
Does the summary reflect actual use, not just implementation detail?

If reviewers treat attributes like harmless syntax garnish, the docs will rot even though they are generated.

5. Add drift checks that matter

The best attribute-based documentation setups fail loudly when the generated output and committed artifacts diverge.

In practice, that means things like:

generating OpenAPI in CI
diffing generated spec files
rejecting undocumented breaking changes
testing examples when possible

Automation cannot create good prose, but it can stop bad reference drift from slipping through quietly.

The shape I would recommend

For a Laravel or broader PHP team, I would use a three-layer model.

Layer 1: attributes for structured source truth

Use PHP attributes for metadata that is local, machine-readable, and tied directly to code.

That includes route contracts, schemas, auth hints, and other declarative surface details.

Layer 2: generated reference for consistency

Use tools like swagger-php to produce API reference artifacts from that source truth. Let generators handle the repetitive shape of endpoint docs so humans do not waste effort retyping stable contract data.

Layer 3: editorial docs for meaning

Write short, opinionated docs that explain how the system is actually used:

which endpoints matter most
common integration flows
business caveats
performance traps
migration notes
examples that reflect reality

That last layer is the one teams try to skip. It is also the layer that separates “technically documented” from “actually usable.”

The practical recommendation

PHP attributes are absolutely worth using for documentation-related metadata. They reduce one of the most annoying forms of drift by keeping structured facts close to the implementation. For Laravel teams especially, that is a real win.

But they are not a substitute for documentation design.

If you want docs that developers trust, use attributes to capture reference truth, use generation to keep that truth consistent, and use editorial writing to explain how the system should be used in practice. That is the balance that works.

The decision rule is simple: attributes should document what the code can assert confidently; humans should document what readers still need help understanding.

Read the full post on QCode: https://qcode.in/php-attributes-as-documentation-useful-shortcut-or-drift-trap/

When Transaction Pooling Starts Making Sense in Laravel

Saqueib Ansari — Sat, 11 Jul 2026 11:49:17 +0000

If your Laravel app is running into Postgres connection limits, transaction pooling is usually the first scaling move worth testing. Not replicas. Not sharding. Not a panicked rewrite of every query that shows up in a slow log. Busy Laravel systems often burn more capacity on connection churn than on actual SQL execution.

That is why PgBouncer-style transaction pooling keeps showing up in serious Postgres setups. PHP requests are short-lived. Horizon workers fan out under load. Scheduled jobs arrive in bursts. Admin dashboards and exports create ugly spikes. Those workloads generate a lot of clients that want database access, but very few of them actually need a dedicated Postgres backend for their whole lifetime.

The catch is simple: transaction pooling only works cleanly when your app behaves like a stateless SQL client between transactions. A lot of Laravel code already fits that model. The parts that do not are usually the parts nobody has reviewed carefully in months: tenancy boot logic, raw SQL helpers, legacy console commands, import jobs, or package glue code.

My recommendation is straightforward. Use transaction pooling when connection count is the real bottleneck, but treat the migration like a code audit, not a config tweak. Pooling is very good at exposing hidden session-level assumptions. That is exactly why it helps and exactly why careless rollouts hurt.

The bottleneck is often connection churn before it is query speed

Laravel apps usually hit this wall in a boring, predictable way. A web tier opens one class of connections. Horizon opens another. Scheduler-driven work wakes up on the minute. Then a report export, a bulk import, or a deploy lands at the wrong time and Postgres suddenly looks fragile.

Teams often misread that moment. They assume the database is slow because slow pages and queue lag are what users notice. But Postgres pays real overhead for every backend process: memory, scheduler pressure, transaction bookkeeping, idle session cost, and general connection management. A database can look unhealthy at 800 live connections even when the actual query workload would be fine at 120 pooled server connections.

That distinction matters because the fix is different. If the real ceiling is connection count, a pooler can buy back headroom faster than incremental query cleanup. You should still fix bad queries. You should still add indexes where they belong. But that is not the same problem.

Laravel now acknowledges this directly in its PostgreSQL docs with pooled connections and a separate direct path for migrations and maintenance work: Laravel database docs. That is a useful signal. The framework is effectively saying what operations teams learned the hard way years ago: application traffic and schema traffic do not want the same connection behavior.

A busy Laravel app is a good candidate for transaction pooling when these symptoms show up together:

Postgres connection usage spikes far harder than CPU or I/O.
Queue bursts hurt more than average request volume.
Deploy windows or cron-heavy periods create short but ugly saturation.
Most requests and jobs are short units of work, not long-lived database conversations.

If that sounds familiar, transaction pooling is not premature optimization. It is often the cleanest first correction.

What transaction pooling really changes

The mechanics are simple enough, but the behavioral consequences matter.

With session pooling, one client gets one server connection for the lifetime of that client session. With transaction pooling, a client borrows a real Postgres backend only while a transaction is active, then gives it back to the pool. That model dramatically improves server connection reuse under bursty traffic.

It also kills the assumption that the next statement from your app will land on the same backend session.

That is the boundary teams have to understand. PgBouncer is explicit that transaction pooling breaks ordinary use of session-bound features like SET/RESET, LISTEN, PREPARE / DEALLOCATE, preserved temp tables, and session advisory locks: PgBouncer feature matrix. PostgreSQL’s own docs explain why one of those failures happens: prepared statements created with PREPARE live only for the duration of the current server session: PostgreSQL PREPARE docs.

So the real question is not whether Laravel supports pooling. It does. The real question is whether your app depends on connection-local state surviving longer than one transaction.

What usually works fine

Most normal Laravel application code survives transaction pooling without much drama:

Eloquent queries
query-builder reads and writes
standard DB::transaction() blocks
queue jobs that read, write, commit, and exit
row-locking patterns that stay inside one real transaction

That is why pooling usually fits Laravel better than it fits more stateful application models. PHP request lifecycles are already short. The framework mostly encourages unit-of-work style database access.

What usually breaks first

The failures are rarely exotic. They are just easy to ignore until a pooler forces the issue:

SET search_path or similar session config done once and assumed forever
raw PREPARE usage
LISTEN/NOTIFY implemented through app connections
temp tables reused outside a single transaction boundary
session advisory locks
long-running worker logic that quietly assumes backend session affinity

That is why one part of an app can look perfect behind PgBouncer while a forgotten console command blows up. The pooler is not being inconsistent. The codebase is revealing where session behavior leaked into application logic.

Laravel now gives you a much cleaner migration shape

A few years ago, teams often shoved PgBouncer in front of production, flipped environment variables, and found out what broke by reading support messages. Laravel’s newer pooled Postgres support gives you a better model than that.

A practical config looks like this:

'pgsql' => [
    'driver' => 'pgsql',
    'url' => env('DB_URL'),
    'host' => env('DB_HOST'),
    'port' => env('DB_PORT', '5432'),
    'database' => env('DB_DATABASE'),
    'username' => env('DB_USERNAME'),
    'password' => env('DB_PASSWORD'),
    'charset' => 'utf8',
    'prefix' => '',
    'prefix_indexes' => true,
    'search_path' => 'public',
    'sslmode' => 'prefer',
    'pooled' => env('DB_POOLED', true),
    'direct' => array_filter([
        'host' => env('DB_DIRECT_HOST'),
        'port' => env('DB_DIRECT_PORT', '5432'),
        'username' => env('DB_DIRECT_USERNAME'),
        'password' => env('DB_DIRECT_PASSWORD'),
        'sslmode' => env('DB_DIRECT_SSLMODE', 'prefer'),
    ]),
],

That structure matters for two reasons.

First, Laravel can automatically use the direct connection for migrations, schema dumps, restores, db:wipe, db:show, and related commands when pooled mode is enabled. That is the right default. DDL and maintenance workflows are exactly where transaction pooling is least pleasant.

Second, Laravel enables emulated prepares for pooled connections. That is not random framework trivia. It is Laravel acknowledging the same compatibility line PgBouncer documents. If your code depends on native session-level prepare semantics, a pooled connection changes the ground rules.

The operational rule should be brutally simple:

Application traffic goes through the pool. Schema and maintenance work gets a direct path.

When you need that direct path from code, make it explicit:

use Illuminate\Support\Facades\DB;

DB::connection('pgsql::direct')->statement(
    'create extension if not exists pg_trgm'
);

That explicitness matters. Hidden infrastructure exceptions are exactly what make rollbacks and late-night repairs harder than they should be.

The Laravel-specific traps most teams miss

The obvious trap is raw PREPARE. The more common traps are subtler and usually more expensive.

Tenancy or schema boot logic hidden behind `SET`

Some multi-tenant or multi-schema apps use SET search_path in middleware, a tenant resolver, or a low-level helper. That can appear to work fine for years if one app connection effectively keeps one backend session. Under transaction pooling, that assumption disappears.

If schema context matters, move that intent into durable connection configuration or explicit SQL design. Session-local setup is not a reliable contract once server connections are shared.

Workers that act like mini database sessions

A lot of queue jobs are perfectly safe behind PgBouncer. The dangerous ones are the jobs that behave like miniature session-oriented scripts.

That usually means jobs that:

create temp tables
depend on advisory locks casually
hold transactions open while calling external APIs
expect multiple statements to preserve backend-specific state

This does not mean workers and transaction pooling do not mix. They usually mix well. It means badly shaped workers become impossible to ignore once the pooler removes backend affinity.

Confusing Laravel `sticky` with session affinity

Laravel’s read/write sticky option is useful, but teams routinely overread what it gives them. The docs are precise: if a write occurs during the current request cycle, later reads in that same request will use the write connection: sticky option.

That does not mean:

future requests keep the same backend session
queue workers inherit read-your-write guarantees from HTTP requests
replica lag stops mattering
transaction pooling becomes stateful

This confusion matters because teams sometimes blame pooling for bugs that are really consistency or routing issues. Those are adjacent concerns, not the same concern.

Old commands nobody owns anymore

The highest-risk code is often not in controllers or service classes. It is in legacy Artisan commands, admin repair scripts, report generators, import tools, or package integration code. Those places are exactly where temp tables, LISTEN, session tweaks, or unusual transaction assumptions like to hide.

If your migration validation is mostly browser clicks, you are validating the safest slice of the system.

How I would audit a real Laravel codebase before cutover

The right posture is simple: assume hidden session coupling exists until you prove otherwise.

Start with a blunt search:

rg -n "SET |LISTEN|NOTIFY|PREPARE|DEALLOCATE|pg_advisory_lock|pg_try_advisory_lock|create temp|search_path" app/ bootstrap/ config/ database/ routes/ tests/

That search is intentionally ugly. It is supposed to catch suspicious patterns quickly, not look elegant in a slide deck.

Then review the parts of the system that are least like ordinary request handling:

imports and exports
raw SQL reporting jobs
scheduled maintenance commands
workers that mix transactions with network calls
retry-heavy jobs with partial side effects

I would classify what I find into three buckets:

Safe through the pool: ordinary app traffic, standard transactions, simple jobs.
Needs review: raw SQL, odd workers, schema-sensitive flows, temp tables, advisory-lock usage.
Direct only: migrations, extension setup, schema repair, operational maintenance tooling.

That classification turns the migration from guesswork into policy. It also makes the inevitable exception paths visible early instead of during an incident.

How to test the move without lying to yourself

Feature tests alone are not enough. The migration changes how database connections are allocated under concurrency, so the validation has to exercise that shape.

The goals are straightforward:

normal pooled app traffic still behaves correctly
direct-path operational tasks still work
connection pressure drops without moving the bottleneck somewhere worse

A small smoke suite aimed directly at the migration seam is more useful than a large generic suite here:

it('keeps ordinary transactional work safe behind the pool', function () {
    DB::transaction(function () {
        DB::table('orders')->insert([
            'number' => 'ORD-1001',
            'status' => 'pending',
        ]);

        $order = DB::table('orders')
            ->where('number', 'ORD-1001')
            ->lockForUpdate()
            ->first();

        expect($order->status)->toBe('pending');
    });
});

it('uses the direct connection for schema-only work', function () {
    expect(fn () => DB::connection('pgsql::direct')
        ->statement('create extension if not exists pgcrypto'))
        ->not->toThrow(Exception::class);
});

Then stage the pool under traffic that resembles production, not a polite demo:

concurrent HTTP requests
Horizon bursts
scheduler windows
dashboards and exports

And watch the signals that actually matter:

active Postgres server connections
connection churn during spikes and deploys
PgBouncer wait time and pool saturation
queue latency and retry behavior
worker-specific or raw-SQL error rates

If latency stays acceptable while Postgres connection pressure drops materially, that is a real win. If PgBouncer becomes a queueing bottleneck or long transactions start starving throughput, you have at least learned something honest before production traffic teaches it harder.

Do one fallback drill too. Before cutover, prove that direct-path migrations and maintenance commands still work when bypassing the pool. That step is boring, but it is the kind of boring step that prevents a rollback from becoming a second outage.

The practical rule

For busy Laravel apps, transaction pooling is usually the right move when connection count is the actual bottleneck and the application mostly behaves like short, stateless units of SQL work. Delay it when the codebase still depends on connection-local behavior it has never isolated properly.

The upside is real. Postgres spends more time executing useful queries and less time babysitting idle or bursty client sessions. Queue spikes become less wasteful. Deploy windows get calmer. But teams only get those benefits when they stop pretending the database session is part of their application state.

That is the lesson worth keeping: pool aggressively, but treat database session state as a liability unless you can prove you truly need it.

Read the full post on QCode: https://qcode.in/postgres-transaction-pooling-lessons-for-busy-laravel-apps/

Feature flag debt gets worse when frontend and backend ship on different clocks

Saqueib Ansari — Sun, 05 Jul 2026 04:19:43 +0000

Feature flags are supposed to make releases safer. In practice, they often create a second deployment system that nobody treats with the same rigor as the first one.

That gets dangerous when your frontend and backend do not ship on the same clock. The SPA is cached globally and updates in minutes. The API rolls out gradually. A worker fleet is still on the previous image. Analytics schemas lag behind both. The flag flips anyway. Now the client assumes a capability that the server does not support yet, or the backend starts emitting shapes the frontend does not understand.

This is where feature flag debt stops being a cleanup issue and turns into a reliability issue. The real problem is not flags themselves. It is uncoordinated assumptions across independently moving systems.

The fix is straightforward, but it requires discipline: design flags around capability boundaries, not UI moments; make backend compatibility the default; and treat flag rollout like a cross-system contract, not a boolean in a dashboard.

The broken state usually comes from mismatched assumptions

Most teams first feel this problem in a simple way. A button appears in the UI, but clicking it returns 404 or 403. Or a page assumes a new response field exists, but one API pod is still serving the old schema. Or a background job starts processing a “new flow” event while the consumer that understands that event has not rolled out yet.

None of these failures are exotic. They happen because a flag is often modeled at the wrong layer.

A common anti-pattern looks like this:

the frontend checks new_checkout_enabled
the backend separately checks new_checkout_enabled
a worker separately checks new_checkout_enabled
analytics separately checks new_checkout_enabled

That looks coordinated, but it is not. It assumes every runtime sees the same flag value, on the same schedule, with the same deployment state, and interprets the flag identically. That assumption is weak in any distributed system.

What actually happens is this:

The flag turns on for 10% of users.
Some frontend clients fetch the new value immediately.
Some backend instances are still on the old release.
Some queued jobs were created before the flag changed.
Some event consumers lag behind by minutes or hours.

Now “the flag is on” does not mean one thing. It means five slightly different things across the stack.

A flag should not be your compatibility layer

Teams get into trouble when they expect the flag service to solve coordination by itself. It cannot. A flag can decide whether a code path is eligible. It cannot guarantee that every dependent system is already compatible.

That means your system needs a stronger invariant than “this flag is true.” The invariant should be closer to this:

If any part of the stack sees the new path, every downstream dependency can either handle it or degrade safely.

That is the bar. If you cannot meet it, the flag is being used too early or at the wrong boundary.

Start with backend compatibility, not frontend exposure

If backend and frontend ship independently, the safest rollout order is boring: make the backend capable first, then expose the frontend later.

This sounds obvious, but teams regularly invert it because the UI is the visible part of the feature. That creates the exact broken state feature flags were supposed to avoid.

A better model is to split a feature into separate concerns:

backend capability exists
API contract supports old and new clients
jobs and consumers can process both versions
analytics can ingest both event shapes
frontend exposure is enabled

Those are not the same milestone. Treating them as one switch creates debt fast.

Additive change beats conditional change

The safest flaggable change is usually additive. Add a new field, a new endpoint, a new optional behavior, or a new event version while keeping the old path valid.

For example, this is safer than replacing a response shape outright:

{
  "id": 42,
  "status": "paid",
  "checkout": {
    "version": "v2",
    "available": true,
    "redirect_url": "/checkout/v2/session/abc123"
  }
}

An old client can ignore checkout. A new client can use it if present. That is much safer than making the frontend assume a brand-new route exists because a UI flag was turned on.

The same principle applies to commands and jobs. If a worker starts seeing a new payload shape, it should either understand both versions or reject the unsupported one explicitly and visibly. Silent partial handling is where long-lived flag debt hides.

Capability detection is stronger than UI gating

A useful pattern is to let the backend expose capability, then let the frontend decide whether to render the experience.

Instead of this:

if (flags.newBillingFlow) {
  showNewBillingPage();
}

prefer something closer to this:

const canUseNewBilling =
  flags.newBillingFlow && apiCapabilities.billingFlow === 'v2';

if (canUseNewBilling) {
  showNewBillingPage();
} else {
  showLegacyBillingPage();
}

Now the flag is no longer the sole source of truth. The rendered state depends on an actual server capability signal.

That gives you a safer rollout path:

Deploy backend support for billingFlow=v2.
Let the API advertise the capability.
Roll out workers and analytics support.
Turn on frontend exposure only where capability is confirmed.

This is more tedious than flipping one boolean. It is also how you avoid shipping fake availability.

Design flag rollout as a contract across systems

Once a feature touches more than one runtime, your rollout plan should be explicit. Not “we’ll turn it on gradually.” Explicit.

A useful mental model is that every multi-system feature has at least four contracts:

read contract: what responses can clients safely consume?
write contract: what payloads can clients or jobs safely send?
processing contract: what events or commands can workers safely handle?
measurement contract: what analytics events and schemas stay valid during the rollout?

If you only think about the first one, you will break the other three.

A practical rollout sequence

For most full-stack product work, the sequence below is safer than ad hoc toggling:

Deploy passive backend support first.
Make response changes additive and backwards compatible.
Update workers, consumers, and analytics to understand both old and new shapes.
Emit observability signals for the new path while exposure is still off.
Enable the flag for internal users or a tiny cohort.
Verify end-to-end behavior across API, queue, and analytics.
Expand exposure gradually.
Remove the old path and the flag only after the new path is boring.

The important bit is step 4. Teams often wait to add monitoring until after exposure starts. That is backwards. You want to know whether the system can survive the new path before real users hit it at scale.

Separate release flags from ops flags

Another source of debt is overloading one flag with multiple meanings.

A release flag answers: “Should users see this feature yet?”

An operational flag answers: “Should this subsystem execute a risky behavior right now?”

Those are not interchangeable. For example:

show_new_import_ui is a release flag
use_new_import_pipeline is an operational flag

If you collapse them into one boolean, you lose control. Sometimes you want the UI visible but the old processing pipeline still active in fallback mode. Sometimes you want the backend pipeline live for internal traffic before any public UI exists.

Separate flags create more names, but fewer accidents.

Make asynchronous systems first-class in the design

Feature flag discussions are often too request-response centric. Real production systems are not just browser plus API. They include queues, cron jobs, webhooks, caches, read replicas, and analytics sinks. Those are usually where rollout bugs become hard to trace.

If a user action under a new flag emits an event that is processed five minutes later by a stale consumer, your deploy is still broken even if the initial API response looked correct.

Version messages, not just endpoints

Teams are often careful with API versioning and careless with internal event versioning. That is a mistake.

If a flagged feature changes event semantics, add an explicit version or event type.

{
  "event": "checkout.completed",
  "version": 2,
  "user_id": 123,
  "payload": {
    "flow": "express",
    "session_id": "sess_abc",
    "total": 4999
  }
}

That gives consumers a clear branch instead of forcing them to infer which world they are in.

The goal is not elegant payloads. The goal is survivable change.

Queues preserve old assumptions longer than you think

Queued work is where “the rollout is complete” becomes fiction. Jobs created before a flag flip may run after the flip. Retried jobs may execute on newer workers with older payload assumptions. Dead-letter replay may resurrect paths you thought were gone.

That means job handlers should be written with rollout windows in mind:

accept old and new payload versions during migration
avoid resolving behavior from current flag state if the job was created under older assumptions
store explicit mode or version on the job payload when behavior matters

This is safer than doing something like:

public function handle(): void
{
    if (Feature::active('new_settlement_flow')) {
        $this->runNewSettlement();
        return;
    }

    $this->runLegacySettlement();
}

That code is fragile because execution-time flag state may not match enqueue-time intent.

A safer approach is to persist the decision:

final class ProcessSettlement implements ShouldQueue
{
    public function __construct(
        public readonly int $paymentId,
        public readonly string $flowVersion,
    ) {}

    public function handle(): void
    {
        match ($this->flowVersion) {
            'v2' => $this->runNewSettlement(),
            default => $this->runLegacySettlement(),
        };
    }
}

That is the kind of detail that prevents async systems from drifting away from the request path.

Build observability around rollout mismatches

Most flag rollouts are monitored too shallowly. Teams watch error rate and maybe conversion. That catches catastrophic failure, but not subtle mismatch.

You need telemetry that answers a more specific question: are different layers of the stack behaving as if they are in different release states?

That means logging and dashboards around:

frontend flag state versus backend capability response
request volume by feature version
job volume by payload version
event consumer success rate by version
analytics ingestion errors by schema version
fallback path usage after the flag is supposedly “on”

If the frontend renders v2 for 20% of users but only 8% of API writes are hitting the v2 path, you have a coordination problem. If v2 jobs enqueue fine but v2 consumer handling lags, you have a coordination problem. If analytics starts dropping new events, the release is not healthy even if users do not notice immediately.

Log decisions, not just failures

One of the best habits here is to log rollout decisions explicitly.

For example, include structured fields like:

feature=checkout_v2
flag_state=true
api_capability=v2
selected_flow=v2
job_payload_version=2

That lets you reconstruct not only that something failed, but why the system believed it should take that path. Without that, debugging coordinated rollouts becomes guesswork.

This matters even more when multiple flags overlap. Two independent booleans can create four states. Three booleans create eight. If you are not logging the decision inputs, you are debugging a state machine blind.

Feature flag debt is mostly lifecycle debt

A lot of teams talk about flag debt as “too many old flags.” That is true, but incomplete. The more dangerous debt is flags with unclear ownership, unclear rollout semantics, and no removal plan.

A feature flag should have metadata that answers basic operational questions:

who owns it?
what systems depend on it?
is it release, experiment, permission, or ops control?
what is the expected cleanup date?
what metrics prove the old path is safe to delete?

If you cannot answer those questions, the flag is already a liability.

Short-lived release flags should stay short-lived

Most release flags should not live for months. If they do, they stop being rollout controls and become permanent branching logic.

That creates three costs at once:

engineers have to reason about both worlds forever
tests multiply across paths nobody wants to maintain
async and analytics systems carry compatibility baggage long after the rollout ended

A practical rule is to decide the exit criteria when you create the flag, not when you are tired of looking at it.

For example:

remove after 100% rollout holds for two weeks
remove after v2 job traffic reaches 100% and no v1 jobs remain in flight
remove after analytics confirms the old schema path is unused

That is better than leaving “cleanup later” in a ticket graveyard.

What to do differently on your next flagged release

If your stack ships frontend, backend, and workers independently, assume clock drift by default. Do not design flags as if every component updates in lockstep.

Start by making backend changes additive. Expose capabilities explicitly. Persist version decisions into jobs and events instead of re-deriving them from current flag state. Split release flags from operational flags. Add rollout telemetry before exposure starts. Then remove the old path aggressively once the new one is stable.

The core decision rule is simple: a feature flag should never be the only thing standing between a user and an incompatible backend state.

If turning a flag on can expose assumptions that the rest of the stack has not caught up with, the rollout design is weak. Fix the contract first. Then flip the flag.

That is how you keep feature flags useful instead of turning them into a distributed systems tax.

Read the full post on QCode: https://qcode.in/feature-flag-debt-gets-worse-when-backend-and-frontend-ship-on-different-clocks/

Interactive Data Visualizations Need Backend Thinking Too

Saqueib Ansari — Thu, 25 Jun 2026 05:48:00 +0000

Interactive data visualizations get praised for the wrong layer. People notice the timeline scrubber, the map replay, the animated dots, the polished easing. They do not notice the ingestion job that cleaned broken timestamps, the cache strategy that kept the API alive, or the artifact builder that cut a 40 MB raw dataset into a 900 KB view payload.

That invisible work is the product.

If you are building data-heavy visual experiences, the frontend is not the system. It is the renderer. The real engineering challenge is deciding what data shape reaches the browser, when it arrives, how much of it arrives, and how repeatable that pipeline stays when traffic and source quality both get worse.

That is the practical takeaway up front: interactive visualizations need backend-first design if you want them to survive production traffic. Otherwise you are shipping a demo with a nice animation layer on top of an unstable data path.

The browser should render, not repair your data

A lot of visualization stacks fail because the API contract is too close to the storage model. The backend exposes raw or lightly filtered records, then the client is forced to deduplicate, aggregate, interpolate, bucket, and infer meaning on every load.

That looks flexible during development because the frontend team can move fast. It becomes expensive later because every user session now pays the cost of data cleanup, and every edge case turns into UI complexity.

For animated station maps, fleet traces, or timeline replays, source data is usually hostile to direct rendering. Event streams arrive out of order. Repeated observations create fake density. Coordinates drift. Entity IDs are inconsistent across sources. Missing records create gaps the UI is expected to smooth over.

If the browser receives this shape:

[
  {"train_id":"A12","station":"Central","lat":19.0728,"lng":72.8826,"seen_at":"2026-06-25T10:00:02Z"},
  {"train_id":"A12","station":"Central","lat":19.0728,"lng":72.8826,"seen_at":"2026-06-25T10:00:09Z"},
  {"train_id":"A12","station":"West End","lat":19.0810,"lng":72.8951,"seen_at":"2026-06-25T10:03:41Z"}
]

then the frontend has to answer questions it should never own:

Is the second record a duplicate or a meaningful stationary update?
Should the gap between timestamps be interpolated?
Is the implied path direct, snapped to rails, or unknown?
What should happen if one station record is missing?

That logic belongs upstream. The client should consume something closer to a playback model than a source log.

{
  "entity":"A12",
  "revision":"2026-06-25T10:05:00Z",
  "segments":[
    {
      "from":"Central",
      "to":"West End",
      "start":1782372002,
      "end":1782372221,
      "path":[[19.0728,72.8826],[19.0763,72.8880],[19.0810,72.8951]],
      "confidence":"high"
    }
  ]
}

That single shift changes the whole system. CPU work moves out of the browser. Behavior becomes testable. Derived assumptions become explicit. Cacheability improves because the response shape now matches the interaction model.

Storage models and view models should diverge on purpose

This is the part many teams resist. They want one canonical API to serve every consumer. That instinct is understandable, but it is usually wrong for rich interactive views.

A visualization surface is a specialized consumer. It needs fast sequential access, compact payloads, stable ordering, and derived state that would be wasteful or awkward in a general-purpose API. Trying to force the visualization to consume the same shape as admin dashboards, exports, and internal analytics usually creates the worst version of all of them.

If the page is interactive, time-based, and traffic-facing, give it a dedicated backend contract.

Preprocessing is where reliability actually comes from

Most production-grade visualization systems are really two systems: a pipeline that prepares data and a delivery layer that serves prepared artifacts. Teams that skip the first one end up overloading the second.

Preprocessing is not just a performance optimization. It is where you turn messy observational data into a product-grade representation that can be replayed consistently.

What preprocessing should handle

For the class of experiences described here, preprocessing usually needs to do at least five things well.

First, it validates source records. If timestamps are malformed, coordinates are outside expected bounds, or IDs fail normalization rules, the pipeline should reject or quarantine them before they contaminate downstream artifacts.

Second, it normalizes structure. Time zones, units, entity identifiers, geometry formats, and schema variants need to collapse into one internal model.

Third, it derives playback segments. Raw event rows are often too granular or too noisy. The useful artifact is a sequence of intervals, paths, summary points, or time buckets.

Fourth, it materializes multiple resolutions. An overview map and an entity drill-down should not read the same fidelity level.

Fifth, it stamps revisions. If a pipeline rebuild changes anything important, the delivery layer needs a durable version signal so stale and fresh fragments do not mix.

Reproducibility matters more than convenience

A fragile pattern is doing the transformation work inside request handlers because it feels simpler. It is simpler for a week. Then traffic increases, one source adds a new field, or the user asks for a longer time range, and the request path turns into an accidental batch job.

A better design is explicit and boring: ingest, normalize, derive, materialize, publish.

final class BuildVisualizationArtifacts
{
    public function handle(Carbon $from, Carbon $to): void
    {
        $rawEvents = app(SourceEventRepository::class)->between($from, $to);

        $normalized = app(EventNormalizer::class)->normalize($rawEvents);
        $segments = app(SegmentBuilder::class)->build($normalized);
        $overview = app(OverviewAggregator::class)->make($segments);
        $detailTiles = app(DetailTileBuilder::class)->make($segments);

        $revision = now()->utc()->format('YmdHis');

        app(ArtifactStore::class)->put("overview:$revision", $overview);
        app(ArtifactStore::class)->put("detail:$revision", $detailTiles);
        app(DatasetRevisionStore::class)->setCurrent($revision);
    }
}

The frameworks and class names do not matter much. The architecture does. If you can rebuild the same artifact deterministically, inspect intermediate stages, and compare outputs across revisions, you have a real pipeline. If not, you are still depending on runtime improvisation.

Uncertainty should be encoded, not hidden

There is another reason preprocessing belongs on the backend: uncertainty handling. Many interactive datasets contain inferred positions, sparse ranges, or partial observations. If you smooth all of that into a visually confident animation, you create a lie with good design.

Better systems keep uncertainty visible in the data model. A segment can carry confidence, interpolated, sample_count, or source_gap_ms. The UI can then use different styles or tooltips to communicate that some motion was derived rather than directly observed.

The backend should not manufacture precision the source system never had.

Payload budgets should drive the API design

If there is one mistake that keeps repeating in visualization projects, it is pretending that payload size is a frontend optimization problem. It is not. It is an API contract problem.

By the time the frontend team is arguing about virtualized lists, memoization, or canvas layers, the more expensive mistake may already be locked in: the server is sending too much data for the interaction to feel immediate.

A first-load payload is not just a technical number. It determines whether the product can support fast pan, zoom, scrub, hover, mobile use, and concurrent traffic.

The first response should be intentionally incomplete

A strong visualization API does not try to send the universe on first load. It sends the smallest truthful view that gets the user oriented.

That usually means bounding the request by:

time window
viewport or region
detail tier
active filters
current dataset revision

Instead of this:

GET /api/visualization/network-history

prefer this:

GET /api/visualization/network-history?from=2026-06-01T00:00:00Z&to=2026-06-07T00:00:00Z&bbox=72.8,18.8,73.1,19.2&detail=overview

That change is not cosmetic. It forces the backend to acknowledge that different user moments need different data density.

Detail tiers should be real, not rhetorical

Many systems expose summary=true or detail=low parameters that barely change anything. That is fake progressive design. A real tiered strategy should produce meaningfully different artifacts.

A practical split looks like this:

overview: counts, coarse paths, simplified geometry, sparse labels
interactive: enough detail for timeline scrubbing and local filters
inspect: selected entity details, per-segment metadata, richer annotations

Each tier should have a target payload range and a target latency envelope. If overview and interactive are nearly the same size, the backend is not doing enough shaping.

Downsampling is not compromise, it is product design

Some engineers still treat downsampling like a reluctant concession. For interactive views, it is usually the correct move.

When the user is zoomed out over a city or scrubbing a week of history, raw fidelity is mostly waste. It increases payload, clutters the display, and gives the illusion that more detail on screen means more truth. Often the reverse is true.

A reduced representation can be more honest because it matches the question the user is actually asking at that zoom level. This is the same logic behind vector tiles, level-of-detail rendering, and multiresolution time-series systems. The interaction decides the density, not the storage layer.

Caching and progressive loading are where the UX is won

Once you have preprocessed artifacts and bounded payloads, delivery becomes the next leverage point. This is where many visualization products either become pleasant or stay permanently sticky.

Caching is not just about reducing database pressure. It is about making repeated navigation patterns feel instantaneous. Progressive loading is not just about skeleton screens. It is about sequencing information so the page becomes useful before the full detail graph exists.

Cache keys need semantic discipline

Bad cache keys create bugs that look random from the frontend. One user sees stale geometry, another sees fresh counts, and a third causes needless rebuilds because the same filters serialized differently.

The fix is to canonicalize request shape before hashing it. Include every dimension that changes the output, and do not forget the dataset revision.

$params = [
    'from' => optional($request->date('from'))->toIso8601String(),
    'to' => optional($request->date('to'))->toIso8601String(),
    'bbox' => array_map('floatval', explode(',', (string) $request->query('bbox'))),
    'detail' => (string) $request->query('detail', 'overview'),
    'filters' => $request->input('filters', []),
    'revision' => app(DatasetRevisionStore::class)->current(),
];

ksort($params);

$cacheKey = 'viz:' . sha1(json_encode($params));

return Cache::remember($cacheKey, now()->addMinutes(15), function () use ($params) {
    return app(VisualizationPayloadBuilder::class)->build($params);
});

The critical part is not the hash. It is the discipline around what enters the hash. If the current dataset revision is missing, you will eventually serve old slices after a pipeline rebuild and spend hours blaming the frontend.

Progressive loading should mirror user intent

A good mental model is to load the visualization in rings.

The first ring is orientation: overview geometry, aggregate counts, bounds, and enough context to make the page feel alive.

The second ring is interaction: the fidelity needed for timeline scrubbing, local filtering, and smooth pan or zoom transitions.

The third ring is inspection: entity-level detail, richer tooltips, segment metadata, and anomaly explanations.

That leads to a concrete sequence:

Serve a compact overview artifact for first paint.
Prefetch adjacent windows or nearby tiles if the user is likely to move there next.
Fetch higher fidelity only after zoom, selection, or scrub focus narrows the question.
Evict high-detail slices aggressively when they stop being relevant.

That is what real progressive loading looks like. It is not “load everything eventually.” It is “load only what the current user moment justifies.”

Observability is what keeps the visualization honest

Visualization systems have a dangerous failure mode: they can be wrong and still look successful. The request returns 200. The animation plays. The UI feels smooth. Meanwhile the counts are stale, one category silently vanished after a schema change, or a path smoothing step introduced physically impossible movement.

That is why plain API uptime is not enough.

Measure the data product, not just the endpoint

You should still track the standard operational metrics: latency, error rate, queue depth, database load. But for interactive visualizations, the important signals go further.

You want visibility into:

payload size by endpoint and detail tier
cache hit rate by request class
artifact build duration and failure rate
freshness lag between source ingestion and published revision
percentage of interpolated or low-confidence segments
frontend render time for overview versus detail payloads
memory pressure in long-running sessions

These metrics expose product failures, not just infrastructure failures. A route can be fast and still useless if it returns 6 MB for a filter toggle. A pipeline can be correct and still dangerous if the published revision lags behind the live source by two hours.

Validate derived truth before the UI sees it

You also need backend-side validation that checks whether the exported artifact still resembles reality. That means rules like:

detect impossible jumps by distance and time
compare aggregate totals before and after normalization
flag sharp drops in entity counts after schema updates
verify that known sample entities appear in each resolution tier
alert when overview and detailed slices diverge beyond tolerance

This is the part teams skip because it feels less visible than the animation. It is also the part that saves you from shipping a beautiful lie.

A derived visualization is a data product. Data products need validation, not just rendering.

What to change in a real codebase

If you already have an interactive visualization that feels fragile, do not start with a frontend rewrite. Start by auditing the contract between the source system and the browser.

If the client is still cleaning, grouping, or interpolating raw records, move that work upstream. If requests are unbounded, introduce hard limits around time range, viewport, and detail tier. If the same expensive transformations happen per request, materialize them into artifacts. If cache invalidation still depends on instinct, add explicit revisioning.

Most importantly, stop thinking of the backend as a passive row supplier. In data-heavy visual products, the backend is part of the user experience. It decides whether the page feels immediate or sticky, truthful or misleading, durable or demo-grade.

The rule of thumb is simple: build the backend as if the frontend were a playback client for a versioned data product. Because at scale, that is exactly what it is.

Once you adopt that framing, the priorities stop being fuzzy. Preprocess aggressively. Keep payloads small. Cache by normalized request shape. Load detail progressively. Measure correctness as seriously as latency.

That is how you build interactive data visualizations that still hold up after the launch post, not just during it.

Read the full post on QCode: https://qcode.in/interactive-data-visualizations-need-backend-thinking-too/

Where PgDog Fits in Real Postgres App Architectures

Saqueib Ansari — Mon, 15 Jun 2026 04:56:31 +0000

Postgres routing becomes an application problem much earlier than most teams admit. The database is still the database, but the moment you add replicas, pooling, failover, or even the possibility of sharding, your app stops talking to a single server and starts depending on traffic policy. That policy decides where reads go, what happens inside transactions, how degraded mode works, and whether queue workers behave the same way as HTTP requests.

That is the real case for PgDog. It is not just another Postgres tool with a nicer landing page. It is a sign that some teams have outgrown the fiction that routing can stay tucked inside ORM config forever.

My view is straightforward: PgDog is interesting when you want routing policy to become infrastructure instead of framework behavior. If you mostly need connection pooling, stick with PgBouncer. If reads, replicas, failover, and consistency rules are already leaking into Laravel services, Node repositories, workers, and scripts, a smarter routing layer starts to make architectural sense.

Postgres Routing Is Usually Hidden Technical Debt

A lot of systems reach for database scaling through the wrong mental model. Teams think they are solving a throughput problem in Postgres, when they are actually creating coordination problems in the app.

The first symptom is easy to recognize: too many connections. PHP-FPM workers spike, queue consumers scale out, background jobs open short-lived sessions, and Postgres starts wasting resources on connection churn instead of query execution. That is the point where people add pooling and feel smart for a week.

The second symptom is more dangerous: now there is a primary, one or more replicas, and some rough rule like "reads go here, writes go there." The app starts carrying that rule around. Sometimes it lives in a database abstraction layer. Sometimes it leaks into custom repository code. Sometimes it becomes tribal knowledge like "this endpoint must force primary because the replica lags after checkout."

That is where architecture drifts. Your HTTP app might know how to route a safe read. Your queue worker may not. Your reporting job may bypass the app container entirely and connect directly. Your migration scripts may ignore the same rules. The result is not one database architecture. It is several inconsistent ones wearing the same brand name.

This is why routing matters more than it sounds. Once the application knows too much about topology, every runtime becomes a potential split-brain of behavior.

A cleaner mental model is this:

the app should express business intent
the infrastructure should own topology intent
the boundary between the two should stay explicit

That boundary is exactly what a proxy or routing layer tries to formalize.

What Native Postgres Clients Already Give You, and What They Do Not

Before adding any proxy, it is worth being honest about what the official Postgres stack can already do.

The libpq connection layer supports multiple hosts, target_session_attrs, and load_balance_hosts; the PostgreSQL docs describe how clients can select a primary, prefer a standby, or randomize host choice during connection establishment: libpq connection parameters. That is useful, and many teams underuse it.

If all you need is resilient connection establishment, you can often get farther than expected with plain client features:

host=db-primary,db-replica-1,db-replica-2
port=5432,5432,5432
target_session_attrs=read-write
load_balance_hosts=random
connect_timeout=2

That kind of setup helps with a few important things:

choosing a writable node when several hosts are listed
preferring standby servers for specific read-only clients
failing over without hardcoding a single IP everywhere
reducing dependency on DNS tricks that age badly during incidents

But there is a hard limit here: native client host selection happens at connection time, not at query time. Once a client connects, every subsequent query stays on that backend until the connection is dropped or recycled.

That means client-native features do not solve the actual routing problems most growing apps run into:

splitting reads and writes behind a single endpoint
ensuring workers, web requests, and scripts follow the same rules
handling query-level edge cases like locking reads or write CTEs
centralizing failover and replica traffic policy
creating a path toward sharding without rewriting application connection logic

So the question is not whether Postgres clients can already do failover-aware connections. They can. The question is whether your team needs query-aware routing policy rather than better connection strings.

If the answer is no, do not add a proxy. If the answer is yes, pretending the ORM can absorb all of that cleanly is where bad architecture starts.

Where PgDog Actually Fits

PgDog positions itself as a Postgres connection pooler, load balancer, and sharding proxy. The interesting part is not the label. The interesting part is that its load balancer works by understanding Postgres queries, not just by choosing a backend once and tunneling blindly.

According to the official load-balancer docs, PgDog can inspect incoming SQL, send plain SELECT traffic to replicas, route writes to the primary, and handle important edge cases like SELECT FOR UPDATE and write-producing CTEs: PgDog load balancer overview.

That sounds like a convenience feature until you compare it with what application-managed splitting usually looks like in practice.

In many apps, read/write splitting starts with code like this:

<?php

$connection = $isWrite ? 'pgsql-primary' : 'pgsql-replica';

return DB::connection($connection)
    ->table('orders')
    ->where('user_id', $userId)
    ->latest()
    ->first();

This looks harmless. It is also the beginning of a long maintenance bill.

The bill arrives in stages:

Stage 1: You duplicate routing decisions

A Laravel app grows one set of routing helpers. A Node service grows another. Queue workers do something slightly different. CLI tasks bypass both. Nobody notices because the happy path still works.

Stage 2: Consistency bugs become context-dependent

A user updates billing details and gets redirected to a page that reads from a lagging replica. Support cannot reproduce it reliably because it only happens after writes and only on one request path.

Stage 3: Incident behavior becomes arbitrary

A replica slows down or disappears. One service spills to primary. Another keeps timing out. A reporting worker hammers the only healthy node because its routing logic was copied from an old script.

That is the point where a routing layer becomes less about convenience and more about removing policy from application code.

The strongest case for PgDog is not "our database is huge." It is "our topology policy must be enforced consistently across many clients, and we no longer trust each app runtime to get it right on its own."

PgBouncer Versus PgDog Is a Scope Decision, Not a Hype Decision

Most teams evaluating PgDog should first ask whether they really just need PgBouncer.

PgBouncer is still the cleaner answer for a huge class of systems. If the main pain is connection churn, backend pressure from too many app processes, or the need for lightweight pooling, PgBouncer remains hard to beat. It is focused, proven, and easier to reason about operationally.

Its limits are also well documented. The official PgBouncer feature matrix makes it clear that transaction pooling changes client expectations in important ways. Session-level features like SET/RESET, LISTEN, session advisory locks, and some temp-table behavior do not behave the same way there: PgBouncer features.

That tradeoff is often acceptable. Many web apps can live with it. But it is solving a different class of problem.

Here is the practical comparison.

PgBouncer is the right answer when

your primary pain is too many connections
your topology is still simple
read routing is limited or already explicit in the app
you want the fewest moving parts between app and database
you are not ready to own query-aware proxy behavior

PgDog becomes more compelling when

you want one Postgres endpoint that hides topology from apps
you need read/write routing across more than one runtime
your worker processes and CLI jobs must behave like the web app
failover behavior should be policy-driven, not framework-driven
sharding is realistic enough to influence today’s connection strategy

That last point matters. Even if you are not sharding now, teams often make a mess by baking one-host assumptions deep into every application process. A proxy can buy optionality. The mistake is paying that complexity tax before the problem is real.

My bias is conservative here. Do not add PgDog because it sounds more future-proof. Add it because your current routing behavior is already fragmented enough to justify centralization.

The Real Design Work Is in Failure Modes

Any routing layer looks good when replicas are healthy, lag is low, and traffic is predictable. The decision gets real when the system is under stress.

The PgDog documentation is useful precisely because it exposes some of the awkward reality instead of pretending all SELECT queries are equal. A query may begin with SELECT and still be operationally part of a write path.

Example 1: Locking reads are not replica reads

A common queue pattern looks like this:

BEGIN;

SELECT id, payload
FROM jobs
WHERE status = 'pending'
ORDER BY id
FOR UPDATE SKIP LOCKED
LIMIT 1;

UPDATE jobs
SET status = 'running', started_at = NOW()
WHERE id = $1;

COMMIT;

If your routing model is based on string matching or ORM-level intuition, this is where it breaks. The first statement reads rows, but it also acquires locks and participates directly in a write workflow. PgDog explicitly documents SELECT FOR UPDATE handling because a serious routing layer has to understand that this belongs on primary.

If your app owns this logic in scattered code, you must trust every implementation path to remember the same nuance.

Example 2: A `SELECT` can still write

WITH created AS (
  INSERT INTO audit_log (user_id, action)
  VALUES ($1, 'email_change')
  RETURNING id, user_id
)
SELECT u.id, u.email, c.id AS audit_id
FROM users u
JOIN created c ON c.user_id = u.id
WHERE u.id = c.user_id;

This is exactly the kind of query that defeats simplistic read/write splitting. It reads like a report, but the CTE mutates state. PgDog’s docs call out write CTE inspection because real SQL is more subtle than "verb at the start of the statement."

Replica lag is not a footnote

Even a clever proxy cannot remove asynchronous replication lag. If your system writes on primary and immediately reads dependent state from a replica, you have an application-level consistency decision to make.

That decision should be explicit. Some flows must read from primary after a write:

checkout and payment confirmation
authentication or role changes
inventory and stock reservation
any flow where stale reads create user-visible contradiction

Other flows can often tolerate replica reads:

dashboards
reporting
search result decoration
analytics and internal back-office views

The failure is not using replicas. The failure is pretending every read has the same correctness requirements.

Degraded mode must be designed before the outage

PgDog documents options around whether the primary also serves reads and whether it can temporarily absorb read traffic when replicas are unavailable. That is operationally useful. It also forces a real decision: when replicas fail, do you want stale partial service, slower correct service, or hard failure for some classes of traffic?

There is no universal right answer.

A product team usually needs to decide among patterns like these:

Fail open to primary. Read traffic spills to primary so the app stays functional, but the write node risks overload.
Fail closed for replica-only classes. Some reporting or low-priority endpoints degrade or disable cleanly.
Mixed policy. Critical user flows fall back to primary; nonessential workloads shed load or queue.

That is not just a database choice. It is product behavior under stress. A proxy can enforce the policy, but it cannot invent it for you.

What Full Stack Teams Should Decide Before Inserting a Routing Layer

Adding PgDog without making these decisions first is how teams create a more sophisticated mess.

1. Define which flows require read-your-write guarantees

Do not wave this away with "we use replicas for reads." Map the actual product surfaces. If a user changes something and expects the next screen to reflect it immediately, that path probably cannot rely on asynchronous replicas.

This is especially relevant in Laravel and Node stacks that mix synchronous user requests with async jobs. A queue worker may update state that a web request reads a second later. If that request is replica-routed by default, you have just built inconsistency into the UX.

2. Standardize the endpoint story

If you adopt PgDog, the win is consistency. The app should stop encoding topology in ten places.

A Node service should be able to treat the database as a stable logical endpoint:

import { Pool } from 'pg';

export const pool = new Pool({
  host: process.env.PGDOG_HOST,
  port: 6432,
  database: process.env.DB_NAME,
  user: process.env.DB_USER,
  password: process.env.DB_PASSWORD,
  max: 20,
  connectionTimeoutMillis: 2000,
  idleTimeoutMillis: 30000,
});

export async function loadAccountSummary(accountId) {
  const { rows } = await pool.query(
    `
      select id, email, plan, created_at
      from accounts
      where id = $1
    `,
    [accountId]
  );

  return rows[0] ?? null;
}

That is a better abstraction boundary than wiring separate read and write DSNs into every service and hoping developers always choose correctly.

3. Decide how transactions interact with routing

Manually started transactions should usually stay boring. Once a unit of work spans several statements, the cost of clever routing often outweighs the benefit. Most teams are better off treating explicit transactions as primary-bound unless they have a very specific reason not to.

That is one reason proxy-level routing can be safer than app-level heuristics. The routing rules can remain conservative by default.

4. Be honest about observability

A routing layer with poor observability is a blame machine. If latency jumps, you need to know whether the problem is the proxy, a replica, the primary, a specific query class, or the app pool behavior.

At minimum, teams should expect visibility into:

backend health and ban state
route-level latency and error rate
replica saturation versus primary saturation
spillover behavior during degraded mode
connection pool pressure and queueing

If you cannot observe those, adding a proxy may make incident response worse before it makes architecture better.

5. Treat sharding as a roadmap signal, not a vanity signal

PgDog’s broader promise includes sharding. That matters only if your domain model, tenancy boundaries, or growth path make it plausible. Do not let hypothetical future sharding justify present-day complexity on its own.

But if your team already expects tenant partitioning, regional data placement, or hot-spot isolation to matter later, it is reasonable to prefer an access layer that does not force every client to relearn topology from scratch.

A Sensible Adoption Path

The best way to adopt a smarter routing layer is not with a big-bang cutover.

Start simple:

stabilize connection behavior first
document consistency-sensitive flows
measure read volume that is actually safe to offload
introduce the proxy for one service class or environment
validate degraded-mode behavior before calling it production-ready

A configuration skeleton might look like this:

[general]
load_balancing_strategy = "round_robin"
read_write_split = "exclude_primary"

[[databases]]
name = "app"
role = "primary"
host = "10.0.0.10"
port = 5432

[[databases]]
name = "app"
role = "replica"
host = "10.0.0.11"
port = 5432

[[databases]]
name = "app"
role = "replica"
host = "10.0.0.12"
port = 5432

That is not the hard part. The hard part is validating whether your app semantics match the routing policy you just declared.

A team that has not mapped stale-read tolerance, transaction expectations, and fallback behavior is not deploying a smart proxy. It is outsourcing confusion to infrastructure.

The Practical Decision Rule

PgDog makes sense when Postgres routing has already escaped the database team and started shaping application design. If replicas, failover, and traffic policy are leaking into repositories, workers, and framework config, centralizing those rules is a good architectural move.

If your problem is still mostly connection count, choose PgBouncer and keep the stack smaller. If your problem is now policy consistency across many clients, PgDog is the more serious tool.

The rule of thumb is simple: add a routing layer when topology has become part of product behavior, not just infrastructure trivia. At that point, hiding the problem inside app code is usually the more expensive choice.

Read the full post on QCode: https://qcode.in/pgdog-smarter-postgres-routing-apps/

Eloquent Filtering Gets Messy Fast. Here’s What Holds Up.

Saqueib Ansari — Thu, 11 Jun 2026 07:34:36 +0000

Flexible Eloquent filtering usually dies the same way: a clean index() endpoint turns into fifteen if ($request->filled(...)) branches, three whereHas() chains, a half-working date range, and one emergency orWhere() that quietly breaks tenant isolation.

The fix is not “use a filtering package” or “keep it simple.” The real fix is choosing the right filtering shape for the kind of API you are building. Laravel gives you enough rope here. Eloquent scopes, query objects, package-driven filters, JSON filters, and relationship filters all work. They just stop working at different complexity levels.

My recommendation is straightforward: use local scopes for reusable model-level constraints, use explicit query objects for serious internal APIs, and use a package like Spatie Query Builder only when you actually want request-driven filtering semantics at the HTTP boundary. Do not let controller methods become your query language.

Start with the failure mode, not the syntax

Most teams don’t choose query spaghetti on purpose. They get there incrementally.

A product listing starts with status and category filters. Then search gets added. Then tags. Then "only products with active discounts." Then sorting. Then a partner integration wants created_from and created_to. Then someone asks for ?brand=nike,adidas because that feels natural in a URL.

The code often ends up looking like this:

public function index(Request $request)
{
    $query = Product::query()->where('tenant_id', tenant()->id);

    if ($request->filled('status')) {
        $query->where('status', $request->string('status'));
    }

    if ($request->filled('category')) {
        $query->whereHas('category', function ($q) use ($request) {
            $q->where('slug', $request->string('category'));
        });
    }

    if ($request->filled('search')) {
        $search = $request->string('search');
        $query->where(function ($q) use ($search) {
            $q->where('name', 'like', "%{$search}%")
              ->orWhere('sku', 'like', "%{$search}%");
        });
    }

    if ($request->boolean('discounted')) {
        $query->whereHas('discounts', fn ($q) => $q->where('active', true));
    }

    if ($request->filled('created_from')) {
        $query->whereDate('created_at', '>=', $request->date('created_from'));
    }

    if ($request->filled('created_to')) {
        $query->whereDate('created_at', '<=', $request->date('created_to'));
    }

    return ProductResource::collection(
        $query->latest()->paginate()
    );
}

Nothing in that method is individually outrageous. The problem is architectural. The controller is now doing four jobs:

parsing HTTP input
defining business filtering rules
composing SQL constraints
hiding edge cases nobody wants to touch

That structure is cheap on day one and expensive forever after. It gets harder to test, easier to break, and nearly impossible to reuse from jobs, commands, admin screens, or other services.

The first decision, then, is not which package to install. It is this: is your filtering logic request-shaped, domain-shaped, or both?

Scopes are excellent until they become a language

Laravel’s local scopes are still the cleanest starting point for common reusable constraints. If you have one meaningful business concept, a scope is usually the right answer.

class Product extends Model
{
    #[Scope]
    protected function active(Builder $query): void
    {
        $query->where('status', 'active');
    }

    #[Scope]
    protected function forTenant(Builder $query, int $tenantId): void
    {
        $query->where('tenant_id', $tenantId);
    }

    #[Scope]
    protected function inCategory(Builder $query, string $slug): void
    {
        $query->whereHas('category', fn (Builder $q) => $q->where('slug', $slug));
    }
}

That gives you readable query code:

Product::query()
    ->forTenant($tenantId)
    ->active()
    ->inCategory('laptops')
    ->latest()
    ->paginate();

This is where scopes win:

the condition has a clear domain meaning
you will reuse it in multiple places
it composes cleanly with other builder calls
the parameter shape is small and obvious

This is where scopes start losing:

you need ten optional filters from one request
filters interact with each other
you need branching logic based on user role, feature flags, or API version
you are effectively inventing a mini query DSL

A scope should represent one stable concept, not half a search form. active(), forTenant(), visibleToUser() and withPublishedPosts() are good scopes. filterFromRequest() is a code smell wearing Laravel clothes.

Another common mistake is pushing too much parsing into scopes. If a scope is exploding CSV values, reading request keys, and inferring boolean semantics, you are no longer modeling data access cleanly. You are smuggling transport concerns into the model.

Rule of thumb: if the scope name reads well in a sentence, it probably belongs. If it reads like URL syntax, it probably does not.

Query objects are the best default for serious APIs

Once an endpoint supports multiple optional filters, explicit query objects usually beat every other pattern on maintainability.

Why? Because they separate responsibilities cleanly. The request object validates input. A filter DTO normalizes it. A query object applies database constraints. Your controller becomes boring again, which is what you want.

Here is a practical shape that holds up well:

final readonly class ProductFilters
{
    public function __construct(
        public ?string $status,
        public ?string $category,
        public ?string $search,
        public ?bool $discounted,
        public ?Carbon $createdFrom,
        public ?Carbon $createdTo,
    ) {}

    public static function fromRequest(Request $request): self
    {
        return new self(
            status: $request->string('status')->toString() ?: null,
            category: $request->string('category')->toString() ?: null,
            search: $request->string('search')->toString() ?: null,
            discounted: $request->has('discounted') ? $request->boolean('discounted') : null,
            createdFrom: $request->date('created_from'),
            createdTo: $request->date('created_to'),
        );
    }
}

final class ProductIndexQuery
{
    public function apply(Builder $query, ProductFilters $filters): Builder
    {
        return $query
            ->when($filters->status, fn (Builder $q, string $status) => $q->where('status', $status))
            ->when($filters->category, fn (Builder $q, string $category) =>
                $q->whereHas('category', fn (Builder $categoryQuery) =>
                    $categoryQuery->where('slug', $category)
                )
            )
            ->when($filters->search, function (Builder $q, string $search) {
                $q->where(function (Builder $nested) use ($search) {
                    $nested->where('name', 'like', "%{$search}%")
                        ->orWhere('sku', 'like', "%{$search}%");
                });
            })
            ->when($filters->discounted === true, fn (Builder $q) =>
                $q->whereHas('discounts', fn (Builder $discounts) => $discounts->where('active', true))
            )
            ->when($filters->createdFrom, fn (Builder $q, Carbon $date) => $q->whereDate('created_at', '>=', $date))
            ->when($filters->createdTo, fn (Builder $q, Carbon $date) => $q->whereDate('created_at', '<=', $date));
    }
}

Then your controller becomes small enough to trust:

public function index(ProductIndexRequest $request, ProductIndexQuery $productIndexQuery)
{
    $filters = ProductFilters::fromRequest($request);

    $products = $productIndexQuery
        ->apply(Product::query()->forTenant(tenant()->id), $filters)
        ->latest()
        ->paginate();

    return ProductResource::collection($products);
}

This approach is not flashy. It is better than flashy.

Why query objects hold up better

First, they scale in plain PHP. You can unit test the filter object, feature test the endpoint, and integration test SQL-sensitive paths without pretending the controller is an architecture.

Second, they make unsafe logic easier to see. A loose orWhere() hidden inside nested conditions is much easier to spot in a dedicated query class than inside a 120-line action method.

Third, they are reusable. The same query object can power an API endpoint, an admin table, an export job, or a queued report.

If your team builds internal tools, back-office dashboards, or domain-heavy SaaS APIs, query objects are the most boring sustainable answer. That is a compliment.

Package-based filtering is great at the boundary, not in the core

If your API is intentionally request-driven, Spatie Laravel Query Builder is one of the few packages I would recommend without hand-waving. It gives you a controlled way to expose filtering, sorting, and includes from HTTP query parameters.

That matters because the package forces one discipline most homegrown filtering layers never get right: an explicit allowlist.

use Spatie\QueryBuilder\AllowedFilter;
use Spatie\QueryBuilder\QueryBuilder;

$products = QueryBuilder::for(Product::class)
    ->where('tenant_id', tenant()->id)
    ->allowedFilters([
        AllowedFilter::exact('status'),
        AllowedFilter::scope('active'),
        AllowedFilter::callback('category', function (Builder $query, $value) {
            $query->whereHas('category', fn (Builder $q) => $q->where('slug', $value));
        }),
        AllowedFilter::callback('search', function (Builder $query, $value) {
            $query->where(function (Builder $nested) use ($value) {
                $nested->where('name', 'like', "%{$value}%")
                    ->orWhere('sku', 'like', "%{$value}%");
            });
        }),
    ])
    ->allowedSorts(['created_at', 'price'])
    ->defaultSort('-created_at')
    ->paginate();

For public or partner-facing APIs, that is a strong trade. You get predictable syntax like ?filter[status]=active, explicit surface area, and less controller glue.

But packages like this are not magic. They are best when the request itself is the product. They are less compelling when your filtering rules are mostly domain logic.

Where package filtering wins

public APIs with documented query parameters
index endpoints with many optional filters
teams that want consistency across resources
cases where sort/include/filter conventions should feel uniform

Where it becomes awkward

deeply coupled business rules
nontrivial authorization-driven filtering
multi-step query assembly across services
highly custom search behavior that stops looking like simple request filters

There is also a real footgun here: once the package feels convenient, teams start exposing more surface area than they should. Just because you can allow a field or relation does not mean the endpoint should support it.

The package should not become permission to turn your database schema into your API contract.

Strong recommendation: use package filtering at the HTTP edge, then keep domain-critical query logic behind scopes, query objects, or dedicated callbacks. Let the package route requests. Do not let it design your data access model.

Relationship and JSON filters are where clean code usually rots

This is the part most filtering tutorials underplay. Filtering gets ugly fastest when it crosses relationships or dives into semi-structured JSON columns.

Relationship filters with whereHas() are powerful, but they are also where query performance, readability, and accidental logic leaks start showing up.

$query->whereHas('orders', function (Builder $orders) use ($filters) {
    $orders->where('status', 'paid')
        ->when($filters->paidFrom, fn (Builder $q, Carbon $date) => $q->whereDate('paid_at', '>=', $date))
        ->when($filters->paidTo, fn (Builder $q, Carbon $date) => $q->whereDate('paid_at', '<=', $date));
});

That is fine when it is deliberate. It becomes a mess when every new filter adds another nested closure and nobody reviews the resulting SQL.

JSON filters are even worse when used lazily. Yes, MySQL and PostgreSQL can query JSON. Yes, Eloquent supports JSON path syntax. That does not mean arbitrary user-facing filtering should live there.

$query->where('settings->notifications->email', true)
      ->whereJsonContains('settings->roles', 'editor');

This is acceptable for a few stable flags. It is not a good foundation for a broad filtering API.

Why these filters become maintenance traps

they hide indexing problems until production traffic arrives
they make database portability harder
they encourage schema avoidance instead of schema design
they are easy to compose badly with orWhere and nested conditions
they are harder to explain and document than normal relational filters

If a filter matters enough to be exposed, measured, and depended on, it usually deserves a real column, a real relation, or a real query object path. JSON is a storage format, not a long-term filtering strategy.

The same principle applies to relationship-heavy filters. If your endpoint needs repeated cross-relation filtering, stop sprinkling whereHas() everywhere and give that behavior a name. Hide it behind a scope or query object method that states intent clearly.

The practical selection rule

You do not need one filtering pattern. You need a selection rule that keeps your codebase consistent.

Here is the rule I would use on a Laravel team today:

Use local scopes for small, reusable, domain-named constraints.
Use query objects when an endpoint has several optional filters or meaningful business rules.
Use Spatie Query Builder when the API contract itself is request-driven and you want explicit HTTP filtering semantics.
Use relationship filters deliberately, but hide repeated ones behind named abstractions.
Use JSON filters sparingly, and treat them as a compromise, not a default.

If you already have a spaghetti controller, do not rewrite everything at once. Pull it apart in this order:

move obvious reusable rules into scopes
introduce a dedicated query object for the endpoint
move request parsing into validation or a filter DTO
only then decide whether package-level request filtering actually improves the API

That sequence matters. Teams often install a package first because it feels like progress. In many codebases, the real problem is not missing syntax. It is missing boundaries.

The best Eloquent filtering code is not the most clever. It is the code that still makes sense six months later when someone adds one more filter under deadline pressure. If your controller is becoming a query language, you are already late. Split the responsibilities, keep the HTTP layer honest, and make your filtering strategy explicit before the endpoint turns into something nobody wants to touch.

Read the full post on QCode: https://qcode.in/advanced-eloquent-filtering-without-turning-apis-into-query-spaghetti/

Laravel `Bus::bulk()`: Faster Dispatch, Harder Queue Tradeoffs

Saqueib Ansari — Thu, 11 Jun 2026 04:08:06 +0000

Bus::bulk() is not a fancy alias for dispatch() in a loop, and it is definitely not a lighter Bus::batch(). In Laravel 13, it is a lower-level dispatch optimization for many independent jobs where you care about enqueue efficiency more than workflow semantics. That can be a real win. It can also make a queue system harder to reason about if you adopt it for the wrong workload.

My recommendation is simple: use Bus::bulk() when the jobs are independent, idempotent, and high-volume, and when faster enqueueing actually matters. Do not use it because the method name sounds more scalable. Bulk dispatch changes the shape of failure, observability, queue pressure, and recovery. If your team ignores those tradeoffs, the performance win is usually fake.

Laravel introduced Bus::bulk() in Laravel 13.13, and the official queue documentation is careful about its scope: it is for cases where you do not need batch tracking or callbacks. That line matters more than most people think.

`Bus::bulk()` optimizes transport, not workflow

The first mental model to fix is this: Bus::bulk() is about how jobs are pushed, not about how a larger business operation is managed.

When you call dispatch() repeatedly, Laravel resolves and pushes each job individually. With Bus::bulk(), Laravel groups jobs by their configured connection and queue name, then calls the queue driver's bulk() implementation for each group. That means the behavior is partly framework-level and partly driver-specific.

That distinction matters because not every queue backend gets the same benefit.

The upside depends on the driver

On Redis, bulk dispatch can reduce round-trips and make large fan-out workloads cheaper to enqueue. On the database driver, it can collapse many inserts into a single write operation, which can dramatically reduce application-side dispatch overhead.

But on SQS, the improvement is much less exciting. Laravel's queue driver does not currently convert Bus::bulk() into a single AWS SendMessageBatch operation. It still iterates through jobs internally. So if you expected one bulk network call instead of thousands, that assumption does not hold.

That is the first place teams overstate the benefit. Bus::bulk() is not one universal optimization. It is a facade over different backend strategies.

It is intentionally weaker than batching

The second mental model to fix is that Bus::bulk() is not a workflow primitive. It gives you no built-in batch ID, no progress tracking, no completion callbacks, no cancellation semantics, and no batch-level failure handling.

If your use case needs to answer questions like these, Bus::bulk() is probably the wrong tool:

Has the whole import finished?
Which jobs from this run failed?
When should the next phase start?
Can we cancel the remaining work?
Can the UI show progress for this operation?

Those are Bus::batch() questions, not Bus::bulk() questions.

That difference is why the method can be faster. Laravel is doing less coordination for you.

Where bulk dispatch is genuinely useful

There are real workloads where Bus::bulk() is the right call. The best ones share a few traits: the jobs are independent, there are a lot of them, their payloads are small, and the producer is spending non-trivial time enqueueing work.

Good fit: wide fan-out, independent work

A classic example is search indexing, thumbnail generation, export assembly, cache warming, or syncing records to a third-party system where each item can succeed or fail on its own.

If the jobs do not depend on each other, and there is no single coordinated "all done" step that needs framework support, bulk dispatch is a reasonable optimization.

use App\Jobs\SyncProductToSearch;
use Illuminate\Support\Facades\Bus;

$jobs = Product::query()
    ->where('is_active', true)
    ->select('id')
    ->cursor()
    ->map(fn ($product) => new SyncProductToSearch($product->id));

Bus::bulk($jobs);

The key detail is not the method call. The key detail is that each job only needs a product ID and can run without coordination with the rest.

Best fit: Redis-backed queues

Redis is where Bus::bulk() is easiest to justify. Redis handles high-throughput enqueueing well, and Laravel's implementation can reduce the chatter required to push a large number of jobs.

If you have a command or scheduled task that creates tens of thousands of small jobs, the wall-clock difference between a plain loop and bulk dispatch can be noticeable. This is especially true when the enqueue path itself is part of a latency-sensitive operation, such as an admin action or a scheduled window with a hard runtime budget.

Conditional fit: database queues

The database queue can also benefit because its bulk path can insert many job rows in a single operation. That sounds attractive, and sometimes it is. But this is where teams need discipline.

Database queues are usually fine for modest workloads, but they are not the backend I would choose for sustained high-volume fan-out. If you need Bus::bulk() because you are generating a huge amount of work regularly, that is often a signal to revisit the backend first.

A faster insert path does not remove the downstream cost of a relational database being your queue broker. It just lets you feed that broker harder.

Weak fit: SQS when you expect dramatic throughput gains

SQS remains a good queue backend overall, but Bus::bulk() is not a transport miracle there. If your main reason to adopt it is dispatch-time performance, benchmark first. You may still like the cleaner API, but the performance story is weaker than on Redis or the database driver.

That matters because engineering teams tend to cargo-cult queue APIs. One developer sees a new method, assumes it is categorically faster, and starts replacing loops everywhere. That is not engineering. That is styling.

The hidden costs show up after dispatch, not during it

The biggest trap with Bus::bulk() is that it looks like a producer-side optimization, so people evaluate it only by enqueue timing. In practice, the harder problems show up later.

Queue pressure gets worse faster

Bulk dispatch makes it easier to create a backlog spike than to drain one. That is the trade.

If your code can now enqueue 50,000 or 200,000 jobs in a burst, you have changed the operational shape of the system even if each job is unchanged. Redis memory can jump. The jobs table can absorb a large write burst. Horizon dashboards can flatten into one huge queue mountain. More importantly, shared workers can become busy with bulk work while user-facing jobs wait.

That means queue topology matters more once you adopt bulk dispatch.

If you bulk-dispatch low-priority work onto the same queue as password emails, checkout webhooks, or billing callbacks, you are asking for user-visible regressions. The producer got faster. The system got less fair.

A safer design usually means at least one of these:

a dedicated queue for the bulk workload
dedicated worker pools for that queue
capped concurrency if the jobs hit a fragile dependency
chunked dispatch instead of one giant burst

Observability becomes something you have to rebuild

With plain bulk dispatch, Laravel knows about individual jobs. It does not know much about the logical run that produced them unless you encode that yourself.

That becomes painful the first time someone asks, "Which product reindex run caused these failures?" or "Did yesterday's CRM sync complete?"

Bus::batch() gives you a first-class unit of work. Bus::bulk() gives you raw job fan-out. If you want run-level visibility, you need to create it.

The practical fix is to stamp correlation metadata into every job and log around that metadata consistently.

use App\Jobs\PushInvoiceToCrm;
use Illuminate\Support\Facades\Bus;
use Illuminate\Support\Str;

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

$jobs = $invoices->map(
    fn ($invoice) => new PushInvoiceToCrm(
        invoiceId: $invoice->id,
        runId: $runId,
        triggeredBy: auth()->id(),
    )
);

Bus::bulk($jobs);

That runId should then flow through logs, failed job records, metrics, and any operational dashboards you care about. Without that, bulk workloads are much harder to debug than teams expect.

Failure becomes fragmented by design

With Bus::bulk(), partial success is not an edge case. It is normal.

A queue worker can crash after processing some jobs. A deployment can restart workers mid-run. Downstream APIs can start rate limiting halfway through. A subset of jobs can serialize or deserialize differently due to stale assumptions in the payload. Some jobs can succeed while others fail and retry repeatedly.

That is not a flaw in Bus::bulk(). It is the consequence of choosing an independent-job model. But your application code needs to be honest about it.

If the business operation actually requires coordinated all-or-nothing behavior, bulk dispatch is already the wrong abstraction.

The real production requirement is idempotency

If you adopt Bus::bulk() without strong idempotency, you are building a queue system that only works on good days.

This is the point most teams underinvest in. They focus on the dispatch API and ignore the job contract.

What idempotency means here

An idempotent job can run more than once without causing broken state, duplicate external effects, or corrupted accounting. That does not mean the code is literally side-effect free. It means the side effects are safe to repeat or safely de-duplicated.

With bulk dispatch, idempotency matters even more because large bursts multiply the odds that you will eventually see duplicates, retries, replay scenarios, or ambiguous outcomes.

A bad bulk job

A bad bulk job assumes:

it will only run once
it will run after all related records are fully committed
no other worker will race it
no retry will hit the same side effect twice
the external API will always accept a duplicate write cleanly

That job may appear fine in staging. It will not stay fine in production.

A better bulk job pattern

A safer job keeps its payload small, reads fresh state inside handle(), and uses an idempotent persistence pattern around the side effect.

use App\Models\Invoice;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Queue\Queueable;
use Illuminate\Support\Facades\DB;

class PushInvoiceToCrm implements ShouldQueue
{
    use Queueable;

    public function __construct(
        public int $invoiceId,
        public string $runId,
        public ?int $triggeredBy = null,
    ) {}

    public function handle(CrmClient $crm): void
    {
        $invoice = Invoice::query()->findOrFail($this->invoiceId);

        DB::transaction(function () use ($invoice, $crm) {
            $existing = DB::table('crm_sync_log')
                ->where('invoice_id', $invoice->id)
                ->where('run_id', $this->runId)
                ->first();

            if ($existing && $existing->status === 'synced') {
                return;
            }

            $remoteId = $crm->upsertInvoice(
                idempotencyKey: "invoice:{$invoice->id}:run:{$this->runId}",
                payload: [
                    'number' => $invoice->number,
                    'total' => $invoice->total,
                    'currency' => $invoice->currency,
                ],
            );

            DB::table('crm_sync_log')->updateOrInsert(
                [
                    'invoice_id' => $invoice->id,
                    'run_id' => $this->runId,
                ],
                [
                    'remote_id' => $remoteId,
                    'status' => 'synced',
                    'triggered_by' => $this->triggeredBy,
                    'updated_at' => now(),
                    'created_at' => now(),
                ]
            );
        });
    }
}

This job is not fancy. That is a good sign. It loads current state, uses a stable idempotency key, and records whether the logical unit of work already completed for the given run.

That pattern is much more valuable than shaving a few milliseconds off dispatch.

Payload discipline matters too

Bulk-dispatched jobs should usually carry IDs and metadata, not fat object graphs. Passing hydrated models is convenient, but it makes queue payloads heavier and makes serialization behavior more brittle.

This matters more at scale. A queue system that handles 500 small payloads may behave very differently when asked to store 100,000 large serialized jobs. Bulk dispatch makes that mistake more expensive, not less.

How to keep bulk dispatch from overwhelming the system

The safest pattern with Bus::bulk() is usually not "collect everything and fire once." It is chunked bulk dispatch with queue isolation.

Prefer chunked fan-out over one giant submission

Chunking gives you three concrete benefits:

It bounds memory usage in the producer.
It reduces the blast radius of a dispatch-time failure.
It lets the workers start draining while the producer is still generating more work.

That is often a much healthier operating pattern than one massive enqueue burst.

use App\Jobs\GenerateStatementPdf;
use App\Models\Customer;
use Illuminate\Support\Facades\Bus;

Customer::query()
    ->where('needs_statement', true)
    ->select('id')
    ->chunkById(1000, function ($customers) {
        $jobs = $customers->map(
            fn ($customer) => (new GenerateStatementPdf($customer->id))
                ->onQueue('statements')
        );

        Bus::bulk($jobs);
    });

This pattern is operationally boring, which is what you want. It avoids building one enormous in-memory collection, and it gives your workers a steadier stream of work instead of a queue cliff.

Isolate bulk queues from user-facing queues

If the workload is high-volume, do not share a queue with latency-sensitive jobs unless you have a very good reason.

This is one of the easiest queue design mistakes to make in Laravel because the framework makes adding jobs so convenient. A bulk reindex run should not be able to delay password reset mail, checkout events, or subscription webhooks.

Separate queue names are cheap. Worker isolation is cheaper than production incidents.

Align concurrency to the dependency, not the CPU

A common failure mode is scaling workers based on server capacity while ignoring what the jobs actually hit.

If the jobs call an external API with rate limits, increasing workers may only turn a manageable queue into a retry storm. If the jobs write to the same hot tables, more workers may just increase lock contention. If the jobs hit S3 or image processing, the bottleneck may sit in network bandwidth or disk I/O instead of PHP execution.

Bulk dispatch forces this conversation because it can feed workers much faster. That is useful only when the rest of the pipeline is ready.

Watch transaction boundaries

Another subtle risk is dispatch timing relative to database commits. If you bulk-create jobs based on records that are still being written inside a transaction, workers may begin processing before the expected state is visible.

That is not unique to Bus::bulk(), but bulk dispatch makes the failure mode wider because many jobs can be enqueued at once.

The practical rule is the same one good queue systems always follow: dispatch jobs after the state they depend on is durably committed, or use after-commit semantics where appropriate.

What to benchmark before adopting it broadly

A lot of queue articles stop at "bulk is faster." That is not enough. The only benchmark that matters is one that measures both enqueue cost and downstream impact.

At minimum, compare a loop of dispatch() calls against Bus::bulk() using the same workload and the same backend. Measure:

time spent enqueueing
time until the first job starts
total drain time for the workload
queue depth peak during the run
failed jobs and retry volume
Redis memory or database pressure during the spike
whether other queues got slower while the bulk run was active

If you use Horizon, watch the whole system, not just the bulk queue. It is very common to cut producer time in half and quietly make unrelated queues worse.

Also benchmark with realistic payloads. Small fake jobs can hide the real cost of serialization, storage, and downstream calls.

When to use `Bus::bulk()`, `Bus::batch()`, or plain dispatch

The cleanest decision rule looks like this:

Use `Bus::bulk()` when

jobs are independent
you have a lot of them
dispatch overhead is measurable
you do not need framework-level progress or callbacks
each job is idempotent and safely retryable
you are prepared to add your own correlation and observability

Use `Bus::batch()` when

the workload is one logical operation
you need progress tracking or completion callbacks
you need a first-class batch ID
cancellation and failure coordination matter
the UI or ops team needs batch-level visibility

Use plain `dispatch()` in a loop when

the number of jobs is modest
clarity beats micro-optimization
the enqueue path is not a bottleneck
you do not want driver-specific bulk behavior to shape the design

That last point is worth underlining. A lot of teams should stay with plain dispatch() longer than they think. Simpler code is often the better production choice when queue volume is still moderate.

Bus::bulk() earns its place when the producer is demonstrably expensive, not when the method name sounds more scalable.

The practical takeaway

Bus::bulk() is useful, but it is a sharp tool. It helps most when you already have a disciplined queue design: small payloads, idempotent jobs, isolated queues, realistic worker concurrency, and decent observability.

If you do not have those things, bulk dispatch mostly gives you the ability to create bigger problems faster.

So the production rule is this: bulk-dispatch only independent jobs, bulk-dispatch them in chunks, and never treat enqueue speed as the only success metric. If you need coordinated workflow semantics, use Bus::batch(). If you just need raw fan-out efficiency and the jobs are built correctly, Bus::bulk() is the right tool.

Read the full post on QCode: https://qcode.in/laravel-bus-bulk-when-bulk-dispatch-helps-hurts/

Typed Eloquent boundaries without building a second ORM

Saqueib Ansari — Mon, 08 Jun 2026 06:10:35 +0000

Most Laravel teams do not need to "fix" Eloquent. They need to stop letting raw model state leak too far into code that makes real business decisions.

That is the practical version of this debate.

Typed objects around Eloquent can be a big improvement, but only when they are used as boundaries. If you push the pattern too far, you end up with a second object model shadowing the first one. At that point you are not improving Laravel. You are building a parallel ORM that adds mapping code, cognitive load, and friction on every change.

So the right question is not, "Should we replace Eloquent with typed objects?" The right question is, where does untyped Eloquent stop being cheap?

Once you frame it that way, the migration path becomes much clearer. Keep Eloquent where it is good at persistence, hydration, scopes, relationships, and query composition. Introduce typed objects where the shape is messy, the values carry business meaning, or invalid combinations are too easy to represent.

That is the version that pays off.

The Core Recommendation

If you only remember one thing from this article, make it this: add typed boundaries around unstable or meaningful data, not around every model.

That usually means one of four cases:

a JSON column that multiple parts of the app interpret differently
domain values like money, status, addresses, or billing configuration
data crossing from Eloquent into services, jobs, or integrations
code paths where stringly typed state has already caused confusion or bugs

Everything else should be guilty until proven useful.

This is where a lot of teams go wrong. They see a good example of typed objects and immediately generalize it into an architecture rule. Then every model gets a FooData, FooView, FooState, FooRecord, and FooMapper. The app becomes more "designed" and less understandable.

A Laravel codebase does not get better because it has more classes. It gets better because responsibility becomes clearer.

Why Raw Eloquent Starts Hurting

Eloquent is deliberately permissive. That is one reason Laravel teams ship quickly with it. Attributes can be strings, arrays, JSON blobs, cast values, nullable timestamps, or whatever the database currently allows. Early on, that flexibility feels productive.

The problems show up later, usually in boring places.

A field that started as a simple JSON blob becomes important to billing or permissions. A string column that once held two status values now holds six, and one of them is only valid after a webhook arrives. A settings array is read by a controller, a queue job, an action class, and an API transformer, and each one assumes slightly different defaults.

At that point, Eloquent is not the problem by itself. The problem is that storage shape and domain meaning are now fused together.

The hidden cost of array-shaped logic

This is the code smell you want to notice early:

if (($user->settings['plan'] ?? 'free') === 'pro' &&
    ($user->settings['trial_ends_at'] ?? null) !== null &&
    ($user->settings['cancel_at_period_end'] ?? false) === false) {
    // ...
}

That line is doing at least three jobs:

reading a storage format
applying defaults
expressing business intent

It is also impossible to scan quickly. The logic is not hard, but the shape is noisy. If five different parts of the system do their own version of that, you now have a maintenance problem.

The deeper issue is not style. It is semantic drift. One place defaults plan to free. Another assumes missing plan is invalid. One path reads trial_ends_at as nullable string. Another parses a Carbon instance. Eventually two code paths disagree silently.

Typed boundaries help because they centralize interpretation.

Strings are cheap until they are not

Laravel developers are used to raw strings for status fields, provider names, feature flags, event types, and mode switches. That is fine while the meaning is obvious and local.

It stops being fine when the value crosses process boundaries or starts controlling workflow.

A raw status column with values like draft, published, archived, and scheduled does not look dangerous. But once those values drive API responses, jobs, admin actions, and permissions, the weakness becomes obvious:

typos are legal until runtime
invalid transitions are hard to guard consistently
IDE refactors cannot protect you
business rules stay smeared across call sites

A typed object, enum, or small value object is not about code aesthetics here. It is about making the set of legal states more explicit.

What a Good Typed Boundary Looks Like

A good typed boundary does one or more of these things:

normalizes messy incoming storage shape
enforces a small invariant
exposes behavior that belongs with the value
gives the rest of the app a predictable interface

It does not exist just to mirror columns one-to-one.

That distinction matters more than people admit.

Example 1: Typed settings around a JSON column

A JSON column is one of the clearest places to introduce a typed object because the raw database shape tends to spread quickly.

Imagine a users.subscription_settings column. The naive version often starts as this:

$user->subscription_settings = [
    'plan' => 'pro',
    'cancel_at_period_end' => false,
    'trial_ends_at' => '2026-06-30T00:00:00Z',
];

That looks harmless. The trouble starts when those keys are read in ten places with ten slightly different assumptions.

A better boundary is a typed object returned from a cast.

<?php

declare(strict_types=1);

namespace App\Domain\Billing;

final readonly class SubscriptionSettings
{
    public function __construct(
        public string $plan,
        public bool $cancelAtPeriodEnd,
        public ?\DateTimeImmutable $trialEndsAt,
    ) {}

    public static function fromArray(array $data): self
    {
        return new self(
            plan: (string) ($data['plan'] ?? 'free'),
            cancelAtPeriodEnd: (bool) ($data['cancel_at_period_end'] ?? false),
            trialEndsAt: isset($data['trial_ends_at'])
                ? new \DateTimeImmutable((string) $data['trial_ends_at'])
                : null,
        );
    }

    public function toArray(): array
    {
        return [
            'plan' => $this->plan,
            'cancel_at_period_end' => $this->cancelAtPeriodEnd,
            'trial_ends_at' => $this->trialEndsAt?->format(DATE_ATOM),
        ];
    }

    public function isOnTrial(): bool
    {
        return $this->trialEndsAt !== null && $this->trialEndsAt > new \DateTimeImmutable();
    }

    public function isEnterprise(): bool
    {
        return $this->plan === 'enterprise';
    }
}

Then wire it into Eloquent with a cast:

<?php

declare(strict_types=1);

namespace App\Casts;

use App\Domain\Billing\SubscriptionSettings;
use Illuminate\Contracts\Database\Eloquent\CastsAttributes;
use Illuminate\Database\Eloquent\Model;

final class SubscriptionSettingsCast implements CastsAttributes
{
    public function get(Model $model, string $key, mixed $value, array $attributes): SubscriptionSettings
    {
        $decoded = json_decode($value ?: '{}', true, flags: JSON_THROW_ON_ERROR);

        return SubscriptionSettings::fromArray($decoded);
    }

    public function set(Model $model, string $key, mixed $value, array $attributes): string
    {
        if (! $value instanceof SubscriptionSettings) {
            throw new \InvalidArgumentException('Expected SubscriptionSettings instance.');
        }

        return json_encode($value->toArray(), JSON_THROW_ON_ERROR);
    }
}

And in the model:

protected function casts(): array
{
    return [
        'subscription_settings' => \App\Casts\SubscriptionSettingsCast::class,
    ];
}

This is a strong pattern because it improves the code around the model without pretending Eloquent is gone. The storage remains JSON. The domain-facing interface becomes stable.

Why this boundary is worth it

This boundary is useful because it removes repeated interpretation from the rest of the app.

Before:

every caller knows the raw keys
every caller applies its own defaults
every caller decides how to parse dates
changing the payload shape is risky

After:

one place owns the mapping
the type documents the meaning
behavior lives with the data
the rest of the app deals with a real object

That is a real gain, not architecture theater.

Where Teams Accidentally Build a Parallel ORM

The failure mode is predictable: a good local pattern gets promoted into a universal rule.

Someone introduces typed objects for a messy JSON field. It works well. Then the team starts wrapping every model attribute in custom classes, every query result in DTOs, and every relationship traversal in mirrored object graphs.

Now you have two representations of the same thing:

the Eloquent model Laravel uses for persistence and relationships
the typed object system your application uses for everything else

That sounds disciplined. In practice, it often means every change hits five layers.

The one-to-one wrapper trap

This is the pattern to be suspicious of:

final readonly class PostData
{
    public function __construct(
        public int $id,
        public string $title,
        public string $body,
        public ?string $publishedAt,
    ) {}
}

If that class has no invariant, no normalization, no behavior, and no boundary value, it is probably dead weight.

A one-to-one wrapper around database columns does not automatically create better design. It usually just moves the same ambiguity into another file.

Mapper explosion is a tax, not a virtue

Once every model gets a wrapper, mappers multiply fast:

model to data object
data object to API resource
request payload to domain object
domain object back to model

Some of that is necessary in large systems. Most of it is not necessary in a typical Laravel app.

The discipline you want is selective conversion, not universal conversion.

Relationship mirroring is usually the breaking point

The fastest way to overcomplicate this approach is trying to re-model Eloquent relationships as a separate typed graph.

Laravel already gives you a lot here: eager loading, lazy loading, constraints, aggregate helpers, polymorphic relations, scopes, pivot behavior, and query composition. Rebuilding all of that behind a second object model is rarely worth it.

If you end up with TypedUser -> TypedTeam -> TypedSubscription -> TypedPlan, ask yourself whether the code got more explicit or just more indirect.

Most of the time, typed boundaries should sit at meaningful seams, not replace the entire navigation model of the app.

A Better Way to Think About Boundaries in Laravel

Instead of asking "which models should be typed?", ask which movements of data deserve a stronger contract.

That usually leads to better decisions.

Boundary 1: Storage to domain meaning

This is the cast example. A raw database representation becomes a typed value with a stable API.

Good fit:

JSON columns n- compound values stored across loose fields
normalized status or settings logic

Boundary 2: Domain to external integration

When Eloquent data is sent to Stripe, OpenAI, Slack, or an internal service, raw model state often leaks too much incidental shape.

A typed object or dedicated payload object is useful here because it decouples your internal persistence model from the integration contract.

For example:

final readonly class InvoicePayload
{
    public function __construct(
        public string $customerEmail,
        public int $amountInCents,
        public string $currency,
        public string $description,
    ) {}

    public static function fromOrder(Order $order): self
    {
        return new self(
            customerEmail: $order->customer_email,
            amountInCents: $order->total->amount(),
            currency: $order->total->currency(),
            description: "Order #{$order->id}",
        );
    }
}

That boundary matters because integrations are expensive places to be sloppy.

Boundary 3: Eloquent to async work

Jobs, events, and queued actions are another strong seam.

Passing full models through queues can be fine, but it can also create subtle coupling to later database state. Sometimes the job should see whatever the model looks like when it runs. Sometimes it should operate on a precise snapshot.

A typed payload object is often safer when:

the job must preserve exact values from dispatch time
only a subset of model data is relevant
you want the job contract to stay stable as the model evolves

This is not a rule against queueing models. It is a reminder that async boundaries magnify ambiguity.

Incremental Adoption That Does Not Blow Up the Codebase

The right migration path is boring on purpose. That is a good sign.

Do not start with a grand refactor. Start with a recurring pain point and tighten just that boundary.

Step 1: Find repeated interpretation

Look for code patterns like these:

repeated ['some_key'] ?? default access
status strings checked in multiple services
date parsing scattered across call sites
the same normalization logic repeated in requests, jobs, and resources

That is your signal that the raw shape has escaped too far.

Step 2: Introduce one typed object

Pick one value with clear meaning. Do not start with the most central model in the app. Start with something painful but contained.

Good first targets:

shipping or billing address
subscription settings
money totals
workflow state object
external API payloads

The first win should be easy to explain: we used to interpret this shape everywhere; now we interpret it once.

Step 3: Put behavior with the value

A typed boundary that only carries properties is better than raw arrays, but the larger payoff comes when it exposes behavior.

Bad:

if ($order->shipping_address->country === 'IN' && $order->shipping_address->postalCode !== '') {
    // ...
}

Better:

if ($order->shipping_address->isDomesticFor('IN') && $order->shipping_address->hasPostalCode()) {
    // ...
}

That is not about hiding all detail. It is about letting the type speak in domain language.

Step 4: Stop when the boundary is doing its job

This is where restraint matters.

Once a typed object solves the ambiguity, do not automatically expand the pattern outward. You do not need a typed object for every neighboring value just because one boundary worked well.

Architecture gets bloated when people confuse a good pattern with a universal pattern.

Example 2: A Shipping Address Object That Actually Earns Its Keep

A shipping address is a good example because it often starts simple and becomes annoying over time.

You begin with a JSON blob or a handful of nullable fields. Then checkout logic, tax calculations, delivery rules, admin review, and label generation all want slightly different things from it.

A typed object helps because address data has both shape and behavior.

<?php

declare(strict_types=1);

namespace App\Domain\Orders;

final readonly class ShippingAddress
{
    public function __construct(
        public string $line1,
        public ?string $line2,
        public string $city,
        public string $state,
        public string $postalCode,
        public string $country,
    ) {}

    public static function fromArray(array $data): self
    {
        return new self(
            line1: trim((string) ($data['line_1'] ?? '')),
            line2: isset($data['line_2']) ? trim((string) $data['line_2']) : null,
            city: trim((string) ($data['city'] ?? '')),
            state: trim((string) ($data['state'] ?? '')),
            postalCode: trim((string) ($data['postal_code'] ?? $data['postcode'] ?? '')),
            country: strtoupper(trim((string) ($data['country'] ?? ''))),
        );
    }

    public function toArray(): array
    {
        return [
            'line_1' => $this->line1,
            'line_2' => $this->line2,
            'city' => $this->city,
            'state' => $this->state,
            'postal_code' => $this->postalCode,
            'country' => $this->country,
        ];
    }

    public function isDomesticFor(string $countryCode): bool
    {
        return $this->country === strtoupper($countryCode);
    }

    public function hasPostalCode(): bool
    {
        return $this->postalCode !== '';
    }

    public function formattedSingleLine(): string
    {
        return collect([
            $this->line1,
            $this->line2,
            $this->city,
            $this->state,
            $this->postalCode,
            $this->country,
        ])->filter()->implode(', ');
    }
}

This object is doing real work:

normalizing postcode vs postal_code
normalizing country casing
centralizing formatting
exposing behavior useful to rules and integrations

That is what "typed object around Eloquent" should usually mean in a Laravel app. Not total abstraction. Just a sharper seam.

Failure Modes to Watch For

Most architectural patterns do not fail because the first example is bad. They fail because teams stop being selective.

Failure mode 1: treating all data as domain data

Some data is just persistence detail. Audit columns, import metadata, view counters, internal sort positions, and similar fields often do not need domain objects.

If there is no meaningful behavior or invariant, raw Eloquent may be the correct level of abstraction.

Failure mode 2: mixing internal types with API shape

Your internal object and your API resource are not the same thing by default.

A domain object should express meaning. An API response should express what clients need. Sometimes those line up. Often they do not.

When you merge them too early, the domain object ends up carrying serialization quirks, presentation formatting, and backwards compatibility baggage.

Keep that split clean unless you have a strong reason not to.

Failure mode 3: assuming stronger types remove validation needs

Typed objects do not replace validation. They complement it.

Requests still need input validation. Database constraints still matter. Integration boundaries still need defensive checks.

A typed object improves how your application represents a value after it enters the system. It does not magically guarantee the outside world behaved.

Failure mode 4: hiding too much behind tiny methods

There is also an opposite failure mode: turning every property read into a method call just to sound domain-driven.

If a type becomes a wall of trivial wrappers, readability suffers again.

The rule is simple: extract behavior when the behavior is meaningful, repeated, or protection-worthy. Do not hide obvious data behind noise.

Testing Strategy That Matches This Pattern

One benefit of typed boundaries is that they make testing narrower and more honest.

You do not need to boot a full Laravel feature test to verify every bit of interpretation logic.

Test the object directly for:

normalization rules
derived behavior
invalid state rejection if applicable
serialization back to storage shape

Then add a smaller number of model-level tests to verify the cast integration actually works.

That split is useful because it keeps your business semantics testable without pushing everything through Eloquent every time.

The trap to avoid is writing fragile tests that just reassert the implementation line by line. Test the boundary contract, not the existence of getters.

The Practical Decision Rule

Use typed Eloquent objects when they remove ambiguity, centralize interpretation, or protect meaningful business rules.

Do not use them as a blanket ideology.

If a raw model attribute is read in one place, has obvious meaning, and carries no important invariant, leave it alone. If a value is messy, reused, or expensive to misunderstand, give it a proper type.

That is the sweet spot.

Laravel does not need to be purified away from Eloquent. It needs cleaner seams between storage concerns and application meaning. Typed boundaries are excellent at that when used carefully. They are expensive when used everywhere.

So if you are introducing this pattern into an existing app, start small. Pick one ugly boundary. Add one typed object. Move one cluster of logic into it. Watch whether the surrounding code gets simpler.

If it does, keep going where the same pain exists.

If it does not, stop before your migration story turns into an accidental rewrite.

The goal is not to make the codebase feel more abstract. The goal is to make invalid states harder, business logic clearer, and Eloquent less noisy where it actually matters.

Read the full post on QCode: https://qcode.in/typed-eloquent-boundaries-without-rewriting-your-laravel-app/

Drag-and-drop ordering in Laravel admin tools gets messy faster than it looks

Saqueib Ansari — Fri, 05 Jun 2026 12:03:55 +0000

Most admin drag-and-drop ordering features are sold as a UI improvement. In practice, they are usually a data-model decision disguised as polish.

I learned this the hard way. The first version always feels cheap: add a drag handle, send an array of IDs, update a position column, done. Everyone feels productive because the interaction is visible and satisfying. Then the real questions arrive. What exactly is being ordered? What happens when two admins reorder at once? Is the order global or scoped? Does page 2 still mean anything after a reorder? Can support explain who changed it and why? Can a keyboard user do the same job without fighting the interface?

That is the hidden cost. Drag-and-drop ordering is not hard because reindexing integers is hard. It is hard because the feature forces your product to define truth about sequence, scope, and intent.

My rule now is simple: if the order is not a first-class business concept, do not make the list draggable. In Laravel admin tools especially, explicit ranking, pinning, or scoped “move” actions usually age better than freeform sorting.

The first mistake is usually conceptual, not technical

Most teams start by asking how to implement sortable rows. That is already too late. The real first question is: what exact collection owns this order?

If the answer is vague, the database is about to start lying.

Take a typical admin screen for articles, users, tickets, or products. An operator sees a table, maybe filtered by status or search, and drags one row above another. The UI implies they are reordering the list they can see. But what is that list, exactly?

Is it:

all records in the table
records within one tenant
records within one category
records matching the current filter
records on the current page only
records inside a hand-curated editorial collection

Those are completely different contracts. Most “quick” drag-and-drop implementations store one global position and defer the hard part. That works right up until the interface shows a partial slice of the data and the user assumes the slice is the truth.

That is the failure mode I now look for first. A record that appears first in a filtered list may be position 42 in the actual stored sequence. If the user drags it lower in that filtered view, they think they changed local order. The system may actually rewrite a much broader global order they never meant to touch.

This is why I do not treat order as a presentation concern anymore. It is domain state.

Order only behaves well when the scope is explicit

There are cases where manual order is absolutely legitimate:

homepage hero cards
navigation menus
onboarding steps
playlist items
kanban cards within a column
custom fields within a form builder

In each of those cases, the ordered set has a clear parent. The order means something to the business. Users understand that meaning. The list is usually small enough to reason about as a whole.

That is the shape you want.

A good rule is that a reorderable record should be able to answer this sentence cleanly:

I am item X at position Y within collection Z.

If your system cannot fill in Z precisely, you probably do not have a reorderable domain. You have a sortable UI illusion.

Laravel makes the happy path dangerously cheap

Laravel is excellent at getting CRUD features over the line. That is normally a strength. With drag-and-drop ordering, it can hide the real cost.

The easy version looks like this:

Route::post('/admin/articles/reorder', function (Request $request) {
    foreach ($request->input('ids', []) as $index => $id) {
        Article::whereKey($id)->update(['position' => $index + 1]);
    }

    return response()->noContent();
});

That code is short, readable, and wrong for most non-trivial admin systems.

It assumes all of the following without stating any of them:

the client sent a complete authoritative list
the list belongs to one stable scope
no one else changed that scope concurrently
the current page is the whole sequence that matters
overwriting every position is acceptable
auditability does not matter

That is too much unstated product logic for one loop.

A safer baseline starts in the schema

If order matters, define it as scoped order in the database itself.

Schema::create('playlist_items', function (Blueprint $table) {
    $table->id();
    $table->foreignId('playlist_id')->constrained()->cascadeOnDelete();
    $table->foreignId('track_id')->constrained()->cascadeOnDelete();
    $table->unsignedInteger('position');
    $table->unsignedInteger('order_version')->default(1);
    $table->timestamps();

    $table->unique(['playlist_id', 'position']);
    $table->unique(['playlist_id', 'track_id']);
    $table->index(['playlist_id', 'position']);
});

That schema says something valuable:

position is not globally meaningful
collisions are prevented within the parent scope
reads have a stable index
concurrency can be reasoned about via order_version

That already eliminates a surprising amount of ambiguity.

The write path should validate the scope it mutates

When I do accept full-list reorder requests, I want the server to prove that the payload actually matches the current scoped list.

final class ReorderPlaylistItems
{
    public function handle(Playlist $playlist, array $orderedIds, User $actor): void
    {
        DB::transaction(function () use ($playlist, $orderedIds, $actor) {
            $items = $playlist->items()
                ->select(['id', 'position'])
                ->lockForUpdate()
                ->orderBy('position')
                ->get();

            $expectedIds = $items->pluck('id')->values()->all();
            $incomingIds = array_values($orderedIds);

            if ($incomingIds !== $expectedIds && array_diff($expectedIds, $incomingIds) !== []) {
                throw ValidationException::withMessages([
                    'items' => 'Reorder payload does not match the current playlist scope.',
                ]);
            }

            foreach ($incomingIds as $index => $id) {
                $playlist->items()->whereKey($id)->update([
                    'position' => $index + 1,
                ]);
            }

            $playlist->increment('order_version');

            activity()
                ->performedOn($playlist)
                ->causedBy($actor)
                ->withProperties([
                    'before' => $items->map(fn ($item) => ['id' => $item->id, 'position' => $item->position])->all(),
                    'after' => collect($incomingIds)->values()->map(fn ($id, $index) => ['id' => $id, 'position' => $index + 1])->all(),
                ])
                ->log('playlist_reordered');
        });
    }
}

Even here, notice how much work sits around the actual reindexing:

row locking
payload validation
scope validation
version bumping
auditing

That is the hidden cost in code form. The reorder logic is the easy part. Everything around it is the feature.

Laravel’s database and pagination docs are relevant here because they make it very easy to work with ordered and partial result sets, but they do not remove the product-level decisions: https://laravel.com/docs/12.x/database and https://laravel.com/docs/12.x/pagination.

Concurrency is where “simple sorting” stops being simple

A reorderable list is fine in a single-user demo. Admin systems are rarely single-user systems.

The first time two operators touch the same collection, your assumptions get tested. One person moves item A to the top. Another moves item C below item D. Both actions are reasonable. Both can produce valid writes. One of them is still going to feel like the application ignored their intent.

That means the feature needs a concurrency story, not just a controller action.

Last-write-wins is simple and usually bad

The default implicit behavior in many apps is last-write-wins. Whoever submits second overwrites the first order silently.

That is easy to implement and terrible for operator trust. It creates three support problems:

users think the interface is glitchy
admins cannot explain why order changed unexpectedly
auditing shows a valid write but not the lost intent behind it

For non-trivial admin workflows, silent overwrite is not a neutral choice. It is product debt.

Revision-based rejection is boring and correct

The most honest pattern I have used is optimistic concurrency with an order version.

The client receives the current order_version with the list. The reorder request sends it back. If the stored version changed, the server rejects with 409 Conflict and the UI reloads.

final class ReorderPlaylistRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            'ordered_ids' => ['required', 'array'],
            'ordered_ids.*' => ['integer'],
            'version' => ['required', 'integer'],
        ];
    }
}

final class ReorderPlaylistController
{
    public function __invoke(
        ReorderPlaylistRequest $request,
        Playlist $playlist,
        ReorderPlaylistItems $service
    ) {
        abort_if($request->integer('version') !== $playlist->order_version, 409, 'This list changed. Reload and try again.');

        $service->handle($playlist, $request->integer('ordered_ids'), $request->user());

        return response()->json(['ok' => true, 'version' => $playlist->fresh()->order_version]);
    }
}

This is not clever, and that is why it works. It acknowledges that two people cannot meaningfully reorder the same list at the same time without conflict.

Relative move commands often scale better than full-list rewrites

For larger collections, I increasingly prefer explicit commands like:

move item 48 before item 31
move item 12 after item 17
move item 7 to top

Why? Because they match user intent better and reduce the blast radius of a change.

A full-list payload says, “the browser knows the canonical entire order.” That is rarely true once pagination, filtering, or lazy loading exist. A relative move command says, “within this scoped collection, perform this concrete adjustment.” That is a much cleaner contract.

It also makes future implementation options easier. You can keep dense integer positions for small lists, or switch later to gap-based ranking, fractional ordering, or periodic normalization without changing the UI semantics too much.

Pagination is usually the point where the feature becomes dishonest

I have a strong opinion here: if a list needs pagination, drag-and-drop is probably the wrong default ordering interaction.

Not always, but usually.

The reason is not technical difficulty alone. It is user expectation.

When someone drags rows around, they assume they are manipulating a visible whole. Pagination tells them the opposite: this is only a slice. Those two mental models fight each other.

The real questions pagination creates

Suppose an admin table shows 25 rows per page.

If a user drags row 25 to the top of page 1:

should row 26 move to page 1 now
should page 2 reshuffle live
is the user editing global order or page-local order
what happens if the sorted set is filtered by search
what does “move to bottom” even mean without loading the whole sequence

None of these questions are cosmetic. They determine whether the feature is trustworthy.

The common workaround is to allow dragging only within the current page. That sounds pragmatic, but it often creates a worse lie. The UI looks like global ordering, but the behavior is actually page-local mutation against a hidden global sequence.

This is exactly the kind of feature that feels okay in a staging demo and then confuses operators for months.

Better patterns for large admin collections

If the collection is too large to comfortably view as a whole, I would usually choose one of these instead:

move up and move down controls for fine adjustment
pin to top and unpin for featured content
buckets like featured, standard, archived, hidden
explicit numeric rank inputs for users who truly manage sequence
weighted ordering where manual_rank is only one signal in a stable composite sort

Those patterns do not feel as magical as drag-and-drop. They are also easier to explain, easier to audit, and much less likely to make the database represent fake precision.

Exports make the mismatch worse

The moment exported CSVs, API feeds, or downstream jobs depend on the same ordered dataset, your reorder feature is no longer just a UI convenience.

If order affects exports, the questions become sharper:

is export order global or filtered
does a transient admin view change customer-facing order
can two successive exports differ because an operator dragged a row mid-run
do downstream consumers rely on that order as business priority

That is where I see teams accidentally turning position into policy. A hand-adjusted admin rank becomes an invisible source of truth for systems that were never meant to depend on it.

If that is really the business requirement, fine. But then treat it with that seriousness. If it is not, do not let a sortable grid define more truth than the product team intended.

Auditability and accessibility are not edge cases

When teams say drag-and-drop is “working,” they usually mean the rows move and persist. In admin tooling, that is not enough.

If order matters, the change must be explainable later

Someone will eventually ask:

who changed the order
when it changed
what the previous order was
whether the change was deliberate
whether the operator only meant to change one subset

A plain position column cannot answer any of that. If order influences what staff or customers see, log reorder events as events, not just row diffs. Store actor, scope, before-state when affordable, after-state, and request context.

This is also why I prefer order changes that are explicit in intent. “Moved Pricing card above FAQ in Homepage section” is a meaningful audit event. “Updated 47 position values” is not.

Keyboard access changes the product design in a good way

Most drag-and-drop interfaces are pointer-first and accessibility-second. That is a product smell.

If a reorderable task matters, it needs a complete non-pointer path. In practice that usually means controls like:

move to top
move up
move down
move to bottom
move before selected item
move after selected item

Teams sometimes treat this as a compliance add-on. I think that is backwards. When you design those commands well, the whole feature gets better. Intent becomes explicit. Precision improves. Support gets clearer language. Audits become easier to understand.

That is one of the strongest signals that freeform dragging was doing too much theatrical work and not enough operational work.

What I ship instead in most Laravel admin tools

My default production pattern now is not “sortable rows.” It is scoped rank with explicit commands.

The shape is usually:

define a parent scope clearly
store a nullable manual_rank or scoped position
combine it with a stable secondary sort like created_at, name, or business priority
expose deliberate actions instead of unconstrained dragging
audit every reorder operation that affects shared admin state

For example, a practical query often looks like this:

$articles = Article::query()
    ->where('tenant_id', $tenant->id)
    ->orderByRaw('CASE WHEN manual_rank IS NULL THEN 1 ELSE 0 END')
    ->orderBy('manual_rank')
    ->orderByDesc('published_at')
    ->paginate(25);

That model is much more honest. Ranked items float where the business explicitly placed them. Unranked items still behave predictably. Pagination remains understandable. You can add “pin,” “move up,” or direct rank edits without pretending every record lives in one sacred total order.

When I still allow drag-and-drop

I still use it in a narrow band of cases:

the list is small
the whole list is visible
the scope is obvious
the order matters as a business artifact
concurrency conflicts are acceptable or explicitly handled
auditability exists
keyboard alternatives exist

That usually means editorial and builder-style interfaces, not broad CRUD tables.

If your feature fails two or three of those tests, do not compensate with more JavaScript and stronger opinions about the frontend library. The problem is probably the contract, not the drag handle.

The practical takeaway is blunt because it needs to be. Do not add drag-and-drop ordering just because it looks intuitive. Add it only when the ordered collection is real, bounded, auditable, and small enough to reason about as a whole. In every other case, explicit ranking beats theatrical sorting, and your database will tell fewer lies.

Read the full post on QCode: https://qcode.in/the-hidden-cost-of-adding-drag-and-drop-ordering-to-admin-tools/

DEV Community: Saqueib Ansari

Before You Blame Filament, Profile the Screen

Start With a Single Screen, Not a General Complaint

Build a Simple Local Baseline

Most "Filament Is Slow" Problems Are Really Query Problems

Define a Screen-Specific Query Contract

Run EXPLAIN Before You Touch Caching

Table Configuration Can Create Death by a Thousand Cuts

Watch for Queries Inside Column Logic

Be Skeptical of Overly Smart Columns

Search and Sort Need Restraint

Authorization Often Hurts More Than Teams Expect

The Common Multi-Tenant Trap

Profile Authorization Like You Profile Queries

Relation Managers, Widgets, and Tabs Multiply Hidden Work

Relation Managers Are Easy to Underestimate

Widgets and Badge Counts Are Frequent Offenders

Pagination Is Usually Better Than Table Maximalism

A Production-Sane Workflow for Filament Performance Testing

The Order Actually Matters

A Realistic Refactor Pattern

What Not to Do First

The Practical Decision Rule

Passwordless Laravel Auth Is Easy to Demo and Harder to Run Well

The first threat is often your user's email security stack

Use email links to resume a flow, not to finish it

Signed URLs are useful, but not sufficient

The core object is not the link. It is the login attempt

Hash the token and keep the URL boring

One active attempt or many?

Replay protection is the part that separates demos from systems

Consume with an atomic state transition

Do not overfit to IP and user agent

Expiration should reflect attack window, not developer convenience

Device trust and step-up auth are where the architecture gets real

Magic link first, Fortify second

Provisional sessions are underrated

Trusted device should be revocable server state

Support and observability determine whether the system survives launch

Log events across the lifecycle

Build for common failure stories, not just malicious ones

Recovery policy is part of the auth design

What I would actually ship in a Laravel app

Testing Laravel AI features without burning API credits

Put a boundary around the model first

Fake model responses, not just success codes

Test malformed-but-plausible output

Tool calls need contract tests, not vibes

Failure modes worth forcing

Streaming tests should validate transcript flow

Do not skip interrupted streams

Force ugly failures on purpose

Make AI behavior reviewable

Keep canonical fixtures small

Assert on normalized outputs

Snapshot only after normalization

Keep one or two live integration tests

PHP Attributes Can Help Your Docs, But They Won’t Save Them

What attributes are actually good at

Where attribute-driven docs become a trap

1. The docs become local but not meaningful

2. The reference starts lying through omission

3. Attributes accumulate faster than they get curated

The real comparison: attributes versus editorial docs

Where attributes help most in Laravel codebases

A useful rule of thumb

How to keep generated docs honest

1. Decide what attributes are allowed to own

2. Generate references, then curate entry points

3. Treat examples as first-class documentation

4. Review attributes like API surface, not like decoration

5. Add drift checks that matter

The shape I would recommend

Layer 1: attributes for structured source truth

Layer 2: generated reference for consistency

Layer 3: editorial docs for meaning

The practical recommendation

When Transaction Pooling Starts Making Sense in Laravel

The bottleneck is often connection churn before it is query speed

What transaction pooling really changes

Run `EXPLAIN` Before You Touch Caching

Tenancy or schema boot logic hidden behind `SET`

Confusing Laravel `sticky` with session affinity

Example 2: A `SELECT` can still write