DEV Community: Saqueib Ansari

Laravel cooldowns work better when each action has its own rules

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

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

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

Where Rate Limits Get Too Blunt

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

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

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

A few common cases where cooldowns beat generic throttles:

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

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

Model The Cooldown Around Ownership and Action

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

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

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

A practical key format looks like this:

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

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

A Minimal Laravel Service

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

<?php

namespace App\Support;

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

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

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

        if (! $expiresAt) {
            return null;
        }

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

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

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

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

        return $expiresAt;
    }

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

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

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

Why Cache TTL Is Usually Enough

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

A cache-backed cooldown has the right properties:

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

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

Add Cooldowns At The Workflow Boundary

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

Example: AI Generation

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

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

    $cooldowns->enforce($workspace->id, 'ai-summary-generate');

    dispatch(new GenerateSummaryJob(
        workspaceId: $workspace->id,
        prompt: $request->string('prompt')->toString(),
    ));

    $cooldowns->start($workspace->id, 'ai-summary-generate', 20);

    return response()->json([
        'message' => 'Generation queued.',
    ], 202);
}

That policy is much sharper than throttle:10,1 on the route. It protects the exact action that costs money while allowing the user to keep navigating, editing, or fetching other data.

A useful refinement is dynamic cooldowns. If the model is expensive or the prompt size is large, increase the cooldown. If the workspace is on a higher plan, shorten it. Cooldowns are product policy, so they should reflect product reality.

Example: Export Generation

Exports tend to create operational spikes, especially when users click again because the UI did not make progress obvious.

public function export(Request $request, ActionCooldowns $cooldowns)
{
    $account = $request->user()->account;

    $cooldowns->enforce($account->id, 'orders-export');

    ExportOrders::dispatch($account->id, $request->all());

    $cooldowns->start($account->id, 'orders-export', 120);

    return response()->json([
        'message' => 'Export started. We will notify you when it is ready.',
    ], 202);
}

This does two things a global rate limit does not.

First, it stops repeated export launches even if the user is otherwise behaving normally. Second, it creates a predictable product contract: one export every two minutes for this account.

That is easier to explain, easier to support, and easier to reason about than a generic route throttle that may or may not trigger depending on unrelated requests.

The UX Matters More Than The Backend Trick

A cooldown without a clear UI is just a bug with a timer. If the user clicks a button and gets a 429 with no context, they will keep clicking, retry from another tab, or assume your app is broken.

You need to surface the policy clearly.

Return Structured Retry Data

Do not just return "Too many requests." Return when the user can try again.

A good response includes:

a stable error message
retry_after_seconds
an absolute retry_at timestamp
optionally the action name for the client

That gives the frontend enough data to disable the button, start a countdown, and avoid blind retries.

Show Cooldowns In The Interface

If a user triggers an action with a cooldown, the UI should reflect it immediately. Disable the action, show a countdown, and explain why. For AI generation, say it is preventing duplicate runs. For exports, say one export is already in progress or recently started.

This is not decoration. It reduces duplicate work and support noise.

Pair Cooldowns With Idempotency When Needed

Cooldowns stop repeated triggers across a time window. They do not solve duplicate submissions caused by network retries or double form posts at the same instant. For that, use idempotency keys or job deduplication.

Cooldowns and idempotency solve different failures. If the workflow is expensive enough, you usually want both.

A good decision rule:

Use idempotency to prevent accidental duplicates of the same intent.
Use cooldowns to limit how often a costly intent may be started.
Use rate limits for broad traffic control, abuse protection, and API fairness.

Failure Modes To Avoid

Most bad cooldown implementations are not conceptually wrong. They are just attached to the wrong identity, stored in the wrong place, or tuned with no product thinking.

Cooldown By IP

This is usually the wrong key for authenticated product workflows. Shared office IPs, VPNs, mobile networks, and browser privacy features make IP-based cooldowns noisy and unfair. If the action belongs to an account or workspace, key it that way.

Cooldown That Starts Too Early

If you start the cooldown before basic validation or authorization, you can punish harmless user mistakes. Start it when the system actually accepts the action and begins meaningful work.

Cooldown That Starts Too Late

If you only set the cooldown after a long-running job completes, repeated clicks can queue duplicates before the window exists. For queued workflows, start the cooldown at dispatch time or reserve the action with an atomic lock first.

No Atomic Guard Around First Trigger

If two requests arrive at nearly the same moment, both can pass the "not on cooldown" check before one writes the TTL. In high-contention actions, use Redis-backed atomic primitives such as locks or Cache::add() semantics instead of a naive read-then-write sequence.

A stronger pattern looks like this:

$acquired = Cache::add("cooldown:{$ownerId}:{$action}", now()->addSeconds($seconds)->timestamp, now()->addSeconds($seconds));

if (! $acquired) {
    return response()->json([
        'message' => 'Please wait before retrying this action.',
    ], 429);
}

That closes the race for the first write in a simple way.

Inventing Cooldowns For Everything

This is where teams go wrong after discovering the pattern. Not every action needs a cooldown. If the action is cheap, reversible, and already protected by validation, adding a wait window is just friction.

Use cooldowns for actions that are at least one of these:

expensive
spam-prone
operationally heavy
externally visible
confusing when triggered multiple times

If an action does not hit one of those, do not force it.

A Better Default For Real Laravel Products

If your app has AI features, exports, invites, notifications, or any workflow with uneven cost, stop reaching for one generic throttle first. Per-action cooldowns give you a more honest policy surface. They let you protect expensive paths tightly while leaving the rest of the product responsive.

Laravel makes this easy because the underlying pieces are already there: cache, Redis, jobs, policies, and clean service abstractions. The trick is not technical difficulty. The trick is choosing the right control for the job.

My recommendation is simple: keep Laravel rate limiting for broad API and auth protection, then add owner-scoped action cooldowns for workflows that cost real money or create real operational drag. When the action is expensive, user-facing, and easy to spam, a cooldown is usually the cleaner answer.

If your current policy reads like "5 requests per minute" for a costly button, you probably have the wrong abstraction. Replace it with a rule the product can actually defend: who can do what, and how often, without harming cost, systems, or UX.

Read the full post on QCode: https://qcode.in/per-action-cooldowns-laravel-rate-limits/

Laravel image jobs need idempotency before they need new APIs

Saqueib Ansari — Sat, 01 Aug 2026 05:24:34 +0000

Laravel getting first-party image processing is useful, but it also creates the wrong instinct in a lot of teams. They start thinking the hard part is finally solved because the resize and transform layer is now closer to the framework.

It is not.

If your app handles uploads through queues, the dangerous part is still retries, partial completion, duplicate writes, and stale state. A cleaner API for cropping or encoding does not fix a worker running twice, a timeout after two variants, or a replace flow that leaves old files live behind the CDN.

My recommendation is blunt: treat Laravel image jobs as idempotent workflow code first and image manipulation code second. If you get that order wrong, the pipeline will look fine in demos and slowly become operational debt in production.

The Real Bug Is Usually Workflow Drift

Most broken image systems are not broken because the JPEG library failed. They are broken because the surrounding workflow had no durable memory.

A typical naive implementation looks like this:

Accept upload
Save original with a random name
Dispatch a queued job
Generate a few variants
Update the database at the end

That sounds reasonable until reality arrives.

What happens if the worker dies after writing the thumbnail but before writing the hero image? What happens if the queue retries the job automatically? What happens if the user re-uploads a replacement while the first job is still running? What happens if S3 accepts one object write but the DB transaction rolls back? What happens if Horizon runs the same job again after a timeout even though some files are already present?

Those are not weird edge cases. They are normal production behavior once your queue, storage, and HTTP boundary stop behaving like one process.

Laravel's queue docs already push you toward this mental model: jobs may be retried, may time out, and may be processed asynchronously by separate workers. That is exactly why image work must be retry-safe in the first place: https://laravel.com/docs/13.x/queues.

If your image pipeline assumes every job runs exactly once from start to finish, you do not have a resilient pipeline. You have a best-case script.

The Failure Modes Worth Designing For

The recurring failure modes are boring, which is exactly why teams under-design them:

duplicate original files for the same logical image
half-generated variants with no reliable way to resume
a DB row marked processed while one or more files are missing
an older job overwriting paths after a newer upload already replaced the image
retries generating the same derivatives repeatedly and inflating storage cost
cleanup code deleting active files because it cannot distinguish versions

The common thread is simple: the system cannot tell what work is intended, what work is complete, and what work has been superseded.

That is an idempotency problem, not an imaging problem.

Start With A Durable Image Record, Not With `Storage::put()`

The first design move should be a database record that represents the lifecycle of a logical image. Do that before you worry about which driver or image library you prefer.

You want one place that can answer these questions at any moment:

what is the canonical original for this image?
which processing version is current?
what status is the workflow in right now?
which variants are already durable?
was this image replaced, failed, or completed?
do two uploads contain the same original bytes?

A minimal schema can carry most of that:

Schema::create('media_images', function (Blueprint $table) {
    $table->uuid('id')->primary();
    $table->morphs('imageable');

    $table->string('disk', 32);
    $table->string('status', 24)->default('pending')->index();
    $table->unsignedInteger('version')->default(1);

    $table->string('original_path');
    $table->string('original_extension', 16);
    $table->string('original_checksum', 64)->index();
    $table->unsignedBigInteger('original_bytes');
    $table->string('mime_type', 100);

    $table->json('variants')->nullable();
    $table->json('meta')->nullable();

    $table->timestamp('processing_started_at')->nullable();
    $table->timestamp('processed_at')->nullable();
    $table->timestamp('failed_at')->nullable();
    $table->text('failure_reason')->nullable();
    $table->timestamp('superseded_at')->nullable();

    $table->timestamps();
});

That table is doing real work.

The status field gives the queue something explicit to reconcile against. The version field gives replacements a clean upgrade path. The original_checksum gives you content identity instead of guessing from filenames. The variants JSON gives you durable progress tracking without having to scan storage on every decision.

Status Columns Matter More Than People Admit

A lot of teams try to infer state from file existence. If thumb.webp exists, they treat the image as processed. That is fragile.

File existence alone cannot tell you whether:

the current version is the one on disk
all required variants are present
the database metadata matches the actual artifacts
the image was replaced and the old path is now stale
the workflow failed after partial success

Use explicit workflow states instead. Keep them small and operationally meaningful:

pending
processing
processed
failed
superseded

That is enough for most Laravel apps. Resist the urge to invent a state machine with 15 statuses unless you genuinely need it.

Deterministic Paths Are The Backbone Of Retry Safety

Randomized filenames are fine for raw uploads at the edge. They are bad as the long-term identity of a processing workflow.

If every retry produces a different target path, you cannot safely answer basic questions like "did we already write this variant?" or "which files belong to version 2 of this image?" You may avoid collisions, but you create a bigger mess: hidden duplicates, expensive cleanup, and no stable namespace.

A better rule is this: each logical image should own a deterministic directory, and each version should own deterministic child paths.

For example:

final class ImagePaths
{
    public static function original(string $imageId, int $version, string $extension): string
    {
        return "images/{$imageId}/v{$version}/original.{$extension}";
    }

    public static function variant(string $imageId, int $version, string $name, string $extension = 'webp'): string
    {
        return "images/{$imageId}/v{$version}/{$name}.{$extension}";
    }
}

That path scheme is boring, which is exactly what you want.

It gives you stable targets across retries, clean version isolation across replacements, and predictable cleanup scopes. It also plays nicely with Laravel's filesystem abstraction because the framework can switch disks without changing your naming contract: https://laravel.com/docs/13.x/filesystem.

Why Versioned Paths Beat Overwrites

Many teams try to overwrite original.jpg and regenerate the same variant paths in place when an image is replaced. That looks simpler until concurrency shows up.

Imagine this timeline:

User uploads image A
Job A starts generating variants
User replaces it with image B
Job B starts
Job A finishes late and writes over shared paths

Now you have stale data winning because the path contract allowed two generations to compete for the same filenames.

Versioned paths stop that class of bug. Job A writes only under v1. Job B writes only under v2. The database decides which version is current. Cleanup can remove v1 later, but only after v2 is fully durable.

That is a much cleaner system boundary than trying to make timing guarantees you do not actually control.

Checksums Turn Upload Chaos Into Something You Can Reason About

The checksum is the underrated field in this whole pipeline.

Without it, repeated uploads are guesswork. With it, you can make concrete decisions.

If the user retries the same request, or your frontend double-submits, or an API client replays an upload after a network wobble, the checksum lets you tell whether this is genuinely new content or the same file arriving twice.

That creates practical rules:

same image record + same checksum: do not regenerate everything
same image record + different checksum: increment version and reprocess
different record + same checksum: maybe deduplicate later, but only if the added complexity is worth it

Per-record idempotency is usually enough. Global deduplication across the whole app sounds clever, but it adds reference counting, ownership questions, and cleanup complexity fast. Most teams should earn that complexity only after local idempotency is solid.

Compute The Checksum At Ingress

You want the checksum as early as possible, ideally when the original file is first accepted:

$stream = fopen($uploadedFile->getRealPath(), 'rb');
$checksum = hash_file('sha256', $uploadedFile->getRealPath());
$extension = strtolower($uploadedFile->getClientOriginalExtension() ?: 'bin');

$image = MediaImage::create([
    'id' => (string) Str::uuid(),
    'imageable_type' => $post::class,
    'imageable_id' => $post->getKey(),
    'disk' => 's3',
    'status' => 'pending',
    'version' => 1,
    'original_extension' => $extension,
    'original_checksum' => $checksum,
    'original_bytes' => $uploadedFile->getSize(),
    'mime_type' => $uploadedFile->getMimeType(),
    'original_path' => ImagePaths::original($id, 1, $extension),
]);

Storage::disk('s3')->put($image->original_path, $stream);

This is also where you want to make a judgment call about request-level idempotency. If your API surface can receive the same upload twice from a flaky client, it is often worth pairing the checksum with an application-level idempotency key so you can return the existing image record instead of creating a new one.

The Job Should Reconcile Progress, Not Rebuild Blindly

The core mistake in most image jobs is that they act like a one-shot script. They should act like a reconciler.

A reconciler asks:

what state should exist?
what state already exists?
what is missing?
what has become obsolete?

That mental model is better than "run all transforms and hope it finishes" because retries become safe by construction.

Here is the shape I prefer:

final class ProcessImageVariants implements ShouldQueue
{
    public int $timeout = 120;

    public function __construct(
        public string $imageId,
        public int $version,
    ) {}

    public function handle(): void
    {
        $image = MediaImage::query()->findOrFail($this->imageId);

        if ($image->version !== $this->version || $image->status === 'superseded') {
            return;
        }

        if ($image->status === 'processed' && $this->allRequiredVariantsExist($image)) {
            return;
        }

        $image->forceFill([
            'status' => 'processing',
            'processing_started_at' => $image->processing_started_at ?? now(),
            'failed_at' => null,
            'failure_reason' => null,
        ])->save();

        $written = $image->variants ?? [];

        foreach ($this->variantDefinitions() as $name => $definition) {
            if ($this->variantAlreadyDurable($image, $written, $name)) {
                continue;
            }

            $binary = app(ImageVariantBuilder::class)->build(
                image: $image,
                width: $definition['width'],
                height: $definition['height'],
                fit: $definition['fit'],
            );

            $path = ImagePaths::variant($image->id, $image->version, $name, 'webp');

            Storage::disk($image->disk)->put($path, $binary);

            $written[$name] = [
                'path' => $path,
                'width' => $definition['width'],
                'height' => $definition['height'],
                'format' => 'webp',
            ];

            $image->forceFill(['variants' => $written])->save();
        }

        $image->forceFill([
            'status' => 'processed',
            'processed_at' => now(),
            'variants' => $written,
        ])->save();
    }
}

There are three important ideas here.

First, the job exits early if it is no longer the current version. That prevents stale work from winning late.

Second, the job persists progress after each successful variant. That means a crash after two variants is annoying, not catastrophic.

Third, completion is earned only after the required set is actually present.

Incremental Persistence Beats Fake Atomicity

You cannot make storage writes and database writes one perfect transaction across systems. Pretending otherwise just hides the truth.

The pragmatic answer is incremental honesty:

mark processing
write one artifact
persist that artifact's metadata
continue
mark processed only when the full required set exists

That pattern gives retries something real to work with. It also makes operator debugging much easier because the record reflects partial progress instead of collapsing everything into a binary success/failure fantasy.

Concurrency And Replacement Flows Need Explicit Rules

Image systems usually get messy when the same logical image can be edited, replaced, or reprocessed while workers are still active.

Do not solve that with hope. Solve it with rules.

Rule 1: Jobs Must Carry Version Context

Never dispatch a generic "process this image" job without the version it is supposed to process. Pass both image ID and version.

That way, when the worker wakes up, it can immediately verify whether it still owns relevant work. If the DB row has already advanced to a newer version, the old job should do nothing.

Rule 2: Replacements Should Supersede, Not Mutate In Place

When the original changes, do not quietly rewrite the existing artifacts. Increment version, write the new original under the new namespace, reset status to pending, and dispatch a fresh job.

The old version can remain on disk for a short time. That is fine. Temporary duplication is much safer than cross-version corruption.

Rule 3: Cleanup Should Be Separate From Processing

Do not mix destructive cleanup into the happy-path processing job unless you absolutely need to. A failed cleanup should not poison image generation.

Use a later job that removes obsolete versions only after the new one is fully processed and any publish/CDN rules are satisfied.

That separation keeps the hot path smaller and prevents one category of failure from cascading into another.

Storage Writes Need To Be Retry-Safe Too

A surprising number of pipelines are "idempotent" in theory but still perform wasteful or dangerous writes in practice.

The simplest rule is this: before writing a variant, know the exact target path and know whether an existing durable file already satisfies the contract.

That often means checking both:

the DB metadata says the variant exists
the storage disk confirms the path exists

If both are true, skip the write. If the DB says it exists but storage disagrees, repair it. If storage says it exists but the DB row never recorded it, verify it belongs to the current version before trusting it.

That sounds like extra bookkeeping because it is. That bookkeeping is what turns retries into recovery instead of duplication.

S3 And Local Disk Fail Differently

Laravel makes local disk and S3 look similar from the app code, which is a good abstraction. But operationally, the tradeoffs are still different.

Local disk gives you lower latency and simple existence checks but ties durability to host topology. S3 gives you better durability and easier horizontal scale but makes object writes, verification, and cleanup more distributed in feel.

The idempotency rules do not change across disks. What changes is how much you trust path existence, how expensive repeated writes are, and how carefully you want to stage cleanup.

That is why designing around deterministic paths and explicit workflow state matters so much. It survives infrastructure changes better than path conventions invented ad hoc in controllers.

What I Would Ship In A Real Laravel App

If I were implementing image jobs in a production Laravel codebase today, the baseline would be:

one DB row per logical image
explicit status and version columns
checksum captured at upload time
deterministic original and variant paths
queued jobs that receive image ID plus version
per-variant progress persistence
completion only after required variants are verified
replacement flows that create new versions instead of overwriting paths
cleanup handled asynchronously after successful supersession

That is not over-engineering. That is the minimum structure that keeps image work understandable once retries and replacements show up.

New first-party image APIs are a good addition. They should reduce glue code, make transforms more Laravel-native, and clean up the manipulation layer. Use them.

Just do not confuse a better transform API with a reliable image pipeline.

Practical Decision Rule

If an image job can run twice, then it must be idempotent. That means stable identity, deterministic paths, explicit workflow state, and retry-safe writes. Everything else is secondary.

In other words: the best Laravel image pipeline is not the one with the nicest resize syntax. It is the one that can crash halfway through, run again, and still converge on the same correct result.

Read the full post on QCode: https://qcode.in/laravel-image-jobs-need-idempotency-more-than-new-apis/

Using HTTP QUERY in Laravel Without Making Your API Harder to Maintain

Saqueib Ansari — Thu, 30 Jul 2026 04:20:25 +0000

The short version is this: GET should remain your default search method in Laravel, POST is still the pragmatic fallback for complex filters, and QUERY is only worth it when you care enough about HTTP semantics to also absorb the infrastructure cost. That is the real trade.

The new HTTP QUERY method is no longer just an idea floating around in standards discussions. It became an RFC in June 2026 as RFC 10008. Its pitch is clean: let clients send a safe, idempotent request with a body. In other words, keep the semantics of retrieval while avoiding the ugliness of packing large search payloads into query strings or pretending a safe read is a POST.

That sounds perfect for search APIs. Laravel teams, especially the ones building admin panels, reporting endpoints, AI-assisted filtering, or multi-criteria dashboards, will look at it and think: finally, a method that matches the actual intent.

The catch is that protocol correctness is only half the job. The other half is everything around it: proxies, clients, caches, API gateways, analytics tools, team familiarity, browser behavior, and fallback design. QUERY can absolutely make an API cleaner. It can also become one of those technically elegant choices that quietly increases maintenance drag for the next two years.

What `QUERY` Fixes That `GET` and `POST` Do Not

The value of QUERY is easiest to see when your search endpoint has outgrown a nice URL.

Simple filtering belongs on GET:

GET /orders?status=paid&sort=-created_at&page=2

That is still the best option when the filter is small, linkable, and cache-friendly. Laravel, browsers, CDNs, observability tools, and every API client on earth understand it.

The problem starts when search payloads get richer:

nested filters
grouped conditions
long lists of IDs
full-text rules with weights
date windows and facets
export-style report queries
AI-generated filter payloads

At that point, teams usually jump to POST /orders/search with JSON. It works, but it muddies the semantics. You are making a read-only operation look like a state-changing write. RFC 10008 exists precisely for that gap. It defines QUERY as safe and idempotent, similar to GET, while still allowing request content in the body. The RFC explicitly describes it as the bridge between URI-based GET queries and body-based POST queries.

That semantic clarity is not academic. It affects retry logic, caching assumptions, API readability, and how future maintainers reason about your endpoint. A POST search route always forces a mental footnote: "yes, this is actually a read." A QUERY route does not.

There is another nice detail in the RFC: support can be discovered with the standard Allow header and with the new Accept-Query response header, which can advertise supported query body media types. In spec terms, this is cleaner than the usual undocumented convention of "POST here with JSON and trust us."

So if you are comparing the methods purely on semantic accuracy, the ranking is straightforward:

GET wins for small, URL-friendly searches.
QUERY wins for complex, body-based searches that are still safe reads.
POST is the compatibility workhorse, not the cleanest model.

That is the good part. The harder question is whether your actual stack can live with it.

Where `QUERY` Really Helps in a Laravel Codebase

If you are going to adopt QUERY, do it for endpoints where the semantic gain is real, not cosmetic.

Best Fit: Complex Safe Search

The best case is a search or reporting endpoint whose payload is too large or structured for a query string, but which still has no side effects.

Think of an internal analytics screen with nested filter groups:

{
  "filters": [
    {"field": "status", "operator": "in", "value": ["paid", "refunded"]},
    {"field": "country", "operator": "eq", "value": "IN"}
  ],
  "date_range": {
    "from": "2026-07-01",
    "to": "2026-07-27"
  },
  "sort": [
    {"field": "revenue", "direction": "desc"}
  ],
  "page": 1,
  "per_page": 50
}

This payload is awkward in GET, but it is clearly not a write. QUERY matches the intent better than POST.

Better Fit for Shared Search Engines

If your Laravel app exposes a search abstraction used by multiple clients, QUERY can also make the contract clearer. Mobile apps, internal tools, backend services, and AI agents all understand a resource that is being queried, not mutated.

That matters when your API surface starts to sprawl. Naming every safe search route .../search behind POST works, but it slowly trains your codebase to treat reads as writes whenever the filter becomes inconvenient.

A Cleaner Service Boundary

The good Laravel design here is not "put search logic in the route and celebrate modern HTTP." The good design is to normalize all search inputs into a single query object and let transport be an edge concern.

For example:

final class OrderSearchData
{
    public function __construct(
        public array $filters = [],
        public array $sort = [],
        public ?string $from = null,
        public ?string $to = null,
        public int $page = 1,
        public int $perPage = 50,
    ) {}

    public static function fromRequest(Request $request): self
    {
        $payload = $request->isMethod('QUERY')
            ? $request->json()->all()
            : $request->all();

        return new self(
            filters: $payload['filters'] ?? [],
            sort: $payload['sort'] ?? [],
            from: data_get($payload, 'date_range.from'),
            to: data_get($payload, 'date_range.to'),
            page: (int) ($payload['page'] ?? 1),
            perPage: min((int) ($payload['per_page'] ?? 50), 200),
        );
    }
}

That pattern matters because if you adopt QUERY, you should almost certainly also keep a compatibility path for GET or POST. The application core should not care which transport brought the search payload in.

Why `QUERY` Can Still Become a Maintenance Trap

This is the part people skip when they get excited about standards.

QUERY is a better semantic fit than POST for body-based reads. That does not mean it is a better operational choice for every Laravel team in 2026.

Laravel Is Friendly, the Rest of the Stack May Not Be

Laravel’s request object is flexible. The docs explicitly show that Request::method() returns the incoming verb and isMethod() can test it, which means the framework can inspect whatever method reaches it. Laravel routing docs also show first-class helpers only for the common verbs plus match() and any(). That gap is telling.

QUERY is not a first-class Laravel happy path yet. You are stepping off the paved road.

That means you have to think beyond framework code:

Will your web server pass the method through untouched?
Will your load balancer or API gateway allow it?
Will your WAF rules treat it as suspicious by default?
Will your request logs, dashboards, and APM tooling group it correctly?
Will your SDKs, test tools, and generated clients preserve it?

A method can be valid HTTP and still be awkward in real infrastructure for years.

Browser and Client Ergonomics Are Still Uneven

This is where many elegant API ideas lose momentum. Your server may accept QUERY, but your consumers are not just servers. They are browsers, frontend apps, mobile clients, Postman collections, CLI tools, generated SDKs, and internal scripts.

Even when a client can technically send a custom method, that does not mean the surrounding tooling treats it as normal. Teams end up discovering soft failures instead of hard ones: middleware assumptions, CORS friction, analytics blind spots, auto-generated docs that misrender the method, or testing utilities that need manual overrides.

A clean spec with awkward tooling adoption is exactly how maintenance traps get born.

Caching Is Better in Theory Than in Commodity Infrastructure

RFC 10008 says QUERY responses are cacheable. That is a real semantic advantage over the usual hand-wavy POST search pattern. But the same RFC also points out that caching QUERY is inherently more complex than GET, because the cache key has to account for the request body.

That is the key practical point. Commodity caches and CDNs are built around GET muscle memory. Once your cache key depends on request content, you need much more confidence in the behavior of your intermediaries.

So yes, QUERY is semantically more cacheable than POST. No, that does not mean your stack will suddenly deliver effortless query-body caching.

Observability Gets Slightly Worse Before It Gets Better

GET requests are easy to inspect because the filters are in the URL. That is noisy, but operationally convenient. POST requests are boring but familiar. QUERY sits in an awkward middle state: safe like GET, body-based like POST, and uncommon enough that some tooling will not know what to do with it by default.

If your team relies heavily on request logs, metrics tagging, or ops dashboards, uncommon verbs create extra work. Not impossible work. Just work you need to budget for before calling the design "cleaner."

The Laravel Implementation Pattern That Makes Sense

If you want to experiment with QUERY, do it with a dual-path design, not a purity play.

The wrong rollout is this:

invent a QUERY endpoint
remove POST search immediately
assume infrastructure will cooperate
discover breakage one proxy or one client at a time

The better rollout is to centralize search logic and expose multiple transports intentionally.

Recommended Route Shape

Keep your canonical search behavior in one action or service, then expose:

GET for simple filters
POST as the broad compatibility route
QUERY as the semantically correct route for capable clients

That can look like this:

use App\Http\Controllers\OrderSearchController;
use Illuminate\Support\Facades\Route;

Route::get('/orders', [OrderSearchController::class, 'index']);
Route::post('/orders/search', [OrderSearchController::class, 'search']);
Route::any('/orders/query', [OrderSearchController::class, 'query']);

And in the controller:

final class OrderSearchController
{
    public function index(Request $request, OrderSearch $search)
    {
        $data = OrderSearchData::fromRequest($request);

        return response()->json($search->run($data));
    }

    public function search(Request $request, OrderSearch $search)
    {
        $data = OrderSearchData::fromRequest($request);

        return response()->json($search->run($data));
    }

    public function query(Request $request, OrderSearch $search)
    {
        abort_unless($request->isMethod('QUERY'), 405);

        $data = OrderSearchData::fromRequest($request);

        return response()
            ->json($search->run($data))
            ->header('Accept-Query', 'application/json');
    }
}

This is not pretty in a framework-purist sense, but it is honest. It acknowledges that Laravel does not yet hand you a polished Route::query() abstraction and that compatibility still matters.

Validation and Idempotency Still Matter

Because QUERY is safe and idempotent, your implementation needs to behave like it. That sounds obvious, but it is easy to accidentally violate.

Do not let a search endpoint with QUERY:

persist "last searched" state as a side effect
write audit rows on every request unless you are comfortable treating them as benign side effects
trigger exports, notifications, or queue jobs automatically
warm expensive materialized views in a way that behaves like a write API

If you label an endpoint as QUERY, keep it operationally read-only. Otherwise you get the worst of both worlds: unfamiliar method plus broken semantics.

Use `Accept-Query` If You Are Serious

If you adopt QUERY, do not hide it as tribal knowledge. RFC 10008 added the Accept-Query response header for a reason. If your endpoint supports JSON query bodies, advertise that.

That makes the feature discoverable and gives your API contract a little more honesty than a random internal wiki page.

So Should Laravel Teams Use `QUERY`?

Usually, not as the only search method.

That is the recommendation I would defend in a real code review.

If your audience is broad, public, browser-heavy, or integration-heavy, GET plus POST is still the safest pairing. GET covers the simple and URL-friendly cases. POST covers complex body-based search without forcing the rest of your stack to learn a still-uncommon verb.

If your environment is controlled, your clients are known, your infrastructure team can validate method pass-through, and you care enough about protocol semantics to maintain the edges properly, then QUERY becomes worth considering. In that narrower setup, it is genuinely cleaner than pretending every complex read is a POST.

So the real comparison looks like this:

Use GET when the search is naturally representable in the URL and benefits from universal tooling support.
Use POST when compatibility matters more than semantic purity.
Use QUERY when the operation is truly a safe read, the payload belongs in the body, and your stack is mature enough to support a less-traveled method without surprises.

That last condition is the whole story. QUERY is not a gimmick, and it is not automatically a trap. It is a sharper tool that only pays off when the rest of the system is ready for it.

If your team is still fighting basic API consistency, do not start here. If your team already cares about transport semantics, cache behavior, and multi-client search design, then QUERY is finally a real option. Just adopt it like an infrastructure decision, not a syntax upgrade.

Read the full post on QCode: https://qcode.in/http-query-laravel-cleaner-search-api-future-maintenance-trap/

Claude Code on Bun: What Runtime Choices Actually Mean for Agentic Tools

Saqueib Ansari — Tue, 28 Jul 2026 04:08:26 +0000

Claude Code’s move through a Bun plus Rust story is not interesting because it proves one runtime is universally better. It is interesting because it exposes what agentic developer tools actually optimize for once they stop being simple CLIs and start acting like local operators.

A coding agent is a weird product. It has to boot fast enough to feel conversational, stream output without stalling, spawn real developer tools, survive broken local environments, package cleanly across platforms, and remain debuggable when users say, "it got stuck after editing three files and running tests." That is a very different runtime problem than building a web API.

So the right takeaway is not "everyone should rewrite their tools on Bun". The right takeaway is that agent runtimes are chosen by friction, control, and failure behavior more than by raw benchmark throughput. Claude Code’s direction just makes that reality easier to see.

Anthropic’s public material now makes that connection fairly explicit. Bun announced in December 2025 that Anthropic was betting on it as infrastructure for Claude Code and future AI coding tools, and Anthropic has separately written about Claude Code’s sandboxing model and agent SDK direction. Those are not isolated product notes. Together they point to a broader architecture bias: agent tools want a tighter runtime surface, not a looser one. See Anthropic’s acquisition note, Bun’s announcement, and Anthropic’s sandboxing write-up.

Agentic Tools Punish the Wrong Runtime Fast

Developers still talk about runtimes as if the main question is request throughput or ecosystem size. For a coding agent, those are secondary. The runtime gets judged by much harsher product constraints.

A coding agent sits between the model and the operating system. It reads files, writes patches, spawns subprocesses, parses logs, watches test output, manages permissions, sometimes talks to IDEs, and often tries to recover from partial failure. That means the runtime is not just an execution engine. It becomes part of the product surface.

If that surface is slow to start, users feel lag before the first useful token. If subprocess handling is flaky, test runs hang. If packaging is messy, install scripts fail on real laptops. If stack traces are noisy or state is spread across too many layers, incident diagnosis becomes miserable.

This is why agentic tools punish the wrong runtime faster than ordinary apps do. A standard backend can hide a lot of runtime awkwardness behind containers, CI, and a stable deployment envelope. A local coding agent cannot. It runs in the user’s environment, touches their actual repo, and shells out to their actual toolchain. Every weak edge is now a product bug.

A practical checklist for agent runtimes looks more like this:

cold start and interactive latency
install and upgrade friction
subprocess, pipe, and TTY behavior
cross-platform filesystem correctness
packaging and binary distribution
sandbox compatibility and permission control
observability during long-running sessions

That list tells you why the runtime discussion has shifted. It is not really about JavaScript versus Rust. It is about which stack gives the product team the most reliable control over a messy, local, tool-heavy workflow.

Bun Fits the Agent Shape Because It Collapses Tooling Layers

Bun’s appeal in this space is not just speed. Speed matters, but the bigger story is surface area reduction.

Traditional JavaScript CLI distribution often means stitching together Node, npm, a global install path, lockfile assumptions, version manager quirks, package resolution behavior, and sometimes native module surprises. That stack can work well, but it also creates a lot of places where a coding agent can fail before doing anything useful.

Bun changes the shape of the problem by collapsing runtime, package manager, bundling assumptions, and CLI ergonomics into a tighter experience. For a consumer web app, that might be a nice productivity boost. For a local agent, it is much more than that. It is an attack on setup entropy.

Install Friction Is a Product Metric

Most developers underestimate how much agent adoption is governed by install quality. A coding tool does not get judged only after the tenth session. It gets judged during the first three minutes.

If the install path looks like this, the tool already feels fragile:

Install a specific Node version.
Upgrade npm.
Hope your shell profile exposes the correct global bin path.
Work around one transitive dependency issue.
Re-run because the postinstall step behaved differently on macOS and Linux.

That is not a technical nuisance. That is user churn.

A runtime that shortens the number of assumptions between download and first prompt wins disproportionate product value. Bun is attractive because it helps reduce that path length.

Cold Start Is Not a Benchmark Detail

Interactive agents are judged like editors, not like web services. A one-second startup penalty is noticeable. Repeated across every invocation, context restore, or tool subprocess boundary, it becomes part of the perceived intelligence of the product.

Users rarely say, "this runtime has poor startup characteristics." They say, "the tool feels heavy," or "I stopped using it for small tasks." That is the same complaint.

When a runtime reduces boot cost and CLI overhead, it changes what kinds of tasks feel worth delegating to the agent. That is a product leverage point, not a micro-optimization.

Tighter Ownership Matters

There is also an organizational angle here. If a vendor owns or strongly influences more of the runtime surface, they can close bugs across layers instead of endlessly routing around them.

That matters for agent products because many failures do not live cleanly inside app code. They live in the seams between process execution, streaming, package resolution, permissions, and local OS behavior. A tighter runtime stack gives the product team more leverage on the exact places that hurt users.

Why the Rust Layer Matters More Than Marketing Suggests

The phrase "written in Rust" gets abused in marketing, but in this context it points to something real. Agentic tools have a lot of systems-level failure modes.

These tools need to manage:

subprocess lifetime and cancellation
streaming stdout and stderr without deadlocks
large filesystem walks
low-latency parsing and transformation
isolation boundaries
memory behavior over long sessions
crash resistance under ugly edge cases

Those are not glamorous product features, but they are core to the user experience. When part of the runtime foundation shifts closer to systems-language constraints, it usually means the team is trying to take tighter control over correctness and operational behavior.

That does not mean Rust automatically fixes agent problems. It does mean the product team is less willing to accept vague, dynamic, layered failure modes in the runtime substrate.

For coding agents, that is rational. The tool is already taking meaningful action on the developer’s machine. If it is going to edit files, launch commands, inspect repos, and potentially run inside restricted sandboxes, the underlying execution model needs to be boring in the best possible way.

A useful way to think about the Rust angle is this: the closer your product gets to orchestrating the operating system, the more runtime implementation details start behaving like product features. Safety, predictable concurrency, and resource control stop being internal engineering preferences. They become user trust factors.

The Runtime Decision Gets Real at the Subprocess Boundary

If you want to evaluate an agent runtime honestly, stop looking at HTTP benchmarks and start looking at subprocess behavior.

Coding agents are really subprocess orchestration engines with a model attached. They spend huge amounts of time running git, rg, npm, pnpm, bun, cargo, pytest, php artisan, composer, docker, and custom repo scripts. The agent is only as reliable as its ability to manage those tools under real-world noise.

What Good Subprocess Support Needs to Handle

A production-grade agent runtime needs predictable behavior for:

streaming large outputs without buffering disasters
killing child processes cleanly on cancellation
distinguishing normal exit, timeout, and signal termination
handling interactive programs and pseudo-terminals
preserving environment variables intentionally
preventing hangs when stdout is noisy or stderr is bursty

Those are not edge cases. They are everyday paths for coding tools.

Here is the kind of execution wrapper an agent ends up needing, regardless of language:

type CommandResult = {
  exitCode: number | null;
  stdout: string;
  stderr: string;
  timedOut: boolean;
  durationMs: number;
};

export async function runCommand(
  cmd: string[],
  timeoutMs = 60_000,
): Promise<CommandResult> {
  const startedAt = Date.now();

  const proc = Bun.spawn(cmd, {
    stdout: 'pipe',
    stderr: 'pipe',
    stdin: 'ignore',
  });

  const timeout = setTimeout(() => proc.kill(), timeoutMs);

  const [stdout, stderr, exitCode] = await Promise.all([
    new Response(proc.stdout).text(),
    new Response(proc.stderr).text(),
    proc.exited,
  ]).finally(() => clearTimeout(timeout));

  return {
    exitCode,
    stdout,
    stderr,
    timedOut: exitCode === null,
    durationMs: Date.now() - startedAt,
  };
}

This example is simple on purpose. Real agents add streaming callbacks, allowlists, structured events, output truncation, retry logic, and environment scoping. The point is not the syntax. The point is that the runtime must make this layer predictable enough that the product team can build policy on top of it.

Failure Behavior Is More Important Than Success Speed

A fast happy path is nice. What matters more is whether the tool fails cleanly when the repo is weird.

Common real failures include:

a test command waiting for interactive input
a child process spawning grandchildren that outlive cancellation
environment drift between shell startup modes
repo scripts that output gigabytes of logs
tools that behave differently when no TTY exists
Windows, WSL, and macOS path differences

If the runtime makes those failures hard to observe or recover from, the agent will feel unreliable no matter how fast its benchmarks look.

That is why the Bun story matters less as "faster JavaScript" and more as "a runtime stack willing to care deeply about CLI and systems ergonomics." That is the actual product need.

Sandboxing Changes the Runtime Conversation Completely

Once an agent can run commands and edit files, sandboxing stops being a feature checkbox. It becomes a first-order architectural constraint.

Anthropic’s sandboxing write-up on Claude Code is useful because it shows the real threat model: prompt injection, over-broad command access, accidental data exposure, and risky tool execution in a local environment. An agent runtime that cannot cooperate cleanly with isolation controls is a weak foundation.

Sandboxing Needs Runtime Cooperation

The runtime does not need to provide the entire sandbox by itself, but it must play well with the layers around it:

operating system sandbox primitives
containerized execution
command allowlists
temp directory isolation
file permission boundaries
policy checks before dangerous actions

A coding agent often needs an execution funnel that looks something like this:

User request
  -> planner
  -> policy check
  -> tool selection
  -> sandbox / permission gate
  -> subprocess execution
  -> structured result
  -> model reflection

If the runtime makes subprocess control, environment shaping, or temporary filesystem isolation awkward, the product team ends up fighting the platform instead of implementing safety policy.

Native Extensions and System Interfaces Still Matter

This is where the runtime choice gets uncomfortable. Pure developer experience is not enough. Agent tools often end up touching native capabilities or low-level OS interfaces indirectly through libraries, platform APIs, or security wrappers.

That means compatibility still matters. Node remains strong here because of ecosystem inertia. There are simply more libraries, more edge-case integrations, and more enterprise-tested patterns.

Bun can still be the right choice, but the burden shifts. If your agent needs a narrow, predictable, tightly controlled stack, Bun’s tradeoffs can be excellent. If your tool depends on long-tail packages, ancient build assumptions, or deeply entrenched enterprise environments, Node’s ecosystem gravity is still very real.

That is why this is not a religion war. It is a product topology question.

Packaging, Updates, and Operational Debugging Decide Who Wins

The least glamorous parts of developer tooling usually decide the winner.

A coding agent is not done once it works on the maintainer’s laptop. It has to update cleanly, recover from partial installs, report meaningful failure states, and leave enough diagnostics behind that support engineers can tell whether the problem was the model, the runtime, the repo, or the OS.

Packaging Is Part of Trust

A bad packaging story creates a trust tax. Users become hesitant to upgrade. Teams pin old versions. Bug reports get contaminated by environment drift.

The strongest developer tools minimize that drift by making updates boring. That usually means:

one obvious install path
one obvious upgrade path
minimal global dependency assumptions
small number of runtime layers
clear version reporting and health checks

That is another reason integrated runtime stacks are attractive. They reduce the number of actors that can disagree with each other during install or upgrade.

Debugging Needs Structured Events, Not Just Logs

Agent incidents are usually multi-layer failures. A user says, "the tool froze while reviewing a PR." That can mean any of the following:

model request stalled
subprocess hung
sandbox denied access
file walker hit a symlink trap
output parser blocked on a stream
background task died without surfacing an error

If your runtime and harness do not emit structured execution events, debugging becomes guesswork.

A serious agent product should be able to record a session trail like:

command selected
policy decision made
subprocess started
timeout threshold reached
cancellation signal sent
subprocess exit observed
stderr classified
model resumed with summarized result

That is not overengineering. It is what makes support and reliability work possible once real developers adopt the tool.

The Ecosystem Tradeoff Still Has Teeth

This is where Node keeps its strongest argument. Mature ecosystems are full of ugly compatibility knowledge that newer stacks do not have yet. For some products, that matters more than startup speed or surface reduction.

A rough decision split looks like this:

Bun is attractive when you want:

low-friction CLI installs
fast interactive startup
tighter control over distribution
fewer runtime layers to debug
an execution model optimized for modern JS tooling

Node is safer when you need:

maximum compatibility with older packages
enterprise environments with conservative assumptions
broader support for obscure integrations
fewer unknowns around long-tail ecosystem behavior

That is the real comparison. Not speed chart versus speed chart. Just which runtime gives the product team fewer failure classes they cannot control.

What Claude Code’s Runtime Choice Actually Teaches

The lesson from Claude Code is not that Bun is the future of everything. The lesson is that agentic tools are forcing runtime decisions to become product decisions.

When your tool is terminal-native, model-driven, subprocess-heavy, and safety-sensitive, the runtime is no longer just an implementation detail. It shapes install quality, latency, command execution, sandbox design, and incident response. That is a different bar than most app developers are used to.

My recommendation is straightforward.

If you are building a coding agent or local AI operator, evaluate runtimes in this order:

Does it make first-run success easier?
Does it make subprocess execution predictable?
Does it cooperate with sandboxing and permission policy?
Does it simplify packaging and updates?
Does it make operational debugging easier under failure?
Only then ask about broad ecosystem preference or benchmark bragging rights.

By that standard, Bun is a serious runtime choice for agentic tooling, and the Bun plus Rust direction makes strategic sense. It is aiming at exactly the surfaces that hurt local AI tools most.

But do not copy the move blindly. If your product depends on ecosystem breadth more than runtime control, Node may still be the better engineering choice. If your product lives or dies on install quality, CLI responsiveness, and subprocess reliability, the Bun-style bet becomes much easier to justify.

The clean decision rule is this: pick the runtime that reduces user-facing operational friction, not the one that wins the loudest benchmark debate. For coding agents, that usually means the runtime that makes the tool easier to install, safer to run, and less mysterious to debug when it fails.

Read the full post on QCode: https://qcode.in/claude-code-on-bun-agentic-tools-runtime-choices/

Keeping Laravel Projects Findable When Local Work Starts to Sprawl

Saqueib Ansari — Sat, 25 Jul 2026 04:23:11 +0000

If you keep more than a handful of Laravel apps on your machine, the real problem is not php artisan serve. It is finding the right project fast enough to stay in flow.

That sounds minor until you are juggling client work, experiments, internal tools, and old repos with nearly identical names. Then the waste compounds: wrong .env, wrong database, wrong branch, wrong terminal tab, wrong PHP version, wrong queue worker. The fix is not another bookmark folder. The fix is a local project workflow that makes Laravel apps discoverable, identifiable, and safe to switch between.

My recommendation is simple: treat local Laravel projects like an indexed system, not a pile of folders. Use consistent naming, one searchable project root, machine-readable metadata, and a small layer of shortcuts. Once you do that, project sprawl stops feeling like chaos and starts feeling operational.

Start With a Single Project Map

Most Laravel sprawl begins with random placement. One app lives in ~/Code, another in ~/Sites, two more inside a client archive folder, and one odd internal tool is buried under Desktop/new-final-final. No launcher can fix a layout that has no rules.

The first move is to create a single top-level convention for active work. That does not mean every repo must physically live in one folder, but your active Laravel estate should follow one predictable structure.

A pragmatic layout looks like this:

~/work
  /clients
    /acme-billing-api
    /acme-admin-portal
    /northwind-dashboard
  /products
    /qcode-cms
    /internal-ops
  /experiments
    /laravel-octane-bench
    /rag-prototype
  /archive
    /old-client-portal

This is intentionally boring. That is the point. A naming scheme should remove decisions, not create branding opportunities.

A few rules matter more than people think:

Put project type or ownership in the path: clients, products, experiments, archive.
Make folder names globally unique on your machine.
Stop using vague names like admin, backend, api, or new-app without context.
Move dead repos to archive so search results stay clean.

The useful shift here is cognitive. You are no longer asking, "Where did I put that Laravel app?" You are asking, "Which bucket should this live in?" That question is much cheaper.

Name Projects for Retrieval, Not Aesthetics

A lot of local confusion comes from pretty repo names that are terrible search keys. pulse, forge, core, platform, studio, dashboard all sound fine until you have six unrelated projects with overlapping intent.

Local naming needs to optimize for retrieval under pressure. When you are in Spotlight, Raycast, Alfred, a shell fuzzy finder, or a menu bar launcher, you want project names that disambiguate themselves immediately.

A better pattern is:

{owner-or-domain}-{app-name}-{role}

Examples:

acme-inventory-api
acme-inventory-admin
northwind-client-portal
qcode-content-pipeline
internal-support-desk

That may look slightly longer, but it pays for itself every single day. Long names are not the problem. Ambiguous names are the problem.

What Good Names Prevent

Good naming does more than help search. It prevents operational mistakes.

If you have both acme-api and acme-admin, you are less likely to run migrations in the wrong repo than if both directories are called some variation of backend. If one app is archived, the path itself tells you that before you even open it.

This also helps with Git branch lists, terminal prompts, Docker container names, and editor workspace tabs. A strong project name keeps paying rent across the whole toolchain.

My rule: if a folder name cannot tell you who it belongs to and what it does, rename it.

Add Lightweight Project Metadata

Folder structure gets you halfway. The next step is to make each Laravel app self-identifying.

When you open a repo after three weeks away, you should be able to answer these questions instantly:

Which PHP version does it need?
Does it use Valet, Herd, Sail, or a custom Docker stack?
Which database does it talk to locally?
Which branch is considered safe or default?
Are queues, Horizon, Reverb, or Vite expected to be running?

Do not keep that in your head. Put it in the repo or alongside it.

A simple approach is a small machine-friendly file like .project-meta.json or a short PROJECT.md at the root.

{
  "name": "acme-inventory-admin",
  "runtime": "laravel-herd",
  "php": "8.3",
  "node": "22",
  "database": "acme_inventory_admin",
  "default_branch": "main",
  "services": ["vite", "queue"],
  "notes": "Uses S3-compatible local storage and requires Redis"
}

This is not about documentation theater. It is about making the project indexable by scripts and readable by humans.

For example, a launcher script can parse that file and tell you whether the app expects Sail or whether it should open a terminal and start npm run dev. Even if you never automate it, the metadata reduces hesitation.

The Hidden Win: Safer Context Switching

Most local friction is really context switching risk. You are not slow because cd is hard. You are slow because every project switch carries uncertainty.

That uncertainty creates annoying habits:

opening .env to double-check the database
checking php -v because older apps might break
searching old notes for the right local URL
guessing whether this repo uses npm run dev or composer dev

A tiny metadata file turns those repeated checks into one glance. That is a real workflow improvement, not a cosmetic one.

Use Searchable Shortcuts, Not Memory

Once your folders and names are sane, add a thin shortcut layer. This is where a launcher, menu bar app, Raycast script, shell function, or even fzf becomes genuinely useful.

The mistake is relying on memory first and tools second. Flip that. Assume you will not remember where the project lives or what command it needs. Build the lookup path so it is faster than remembering.

A shell-based version is enough for most developers.

# ~/.zshrc
lp() {
  local root="$HOME/work"
  local project
  project=$(find "$root" -maxdepth 3 -type d \( -name .git -prune \) -o -name artisan -print 2>/dev/null | \
    sed 's#/artisan##' | \
    fzf --prompt='Laravel project > ' --height=40%)

  [ -z "$project" ] && return
  cd "$project" || return
  echo "Switched to: $project"
}

That function is intentionally simple. It finds directories containing artisan, lets you fuzzy-search them, and drops you into the chosen app.

You can extend it without turning it into a framework:

show branch name in the picker
preview .project-meta.json
open in Cursor or VS Code automatically
copy the local URL
start the expected services

If you prefer GUI tools, the same logic applies. A menu bar app or launcher is useful when it is backed by your conventions. Without that, it is just a prettier search box.

Example: From Finder Hunting to One Command

Before a real workflow:

Open Finder.
Search for a client name.
Open the wrong repo first.
Check .env.
Open the terminal.
Realize the app actually lives in another folder.

After a real workflow:

Run lp.
Type acme adm.
Land in acme-inventory-admin with the right context.

That difference sounds trivial. It is not. Across dozens of switches per week, it is the difference between feeling sharp and feeling scattered.

Standardize Local Runtime Entry Points

A discoverable project is still annoying if every repo boots differently. One Laravel app wants composer run dev, another needs php artisan serve, another uses Sail, and one ancient client project still expects Valet plus a manual queue worker.

You do not need to eliminate those differences entirely, but you should normalize the entry point.

The cleanest pattern is to make every project support one obvious startup command, even if the internals differ.

For example, add a make dev, just dev, or Composer script per repo:

{
  "scripts": {
    "dev": [
      "Composer\\Config::disableProcessTimeout",
      "php artisan serve",
      "php artisan queue:listen --tries=1",
      "npm run dev"
    ]
  }
}

For Sail-based apps, your shortcut can still show dev, but the implementation may call Docker instead. The external interface stays stable.

That matters because the brain remembers one action per project category much better than a pile of exceptions.

Where Teams Usually Get This Wrong

They document startup steps in a README and call it done. That helps onboarding, but it does not solve day-to-day retrieval. The local workflow still depends on recall.

A better rule is:

README explains the stack.
metadata describes the local context.
one standard command starts the app.
your launcher or shell function exposes both.

This is the difference between documentation and operations.

Make Wrong-Project Mistakes Harder

The real danger in project sprawl is not wasted seconds. It is doing the right action in the wrong repo.

That is how people run a migration against the wrong local database, delete seed data they needed, or commit to a stale branch they forgot existed.

You should make those mistakes harder by default.

Practical safeguards:

Show the project name and Git branch in your shell prompt.
Use distinct local database names per app, never shared generic names like app or laravel.
Put the app name in .env values where it helps, such as Redis prefixes or queue names.
Add a visible APP_NAME that makes the browser tab unmistakable.
Keep archived apps out of your active search scope.

A Good Safety Pattern

If you work on many similar client dashboards, create an environment check command that tells you exactly where you are before destructive work:

php artisan about
php artisan env
git branch --show-current

Better yet, wrap it:

ctx() {
  echo "Project: $(basename "$PWD")"
  echo "Branch:  $(git branch --show-current 2>/dev/null)"
  php artisan env 2>/dev/null
}

Run ctx before migrations, bulk imports, queue restarts, or search-and-replace work. It is a tiny habit, but it kills a surprising number of avoidable mistakes.

Build the Workflow in Layers

Do not over-engineer this on day one. The right approach is layered.

Start with the minimum system that solves the actual problem:

One predictable folder structure.
Clear, searchable names.
Basic project metadata.
One fuzzy shortcut or launcher.
One standard local startup command.

That alone will clean up most Laravel project sprawl.

Only after that should you add richer tooling like a menu bar index, auto-detected local URLs, branch-aware launchers, or project dashboards. Those are useful, but they are multipliers. They are not the foundation.

This is why many local productivity tools disappoint. They try to become the solution while your filesystem, naming, and runtime conventions remain inconsistent underneath. Tooling helps, but tooling cannot rescue chaos you chose to keep.

The Practical Rule

If you regularly work across multiple Laravel codebases, stop treating project discovery as an informal habit. Turn it into a system.

The winning setup is not complicated: stable paths, explicit names, lightweight metadata, searchable shortcuts, and standardized startup commands. That combination removes friction without adding ceremony.

If you only change one thing this week, rename your ambiguous repos and put active Laravel apps under a single indexed root. That one move usually exposes the rest of the mess quickly, and once you can find projects reliably, every other local workflow improvement gets easier.

Read the full post on QCode: https://qcode.in/laravel-project-sprawl-keep-local-apps-findable/

AI Labels Aren’t Enough. Technical Writing Needs Better Signals

Saqueib Ansari — Thu, 23 Jul 2026 03:50:54 +0000

I’m in favor of labeling AI-generated technical content. That part is easy. The harder part is admitting that the label is not the thing that protects readers.

A disclosure badge can tell me how an article was produced. It cannot tell me whether the author understands the system, whether the advice survived contact with production, or whether the piece contains any original thought at all. And if you publish for builders, those are the questions that matter.

That is the lesson I keep coming back to after reading more AI-assisted technical content, generating some of it, throwing plenty of it away, and tightening editorial standards around what should ship. The real trust signal is not “AI was used.” The real trust signal is evidence. Evidence of implementation. Evidence of tradeoff awareness. Evidence that the author has enough scar tissue to make a recommendation worth listening to.

That is why I think technical publishers should absolutely support disclosure, but stop pretending disclosure is a quality system. It isn’t. It is a transparency layer sitting on top of a much more important question: did anyone do the work?

Labels Matter, but Mostly for the Wrong Reason

The current debate around AI-generated articles is full of moral energy and very little operational thinking.

A lot of people treat labeling as if it solves authenticity. If the post says "AI-assisted," they feel informed. If it says nothing, they feel deceived. That response makes sense in broad consumer publishing, where readers may want to know whether they are reading a person’s direct expression or a generated composite.

Technical publishing works differently. Developers are not primarily consuming prose for self-expression. They are consuming it to make decisions. They want to know which tool to pick, which failure mode to expect, which architecture choice will age badly, and which pattern will save them from rework six weeks later.

For that kind of reading, the important distinction is not "human" versus "AI." The important distinction is earned guidance versus empty synthesis.

A human can produce empty synthesis all day. The internet has been full of it for years. We have all seen tutorial posts that walk through a framework feature without once explaining where it breaks. We have all seen "best practices" articles that are basically doc paraphrases with better formatting.

AI did not invent shallow content. AI industrialized it.

That is why labels feel emotionally satisfying but intellectually incomplete. They are describing the manufacturing process when the reader really needs an inspection report.

If an article says it was AI-assisted, fine. I learned something about the workflow. But I still do not know:

whether the examples were run or merely plausible
whether the recommendations came from real constraints
whether the author can distinguish a demo pattern from a production pattern
whether the piece contains any judgment beyond the statistical average of public writing on that topic

That is the gap. Disclosure tells me what touched the text. It does not tell me what touched reality.

Builders Don’t Need Purity, They Need Proof

When I read technical content now, I look for proof before I look for polish.

That proof does not have to come in one format. It can be code, a design tradeoff, a postmortem-style section, a benchmark caveat, a migration note, or even a strong opinion that obviously came from direct implementation pain. But something in the article has to prove that the author got close enough to the system to have learned something non-obvious.

This is the same instinct most good engineers already have in code review. If someone proposes a large architectural change and the rationale is purely abstract, experienced reviewers push back. They ask what problem happened, what load pattern exists, what operational burden changes, what rollback plan looks like, and what edge cases were considered.

Technical writing should be held to a similar standard.

What Operational Proof Looks Like

Operational proof is any part of the article that reveals real contact with the problem.

That might be:

a queue boundary introduced because synchronous handling actually timed out
a memory strategy changed because agent runs started contaminating later sessions
a caching layer removed because invalidation complexity outweighed the gain
a framework abstraction bypassed because observability disappeared at the worst possible point
a "simple" AI workflow replaced with evals because regressions kept slipping through review

The key is not that the author describes success. The key is that the author can describe why the first obvious version was not enough.

That is one reason I trust articles with failure sections more than perfectly linear tutorials. Failure sections leak real understanding. They expose what the system did under stress, what assumptions turned out to be false, and what compromise the final design accepted.

What Weak AI-Assisted Content Usually Gets Wrong

Weak AI-assisted technical writing often fails in a predictable way. It sounds complete one level too early.

The article has a decent title, a tidy structure, and correct surface-level terminology. But once you read closely, there is no pressure in it. No specific constraints. No hard choice. No section where the recommendation becomes costly. No explanation of where the pattern stops working.

That is why so much synthetic content feels strange even when it is factually acceptable. It is missing the parts that make technical advice expensive to learn.

I would rather read a rough article by someone who clearly fought the system than a polished article that never got past the default branch of thought.

The Editorial Standard Should Look More Like Code Review

If I were defining a modern editorial standard for a technical site, I would separate disclosure from trust scoring.

Disclosure is simple. Readers should know whether the article was heavily AI-assisted, lightly AI-assisted, or effectively human-authored with tooling around the edges. That is basic transparency.

Trust scoring is the real work. That is where the publication decides whether the piece deserves space.

A useful review pass might look like this:

article_review:
  disclosure:
    required: true
    values:
      - human_written
      - ai_assisted
      - ai_generated_draft_human_reviewed

  trust_signals:
    originality:
      pass_if: "The article adds a real argument, pattern, synthesis, or decision rule"
      fail_if: "It mostly restates docs, public opinions, or release notes"

    implementation_depth:
      pass_if: "The reader can see architecture choices, constraints, or concrete examples"
      fail_if: "Examples stay generic and transferable to any topic"

    operational_proof:
      pass_if: "The article exposes failure modes, tradeoffs, or evidence of hands-on use"
      fail_if: "The piece reads like theory without contact with systems"

    recommendation_strength:
      pass_if: "The article clearly tells the reader what to do in a specific context"
      fail_if: "It avoids judgment and hides behind neutrality"

    maintenance_honesty:
      pass_if: "The author explains what this approach costs over time"
      fail_if: "The article presents the pattern as universally good"

Notice what this does. It makes AI usage a tracked fact, not the central editorial event.

That is the right priority for developer publishing. A builder does not need a moral lecture about tooling. A builder needs help deciding whether a recommendation survives real usage.

Why This Standard Is Better Than a Badge

A badge rewards disclosure. A review rubric rewards substance.

That matters because once AI is normal inside editorial workflows, the temptation is to let the badge do too much work. The team can say, "We disclosed it," and mentally downgrade the need for deeper review. That is a mistake.

A disclosed bad article is still a bad article.

Worse, a visible label can create a false sense of fairness. Editors may think they are being responsible because they told readers the workflow. But from the reader’s point of view, the actual harm is not that AI was involved. The harm is that low-value content entered a trust channel wearing technical authority.

If a publication wants to preserve credibility, it should be much stricter about what counts as a publishable insight than about whether a first draft began in a text box.

Two “AI-Assisted” Articles Can Be Miles Apart in Value

This is the point most broad AI-content discussions flatten beyond usefulness. They talk as if "AI-generated article" describes a meaningful quality category. For technical readers, it doesn’t.

The label groups together outputs that may have radically different value.

Example 1: Same Label, No Insight

Take a hypothetical article called How to Build Reliable AI Features in Laravel.

It is labeled AI-assisted. Good. Transparent.

The body explains queues, retries, validation, and logging in clean prose. It mentions that prompts should be versioned. It says failures should be monitored. It warns that costs can rise. Every sentence is individually reasonable.

But there is no sign that the author built anything difficult.

The queue section never explains what job boundaries matter. The retry section ignores idempotency. The prompt-versioning note never connects to eval drift. The observability advice stops at "add logs" instead of showing which events actually surfaced useful failure signals. It is not wrong. It is just not carrying enough reality to change how a serious team would build the system.

That article will still rank, still sound competent to newcomers, and still waste a sharper reader’s time.

Example 2: Same Label, Real Engineering Value

Now take another article with the same AI-assisted label.

This one opens with a narrower claim: if your AI workflow spans external tools, human approval, and asynchronous retries, don’t model it like a request-response feature. Model it like a state machine with explicit checkpoints.

Immediately the author has made a real decision.

Then the piece explains how the first version failed. A controller triggered the LLM call directly, external tool execution made request time explode, and retry logic duplicated actions because the system had no durable operation state. The author shows the refactor into queued transitions and explains why completed, waiting_for_human, retry_scheduled, and failed_terminal became first-class states.

final class AdvanceAgentRun implements ShouldQueue
{
    public function handle(AgentRunService $runs): void
    {
        $run = $runs->loadForProcessing($this->runId);

        if ($run->status->isTerminal()) {
            return;
        }

        $result = $runs->advance($run);

        match ($result->nextState) {
            'waiting_for_human' => NotifyReviewer::dispatch($run->id),
            'retry_scheduled' => self::dispatch($run->id)->delay($result->retryAt),
            'completed' => PublishRunOutput::dispatch($run->id),
            'failed_terminal' => RecordRunFailure::dispatch($run->id, $result->reason),
            default => null,
        };
    }
}

The code by itself is not the value. The value is in the reasoning around it. The article explains why the service owns state progression, why idempotent transitions matter, why human review is represented as state instead of a side notification, and which metrics revealed the original design was unstable.

That piece teaches something because it contains implementation judgment.

Same label. Completely different signal.

If your publishing system cannot distinguish between those two articles, your labeling policy is not solving the actual problem.

The Real Failure Mode Is Unearned Authority

The most dangerous property of current AI writing tools is not hallucination. Hallucinations are at least obvious once they become concrete enough.

The deeper problem is unearned authority.

A model can produce tidy, plausible, strongly voiced prose without paying the normal cost of learning. That cost usually includes failed experiments, debugging, edge cases, re-architecture, and boring maintenance. When those costs are absent, the prose may still sound mature. That makes it easy for weak content to borrow the tone of experience without carrying the substance.

This is especially risky in technical publishing because tone matters a lot. Developers often use writing style as a shortcut for competence. A clear, opinionated article feels authoritative. That feeling used to correlate more strongly with actual expertise because writing polished technical prose was relatively expensive. Now the packaging cost has collapsed.

So the old instincts are less reliable.

That does not mean readers should distrust all AI-assisted content. It means editors and readers need better filters.

The Filter I Actually Use

When I am deciding whether a technical piece is worth publishing or trusting, I ask a few blunt questions:

What claim is this article making that would help someone act differently?
What evidence shows the author actually encountered the problem?
Where does the recommendation become expensive, annoying, or limited?
What part of this piece could not have been produced by averaging public explanations?
If I remove the style, is there still a transferable insight left?

That fifth question matters a lot. Plenty of AI-assisted posts are mostly style plus sequencing. They present familiar ideas in a clean order. That is not useless, but it is rarely enough for a publication trying to build durable trust.

A serious technical site should bias toward articles where the core value survives the removal of tone.

What Changed in My Own Workflow

Using AI seriously for writing made me much less romantic about authorship and much stricter about evidence.

At first, the obvious temptation was speed. Let the model draft the skeleton, expand the sections, smooth the transitions, and turn raw notes into a polished article. That workflow works well enough if your bar is generic competence.

It works badly if your bar is publication-grade insight.

The reason is simple: the model can make an unfinished argument look finished. It hides missing depth under fluency. It fills gaps with structurally correct filler. If you are busy, that feels like progress. In reality, it often pushes the hardest editorial questions out of sight.

The better workflow, at least for technical publishing, is to force proof in before fluency.

Drafting loop for technical articles:

1. Write the real claim in one sentence.
2. Add one failure mode that made the claim necessary.
3. Add one artifact from implementation: code, log, config, metric, or architecture note.
4. State where the recommendation stops being good.
5. Only then use AI to tighten sequencing, cut repetition, and improve flow.
6. Re-review every strong sentence for lived evidence.
7. Delete anything that sounds smart but cannot be defended.

That sequence changes the role of AI from ghost author to compression tool.

That is the only mode I trust for serious technical writing. Not because AI is incapable of generating coherent articles, but because technical credibility does not come from coherence. It comes from justified specificity.

Where Labels Still Earn Their Keep

I do think labels help in one important way: they tell the reader how suspicious to be of polish.

If an article is marked AI-generated draft, human-reviewed, I know to inspect the proof layer harder. I know the clean cadence of the writing is not itself evidence of expertise. That is useful information.

But it is only useful because I already know what better signals to look for next.

Without that second layer, the label becomes theater. It satisfies transparency norms without materially improving the reader’s ability to trust the advice.

The Standard Technical Publications Should Adopt

My view is straightforward.

Require disclosure. Review for substance. Publish only when the article proves contact with reality.

That means the article should usually contain some mix of:

an original recommendation or argument
clear implementation detail
at least one real failure mode or tradeoff
evidence that the author used or tested the pattern
a conclusion that changes how the reader should decide

If those are missing, the article is weak regardless of who typed the words.

If those are present, the AI label becomes contextual information instead of a credibility crisis.

That is where I’ve landed after spending more time with these tools: the enemy is not AI-assisted writing. The enemy is technical content that sounds authoritative without paying for authority.

So yes, label AI-generated articles. That is basic hygiene.

But if you are a builder, an editor, or a technical publisher, do not stop there. Ask the harder question every time: where is the proof?

That is the signal worth building around. That is the signal readers actually need. And that is the standard that will still matter long after AI disclosure itself becomes routine.

Read the full post on QCode: https://qcode.in/ai-generated-technical-content-needs-better-signals/

Streaming AI in Laravel without fighting Livewire

Saqueib Ansari — Wed, 22 Jul 2026 04:20:42 +0000

Streaming tokens is the easy demo. Shipping a chat UI that feels native inside a Laravel product is the hard part.

Most teams get the first 20 percent working fast: call a model, stream text, print it into a box. Then the UX starts breaking in ways users notice immediately. The scroll jumps while they are reading. Stop does not really stop. A failed request leaves a half-answer that looks finished. Retry duplicates messages. Livewire keeps re-rendering the whole thread for every tiny chunk and the interface starts feeling sticky.

If you want Laravel AI streaming to feel production-ready, the core rule is simple: streaming is a state-management problem first, and a rendering problem second. Treat partial output as temporary UI state, keep durable message state explicit, and let Livewire coordinate structure instead of repainting the world on every token.

This tutorial walks through a practical architecture that handles the parts that actually matter: partial tokens, cancellation, retries, scroll behavior, optimistic UI, and failure states. The goal is not a flashy demo widget. The goal is a chat experience that feels like it belongs in a real SaaS product.

The Baseline Architecture That Does Not Fight Livewire

The first mistake is letting the provider stream drive your UI model directly. If your frontend is just “whatever tokens arrived so far,” you have no clean answer for cancellation, reconnects, or partial persistence.

A better mental model is to split the system into three layers:

durable chat state in Laravel and your database
transient stream state in the browser
provider transport hidden behind a service class

That sounds boring, and that is exactly why it works.

What Should Be Durable

At minimum, each message in your database should store:

chat_id
role
content
status
sequence
error_message or error_code
timestamps

The important field is status. Do not reduce assistant output to “message exists or does not exist.” You want explicit lifecycle states such as:

queued
streaming
completed
cancelled
failed

That gives your UI real semantics. A streaming message can show a stop button and cursor. A failed message can show retry. A cancelled message can remain visible without pretending the answer finished cleanly.

What Should Stay Transient

The browser should own the temporary token buffer for the active assistant message. That buffer is not durable truth. It is presentation state.

This distinction matters because users do not care whether token 147 reached the DOM. They care that the final message state is predictable. If the stream dies halfway through, the UI should know whether that partial text is recoverable, cancelled, or failed. A raw stream alone cannot tell you that.

What Livewire Should Actually Do

Use Livewire for:

submitting the user message
rendering the stable message list
reflecting durable status changes
exposing actions like stop and retry

Do not use Livewire for ultra-high-frequency token painting if that means re-rendering the component on every chunk. Livewire is excellent at server-driven structure. It is not the best place to diff and repaint a whole thread 20 times per second.

The official Livewire docs and Laravel broadcasting docs give you the primitives. The real design choice is responsibility: Livewire owns the structure, a small client-side layer owns the active stream buffer, and your AI client owns provider-specific transport.

Build The Message Lifecycle Before You Build The Pretty UI

This is the step teams skip because it feels like backend ceremony. It is also the step that prevents weeks of ugly edge-case cleanup later.

When a user sends a prompt, the sequence should be deliberate.

Persist the user message.
Create an empty assistant message shell with status = streaming.
Start the provider stream.
Append chunks into a transient buffer in the browser.
On clean completion, persist the final content and mark completed.
On user stop, mark cancelled and halt the stream loop.
On failure, preserve what you have, mark failed, and expose retry.

That is the real lifecycle. Everything else is UI polish.

A Practical Service Boundary

Wrap your model provider behind a small interface. Even if you are only targeting one provider today, you will want this abstraction the moment you add fallback models, custom logging, or a non-streaming retry path.

<?php

namespace App\AI;

use App\Models\Chat;
use App\Models\Message;
use Generator;

interface StreamsResponses
{
    /**
     * @return Generator<int, StreamChunk>
     */
    public function stream(Chat $chat, Message $userMessage): Generator;
}

A chunk object can stay tiny:

<?php

namespace App\AI;

final class StreamChunk
{
    public function __construct(
        public readonly string $type,
        public readonly string $text = '',
        public readonly array $meta = [],
    ) {}

    public static function token(string $text): self
    {
        return new self(type: 'token', text: $text);
    }

    public static function done(array $meta = []): self
    {
        return new self(type: 'done', meta: $meta);
    }
}

The Laravel service that orchestrates a single assistant turn can then focus on state transitions instead of provider mechanics.

<?php

namespace App\Actions\Chat;

use App\AI\StreamsResponses;
use App\Events\ChatStreamChunked;
use App\Events\ChatStreamFinished;
use App\Models\Chat;
use App\Models\Message;
use Throwable;

final class StreamAssistantReply
{
    public function __construct(private StreamsResponses $client) {}

    public function handle(Chat $chat, Message $userMessage): Message
    {
        $assistant = $chat->messages()->create([
            'role' => 'assistant',
            'content' => '',
            'status' => 'streaming',
            'sequence' => $chat->messages()->max('sequence') + 1,
        ]);

        $buffer = '';

        try {
            foreach ($this->client->stream($chat, $userMessage) as $chunk) {
                if ($assistant->fresh()->status === 'cancelled') {
                    break;
                }

                if ($chunk->type === 'token') {
                    $buffer .= $chunk->text;

                    broadcast(new ChatStreamChunked(
                        chatId: $chat->id,
                        messageId: $assistant->id,
                        text: $chunk->text,
                    ));
                }
            }

            $assistant->update([
                'content' => $buffer,
                'status' => $assistant->fresh()->status === 'cancelled'
                    ? 'cancelled'
                    : 'completed',
            ]);

            broadcast(new ChatStreamFinished(
                chatId: $chat->id,
                messageId: $assistant->id,
                status: $assistant->status,
            ));

            return $assistant->fresh();
        } catch (Throwable $e) {
            $assistant->update([
                'content' => $buffer,
                'status' => 'failed',
                'error_message' => str($e->getMessage())->limit(300),
            ]);

            broadcast(new ChatStreamFinished(
                chatId: $chat->id,
                messageId: $assistant->id,
                status: 'failed',
            ));

            throw $e;
        }
    }
}

There are two details here that matter more than the rest.

First, the database stores the final message and final status, not every token. Second, the loop checks for cancellation between chunks. If your provider supports a true abort signal, use it. If not, a cooperative cancellation check still gives you sane behavior.

Let The Browser Paint Tokens, Not The Entire Livewire Component

This is the part that usually wrecks UX.

If every token update becomes a full Livewire re-render, your app starts doing expensive work for trivial changes. That creates flicker, scroll instability, and wasted network chatter. It also makes the component harder to reason about because durable state and transient state are tangled together.

The fix is not to abandon Livewire. The fix is to give the browser a tiny local stream store.

The Responsibility Split

Use Livewire to render a message list with stable containers. Then use Alpine or a small vanilla JS store to append streamed text only into the active message node.

That gives you three benefits immediately:

the message tree stays structurally stable
token updates touch one DOM node instead of a whole component
final persistence still flows through Laravel cleanly

A simple Blade shape might look like this:

<div x-data="chatStream(@js($chat->id))" class="flex h-full flex-col">
    <div x-ref="scroller" class="flex-1 overflow-y-auto">
        @foreach ($messages as $message)
            <article wire:key="message-{{ $message->id }}" class="mb-4">
                <div class="text-xs text-slate-500">{{ $message->role }}</div>

                <div class="prose max-w-none">
                    @if ($message->status === 'streaming')
                        <div data-stream-id="{{ $message->id }}">{{ $message->content }}</div>
                    @else
                        <div>{!! nl2br(e($message->content)) !!}</div>
                    @endif
                </div>

                @if ($message->status === 'failed')
                    <button wire:click="retry({{ $message->id }})">Retry</button>
                @endif
            </article>
        @endforeach
    </div>
</div>

Then let a tiny client-side store handle incremental updates.

<script>
function chatStream(chatId) {
    return {
        buffers: {},
        followStream: true,

        init() {
            const scroller = this.$refs.scroller;

            scroller.addEventListener('scroll', () => {
                const distance = scroller.scrollHeight - scroller.scrollTop - scroller.clientHeight;
                this.followStream = distance < 120;
            });

            window.Echo.private(`chat.${chatId}`)
                .listen('.chat.stream.chunked', (event) => {
                    this.append(event.messageId, event.text);
                })
                .listen('.chat.stream.finished', (event) => {
                    this.finish(event.messageId, event.status);
                });
        },

        append(messageId, text) {
            if (!this.buffers[messageId]) {
                this.buffers[messageId] = '';
            }

            this.buffers[messageId] += text;

            const node = document.querySelector(`[data-stream-id='${messageId}']`);
            if (node) {
                node.textContent = this.buffers[messageId];
            }

            if (this.followStream) {
                this.$nextTick(() => {
                    this.$refs.scroller.scrollTop = this.$refs.scroller.scrollHeight;
                });
            }
        },

        finish(messageId) {
            delete this.buffers[messageId];
        }
    }
}
</script>

This is not fancy. That is the point. You want the smallest possible client-side layer that can own the active token buffer without dragging the rest of the UI into every incremental update.

Why This Pattern Holds Up Better

This hybrid setup lets you solve real problems cleanly:

a page refresh still restores durable messages from the database
a cancelled stream can stop visually without corrupting history
a failed stream can leave partial content plus an honest status
retry can create a fresh assistant message without DOM gymnastics

That is what “AI feels native in Laravel” actually means. It means the chat behaves like the rest of your product, not like a lab experiment glued into a Blade file.

Handle Stop, Retry, And Duplicate Submission Like They Will Break In Production

Because they will.

These are not edge cases once users start relying on the feature. They are standard paths.

Cancellation Should Be Cooperative And Immediate

A stop button that only hides a spinner is fake cancellation. Users notice.

When the user clicks stop:

update the message status to cancelled immediately
stop showing the streaming cursor in the browser
make the server stream loop notice the cancellation flag
persist whatever partial content you want to keep

In many products, preserving partial content is the better choice. It gives the user something to reference and makes the stop action feel honest instead of destructive.

A simple Livewire action can be enough:

public function stop(int $messageId): void
{
    Message::query()
        ->whereKey($messageId)
        ->where('status', 'streaming')
        ->update(['status' => 'cancelled']);
}

If your provider SDK supports request abortion, wire that in too. But even without transport-level abort, cooperative cancellation still improves UX dramatically because the message state turns truthful immediately.

Retries Should Create A New Assistant Turn

Do not mutate a failed assistant message in place. That makes conversation history ambiguous and complicates debugging.

A retry should usually reuse the same user message context while generating a fresh assistant message shell. That gives you a clean before-and-after trail:

first attempt failed
second attempt succeeded

That history is useful for support, observability, and user trust.

A practical retry rule is:

keep the failed message visible
disable duplicate retries while one is active
create a new assistant placeholder
stream into the new placeholder

If you want a cleaner timeline, you can visually group retries in the UI. But do not rewrite history at the database level just to make the thread look prettier.

Idempotency Is Not Optional

Users double-click. Mobile connections stutter. A request can time out client-side while still running server-side. If you do not add idempotency, you will end up with duplicate assistant turns for the same prompt.

The safest move is to generate a per-submission idempotency key on the client and persist it with the user message or turn record.

Then enforce a rule like this:

if a submission with the same key already exists and is still active, return the active state instead of starting another stream
if it completed, reload the result
if it failed, let the UI offer explicit retry

That single guard prevents a lot of messy “why did the bot answer twice?” bugs.

Scroll Behavior And Error Handling Are Where The UX Either Feels Calm Or Cheap

Bad scroll behavior destroys trust faster than most model mistakes. It makes the interface feel unstable.

Follow Only When The User Wants To Follow

The rule is simple: auto-scroll only if the user is already near the bottom. If they scroll upward to read something, stop following the stream and show a small “jump to latest” affordance instead.

This is better than unconditional auto-scroll because it respects intent. The user is telling you they want context, not motion.

A threshold-based check is enough in most apps:

function isNearBottom(container, threshold = 120) {
    const distance = container.scrollHeight - container.scrollTop - container.clientHeight;
    return distance < threshold;
}

Do not over-engineer this. You do not need a scroll physics engine. You need a sensible rule and consistent behavior.

Render Errors With Useful Honesty

AI chat fails in several distinct ways:

the provider rejected the request
the stream disconnected before completion
your application failed while saving or broadcasting
the user cancelled intentionally

Those should not all surface as “Something went wrong.” That message is content-free.

Instead, make the UI specific enough to guide the next action:

Response stopped before completion. Retry from the last prompt.
Model provider rejected the request. Try again or switch models.
Reply could not be saved. Refresh the thread before retrying.
Generation stopped by you.

The user does not need your exception trace. They do need a clear explanation of what state the message is in and what action is available next.

Keep Diagnostics On The Server

The UI should be clean. Your logs should not.

Track at least:

provider name and model
time to first token
total duration
stop reason
failure class
token or usage metadata where available

If you want to improve your AI feature later, these metrics matter more than vague intuition. They help you answer practical questions like whether a model is too slow for your UX budget, whether one provider fails more often during peak times, or whether a long-running generation path needs a fallback.

The official Laravel logging and queue monitoring patterns are enough to start. You do not need a huge observability platform on day one. You do need structured events and enough metadata to reconstruct a broken session.

The Production Version Is Smaller And Stricter Than Most Demos

A lot of AI demos look impressive because they ignore the hard parts. Real Laravel products need the opposite mindset.

The production-ready version is usually stricter, not bigger:

one active assistant message per turn
explicit message statuses
browser-owned transient token buffer
Livewire-owned durable thread structure
cooperative cancellation
retry as a new assistant turn
auto-scroll only when the user stays near the bottom
honest error states
idempotency for submissions

That stack is enough to make a chat UI feel solid.

What usually does not matter early:

token-by-token Markdown rendering
animated typing gimmicks
fancy streaming cursors
complex optimistic threading across multiple parallel generations

Those features are nice later. They are not the foundation.

If you are building this now, start with the simplest shape that preserves truth:

persist user message
create assistant shell with streaming
append chunks in the browser only
finalize content and status in Laravel
support stop, retry, and scroll intent before adding polish

That order matters. It keeps your UI calm and your code understandable.

The practical decision rule is this: if a streamed token would force you to rewrite durable state on every update, your architecture is too coupled. Keep the stream transient, keep message states explicit, and let Livewire do what it does best: coordinating stable server-driven UI.

That is how you ship Laravel AI streaming without wrecking Livewire UX.

Read the full post on QCode: https://qcode.in/how-to-stream-ai-responses-in-laravel-without-wrecking-livewire-ux/

When local LLMs are actually worth using for agentic development

Saqueib Ansari — Tue, 21 Jul 2026 04:53:47 +0000

Most developers get interested in local models for the wrong reason. They see a demo of a respectable model running on a laptop, watch tokens stream in a terminal, and jump straight to the conclusion that hosted models are now optional.

That is not the right takeaway.

The real question in local LLMs for agentic development is not whether a local model can answer coding questions. The real question is whether it can hold up inside an agent loop where the costs come from retries, bad tool calls, long context, flaky structured output, and operator glue.

My recommendation is opinionated on purpose: local models make sense when the agent job is narrow, high-volume, privacy-sensitive, and easy to verify. Hosted models still win when the work is open-ended, tool-heavy, cross-file, or expensive to get wrong. If you design around that boundary, local models can be genuinely useful. If you ignore it, they become an attractive source of hidden engineering tax.

The local case gets stronger when the task is smaller than the hype

A lot of agent discussions quietly assume every useful workflow looks like a repo-wide coding assistant. That assumption makes local models look weaker than they are and hosted models look cheaper than they really are.

Most real agent systems are made of smaller jobs.

A coding agent may have a frontier model for planning, but it often still needs cheaper inner-loop work: classify a request, rewrite a search query, validate tool arguments, summarize logs, rank candidate files, or normalize output into a schema. Internal automation flows look similar. They route tickets, extract fields, score risk, rewrite drafts, or apply guardrails before a more capable model touches the hard part.

That matters because local models do not need to beat hosted models at everything. They only need to beat them at the specific layer they own.

Privacy is not just a compliance bullet point

If the workflow touches internal code, unreleased features, ops notes, customer data, or messy business logic, local inference changes the trust boundary immediately. You are no longer shipping every intermediate thought and prompt fragment to an external API. For some teams that is the entire justification.

This is especially relevant for:

internal coding copilots over proprietary repos
support or sales automations over sensitive account notes
incident-analysis tools that touch logs and infrastructure context
enterprise environments where data routing alone triggers review overhead

Of course, local does not magically mean secure. You still need to care about who can access the host, where model files came from, whether prompts or outputs are logged, and how the inference service is exposed on the network. But the privacy advantage is real. It is architectural, not cosmetic.

Latency feels different when the model is part of a loop

A single hosted call can be fast enough that local inference barely matters. But agentic systems rarely make one clean call.

They do this instead:

classify the task
decide whether a tool is needed
shape tool arguments
validate the arguments
inspect the result
summarize or transform the result
maybe retry with a narrower instruction

When the system behaves like that, round-trip overhead accumulates. Local models become interesting because they can make the cheap parts of the loop feel immediate. That does not just save time. It changes product behavior. You become more willing to add validation, scoring, filtering, or preflight checks when those checks are fast and nearly free.

Cost gets distorted if you only compare one prompt to one prompt

Teams regularly underestimate the number of LLM calls hiding behind a single user-visible action. An “answer this” feature may actually trigger multiple invisible operations. A coding agent may reason, search, rewrite its search, summarize files, rank edits, validate commands, and then draft the final answer.

That is why local models can become compelling even when their raw quality is lower. If you can move repetitive low-risk calls off the expensive path, the economics change fast.

The mistake is thinking this means “replace the hosted model.” Usually it means “stop wasting the hosted model on mechanical work.”

Where local models usually fail first in agent systems

If you have only used local models for chat or autocomplete, it is easy to miss where the pain starts. The hard part is rarely the first answer. The hard part is what happens after the system has to do something.

Tool-calling reliability is the real dividing line

Most agentic systems do not fail because the model writes an ugly paragraph. They fail because the model cannot behave like a dependable orchestrator.

Common failure modes look like this:

the model picks the wrong tool because two tools look semantically similar
it emits malformed JSON that is almost correct but not machine-safe
it invents optional parameters that should have been left empty
it skips the tool and answers directly with false confidence
it mishandles the result of a previous tool call and compounds the mistake
it loses track of the contract after several turns and drifts into free-form text

This is where hosted frontier models still hold a major advantage. They are usually better at maintaining structure across longer loops, recovering after a tool failure, and keeping the output inside the agreed schema.

That matters more than eloquence. In an agent system, schema discipline beats pretty prose.

Hardware limits show up exactly when the task gets useful

Running a model locally is not the same as running it comfortably.

The first local success usually happens under flattering conditions: small prompt, single user, fresh process, low concurrency, and no complicated retrieval chain. Real agent workflows are harsher. They grow context. They retry. They juggle multiple requests. They compete with embeddings, indexing, editor tooling, and background jobs.

That is when hardware starts setting product limits.

A modest local setup can feel great for:

short classification prompts
log summarization
structured extraction
guardrail checks
shallow code explanation

The same setup can feel miserable for:

large cross-file reasoning
long-running coding sessions
multi-turn tool orchestration
concurrent background workers
anything that depends on generous context windows remaining fast

This is why “it runs on my machine” is a weak success metric. The only meaningful test is whether it runs fast enough, predictably enough, on the actual workload shape you intend to ship.

The hidden cost is not inference. It is operator glue

Local-first experiments often look cheap until you count the engineering around them.

To make a local model usable inside an agent pipeline, you may need:

prompt variants per model family
stricter schema validators
repair passes for malformed output
fallback routing when confidence is low
queuing or concurrency control for the host machine
monitoring around throughput and latency
carefully tuned context limits
different sampling settings for different task classes

That work is not a temporary inconvenience. It is the price of operationalizing a weaker or narrower model surface.

If your team does not want to own that layer, hosted models are often the cheaper option even when the per-token bill looks worse.

The best use cases are narrower, more boring, and more profitable

Local models become much more valuable once you stop asking them to be a general-purpose teammate and start treating them like bounded infrastructure.

That means giving them jobs with tight contracts, strong verification, and low ambiguity.

Good local jobs: inner-loop agent work

The best candidates usually share four properties:

the task is repetitive
the prompt shape is stable
the output can be validated
failure is cheap or recoverable

Examples that fit well:

rewriting user requests into better retrieval queries
classifying tickets or issue reports into workflows
extracting fields from bug reports or docs
checking whether a proposed tool action matches user intent
summarizing repetitive logs or CI output
ranking likely files before a stronger model does deeper reading
generating low-risk boilerplate such as test skeletons or changelog drafts

None of these are glamorous. That is why they work.

Weak local jobs: high-ambiguity operator work

Local models are much less attractive when the task depends on broad judgment rather than bounded pattern handling.

Examples that still strongly favor hosted frontier models:

repository-wide refactors in unfamiliar codebases
production debugging with sparse or conflicting evidence
multi-step tool use where one wrong action widens blast radius
customer-facing writing where both polish and correctness matter
architecture advice from incomplete requirements
long-horizon planning across several files, commands, and retries

That does not mean a local model cannot occasionally succeed there. It means the error budget is worse. One bad tool call or one false assumption costs more than the inference savings.

A practical decision filter

If you want a short rule, use this one:

Low ambiguity + easy verification: local is a strong candidate
Medium ambiguity + structured output: local can work with fallback
High ambiguity + expensive failure: start hosted

That filter is more useful than asking whether a given model is “good at coding.” Agentic development is about workflow economics, not leaderboard identity.

The winning architecture is usually hybrid, not ideological

The cleanest way to use local models is to stop framing the decision as local versus hosted. In most serious systems, the right answer is a routed stack.

Use local for cheap, frequent, narrow work. Escalate to hosted for reasoning-heavy or risk-heavy steps.

Route by risk, not by excitement

A simple router already gets you most of the value.

from dataclasses import dataclass

@dataclass
class AgentTask:
    kind: str
    prompt_tokens: int
    needs_tools: bool
    risk: str  # low, medium, high
    user_visible: bool


def route(task: AgentTask) -> str:
    if task.risk == "high":
        return "hosted_frontier"

    if task.needs_tools and task.prompt_tokens > 6000:
        return "hosted_frontier"

    if task.kind in {"classify", "extract", "guardrail", "rewrite", "summarize"}:
        return "local_model"

    if task.user_visible:
        return "hosted_mid_tier"

    return "local_model"

This is intentionally boring. That is a feature. Reliable systems are often built from boring boundaries.

The point is not to create a perfect classifier. The point is to stop paying frontier-model prices for work that does not need frontier-model judgment.

Use local as a guardrail layer

One of the best patterns is to put local models in front of risky actions rather than asking them to own the whole workflow.

Suppose a coding agent wants to run a command or edit a set of files. A smaller local model can check:

does the proposed action match the original request?
does the scope look wider than necessary?
do the parameters look malformed or suspicious?
should the system force a human confirmation?

That is a much easier task than planning the whole coding session.

Example of a validation payload:

{
  "user_request": "Fix the failing auth tests without touching production login flow.",
  "proposed_action": {
    "type": "edit_files",
    "files": [
      "tests/Feature/Auth/LoginTest.php",
      "app/Http/Controllers/LoginController.php"
    ]
  },
  "checks": {
    "intent_match": true,
    "scope_too_broad": false,
    "needs_confirmation": true,
    "reason": "Production auth controller is in scope; request mentioned tests first."
  }
}

A local model does not need deep architectural brilliance to perform this kind of review. It just needs a stable prompt and a hard schema.

Keep the escalation path cheap

The hybrid pattern only works if escalation is easy.

Do not build a local-first system that treats fallback as embarrassment. Treat it as normal control flow.

That means:

preserve the task state so a hosted model can continue cleanly
keep structured artifacts from the local pass
log why the task was escalated
avoid rewriting the whole prompt stack at handoff time

A good fallback path makes local models useful. A bad fallback path turns them into latency before the “real” model.

What to benchmark before you commit to a local-first agent layer

Too many local-model experiments get approved on feel. The demo is fast enough, the laptop does not melt, and the output looks decent for five prompts. That is not an agent evaluation.

If you want to decide seriously, benchmark the workflow, not the vibe.

Measure the things that actually break agent systems

I would care about these metrics first:

schema success rate: how often the model produces valid structured output on the first try
tool selection accuracy: how often it picks the right action class
retry rate: how often you need another pass because output drifted or malformed
latency at realistic context sizes: not just tiny prompt demos
throughput under concurrency: especially for background workers
escalation rate: how often local needs a hosted rescue
human review burden: whether the savings survive real operator usage

If you only measure token speed, you will approve the wrong system.

Test with boring examples, not showcase prompts

A strong benchmark set for local agent work should include repetitive and irritating real cases:

ten messy but similar issue reports
shell command proposals with subtle scope differences
CI logs with one real failure and several distractions
small code tasks where the right answer is to do less, not more
structured extraction where one missing field should fail validation

Those cases reveal whether the local model is dependable or merely charming.

Watch for the false-economy trap

The most common bad outcome looks like this:

the local model is cheaper per call
the system adds retries, repair passes, and fallbacks
operators lose trust and review more aggressively
the hosted model still handles the hard cases
total complexity rises faster than cost falls

That is the local-model false economy.

If you want to avoid it, calculate cost in full:

inference cost
engineering maintenance cost
operator review cost
failure and retry cost
hardware cost
latency cost to user experience

Local wins when the whole system gets cheaper or better, not when one line item goes down.

When I would actually choose local, hosted, or hybrid

If I were advising a team building agentic development tools today, I would not make this a philosophical decision.

I would make it a routing decision.

Choose local-first when

the workload is internal and privacy matters
tasks are repetitive and easy to verify
structured output matters more than deep reasoning
you expect high call volume in the inner loop
the team is willing to own prompt, validation, and runtime tuning

Examples: internal guardrails, issue triage, retrieval rewrite, CI summarization, low-risk codebase helpers.

Choose hosted-first when

the agent must reason across ambiguity
the workflow uses several tools with real blast radius
repo-scale context is common
failure is expensive or user-facing
the team wants less infrastructure ownership

Examples: coding agents for production repos, architectural assistants, debugging copilots, customer-facing expert answers.

Choose hybrid when

the workflow has obvious low-risk and high-risk layers
you can validate local output cheaply
fallback can preserve state cleanly
you want cost control without lowering the ceiling

This is where I think most serious teams should land. Use local models as infrastructure for the cheap repetitive layers. Use hosted models for judgment, recovery, and long-horizon work.

That is the grown-up pattern.

The takeaway is simple: local models make sense for agentic development when the job looks more like a reliable subsystem than a brilliant collaborator. If the work is narrow, structured, and high-volume, local can be a smart engineering choice. If the work depends on tool discipline, broad judgment, and expensive correctness, hosted models still earn their keep.

Do not ask one model strategy to win every layer. Build the stack so each layer does the kind of work it is actually good at.

Read the full post on QCode: https://qcode.in/when-local-llms-make-sense-for-agentic-development/

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/

DEV Community: Saqueib Ansari

Laravel cooldowns work better when each action has its own rules

Where Rate Limits Get Too Blunt

Model The Cooldown Around Ownership and Action

A Minimal Laravel Service

Why Cache TTL Is Usually Enough

Add Cooldowns At The Workflow Boundary

Example: AI Generation

Example: Export Generation

The UX Matters More Than The Backend Trick

Return Structured Retry Data

Show Cooldowns In The Interface

Pair Cooldowns With Idempotency When Needed

Failure Modes To Avoid

Cooldown By IP

Cooldown That Starts Too Early

Cooldown That Starts Too Late

No Atomic Guard Around First Trigger

Inventing Cooldowns For Everything

A Better Default For Real Laravel Products

Laravel image jobs need idempotency before they need new APIs

The Real Bug Is Usually Workflow Drift

The Failure Modes Worth Designing For

Start With A Durable Image Record, Not With Storage::put()

Status Columns Matter More Than People Admit

Deterministic Paths Are The Backbone Of Retry Safety

Why Versioned Paths Beat Overwrites

Checksums Turn Upload Chaos Into Something You Can Reason About

Compute The Checksum At Ingress

The Job Should Reconcile Progress, Not Rebuild Blindly

Incremental Persistence Beats Fake Atomicity

Concurrency And Replacement Flows Need Explicit Rules

Rule 1: Jobs Must Carry Version Context

Rule 2: Replacements Should Supersede, Not Mutate In Place

Rule 3: Cleanup Should Be Separate From Processing

Storage Writes Need To Be Retry-Safe Too

S3 And Local Disk Fail Differently

What I Would Ship In A Real Laravel App

Practical Decision Rule

Using HTTP QUERY in Laravel Without Making Your API Harder to Maintain

What QUERY Fixes That GET and POST Do Not

Where QUERY Really Helps in a Laravel Codebase

Best Fit: Complex Safe Search

Better Fit for Shared Search Engines

A Cleaner Service Boundary

Why QUERY Can Still Become a Maintenance Trap

Laravel Is Friendly, the Rest of the Stack May Not Be

Browser and Client Ergonomics Are Still Uneven

Caching Is Better in Theory Than in Commodity Infrastructure

Observability Gets Slightly Worse Before It Gets Better

The Laravel Implementation Pattern That Makes Sense

Recommended Route Shape

Validation and Idempotency Still Matter

Use Accept-Query If You Are Serious

So Should Laravel Teams Use QUERY?

Claude Code on Bun: What Runtime Choices Actually Mean for Agentic Tools

Agentic Tools Punish the Wrong Runtime Fast

Bun Fits the Agent Shape Because It Collapses Tooling Layers

Install Friction Is a Product Metric

Cold Start Is Not a Benchmark Detail

Tighter Ownership Matters

Why the Rust Layer Matters More Than Marketing Suggests

The Runtime Decision Gets Real at the Subprocess Boundary

What Good Subprocess Support Needs to Handle

Failure Behavior Is More Important Than Success Speed

Sandboxing Changes the Runtime Conversation Completely

Sandboxing Needs Runtime Cooperation

Native Extensions and System Interfaces Still Matter

Packaging, Updates, and Operational Debugging Decide Who Wins

Packaging Is Part of Trust

Debugging Needs Structured Events, Not Just Logs

The Ecosystem Tradeoff Still Has Teeth

What Claude Code’s Runtime Choice Actually Teaches

Keeping Laravel Projects Findable When Local Work Starts to Sprawl

Start With a Single Project Map

Name Projects for Retrieval, Not Aesthetics

What Good Names Prevent

Add Lightweight Project Metadata

The Hidden Win: Safer Context Switching

Use Searchable Shortcuts, Not Memory

Start With A Durable Image Record, Not With `Storage::put()`

What `QUERY` Fixes That `GET` and `POST` Do Not

Where `QUERY` Really Helps in a Laravel Codebase

Why `QUERY` Can Still Become a Maintenance Trap

Use `Accept-Query` If You Are Serious

So Should Laravel Teams Use `QUERY`?