Forem: Saqueib Ansari

Why Your Laravel Queue Stops Processing Without Telling You

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

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

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

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

A queue feels healthy when:

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

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

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

The root cause is almost always one of:

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

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

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

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

Common causes:

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

What to do (opinionated)

1) Set hard timeouts at multiple layers:

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

2) Make “no progress” alertable:

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

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

Example: enforce timeouts and fail fast

<?php

namespace App\Jobs;

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

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

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

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

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

    public function handle(): void
    {
        $response = Http::timeout(10)           // connect+read timeout
            ->retry(2, 200)                     // short retry with backoff
            ->get('https://api.vendor.com/catalog');

        $response->throw();

        // … process payload
    }
}

This does two important things:

the job cannot hang indefinitely
failures become deterministic (you’ll hit failed_jobs after tries)

If you’re using curl directly, Guzzle, S3 clients, etc., set timeouts there too. Laravel can’t kill a job that’s blocked in a syscall unless the worker timeout triggers.

Operational note

If you run workers with php artisan queue:work, use explicit flags:

--timeout=60
--sleep=1
--tries=3

And don’t pretend queue:listen is acceptable in production; it’s slower and easier to misconfigure.

Official docs: Queues https://laravel.com/docs/queues

Failure mode 2: exceptions are swallowed (your job “succeeds” while doing nothing)

This is the classic silent failure: the job finishes without throwing, so the queue driver marks it as done—even though the intended side effect never happened.

Where it happens:

try { ... } catch (\Throwable $e) { /* log? */ } with no rethrow
returning early on invalid state without recording it
“best effort” integrations that ignore non-200 responses

What to do

Be strict: if a job is responsible for a side effect, it should throw when it can’t perform it. “Best effort” should be explicit and observable.

If you truly want to swallow an error (rare), you still need:

a metric increment
an error report (Sentry/Bugsnag)
a dead-letter workflow (manual replay)

Example: don’t swallow; classify

<?php

namespace App\Jobs;

use App\Services\Payments\PaymentGateway;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;
use Throwable;

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

    public int $tries = 5;
    public int $backoff = 30; // seconds

    public function __construct(public int $orderId) {}

    public function handle(PaymentGateway $gateway): void
    {
        try {
            $gateway->capture($this->orderId);
        } catch (Throwable $e) {
            // If it’s transient, rethrow to retry.
            // If it’s permanent, fail fast so it lands in failed_jobs.

            if ($gateway->isPermanentFailure($e)) {
                $this->fail($e); // marks as failed immediately
                return;
            }

            throw $e;
        }
    }
}

Key judgment call: “permanent failure” should not burn retries. You want it to go to failed_jobs quickly so you can handle it (refund, contact user, etc.).

Failure mode 3: misconfigured retries/backoff create infinite limbo

Laravel makes it easy to back off and retry, but it’s also easy to create jobs that never succeed and never fail loudly.

How this happens:

release() is called repeatedly without a cap
backoff grows but tries is high or defaulted
retryUntil() pushes the failure window far out
Horizon auto-balancing hides the fact that one queue is stuck

What to do

Set finite retries ($tries) for most jobs.
Use bounded retry windows for time-sensitive work (retryUntil).
For idempotent tasks that can be replayed later, fail early and rely on a replay mechanism.

A reasonable default for many teams:

$tries = 3 for external API calls
$tries = 1 for non-idempotent side effects unless you’ve built idempotency
$backoff = [10, 60, 300] for transient network issues

If you can’t explain why a job is safe to retry, it probably isn’t.

Failure mode 4: “lost” jobs due to driver semantics and worker restarts

Not all queue drivers behave the same. Silent loss or duplication is often a mismatch between assumptions and reality.

Database driver gotchas

Jobs are stored in a table; workers poll.
Under load, polling delay can look like “stuck”.
Long transactions can block job reservation.

If you’re at the point where queue latency matters, move off database.

Redis driver gotchas

Redis is the default for a reason: it’s fast and supports good semantics. But you still need to understand:

visibility timeout / retry_after: if a worker dies mid-job, the job becomes available again after retry_after.
if retry_after is too small relative to job runtime, you’ll get duplicate processing.

In Laravel, retry_after is configured per connection in config/queue.php.

Rule: set retry_after comfortably above your maximum real job runtime (including worst-case API slowness), and keep job timeouts below it.

Supervisor/systemd gotchas

Workers restart. Deploys happen. Servers reboot.

Silent failure here is often:

workers not restarted after deploy (stale code)
process manager configured to restart too aggressively (thrashing)
logs not captured anywhere useful

If you deploy frequently, prefer Laravel Horizon for Redis-backed queues. It gives you process control, visibility, and per-queue balancing.

Official link: Horizon https://laravel.com/docs/horizon

Failure mode 5: you have “failed jobs”, but nobody sees them

Laravel will happily write to failed_jobs (or Horizon’s failed list) forever while your team never checks it.

This is the most common “silent failure” in real companies: the system is technically recording failure, but it’s not operationally connected to humans.

What to do (minimum viable)

Ensure failed job storage is configured (queue:failed-table migration for DB).
Alert on failed job rate.
Give engineers a one-command way to inspect and replay.

Concrete setup: hook into Queue events and report

Laravel emits queue events you can subscribe to. Use them to send failures to Sentry/Bugsnag and to emit metrics.

<?php

namespace App\Providers;

use Illuminate\Queue\Events\JobFailed;
use Illuminate\Queue\Events\JobProcessed;
use Illuminate\Queue\Events\JobProcessing;
use Illuminate\Support\Facades\Event;
use Illuminate\Support\ServiceProvider;

class QueueObservabilityServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        Event::listen(JobProcessing::class, function (JobProcessing $event) {
            // Example: increment a metric, add trace context, etc.
            // statsd()->increment('queue.job_processing', 1, ['queue' => $event->job->getQueue()]);
        });

        Event::listen(JobProcessed::class, function (JobProcessed $event) {
            // statsd()->increment('queue.job_processed', 1, ['queue' => $event->job->getQueue()]);
        });

        Event::listen(JobFailed::class, function (JobFailed $event) {
            // Send to your error tracker
            if (app()->bound('sentry')) {
                \Sentry\captureException($event->exception);
            }

            // Also log with strong context
            logger()->error('Queue job failed', [
                'connection' => $event->connectionName,
                'queue'      => $event->job->getQueue(),
                'job'        => $event->job->resolveName(),
                'uuid'       => method_exists($event->job, 'uuid') ? $event->job->uuid() : null,
                'message'    => $event->exception->getMessage(),
            ]);
        });
    }
}

This is deliberately boring: make failures impossible to ignore by routing them into the same system that pages you for HTTP 500s.

If you’re using Horizon, also configure its notification hooks for long waits and failures.

Practical alerting targets

Pick alerts that catch “silent” quickly without constant noise:

Queue backlog: jobs waiting > N for > 5 minutes
Oldest job age: oldest pending job > X minutes
Failed jobs rate: > 0 in 10 minutes for critical queues
No processing: processed count = 0 while pending count increases

Don’t overcomplicate it. Two alerts (oldest job age + failed jobs) catch most incidents.

Failure mode 6: duplication and non-idempotent side effects (the “it ran twice” incident)

Some teams call this a “silent failure” because the queue doesn’t error—but users see double emails, double charges, duplicate webhooks.

Duplication happens when:

a worker times out but the side effect already happened
retry_after expires and the job is re-queued while still running
external systems retry webhooks and you enqueue duplicates

What to do

Assume at-least-once delivery. Build idempotency where it matters.

For emails/notifications: store a send record keyed by a deterministic id
For payments: use provider idempotency keys (Stripe supports this) and store request IDs
For “sync” jobs: use upserts and version checks

Example: simple idempotency guard using cache lock

This won’t solve every case, but it’s a strong baseline for “don’t run twice concurrently” and “avoid rapid duplicates”.

<?php

namespace App\Jobs;

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

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

    public int $tries = 3;

    public function __construct(public int $invoiceId) {}

    public function handle(): void
    {
        $key = "invoice:{$this->invoiceId}:email_sent";

        // 24h idempotency window
        if (Cache::has($key)) {
            return;
        }

        $lock = Cache::lock("lock:{$key}", 30);

        if (! $lock->get()) {
            // Another worker is doing it.
            return;
        }

        try {
            // ... send email

            Cache::put($key, true, now()->addDay());
        } finally {
            optional($lock)->release();
        }
    }
}

Tradeoff: cache-based idempotency is operationally dependent on Redis. For “money moved” side effects, prefer database unique constraints or provider idempotency keys.

What to change in a real Laravel codebase this week

If your queue failures are currently “silent”, don’t start by rewriting jobs. Start by tightening the system around them.

1) Move critical queues to Redis + Horizon if you’re still on the database driver.

2) Set explicit timeouts and retries on every job that touches the network.

3) Wire JobFailed to your error tracker and create one alert: “failed jobs > 0 on critical queue”.

4) Alert on oldest job age (this catches stuck workers even when nothing is failing).

5) Add idempotency to the top 1–2 risky jobs (payments, emails, webhooks). Don’t boil the ocean.

Decision rule to keep you out of trouble

If a queued job triggers an external side effect (email, payment, webhook, data sync), treat it like a mini production service:

it must time out
it must fail loudly (error tracker + alert)
it must be safe to retry (or it must not retry)

When you’re unsure, bias toward: fail fast → land in failed jobs → replay intentionally. Silent “best effort” is how queues rot in production.

Read the full post on QCode: https://qcode.in/why-your-laravel-queue-fails-silently-and-how-to-fix-it/

Laravel Multitenancy: How to Isolate Tenant Databases Without Packages

Saqueib Ansari — Sun, 12 Apr 2026 02:31:40 +0000

Most teams should start with single-database, tenant-scoped rows and only graduate to database-per-tenant when you have a clear reason (regulatory isolation, noisy-neighbor issues, or operational boundaries). But if your goal is database isolation—separate schemas or separate databases per tenant—you don’t need a multitenancy package to do it well in Laravel. You need three things you can own and reason about:

1) a reliable way to resolve the current tenant for every request/job, 2) a safe way to route queries to the tenant database, and 3) guardrails so you don’t accidentally query the landlord database with tenant credentials (or vice versa).

This article shows a production-ready pattern for database-per-tenant isolation using middleware, a tenant resolver, and a small amount of connection plumbing—no third-party multitenancy package. The bias here is intentional: packages are great until you hit an edge-case (queue workers, Octane, migrations, reporting queries, cross-tenant admin) and you realize you don’t understand the magic. Owning the primitives makes those cases boring.

Choose your isolation model (and don’t overbuild)

Before implementing anything, be honest about what you’re optimizing for.

Approach A: shared database + tenant_id scoping (default recommendation)

Pros: simplest ops, easiest reporting, one migration path, fewer connections.

Cons: weaker isolation; a missing where tenant_id = ? can leak data unless you enforce it hard (global scopes + policies + DB constraints).

Approach B: database-per-tenant (what we’re building)

Each tenant has its own database (or schema), and the app switches connections at runtime.

Pros: strong isolation, easier per-tenant backups/restore, per-tenant performance tuning, cleaner “delete tenant” story.

Cons: operational complexity (migrations across N DBs), connection management, cross-tenant reporting becomes a deliberate pipeline instead of a query.

Decision rule

If you’re early-stage or you need analytics-heavy cross-tenant queries, start with Approach A and enforce scoping. If you have clear isolation requirements or tenants big enough to justify their own DB lifecycle, Approach B is worth it.

The rest of this post assumes database-per-tenant.

The core architecture: landlord DB + tenant DB

You’ll typically have:

A landlord (central) database containing tenants, domains, billing, feature flags, and audit metadata.
A tenant database per tenant containing tenant-owned tables (users, projects, orders, etc.).

The application resolves the tenant from the request (domain/subdomain/header), loads tenant connection info from the landlord DB, then sets the current tenant connection for the duration of the request.

Laravel already gives you most of the tools:

Database connections via config/database.php
Middleware for per-request initialization
Model connection selection via $connection or Model::on('connection')
Queue events and job middleware for worker-side initialization

The main thing you must get right: don’t let state leak between requests, especially under Laravel Octane.

Implement tenant resolution (domain-first, explicit, and testable)

Resolve tenants using a dedicated service. Keep it boring, deterministic, and easy to unit test.

Landlord models

In the landlord DB, store tenant connection details (or enough to derive them).

// app/Models/Landlord/Tenant.php
namespace App\Models\Landlord;

use Illuminate\Database\Eloquent\Model;

class Tenant extends Model
{
    protected $connection = 'landlord';

    protected $fillable = [
        'name',
        'slug',
        'db_host',
        'db_port',
        'db_name',
        'db_username',
        'db_password',
        'active',
    ];

    protected $casts = [
        'active' => 'bool',
    ];
}

If you don’t want to store raw passwords, use a secrets manager and store a reference. But don’t pretend you’re “more secure” by base64-encoding it in the DB.

Resolver service

Resolve by host (custom domains or subdomains). You can support multiple strategies, but pick one as primary.

// app/Tenancy/TenantResolver.php
namespace App\Tenancy;

use App\Models\Landlord\Tenant;
use Illuminate\Http\Request;

class TenantResolver
{
    public function resolve(Request $request): ?Tenant
    {
        $host = $request->getHost();

        // Example: tenant1.example.com -> tenant1
        $baseDomain = config('tenancy.base_domain');
        if ($baseDomain && str_ends_with($host, $baseDomain)) {
            $subdomain = rtrim(str_replace('.'.$baseDomain, '', $host), '.');
            if ($subdomain && $subdomain !== 'www') {
                return Tenant::query()
                    ->where('slug', $subdomain)
                    ->where('active', true)
                    ->first();
            }
        }

        // Example: custom domain mapping
        return Tenant::query()
            ->whereHas('domains', fn ($q) => $q->where('host', $host))
            ->where('active', true)
            ->first();
    }
}

This implies a domains relation; if you don’t need it, drop it. The point is: resolution should be explicit and centralized.

Failure mode to design for

If tenant resolution fails, do not silently fall back to a default tenant DB. That’s how cross-tenant leaks happen.

Return a 404/410, or redirect to marketing, or show “Tenant not found”. But don’t proceed with tenant queries.

Switch the database connection safely (without global magic)

Laravel lets you define connections at runtime by mutating config and purging the connection so a new PDO is created.

The pattern that works in production:

Keep a fixed tenant connection name.
On each request, overwrite database.connections.tenant with the resolved tenant credentials.
Call DB::purge('tenant') then DB::reconnect('tenant').
Set a current tenant in a scoped container so your app can access it.

Tenancy manager

// app/Tenancy/TenancyManager.php
namespace App\Tenancy;

use App\Models\Landlord\Tenant;
use Illuminate\Support\Facades\DB;

class TenancyManager
{
    public function initialize(Tenant $tenant): void
    {
        // Build a connection array compatible with config/database.php
        $connection = [
            'driver' => 'mysql',
            'host' => $tenant->db_host,
            'port' => $tenant->db_port ?? 3306,
            'database' => $tenant->db_name,
            'username' => $tenant->db_username,
            'password' => $tenant->db_password,
            'charset' => 'utf8mb4',
            'collation' => 'utf8mb4_unicode_ci',
            'prefix' => '',
            'strict' => true,
            'engine' => null,
            // Consider setting options like SSL here if needed
        ];

        config(['database.connections.tenant' => $connection]);

        // Very important: drop any existing connection state
        DB::purge('tenant');
        DB::reconnect('tenant');

        // Optional: set default connection for the request
        DB::setDefaultConnection('tenant');

        app(CurrentTenant::class)->set($tenant);
    }

    public function end(): void
    {
        // Reset to landlord to avoid accidental tenant queries later
        DB::setDefaultConnection(config('database.default', 'landlord'));

        // Purge tenant connection so Octane/long-running workers don’t reuse it
        DB::purge('tenant');

        app(CurrentTenant::class)->clear();
    }
}

Current tenant holder

Don’t use a static global. Use the container.

// app/Tenancy/CurrentTenant.php
namespace App\Tenancy;

use App\Models\Landlord\Tenant;

class CurrentTenant
{
    private ?Tenant $tenant = null;

    public function set(Tenant $tenant): void
    {
        $this->tenant = $tenant;
    }

    public function get(): Tenant
    {
        if (!$this->tenant) {
            throw new \RuntimeException('No tenant initialized for this context.');
        }

        return $this->tenant;
    }

    public function optional(): ?Tenant
    {
        return $this->tenant;
    }

    public function clear(): void
    {
        $this->tenant = null;
    }
}

// app/Providers/AppServiceProvider.php
use App\Tenancy\CurrentTenant;

public function register(): void
{
    $this->app->singleton(CurrentTenant::class, fn () => new CurrentTenant());
}

Middleware to wire it up

// app/Http/Middleware/InitializeTenancy.php
namespace App\Http\Middleware;

use App\Tenancy\TenantResolver;
use App\Tenancy\TenancyManager;
use Closure;
use Illuminate\Http\Request;

class InitializeTenancy
{
    public function __construct(
        private TenantResolver $resolver,
        private TenancyManager $tenancy
    ) {}

    public function handle(Request $request, Closure $next)
    {
        $tenant = $this->resolver->resolve($request);

        if (!$tenant) {
            abort(404);
        }

        $this->tenancy->initialize($tenant);

        try {
            return $next($request);
        } finally {
            $this->tenancy->end();
        }
    }
}

Apply it to tenant routes only (not your public marketing site, webhooks that aren’t tenant-specific, or landlord admin).

Octane note: the finally block is non-negotiable. Under long-running workers, forgetting to reset state is how tenant A’s connection bleeds into tenant B’s request.

Make models tenant-aware (and prevent accidental landlord access)

Once you set the default connection to tenant, most queries will go to the tenant DB. That’s convenient—and also dangerous if some code path should never touch tenant DB.

The clean approach is to be explicit:

Landlord models always set $connection = 'landlord'.
Tenant models always set $connection = 'tenant'.

Tenant base model

// app/Models/Tenant/TenantModel.php
namespace App\Models\Tenant;

use Illuminate\Database\Eloquent\Model;

abstract class TenantModel extends Model
{
    protected $connection = 'tenant';
}

Then:

// app/Models/Tenant/Project.php
namespace App\Models\Tenant;

class Project extends TenantModel
{
    protected $fillable = ['name'];
}

This removes ambiguity: even if some code accidentally switches the default connection, your tenant models still target tenant.

Guardrail: block tenant queries when not initialized

If you want a hard fail instead of silent misrouting, add a connection “health check” at the model layer.

A pragmatic way is to ensure tenant middleware runs for routes that touch tenant models, and to throw if CurrentTenant is missing in sensitive service methods.

Example:

// app/Services/Projects/CreateProject.php
namespace App\Services\Projects;

use App\Models\Tenant\Project;
use App\Tenancy\CurrentTenant;

class CreateProject
{
    public function __construct(private CurrentTenant $currentTenant) {}

    public function handle(string $name): Project
    {
        // Hard requirement: no tenant, no write
        $this->currentTenant->get();

        return Project::create(['name' => $name]);
    }
}

This is opinionated, but in real systems it prevents “it worked in dev” surprises.

Failure mode: cross-connection joins

Once you’re database-per-tenant, cross-database joins are not a feature, they’re a trap. If you need landlord + tenant data together, fetch them separately and combine in memory or build a reporting pipeline.

Example 1: Tenant-aware migrations without packages

Migrations are where database-per-tenant systems often collapse into ad-hoc scripts.

The pattern that scales: maintain two migration paths.

database/migrations/landlord for central tables
database/migrations/tenant for tenant tables

Then run tenant migrations per tenant.

Configure migration paths

You can keep standard migrations for landlord and add a custom command for tenant.

// app/Console/Commands/TenantsMigrate.php
namespace App\Console\Commands;

use App\Models\Landlord\Tenant;
use Illuminate\Console\Command;
use Illuminate\Support\Facades\Artisan;
use Illuminate\Support\Facades\DB;

class TenantsMigrate extends Command
{
    protected $signature = 'tenants:migrate {--tenant_id=} {--fresh} {--seed}';
    protected $description = 'Run tenant migrations for one or all tenants';

    public function handle(): int
    {
        $query = Tenant::query()->where('active', true);

        if ($id = $this->option('tenant_id')) {
            $query->whereKey($id);
        }

        $tenants = $query->get();

        foreach ($tenants as $tenant) {
            $this->info("Migrating tenant {$tenant->id} ({$tenant->name})...");

            config(['database.connections.tenant' => [
                'driver' => 'mysql',
                'host' => $tenant->db_host,
                'port' => $tenant->db_port ?? 3306,
                'database' => $tenant->db_name,
                'username' => $tenant->db_username,
                'password' => $tenant->db_password,
                'charset' => 'utf8mb4',
                'collation' => 'utf8mb4_unicode_ci',
                'prefix' => '',
                'strict' => true,
            ]]);

            DB::purge('tenant');
            DB::reconnect('tenant');

            if ($this->option('fresh')) {
                Artisan::call('migrate:fresh', [
                    '--database' => 'tenant',
                    '--path' => 'database/migrations/tenant',
                    '--force' => true,
                ]);
            } else {
                Artisan::call('migrate', [
                    '--database' => 'tenant',
                    '--path' => 'database/migrations/tenant',
                    '--force' => true,
                ]);
            }

            if ($this->option('seed')) {
                Artisan::call('db:seed', [
                    '--database' => 'tenant',
                    '--force' => true,
                ]);
            }

            $this->output->write(Artisan::output());
        }

        return self::SUCCESS;
    }
}

This is intentionally straightforward. You can optimize later (batching, parallelization, locking), but first make it correct.

Operational takeaway: if you have hundreds/thousands of tenants, tenant migrations become a deployment step that needs observability. Log per-tenant migration duration and failures, and never run them blindly during peak traffic.

Example 2: Queue jobs and scheduled tasks (where leaks actually happen)

Requests are easy. Workers and schedulers are where “no package” implementations usually fail.

The problem

A job runs later, on a different machine/process. If you don’t serialize tenant identity and re-initialize the connection, the job will run on whatever default connection the worker has.

Pattern: make jobs tenant-aware explicitly

Create a small trait that stores tenant_id and initializes tenancy in handle.

// app/Tenancy/Queue/TenantAware.php
namespace App\Tenancy\Queue;

use App\Models\Landlord\Tenant;
use App\Tenancy\TenancyManager;

trait TenantAware
{
    public int $tenantId;

    public function forTenant(int $tenantId): static
    {
        $this->tenantId = $tenantId;
        return $this;
    }

    public function initializeTenancy(): void
    {
        $tenant = Tenant::query()
            ->whereKey($this->tenantId)
            ->where('active', true)
            ->firstOrFail();

        app(TenancyManager::class)->initialize($tenant);
    }

    public function endTenancy(): void
    {
        app(TenancyManager::class)->end();
    }
}

Use it in a job:

// app/Jobs/RecalculateUsage.php
namespace App\Jobs;

use App\Models\Tenant\Project;
use App\Tenancy\Queue\TenantAware;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;

class RecalculateUsage implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
    use TenantAware;

    public function __construct(int $tenantId)
    {
        $this->tenantId = $tenantId;
    }

    public function handle(): void
    {
        $this->initializeTenancy();

        try {
            // All tenant queries go to the tenant DB
            Project::query()->chunkById(500, function ($projects) {
                foreach ($projects as $project) {
                    // ...recalculate usage...
                }
            });
        } finally {
            $this->endTenancy();
        }
    }
}

Dispatching:

RecalculateUsage::dispatch($tenant->id);

Scheduler

For scheduled commands, do the same thing: iterate tenants and initialize tenancy per tenant, with a try/finally.

Practical takeaway: if you’re using Horizon, add tags like tenant:{id} for visibility. If you’re using Octane + queues, be even more strict about cleanup.

Hard edges: reporting, auth, and performance

Database-per-tenant isn’t hard because of the happy path. It’s hard because of the “one day you need…” path.

Cross-tenant reporting

Don’t fight your isolation model. If you need cross-tenant analytics:

Emit events (orders created, invoice paid) into a central analytics store (landlord DB tables, ClickHouse, BigQuery, etc.).
Or run ETL jobs that aggregate tenant data into landlord tables.

Trying to query N tenant databases on-demand inside a request is a self-inflicted outage.

Authentication and session storage

If your users live in tenant DBs, auth becomes tenant-contextual:

Resolve tenant first.
Then authenticate against tenant DB.

If you use Laravel’s session database driver, decide where sessions live. Most teams put sessions in a shared store (Redis) to avoid per-tenant session tables.

Official docs worth re-reading:

Laravel database config: https://laravel.com/docs/database
Laravel queues: https://laravel.com/docs/queues
Laravel Octane (statefulness concerns): https://laravel.com/docs/octane

Connection churn and pooling

Switching tenant DB per request means more distinct connections. Mitigations:

Use Redis/cache aggressively for landlord lookups (tenant by domain).
Keep tenant credentials stable; avoid generating ephemeral DB users unless you have a strong reason.
If you’re on MySQL/Postgres managed services, watch connection limits. Consider PgBouncer (Postgres) or a proxy/pooler.

Security posture

Database-per-tenant is not automatically secure if your app can still connect to all tenant DBs with the same credentials. The strongest model is:

Each tenant has its own DB user limited to that tenant DB.
The landlord DB holds encrypted credentials or references.

That’s extra ops, but it’s real isolation.

What I would ship first (and what I’d delay)

Here’s the opinionated path that keeps you out of trouble:

1) Ship TenantResolver + TenancyManager + middleware with strict failure behavior (no tenant, no access).
2) Make landlord vs tenant models explicit with $connection properties.
3) Add tenant-aware jobs early, even if you think you “don’t use queues much”. You will.
4) Add tenant migration command and run it in CI/staging with multiple tenants.

Delay until you actually need them:

Fancy cross-tenant query abstractions
Per-tenant read replicas
Automatic tenant provisioning with zero-touch credentials rotation

Rule of thumb to remember

If there is any chance the code runs outside an HTTP request (queues, scheduler, Octane worker), assume tenant context is missing and make initialization explicit. In multitenancy, “implicit defaults” are just bugs waiting for a customer to find them.

Read the full post on QCode: https://qcode.in/laravel-multitenancy-database-isolation-without-packages/

Laravel API Versioning Strategies That Don’t Suck

Saqueib Ansari — Sat, 11 Apr 2026 02:31:51 +0000

Most teams should avoid “v1/ v2” branching the entire Laravel codebase. It looks clean on paper, but it quietly doubles your maintenance surface area and makes backward compatibility harder, not easier. A better default is: keep one codebase, version at the edges, and evolve your API using additive changes, explicit deprecations, and small compatibility shims when you must.

That recommendation holds for the majority of product APIs: mobile apps, SPAs, partner integrations, and internal services that you control. Only reach for hard version splits when you’re forced to break contracts (auth model changes, resource identity changes, or semantic shifts that can’t be expressed as additive fields).

This article is opinionated and practical: how to design Laravel API versioning that keeps clients moving without turning your app into a museum of old controllers.

The failure mode: “/api/v1” everywhere, duplicated controllers, and two realities

Laravel makes it easy to slap a prefix on routes:

Route::prefix('api/v1')->group(function () {
    Route::get('/users/{user}', [V1\UserController::class, 'show']);
});

Route::prefix('api/v2')->group(function () {
    Route::get('/users/{user}', [V2\UserController::class, 'show']);
});

The first month feels productive. Then reality hits:

You fix a bug in v2 and forget v1.
You add a field in v2 and now serializers diverge.
You change validation rules and now you have to reason about “which version is correct”.
You end up with two sets of policies, resources, requests, docs, tests, and support tickets.

The deeper problem is that route prefixes don’t define versioning—contracts do. If the contract is “a user has an id and email”, you can keep that contract stable without cloning controllers. Conversely, if you change the meaning of id or how authorization works, the prefix won’t save you from breaking clients.

So the goal isn’t “have versions”. The goal is:

Backward-compatible evolution by default.
Predictable breaking changes when required.
Minimal overhead in code, docs, and tests.

Choose a versioning strategy based on what you’re actually changing

There are three common strategies for public-ish JSON APIs. In Laravel, all three are viable, but only one is a good default.

URL versioning (e.g., /v1)

When it wins:

You have large, unavoidable breaking changes.
You need to run two contracts for a long time.
You have external clients you can’t force-upgrade.

Where it fails:

Encourages “forked API” thinking.
Creates duplication pressure (controllers, resources, docs).
Makes it tempting to ship breaking changes in v2 instead of designing additive evolution.

Header-based versioning (e.g., Accept: application/vnd…)

Example:

Accept: application/vnd.qcode.users+json; version=2

When it wins:

You want stable URLs and better cache keys in some gateways.
You have a mature API platform and strong client discipline.

Where it fails:

Harder to debug manually.
Some clients and tools are clumsy with custom media types.
If you don’t enforce it consistently, you end up with “hidden versions”.

“No explicit version” + compatibility rules (recommended default)

This is the pragmatic approach for most product teams:

Keep routes stable (/api/users/{id}), no version in the URL.
Make additive changes (new optional fields, new endpoints).
Use feature flags or capabilities when semantics vary.
Deprecate with headers and timelines.

When it wins:

You control most clients (your mobile app, your SPA).
You want minimal code overhead.
You want to avoid long-lived parallel APIs.

Where it fails:

If you truly must break semantics (not just shape).
If you have many third-party integrators with unpredictable upgrade cycles.

If you’re unsure, start with “no explicit version” and design for compatibility. Add explicit versioning only when you hit a real breaking wall.

The Laravel pattern: version at the boundary, not the core

Even if you decide to support multiple versions, the cleanest architecture is:

Domain/services: one set of business logic.
Requests/validation: minimal version-specific differences.
Resources/transformers: where version differences usually belong.
Routes: detect version, then choose the right transformer.

In other words: keep the “truth” in one place, and treat versioning as a presentation concern.

Example 1: Header-based version negotiation + versioned Resources (minimal duplication)

Let’s implement a simple version negotiation layer in Laravel. We’ll support:

Default version: 1
Client can send X-API-Version: 2

Step 1: Middleware to resolve API version

<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;

class ResolveApiVersion
{
    public function handle(Request $request, Closure $next)
    {
        $version = (int) $request->header('X-API-Version', 1);

        // Clamp to supported range
        if ($version < 1) $version = 1;
        if ($version > 2) $version = 2;

        // Make it accessible everywhere
        app()->instance('api.version', $version);

        // Helpful for debugging and support
        $response = $next($request);
        $response->headers->set('X-API-Version', (string) $version);

        return $response;
    }
}

Register it for your API group in app/Http/Kernel.php (Laravel 11 still supports middleware registration patterns; adjust for your app’s structure).

Step 2: One controller, version-aware Resources

Controller stays stable:

<?php

namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use App\Http\Resources\User\UserResourceV1;
use App\Http\Resources\User\UserResourceV2;
use App\Models\User;

class UserController extends Controller
{
    public function show(User $user)
    {
        $version = app('api.version');

        return match ($version) {
            2 => new UserResourceV2($user),
            default => new UserResourceV1($user),
        };
    }
}

Now the version differences live where they belong: the representation.

UserResourceV1:

<?php

namespace App\Http\Resources\User;

use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\JsonResource;

class UserResourceV1 extends JsonResource
{
    public function toArray(Request $request): array
    {
        return [
            'id' => (string) $this->id,
            'email' => $this->email,
            'name' => $this->name,
        ];
    }
}

UserResourceV2 adds fields and changes naming without breaking v1:

<?php

namespace App\Http\Resources\User;

use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\JsonResource;

class UserResourceV2 extends JsonResource
{
    public function toArray(Request $request): array
    {
        return [
            'id' => (string) $this->id,
            'email' => $this->email,
            'display_name' => $this->name,
            'avatar_url' => $this->avatar_url,
            'created_at' => $this->created_at?->toISOString(),
        ];
    }
}

Why this is low-overhead:

One route, one controller, one policy.
Versioning is mostly in Resources.
You can backport bug fixes to both versions automatically.

Common failure mode: trying to put version checks everywhere (“if v2 then …”) inside services. That’s how your domain becomes unreadable. Keep version checks at the boundary.

Backward compatibility rules that actually work in production

Versioning is mostly about discipline. These rules prevent 80% of breakage.

Prefer additive changes; treat removals as breaking forever

Adding a new optional field is cheap. Removing or renaming a field is expensive because some client somewhere will keep reading it.

Add: avatar_url (safe)
Add: metadata object (safe)
Remove: name (breaking)
Change type: id from string to int (breaking)

If you want to “remove” something, deprecate it first and keep it available until you have a hard cutoff.

Never change meaning under the same key

Changing semantics is worse than changing shape.

Bad: status used to mean “account status”, now means “subscription status”.

If semantics change, ship a new field (account_status, subscription_status) and deprecate the old one.

Be strict about request validation, but tolerant in responses

For requests:

Validate hard. Reject unknown enum values.
Be explicit about constraints.

For responses:

Clients should ignore unknown fields. Your API should assume they will.

This is why JSON:API and similar specs push predictable patterns, but you don’t need to fully adopt a spec to follow the principle.

Use explicit deprecation signals

If you’re serious about stability, communicate deprecations in-band:

Deprecation: true
Sunset: <http-date> (RFC 8594)
Link: <https://docs.example.com/deprecations/v1>; rel="deprecation"

Laravel makes this easy at the middleware level.

Official reference for the Sunset header: https://datatracker.ietf.org/doc/html/rfc8594

Example 2: “Compatibility shim” for a breaking request change (without forking endpoints)

A common breaking change is request shape. Example: you originally accepted:

{ "name": "Asha", "email": "asha@example.com" }

Later you want:

{ "profile": { "display_name": "Asha" }, "email": "asha@example.com" }

Forking /v2/users is the obvious move. A lower-overhead approach is a request normalization shim that maps old payloads into the new internal shape.

Step 1: Middleware to normalize input based on version

<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;

class NormalizeUserPayload
{
    public function handle(Request $request, Closure $next)
    {
        if (!$request->isMethod('post') || !$request->is('api/users')) {
            return $next($request);
        }

        $version = app('api.version');

        if ($version === 1) {
            // Convert v1 payload to v2 internal contract
            $name = $request->input('name');

            $request->merge([
                'profile' => array_merge(
                    $request->input('profile', []),
                    ['display_name' => $request->input('profile.display_name', $name)]
                ),
            ]);
        }

        return $next($request);
    }
}

Step 2: Validate only the new shape in a Form Request

<?php

namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;

class StoreUserRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            'email' => ['required', 'email'],
            'profile.display_name' => ['required', 'string', 'min:2'],
        ];
    }
}

Step 3: Controller uses the normalized contract

<?php

namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use App\Http\Requests\StoreUserRequest;
use App\Models\User;

class UsersController extends Controller
{
    public function store(StoreUserRequest $request)
    {
        $user = User::create([
            'email' => $request->input('email'),
            'name' => $request->input('profile.display_name'),
        ]);

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

Tradeoff: shims can accumulate if you keep them forever. The point is to buy time for migration, not to preserve every legacy contract indefinitely.

A practical policy:

Shims are allowed only when paired with a Sunset date.
Shims must be isolated to middleware/transformers, not services.

Testing and documentation: where versioning usually collapses

Versioning fails when it isn’t testable and observable.

Contract tests per version (cheap, high leverage)

You don’t need full duplicated test suites. You need a thin set of contract tests for the responses that clients depend on.

In PHPUnit/Pest, test the same endpoint with different headers:

it('returns v1 user shape', function () {
    $user = \App\Models\User::factory()->create(['name' => 'Asha']);

    $this->withHeader('X-API-Version', '1')
        ->getJson("/api/users/{$user->id}")
        ->assertOk()
        ->assertJsonStructure(['id', 'email', 'name'])
        ->assertJsonMissing(['display_name', 'avatar_url']);
});

it('returns v2 user shape', function () {
    $user = \App\Models\User::factory()->create(['name' => 'Asha']);

    $this->withHeader('X-API-Version', '2')
        ->getJson("/api/users/{$user->id}")
        ->assertOk()
        ->assertJsonStructure(['id', 'email', 'display_name', 'created_at']);
});

This catches accidental breakage when someone “cleans up” a resource.

Document deprecations like product decisions, not footnotes

If you have an API docs site (OpenAPI/Swagger), don’t just mark things deprecated and move on. Add:

What replaces it
The cutoff date
The client action required

If you’re using OpenAPI, you can model versioning either as separate specs or as one spec with versioned schemas. Many teams do better with separate specs once they truly diverge—but that’s exactly the point: don’t diverge until you must.

Official OpenAPI spec: https://spec.openapis.org/oas/latest.html

Observability: log version usage before you remove anything

Before you sunset v1:

Log api.version, route name, and client identifier.
Create a dashboard: “Requests by version over time”.

In Laravel, you can attach this to middleware and ship to whatever you use (OpenTelemetry, Sentry, Datadog, ELK). The exact stack matters less than the discipline: if you can’t measure usage, you can’t deprecate safely.

When you truly need a hard v2 (and how to do it without a mess)

Sometimes you must break:

Auth changes (e.g., moving from API keys to OAuth2 scopes)
Resource identity changes (/users/{id} becomes /accounts/{uuid})
Pagination semantics change (offset → cursor)
A field’s meaning changes and can’t be expressed additively

In those cases, do URL versioning, but still avoid duplicating the entire stack.

Practical pattern:

Keep shared domain/services.
Keep shared policies where possible.
Use separate route files: routes/api_v1.php, routes/api_v2.php.
Keep controllers thin; put logic in services.
Version the Resources and Requests more than the business logic.

A clean route setup:

// routes/api.php
Route::middleware(['api', \App\Http\Middleware\ResolveApiVersion::class])
    ->group(function () {
        require base_path('routes/api_shared.php');
    });

// If you truly need hard versions:
Route::prefix('api/v1')->middleware('api')->group(function () {
    require base_path('routes/api_v1.php');
});

Route::prefix('api/v2')->middleware('api')->group(function () {
    require base_path('routes/api_v2.php');
});

The judgment call: if your v2 is “we renamed fields and cleaned up JSON”, you don’t need /v2. Use resources and shims. If your v2 is “the meaning of the workflow changed”, you probably do.

The decision rule most teams should adopt

If you want minimal overhead and long-term stability in a Laravel API, adopt this rule of thumb:

Default: no URL versioning; evolve via additive fields + explicit deprecation headers.
Allow: header-based negotiation when you need different representations.
Escalate to /v2 only when semantics break, not when you merely dislike the old shape.

And one warning that saves teams from years of pain: never let versioning leak into your domain layer. Keep it in middleware, request normalization, and resources. If your services start taking $version arguments, you’re building two products in one codebase—and you’ll pay for it every sprint.

Read the full post on QCode: https://qcode.in/laravel-api-versioning-designing-backward-compatible-apis-with-minimal-overhead/

Building AhCalc: A Solar and Battery Sizing Calculator That Works

Saqueib Ansari — Fri, 10 Apr 2026 06:31:53 +0000

Most solar sizing conversations start the same way: “I have a 12V battery, a 500W inverter, and a few appliances… how long will it run?” Or “How many panels do I need for a 1kW load?” Or the classic: “How many Ah battery for my home backup?”

After answering those questions for friends, followers, and a few clients for the hundredth time, I realized the real problem wasn’t the math. It was the friction. People were being forced into spreadsheets, gated calculators, WhatsApp-forwarded charts, or tools that felt like they were designed to capture leads rather than give answers.

So I built AhCalc: a small, fast, public calculator that helps people size batteries (Ah/Wh), inverters, and solar panels for off-grid and backup systems—without logins, without a backend, and without the “fill this form and we’ll email you the report” dance.

This isn’t a “how to build a React app” tutorial. It’s a founder-builder story about taking repeated real-world questions and turning them into a tool people actually use—by making a few opinionated product and engineering decisions.

The failure mode I kept seeing: calculators that “work” but don’t help

Most sizing tools technically compute something. The reason they still fail in practice is predictable:

They’re slow (heavy pages, multiple steps, too many fields).
They’re gated (phone number/email required to see results).
They’re opaque (no clear assumptions, no explanation of what changed the result).
They’re non-shareable (you can’t send a link that preserves inputs).
They’re overconfident (they spit out a single “recommended” product like it’s universally correct).

And a subtle one: many tools treat solar sizing as a generic global problem. In reality, the assumptions that matter—sun hours, common system voltages, typical appliance mixes—are regional. I’m in India, and I kept seeing advice that was technically plausible but practically mismatched to how people actually buy and wire systems here.

The bar I set for AhCalc was simple:

Instant answers (no multi-step form flow).
Shareable state (send a link, get the same result).
No backend (keep it cheap, reliable, and private by default).
Math that respects reality (efficiency losses, surge, DoD, battery type).
Recommendations without pretending certainty (show ranges and constraints, not “buy this exact thing”).

That set the tone for every technical decision.

The product decision that mattered most: “pure math first, UI second”

Sizing logic turns into a mess when it’s intertwined with UI state. If you’ve ever debugged “why did the battery Ah change when I toggled this checkbox?”, you know what I mean.

I forced myself into a constraint: the core logic must be pure calculation functions.

No reading from global state.
No hidden defaults inside random components.
Every function takes explicit inputs and returns explicit outputs.
The UI is just a thin layer that gathers inputs and renders outputs.

This does two things:

It makes the calculator trustworthy because the assumptions are centralized.
It makes it easier to add features without breaking existing results.

Here’s a simplified version of the battery sizing logic (TypeScript). The goal isn’t to model every chemistry edge case—it’s to be honest about the assumptions that actually change outcomes.

// calc/battery.ts
export type BatteryInputs = {
  loadWatts: number;          // average running load
  backupHours: number;        // required runtime
  systemVoltage: 12 | 24 | 48;
  inverterEfficiency: number; // e.g. 0.85 - 0.93
  batteryEfficiency: number;  // e.g. 0.9 for lead-acid, 0.95+ for LiFePO4
  depthOfDischarge: number;   // usable fraction: 0.5 lead-acid, 0.8 LiFePO4
  safetyMargin: number;       // 1.1 - 1.3
};

export type BatteryResult = {
  energyWhRequired: number;
  batteryWhNominal: number;
  batteryAhNominal: number;
};

export function sizeBattery(inputs: BatteryInputs): BatteryResult {
  const {
    loadWatts,
    backupHours,
    systemVoltage,
    inverterEfficiency,
    batteryEfficiency,
    depthOfDischarge,
    safetyMargin,
  } = inputs;

  if (loadWatts <= 0 || backupHours <= 0) {
    return { energyWhRequired: 0, batteryWhNominal: 0, batteryAhNominal: 0 };
  }

  // Energy that must be delivered to the AC load
  const energyWhRequired = loadWatts * backupHours;

  // Account for inverter + battery losses and DoD limits
  const usableFraction = inverterEfficiency * batteryEfficiency * depthOfDischarge;
  const batteryWhNominal = (energyWhRequired / usableFraction) * safetyMargin;

  const batteryAhNominal = batteryWhNominal / systemVoltage;

  return {
    energyWhRequired,
    batteryWhNominal,
    batteryAhNominal,
  };
}

A few opinionated choices are embedded here:

Depth of discharge (DoD) is non-negotiable. Lead-acid users routinely kill batteries by “using the full capacity.” A tool that doesn’t model DoD is worse than no tool.
Efficiency is multiplicative, not additive. Small mistakes here compound.
A safety margin is explicit. People can argue the value, but they can’t pretend it doesn’t exist.

This “pure math first” approach made everything else easier: testing, URL state, UI transitions, and even copywriting.

The engineering choice that made it shareable: URL-encoded state (no backend)

The moment a calculator is useful, people want to share it:

“Check this setup.”
“Is this enough for my fridge + fans?”
“What if I switch to 24V?”

If your tool can’t preserve inputs in a link, the sharing happens via screenshots—and screenshots kill iteration.

AhCalc keeps state in the URL. Not in a database, not in localStorage (though that can be a nice add-on), and not in a server session.

Why?

No backend: less maintenance, fewer failure points.
Privacy by default: inputs don’t leave the browser.
Instant share: copy/paste the URL and you’re done.

The main tradeoff is obvious: URLs can get long. The fix is to encode only what matters, keep keys short, and compress when needed.

A pragmatic pattern is:

Maintain a typed AppState.
Serialize to a compact object with short keys.
Encode as query params.
Debounce updates so the URL doesn’t thrash while typing.

Example pattern (simplified):

// state/urlState.ts
import { z } from "zod";

export type AppState = {
  w: number;          // load watts
  h: number;          // backup hours
  v: 12 | 24 | 48;    // system voltage
  dod: number;        // depth of discharge
};

const StateSchema = z.object({
  w: z.number().min(0).max(20000),
  h: z.number().min(0).max(72),
  v: z.union([z.literal(12), z.literal(24), z.literal(48)]),
  dod: z.number().min(0.1).max(0.95),
});

export function encodeState(state: AppState): string {
  const params = new URLSearchParams();
  params.set("w", String(state.w));
  params.set("h", String(state.h));
  params.set("v", String(state.v));
  params.set("dod", String(state.dod));
  return params.toString();
}

export function decodeState(search: string, fallback: AppState): AppState {
  const params = new URLSearchParams(search);
  const candidate = {
    w: Number(params.get("w") ?? fallback.w),
    h: Number(params.get("h") ?? fallback.h),
    v: Number(params.get("v") ?? fallback.v),
    dod: Number(params.get("dod") ?? fallback.dod),
  };

  const parsed = StateSchema.safeParse(candidate);
  return parsed.success ? parsed.data : fallback;
}

Two details matter more than they seem:

Validation on decode. People will paste weird URLs, bots will crawl, and you’ll ship new versions. If you don’t validate, you’ll ship runtime errors.
Stable keys. Once people share URLs, those links become quasi-API contracts. Breaking them is breaking trust.

If you want to go further, you can compress the state into a single s= parameter using something like lz-string. I avoided that early because debugging becomes harder and the “contract” becomes opaque. For AhCalc, short keys + a small state object was enough.

Region defaults and “honest fallbacks”: building for India without locking out everyone else

A calculator is only as good as its defaults. Defaults are product decisions disguised as engineering.

For India-focused usage, a few defaults are simply more likely:

Common inverter/battery systems at 12V/24V for small setups.
Typical residential backup expectations (fans, lights, router, TV, fridge).
Solar production assumptions based on peak sun hours that match real planning ranges.

But hardcoding India-only assumptions would be a mistake. People travel, people build in different regions, and the web is global.

The pattern I used is what I’d call region-first defaults with honest fallbacks:

Prefer a region default when the user hasn’t expressed a preference.
Make the assumption visible and editable.
If the region cannot be determined reliably, fall back to a conservative global default.

I deliberately didn’t add geolocation prompts. Asking for location permission to calculate battery Ah is the kind of “growth” move that quietly ruins trust.

A practical approach is:

Use a lightweight heuristic (locale/timezone) to pick a default.
Never block usage.
Never hide the chosen default.

Example heuristic:

// region/defaults.ts
export type Region = "IN" | "GLOBAL";

export function detectRegion(): Region {
  // Avoid permission prompts; keep it predictable.
  const tz = Intl.DateTimeFormat().resolvedOptions().timeZone || "";
  if (tz.startsWith("Asia/Kolkata")) return "IN";

  const lang = navigator.language || "";
  if (lang.toLowerCase().startsWith("en-in")) return "IN";

  return "GLOBAL";
}

export function defaultPeakSunHours(region: Region): number {
  // Conservative planning defaults.
  return region === "IN" ? 4.5 : 4.0;
}

Tradeoff: timezone/locale is imperfect. That’s fine. Defaults are not destiny; they’re a starting point.

The real win is that users get a result immediately that feels relevant, and advanced users can change assumptions without fighting the UI.

Recommendations without pretending certainty: product matching logic that doesn’t feel random

A lot of calculators jump from “you need 143Ah” to “buy this exact 150Ah battery.” That’s seductive, and it’s also misleading.

Real purchasing constraints include:

Available capacities in your market (100Ah, 150Ah, 200Ah…)
Series/parallel configurations (especially when moving to 24V/48V)
Surge loads and inverter headroom
Battery chemistry differences (lead-acid vs LiFePO4)

If you recommend a single SKU, you’re implicitly endorsing a wiring plan, a chemistry, and a budget. That’s not a calculator anymore—it’s a sales funnel.

AhCalc’s approach is closer to: compute the requirement, then show a small set of plausible configurations that meet it, with clear constraints.

Pattern:

Compute required Wh/Ah.
Generate candidate configurations from common building blocks.
Filter out candidates that violate constraints.
Sort by “least overshoot” (or cost proxy if you have pricing).
Present 3–6 options, not 30.

Example (simplified candidate generation):

// calc/matching.ts
export type BatteryBlock = { ah: number; voltage: 12 | 24 | 48 };
export type BatteryConfig = {
  blocksInSeries: number;
  stringsInParallel: number;
  totalVoltage: number;
  totalAh: number;
};

export function matchBatteryConfigs(
  requiredAh: number,
  systemVoltage: 12 | 24 | 48,
  blocks: BatteryBlock[] = [
    { ah: 100, voltage: 12 },
    { ah: 150, voltage: 12 },
    { ah: 200, voltage: 12 },
  ]
): BatteryConfig[] {
  const configs: BatteryConfig[] = [];

  for (const block of blocks) {
    // Only consider blocks that can be composed to the system voltage
    if (systemVoltage % block.voltage !== 0) continue;

    const series = systemVoltage / block.voltage;

    for (let parallel = 1; parallel <= 6; parallel++) {
      const totalAh = block.ah * parallel;
      if (totalAh < requiredAh) continue;

      configs.push({
        blocksInSeries: series,
        stringsInParallel: parallel,
        totalVoltage: systemVoltage,
        totalAh,
      });
    }
  }

  return configs
    .sort((a, b) => a.totalAh - b.totalAh)
    .slice(0, 6);
}

This is not “AI recommendations.” It’s deterministic, explainable logic. That’s a feature.

Failure modes to watch:

Too many candidates: users freeze. Keep it tight.
Candidates that look equal: add tie-breakers (fewer parallel strings is often preferable for simplicity).
Market mismatch: if your block list doesn’t match what people can buy, the tool feels fake. Keep the block list regional or user-selectable.

If you ever add pricing, do it carefully. Price data goes stale fast and creates support burden. For most calculators, “configuration plausibility” beats “exact shopping cart.”

The small UI details that made it feel fast: animated numbers, React 19, and avoiding form fatigue

The math can be correct and the tool can still feel unpleasant.

Two UX problems show up in calculators:

Users don’t trust results when numbers jump abruptly.
Users abandon when input feels like a tax (too many fields, too much reading).

AhCalc leaned into instant feedback: change one input, watch outputs update smoothly. That’s not decoration; it’s comprehension. When the number animates from 120Ah to 180Ah as you increase backup hours, your brain understands causality.

Implementation-wise, I kept it simple:

Use React 19 + TypeScript for predictable state and rendering.
Keep calculations synchronous and cheap.
Animate only the displayed number (not the underlying state).

If you’re building something similar, resist the urge to introduce a state management library early. For a calculator, local state + derived computed values is usually enough.

Also: avoid “wizard” flows unless you absolutely need them. A single-page, editable view wins because users compare scenarios. They don’t fill a form once; they tweak.

One more tradeoff I’ll defend: I intentionally kept the app backend-free. Yes, you lose analytics depth and account-based features. But you gain:

Near-zero operational overhead
Better performance and reliability
A product that feels neutral and trustworthy

If you want lightweight analytics, use privacy-respecting tools and keep them optional. For example, Plausible (https://plausible.io/) is a common choice for simple, cookie-light analytics.

What I’d recommend if you’re turning repeated questions into a public tool

Building AhCalc reinforced a few rules I now treat as defaults for “small, useful software”:

Start with the repeated question, not the feature list. The question already contains the UX.
Make assumptions explicit (DoD, efficiency, sun hours). Hidden assumptions are where tools become untrustworthy.
Don’t hide the answer behind a funnel. If the tool is genuinely useful, distribution happens anyway.
Keep the core logic pure and testable. UI can change weekly; math should be stable.
Make it shareable by design. If your users can’t send a link that reproduces results, you’ve added friction where people most want speed.

If you’re deciding what to build first, here’s the decision rule I’d actually use:

If your calculator can’t produce a decent answer in under 15 seconds without requiring personal info, don’t ship it yet. Fix that first. Everything else—SEO pages, product comparisons, “download report” buttons—comes later.

If you’re curious (or you just want to stop doing battery math in your head), try AhCalc at https://ahcalc.com and see how it fits your own solar, battery, and inverter sizing needs.

Read the full post on QCode: https://qcode.in/building-ahcalc-a-solar-and-battery-sizing-tool-people-actually-use/

Laravel Testing Complex Domain Logic Without Over-Mocking

Saqueib Ansari — Mon, 06 Apr 2026 05:31:34 +0000

Testing complex domain workflows in Laravel gets painful fast when every test becomes a maze of mocks. The suite turns brittle, refactors become scary, and you end up “testing the mocks” instead of the behavior that matters. The fix isn’t to ban mocking entirely—it’s to be deliberate: use the real container, real database state, and only mock true boundaries.

This post walks through a pragmatic approach to Laravel testing complex domain logic with minimal mocking: how to structure code to be testable, how to choose the right test type, and how to keep tests fast and reliable while still exercising real workflows.

The core problem with over-mocking in Laravel

Over-mocking usually starts with good intentions: “unit tests should be fast,” “don’t hit the database,” “mock external services.” But in Laravel applications with non-trivial domain logic, the line between domain behavior and framework glue often gets blurred.

Why over-mocking makes tests less reliable

Common failure modes:

False confidence: You assert that a mocked method was called, but you never validate that the system produced the correct state or output.
Brittle refactors: Renaming a method, changing an internal collaborator, or moving logic across classes breaks tests even if behavior is unchanged.
Unrealistic behavior: Your mock returns “happy path” values that can’t happen in production (or ignores edge cases like transactions, concurrency, serialization, timestamps).
Inability to reproduce bugs: The bug occurred due to real database state or a subtle interaction (e.g., query scopes, constraints, event ordering). Mock-heavy tests can’t capture it.

Laravel specifically amplifies this because:

Eloquent behavior is deeply tied to persistence, relationships, casts, mutators, and events.
Transactions and queue dispatching change the timing and ordering of side effects.
The service container is a runtime composition tool; mocking everything often means you never test the actual wiring.

What to mock (and what not to)

A practical rule:

Mock network boundaries: HTTP APIs, payment gateways, email/SMS providers, LLM calls, object storage.
Prefer fakes for Laravel-provided boundaries: Queue::fake(), Event::fake(), Mail::fake(), Http::fake(), Storage::fake().
Avoid mocking domain collaborators that are part of the same bounded context and run in-process (e.g., pricing rules, state transitions, policy checks). Those are exactly what you want to validate.

When you do mock internal collaborators, do it for one of two reasons:

The collaborator is slow or nondeterministic (time, randomness, external IO).
The collaborator is not part of the behavior under test (e.g., a logger, metrics emitter).

A testing strategy that scales: “real state, minimal boundaries”

Instead of “unit vs integration” as a binary, think in layers:

Domain-level tests: Exercise a workflow/service with real models and persistence, but fake external boundaries.
HTTP feature tests: Validate request/response, auth, validation, and that the workflow is invoked correctly.
Pure unit tests (few): Only for algorithmic code that’s genuinely independent of Laravel/Eloquent.

In Laravel terms, most complex business workflows are best tested as application service tests (sometimes called “use-case tests”) using:

RefreshDatabase (or DatabaseTransactions in some setups)
Factories + explicit state setup
Fakes for external boundaries
Assertions on database state, events dispatched, jobs queued, domain invariants

Make the database your primary assertion surface

If the workflow’s purpose is to change state, assert state.

Use assertDatabaseHas() / assertDatabaseMissing()
Reload models ($model->refresh()) before asserting
Assert invariants: totals, statuses, relationships, audit records

This is more robust than asserting internal method calls.

Use time control and deterministic IDs when needed

Complex workflows often depend on time.

Use Carbon helpers: Carbon::setTestNow()
If you use UUIDs, consider deterministic generation in tests (or assert shape rather than exact value).

Keep tests fast without mocking everything

Speed comes from:

Efficient factories (avoid creating huge graphs by default)
SQLite in-memory only if it matches production behavior (often it doesn’t for JSON, constraints, or concurrency)
Running fewer, more meaningful tests: test workflows, not every private method

If you’re on MySQL/Postgres in production, prefer matching that in CI to avoid “works in SQLite” surprises.

Pattern: test the workflow service with real Eloquent + faked boundaries

A clean way to avoid over-mocking is to concentrate complexity into a workflow class (application service) that is container-resolved and uses Eloquent repositories/models.

Example domain: placing an order with:

inventory reservation
coupon validation
payment authorization (external)
order state transitions
dispatching a confirmation email/job

Example 1: Order placement workflow test (minimal mocks)

Let’s assume you have a workflow class like:

App\Domain\Orders\PlaceOrder

It might depend on:

PaymentGateway (external boundary)
InventoryService (could be internal, but still domain critical)
Eloquent models (Order, OrderItem, Coupon, Product)

In tests, you fake the gateway and assert persisted state.

<?php

namespace Tests\Feature\Domain\Orders;

use App\Domain\Orders\PlaceOrder;
use App\Domain\Payments\PaymentGateway;
use App\Models\Coupon;
use App\Models\Order;
use App\Models\Product;
use App\Models\User;
use Carbon\Carbon;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Illuminate\Support\Facades\Bus;
use Illuminate\Support\Facades\Event;
use Tests\TestCase;

class PlaceOrderTest extends TestCase
{
    use RefreshDatabase;

    public function test_it_places_an_order_reserves_stock_and_queues_confirmation(): void
    {
        Carbon::setTestNow('2026-04-01 10:00:00');

        Bus::fake();
        Event::fake();

        $user = User::factory()->create();

        $product = Product::factory()->create([
            'price_cents' => 5000,
            'stock' => 10,
        ]);

        $coupon = Coupon::factory()->create([
            'code' => 'APRIL10',
            'discount_percent' => 10,
            'starts_at' => now()->subDay(),
            'ends_at' => now()->addDay(),
        ]);

        // Mock only the true external boundary.
        $this->mock(PaymentGateway::class, function ($mock) {
            $mock->shouldReceive('authorize')
                ->once()
                ->andReturn([
                    'provider' => 'stripe',
                    'authorization_id' => 'auth_123',
                    'status' => 'authorized',
                ]);
        });

        /** @var PlaceOrder $placeOrder */
        $placeOrder = app(PlaceOrder::class);

        $order = $placeOrder->handle(
            user: $user,
            items: [
                ['product_id' => $product->id, 'quantity' => 2],
            ],
            couponCode: 'APRIL10',
        );

        $this->assertInstanceOf(Order::class, $order);

        $this->assertDatabaseHas('orders', [
            'id' => $order->id,
            'user_id' => $user->id,
            'status' => 'authorized',
            'subtotal_cents' => 10000,
            'discount_cents' => 1000,
            'total_cents' => 9000,
            'authorized_at' => '2026-04-01 10:00:00',
        ]);

        $this->assertDatabaseHas('order_items', [
            'order_id' => $order->id,
            'product_id' => $product->id,
            'quantity' => 2,
            'unit_price_cents' => 5000,
        ]);

        $product->refresh();
        $this->assertSame(8, $product->stock);

        // Assert the side effect was scheduled, not that some internal method was called.
        Bus::assertDispatched(\App\Jobs\SendOrderConfirmation::class, function ($job) use ($order) {
            return $job->orderId === $order->id;
        });
    }
}

What this test buys you:

It validates real calculations (subtotal/discount/total)
It validates real persistence and relationships
It validates inventory mutation
It validates the workflow’s contract with the external payment boundary
It validates a meaningful side effect (job dispatched)

What it avoids:

Mocking Eloquent models
Mocking internal services that define the behavior under test
Asserting method calls between internal collaborators

Tradeoffs and how to keep it maintainable

These tests are slower than pure unit tests, but they’re usually far fewer and far more valuable.
They require good factories and predictable defaults.
You must be intentional about boundaries: mock the gateway, but keep the rest real.

Use transactions and outbox-like patterns to avoid flaky “half-committed” tests

Complex workflows often combine:

database writes
dispatching jobs/events
external calls

The classic failure mode: you dispatch a job/event before the transaction commits, the job runs, and it can’t see the data yet (or sees partial data). Laravel has tooling for this, but your tests should enforce the behavior you want.

Prefer after-commit dispatching for jobs/events tied to persisted state

Laravel supports dispatching jobs after commit in a few ways (depending on how you dispatch).

Jobs can implement ShouldQueue and use $afterCommit = true;
Events/listeners can be configured to run after commit

If you don’t do this, you’ll see flaky behavior in production under concurrency even if tests pass.

Example 2: Testing after-commit dispatch behavior

Assume SendOrderConfirmation should only be queued after the order is committed.

<?php

namespace Tests\Feature\Domain\Orders;

use App\Domain\Orders\PlaceOrder;
use App\Jobs\SendOrderConfirmation;
use App\Models\Product;
use App\Models\User;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Illuminate\Support\Facades\Bus;
use Illuminate\Support\Facades\DB;
use Tests\TestCase;

class OrderAfterCommitDispatchTest extends TestCase
{
    use RefreshDatabase;

    public function test_confirmation_job_is_dispatched_only_after_commit(): void
    {
        Bus::fake();

        $user = User::factory()->create();
        $product = Product::factory()->create([
            'price_cents' => 5000,
            'stock' => 10,
        ]);

        /** @var PlaceOrder $placeOrder */
        $placeOrder = app(PlaceOrder::class);

        DB::beginTransaction();

        $order = $placeOrder->handle(
            user: $user,
            items: [['product_id' => $product->id, 'quantity' => 1]],
            couponCode: null,
        );

        // If the job is configured for after-commit, it should not be visible yet.
        Bus::assertNotDispatched(SendOrderConfirmation::class);

        DB::commit();

        Bus::assertDispatched(SendOrderConfirmation::class, function ($job) use ($order) {
            return $job->orderId === $order->id;
        });
    }
}

This test is incredibly effective at preventing a real class of production bugs. It also demonstrates the broader theme: you’re validating observable behavior (dispatch timing) rather than internal call chains.

When faking is better than mocking

Laravel’s fakes are purpose-built to validate behavior without coupling to implementation.

Http::fake() for external HTTP calls (and you can assert request payloads)
Queue::fake() / Bus::fake() for async behavior
Event::fake() for domain events
Mail::fake() for emails

Official docs:

Designing code to be testable without mocks

If your code requires heavy mocking to test, it’s often a design smell. The goal isn’t “more layers,” it’s better seams.

Keep orchestration in one place

A workflow/service should orchestrate:

loading aggregates (orders, subscriptions, invoices)
applying domain rules
persisting changes
emitting events / scheduling async work

Avoid scattering the logic across controllers, model observers, random helpers, and queued jobs. Otherwise, tests need to mock half the app just to isolate behavior.

Prefer explicit dependencies over static calls

Static/facade calls are testable in Laravel, but they can hide dependencies.

For domain logic, prefer injecting interfaces (e.g., PaymentGateway) and using facades mostly at the application boundary.
For time, prefer now()/Carbon with setTestNow() rather than time().

Use value objects and small pure functions where it matters

Not everything needs to hit the database. The sweet spot is:

core calculations in pure code (easy unit tests)
persistence and orchestration tested with real DB

For example, a pricing calculator can be pure:

final class PriceBreakdown
{
    public function __construct(
        public readonly int $subtotalCents,
        public readonly int $discountCents,
        public readonly int $totalCents,
    ) {}
}

final class Pricing
{
    public static function calculate(int $unitPriceCents, int $qty, int $discountPercent = 0): PriceBreakdown
    {
        $subtotal = $unitPriceCents * $qty;
        $discount = (int) round($subtotal * ($discountPercent / 100));
        $total = max(0, $subtotal - $discount);

        return new PriceBreakdown($subtotal, $discount, $total);
    }
}

You can unit test this with no Laravel at all, while still testing the full workflow end-to-end with real persistence.

Watch out for Eloquent events/observers as hidden behavior

Observers are tempting, but they create invisible side effects:

“Saving an Order automatically recalculates totals”
“Creating a User automatically creates a Profile”

These behaviors are hard to reason about and hard to test without coupling. If you use observers, add tests that validate the observer behavior explicitly, and keep critical workflows from relying on “magic” that triggers indirectly.

Practical heuristics: choosing the right test and avoiding brittleness

A few battle-tested heuristics for complex Laravel apps.

1) Assert outcomes, not interactions

Prefer:

assertDatabaseHas
Bus::assertDispatched
Event::assertDispatched
Http::assertSent

Avoid:

shouldReceive('methodX')->once() on internal collaborators unless it’s a true boundary.

2) Use factories, but don’t let them hide intent

Factories should help, but not obscure the scenario.

Bad: a UserFactory that creates 12 related models by default.

Good: defaults are minimal; relationships are opt-in.

3) Test invariants and edge cases where bugs actually happen

For domain workflows, the money is in:

concurrency-ish issues (stock, idempotency)
invalid state transitions
rounding and currency math
“already processed” / retry behavior

If your workflow supports idempotency (highly recommended for payments/webhooks), add a test that calls the workflow twice and asserts no duplicates.

4) Mock only what you can’t own

If it’s your code and it’s central to the domain, mocking it usually reduces value. If it’s a vendor system or network boundary, mocking/faking is correct.

5) Keep an eye on test runtime, but optimize the right thing

If your suite is slow:

Reduce unnecessary factory graph creation
Use make() instead of create() when persistence isn’t needed
Avoid hitting external services (use fakes)
Run the heavier tests in parallel (Laravel supports parallel testing)

Official docs: https://laravel.com/docs/testing#running-tests-in-parallel

Conclusion: build fewer tests, but make them real

For complex workflows, the most maintainable Laravel test suites are the ones that validate real state and observable side effects, while mocking only true boundaries. Put orchestration into workflow services, keep calculations pure where possible, use Laravel fakes for queues/events/http, and assert on database outcomes.

If you’re starting from a mock-heavy suite, pick one critical workflow (payments, provisioning, billing, fulfillment), rewrite its tests to use real persistence + minimal boundary mocks, and measure the difference: fewer tests, more confidence, and refactors that stop being scary.

Read the full post on QCode: https://qcode.in/laravel-testing-complex-domain-logic-without-over-mocking/

Laravel API Pagination Strategies That Actually Scale

Saqueib Ansari — Fri, 03 Apr 2026 05:11:13 +0000

When building APIs with Laravel that serve large data sets, pagination isn't just a nice-to-have—it's essential for maintaining performance and user experience. Choosing the right pagination strategy can dramatically affect your backend query efficiency and how smoothly clients can navigate large collections.

Understanding Pagination Methods in Laravel

Laravel offers several pagination methods out of the box, but not all fit every use case, especially when dealing with massive datasets or complex queries.

Offset Pagination

The classic approach, offset pagination, works by skipping a number of records and fetching the next chunk:

$users = User::orderBy('id')->skip($offset)->take($limit)->get();

Laravel's paginate() method uses this internally:

$users = User::orderBy('id')->paginate(15);

Pros:

Easy to implement
Works well for small to medium data sets

Cons:

Performance degrades with large offsets because the database scans and skips rows
Can cause inconsistent results if data changes between requests

Cursor Pagination

Laravel 8+ introduced native support for cursor pagination, which uses a unique key (usually an ID) to paginate without skipping rows:

$users = User::orderBy('id')->cursorPaginate(15);

This returns a cursor that clients pass back to fetch the next page.

Pros:

Scales well with large datasets
More consistent with live data changes
Avoids expensive OFFSET scans

Cons:

Requires a unique, sequential column for ordering
Less intuitive for clients (cursor tokens instead of page numbers)

Keyset Pagination

Keyset pagination is conceptually similar to cursor pagination but often implemented manually for complex queries. It filters results based on the last seen record's key:

$lastId = $request->query('last_id');
$users = User::where('id', '>', $lastId)->orderBy('id')->limit(15)->get();

Pros:

Extremely performant for very large datasets
Can be customized for composite keys or multiple ordering columns

Cons:

More manual work than built-in cursor pagination
Clients must manage the last seen key

Choosing the Right Pagination Strategy

When to Use Offset Pagination

Small to moderate data sets
When simplicity is more important than raw performance
When clients expect page numbers

When to Use Cursor or Keyset Pagination

APIs with large or growing data sets
When consistent pagination over frequently changing data is critical
To reduce database load and improve response times

Implementing Cursor Pagination in Laravel

To implement cursor pagination efficiently:

Use an indexed column (usually id or created_at) for ordering.
Ensure your API returns the cursor token from the previous page.
Handle cursor tokens on the client side properly.

Example controller method:

use App\Models\User;
use Illuminate\Http\Request;

public function index(Request $request)
{
    $users = User::orderBy('id')->cursorPaginate(15);
    return response()->json($users);
}

The response includes next_cursor and prev_cursor links that clients can use.

Real-World Takeaways

Avoid offset pagination for APIs with millions of rows. The database workload grows linearly as users request higher page numbers.
Cursor pagination is the Laravel-native solution for large datasets—it strikes a balance between performance and developer ergonomics.
Manual keyset pagination suits highly customized queries or complex sorting requirements.
Always index your pagination keys to maximize query speed.
Communicate pagination strategy clearly in your API docs so clients can implement navigation correctly.

Conclusion

Laravel's pagination methods offer flexible options to handle large data sets effectively. For modern APIs requiring scalability and consistent user experience, cursor pagination is generally the best choice in 2024 and beyond. However, understanding your data access patterns and client needs is vital to select the optimal strategy.

Explore Laravel's official documentation on pagination for the latest features and best practices.

By carefully implementing the right pagination strategy, you ensure your Laravel API remains performant, scalable, and developer-friendly even as your data grows exponentially.

Next.js + Laravel Auth: A Clear Path to Manage Session Boundaries

Saqueib Ansari — Fri, 03 Apr 2026 04:30:01 +0000

If your Next.js frontend and Laravel backend auth setup feels fragile, it usually is. Most teams are not fighting authentication itself. They are fighting session boundaries, cookie scope, CSRF expectations, and mismatched assumptions between browser, frontend app, and API server.

The fix is not another random middleware tweak. The fix is picking a clean architecture and being consistent about it across local development and production.

For a Next.js Laravel auth stack, my strong opinion is simple: let Laravel own authentication and session state, let the browser carry the cookies, and let Next.js act as the application UI layer, not a second auth server pretending to be smarter than the first one.

Stop mixing session auth and token auth without a reason

A lot of broken setups come from trying to combine Laravel Sanctum session auth, custom JWT flows, and frontend-side auth abstractions in one stack. That usually creates more surface area, not more flexibility.

If your product is a normal browser-based SaaS app, use cookie-based session auth with Laravel and keep it boring.

That means:

Laravel handles login, logout, session creation, CSRF, authorization, and user identity
Next.js calls Laravel with credentials: 'include'
The browser stores and sends cookies automatically
Protected user state is fetched from Laravel, not reinvented in the frontend
Use token auth only when you genuinely need it, like:
mobile clients
third-party API consumers
machine-to-machine access
public API products
For a browser app, cookie sessions are usually the right answer because they align with how browsers already work.

The architecture that avoids most auth bugs

The cleanest setup looks like this:

Production domains

Frontend: app.qcode.in
Backend: api.qcode.in
Session domain: .qcode.in ### Local development domains

Do not build auth on localhost chaos if you can avoid it. Use consistent local domains instead:

Frontend: app.qcode.test
Backend: api.qcode.test
Session domain: .qcode.test Then make Laravel explicit.

// .env
APP_URL=https://api.qcode.test
FRONTEND_URL=https://app.qcode.test
SESSION_DOMAIN=.qcode.test
SANCTUM_STATEFUL_DOMAINS=app.qcode.test,api.qcode.test,app.qcode.in,api.qcode.in
SESSION_SECURE_COOKIE=true
SESSION_SAME_SITE=lax

And keep CORS strict enough to work, not loose enough to hide mistakes.

// config/cors.php
return [
    'paths' => ['api/*', 'login', 'logout', 'sanctum/csrf-cookie'],
    'allowed_methods' => ['*'],
    'allowed_origins' => [
        'https://app.qcode.test',
        'https://app.qcode.in',
    ],
    'allowed_headers' => ['*'],
    'supports_credentials' => true,
];

Using * with credentials is not valid. Be explicit.

The request flow that actually works

When using Laravel Sanctum with session auth, the browser flow matters.

Step 1: Prime CSRF

Before login, ask Laravel for the CSRF cookie.

await fetch('https://api.qcode.test/sanctum/csrf-cookie', {
  method: 'GET',
  credentials: 'include',
});

Step 2: Log in with cookies enabled

Then log in with credentials included and standard AJAX headers.

await fetch('https://api.qcode.test/login', {
  method: 'POST',
  credentials: 'include',
  headers: {
    'Content-Type': 'application/json',
    'X-Requested-With': 'XMLHttpRequest',
  },
  body: JSON.stringify({ email, password }),
});

Step 3: Fetch the authenticated user

After login, fetch the user from Laravel. Do not invent a second source of truth.

const response = await fetch('https://api.qcode.test/api/user', {
  method: 'GET',
  credentials: 'include',
  headers: {
    'Accept': 'application/json',
    'X-Requested-With': 'XMLHttpRequest',
  },
});

const user = await response.json();

If you want a reusable client in Next.js App Router, keep it thin.

const API_BASE = process.env.NEXT_PUBLIC_API_BASE_URL!;

export async function apiFetch(path: string, init: RequestInit = {}) {
  return fetch(`${API_BASE}${path}`, {
    ...init,
    credentials: 'include',
    headers: {
      'Accept': 'application/json',
      'X-Requested-With': 'XMLHttpRequest',
      ...(init.headers ?? {}),
    },
  });
}

That is the core loop. No fake local auth cache. No duplicated token parsing. No fragile frontend-side session emulation.

Where most teams break the boundary

This stack usually fails in the same places.

1. Wrong cookie domain

If the session cookie is bound to api.qcode.in instead of .qcode.in, your frontend app on app.qcode.in will not behave the way you expect.

2. Missing `credentials: 'include'`

If your fetch client does not include credentials, you are not doing session auth. You are doing anonymous requests and hoping for magic.

3. Bad CORS config

Laravel must explicitly allow the frontend origin and credentials.

4. Trying to read HttpOnly cookies in client code

You should not need to. That is the whole point of HttpOnly cookies. Let the browser send them.

5. SSR assumptions that do not match browser reality

If a page is rendered on the server, your Next.js server runtime may not automatically have the same cookie context as the user’s browser session. That means you need a deliberate strategy.

The two sane options are:

render auth-sensitive screens from the client after loading the user
forward cookies through route handlers or server components intentionally Do not casually mix both patterns across the app.

What I would ship in a real product

For most internal SaaS or dashboard-style products, this setup is hard to beat:

Laravel for auth, sessions, policies, and user data
Sanctum for SPA session auth
Next.js App Router for UI and product surface
subdomain-based separation between frontend and backend
HTTPS in every environment that matters
explicit CORS and cookie settings
minimal auth state in the frontend
I would avoid:
bolting NextAuth on top of Laravel session auth unless there is a very specific need
storing user auth state in multiple places
debugging cookies on localhost for weeks instead of using proper local domains
mixing SSR, edge middleware, client auth guards, and token refresh logic without a clear boundary
The big idea is simple: one system should own auth. In this stack, that system should usually be Laravel.

Once you accept that, the implementation gets much less confusing.

If your current Next.js Laravel auth setup feels unstable, stop patching symptoms. Redraw the boundary. Let Laravel own the session, let the browser carry the cookie, and let Next.js focus on shipping product features instead of roleplaying as an identity provider.

Official docs worth keeping open while implementing this:

Laravel Sanctum: https://laravel.com/docs/sanctum
Laravel session config: https://laravel.com/docs/session
Next.js App Router: https://nextjs.org/docs/app
MDN Fetch credentials: https://developer.mozilla.org/en-US/docs/Web/API/Request/credentials

The Developer's Guide to Why Your Codebase Is Secretly Burning Claude Tokens

Saqueib Ansari — Tue, 31 Mar 2026 14:17:01 +0000

Every month, developers stare at their Anthropic invoices wondering where all their tokens went — the answer is almost always hiding in plain sight inside their own codebase.

Why Your Codebase Is Secretly Burning Claude Tokens (And You Don't Even Know It)

Most token waste isn't dramatic. It's not one rogue prompt that blows your budget. It's the slow, invisible hemorrhage caused by architectural decisions that made sense when you first wired Claude into your app but quietly compound into thousands of wasted tokens per day. Understanding why your codebase is secretly burning Claude tokens is the first step toward fixing it.

Let's break down the most common culprits and, more importantly, how to kill them.

The Context Window Overloading Problem

The single biggest offender in most codebases is context overloading — dumping everything into the prompt because it's easier than thinking carefully about what Claude actually needs.

Consider this pattern that shows up constantly in Laravel applications:

// The expensive anti-pattern
$response = $claude->messages()->create([
    'model' => 'claude-opus-4-5',
    'max_tokens' => 1024,
    'messages' => [
        [
            'role' => 'user',
            'content' => "Here is our entire product catalog: " . 
                         Product::all()->toJson() . 
                         "\n\nHere are all customer orders: " . 
                         Order::all()->toJson() . 
                         "\n\nNow answer this question: " . $userQuestion
        ]
    ]
]);

That Product::all() call on a catalog with 500 products can easily add 40,000–80,000 tokens to every single request. If you're running 1,000 requests per day, you just burned 80 million tokens answering questions that probably only needed 200 rows of context.

The fix: Implement semantic retrieval. Use pgvector or a dedicated vector store like Pinecone or Weaviate to fetch only the top-k relevant records before building your prompt. A well-tuned RAG pipeline will typically reduce context size by 85–95% while improving answer quality because the model isn't wading through irrelevant noise.

// The efficient pattern
$relevantProducts = $vectorStore->similaritySearch($userQuestion, topK: 10);

$response = $claude->messages()->create([
    'model' => 'claude-opus-4-5',
    'max_tokens' => 1024,
    'messages' => [
        [
            'role' => 'user',
            'content' => "Relevant products:\n" . 
                         collect($relevantProducts)->toJson() . 
                         "\n\nQuestion: " . $userQuestion
        ]
    ]
]);

System Prompt Bloat Is Draining Your Budget

This one is painful because it's usually caused by good intentions. Teams iterate on their system prompts, adding more instructions, more examples, more edge case handling — and before long you've got a 3,000-token system prompt being sent on every request, even the ones that only need 50 tokens to complete.

The Hidden Cost of Static System Prompts

In the Claude API, your system prompt counts toward your token bill on every call. A 3,000-token system prompt across 10,000 daily requests costs you 30 million tokens per day before Claude has read a single word of actual user input.

Audit your system prompt ruthlessly. Ask yourself:

Does every instruction apply to every request type?
Are you including few-shot examples that could be dynamic instead of static?
Are you explaining Claude's own capabilities back to it (it already knows)?

Dynamic system prompts are underused and underrated. Route different request types to purpose-built, minimal system prompts rather than one bloated universal one:

class SystemPromptRouter
{
    public function getPrompt(string $taskType): string
    {
        return match($taskType) {
            'summarize'  => "Summarize the following text concisely.",
            'classify'   => "Classify the input into one of the provided categories.",
            'extract'    => "Extract the requested fields from the input as JSON.",
            default      => "You are a helpful assistant."
        };
    }
}

A targeted 20-token system prompt does the same job as a 2,000-token one if the task is specific enough.

You're Probably Not Using Prompt Caching

As of mid-2026, Claude's prompt caching feature is one of the highest-impact optimizations available and still wildly underused. With prompt caching, you can mark large, stable portions of your prompt (like a lengthy system prompt, a reference document, or a large code file) to be cached by Anthropic's infrastructure. Cached tokens are charged at roughly 10% of the normal input token price.

If you're building a code assistant that always sends a 10,000-token codebase context, prompt caching alone can cut your input costs by 90% on cache hits. The implementation is a single API change:

$response = $client->messages()->create([
    'model' => 'claude-opus-4-5',
    'max_tokens' => 2048,
    'system' => [
        [
            'type' => 'text',
            'text' => $largeSystemPrompt,
            'cache_control' => ['type' => 'ephemeral'] // Mark for caching
        ]
    ],
    'messages' => $conversationHistory
]);

If you're not using this today, you're leaving money on the table every single hour your app is running.

Why Your Codebase Is Secretly Burning Claude Tokens Through Redundant API Calls

Beyond what's inside your prompts, many codebases waste tokens by making calls they simply shouldn't be making at all.

The Missing Cache Layer Problem

Response caching is table-stakes infrastructure for any serious Claude integration, yet it's absent from most codebases beyond prototype stage. Identical or near-identical queries hitting Claude repeatedly is pure waste. Full stop.

class CachedClaudeService
{
    public function __construct(
        private ClaudeClient $claude,
        private Cache $cache
    ) {}

    public function ask(string $prompt, int $ttl = 3600): string
    {
        $cacheKey = 'claude:' . hash('xxh3', $prompt);

        return $this->cache->remember($cacheKey, $ttl, function () use ($prompt) {
            $response = $this->claude->messages()->create([
                'model'      => 'claude-haiku-4-5',
                'max_tokens' => 512,
                'messages'   => [['role' => 'user', 'content' => $prompt]]
            ]);

            return $response->content[0]->text;
        });
    }
}

For many product use cases — FAQ answering, classification tasks, template-based generation — cache hit rates of 40–70% are achievable. At scale, that's a massive reduction in both cost and latency.

Model Selection Mismatch

Using claude-opus-4-5 for every task is like hiring a senior architect to check whether your HTML has a closing tag. Claude Haiku is dramatically cheaper per token and handles the majority of classification, extraction, formatting, and simple Q&A tasks with equivalent quality.

Implement a task router that matches complexity to model:

Task Type	Recommended Model	Why
Classification / Extraction	claude-haiku-4-5	Fast, cheap, sufficient
Summarization	claude-sonnet-4-5	Balanced quality/cost
Complex reasoning / Code gen	claude-opus-4-5	Worth the premium

The cost difference between Haiku and Opus is roughly 25x. Routing even 60% of your traffic to Haiku will transform your unit economics. Why are you paying Opus prices for work that doesn't need it?

Monitoring: You Can't Fix What You Can't See

None of the above optimizations stick unless you build token usage observability into your application. Log input tokens, output tokens, model used, cache hit/miss status, and the feature or endpoint that triggered each call.

Tools like LangSmith, Helicone, and Braintrust provide this out of the box with minimal instrumentation. Even a simple database log table beats flying blind:

ClaudeUsageLog::create([
    'model'          => $response->model,
    'input_tokens'   => $response->usage->input_tokens,
    'output_tokens'  => $response->usage->output_tokens,
    'cache_hit'      => $response->usage->cache_read_input_tokens > 0,
    'endpoint'       => request()->route()->getName(),
    'cost_usd'       => $this->calculateCost($response->usage),
]);

Once you have this data, patterns emerge fast. You'll find one endpoint responsible for 40% of your spend, or discover a background job that's been sending a 15,000-token context that nobody reviewed since the initial implementation.

The Real Reason Why Your Codebase Is Secretly Burning Claude Tokens

The root cause isn't technical — it's the absence of a cost-aware development culture. Token cost is invisible during local development. Nobody sees the bill when they push a feature. CI/CD pipelines don't fail because a prompt got bloated by 2,000 tokens. The waste accumulates silently until the invoice lands.

The fix is to treat token efficiency the way you treat database query performance: profile it, review it in code review, set budgets per feature, and alert when usage spikes. Build your integration with prompt caching from day one, implement a semantic retrieval layer before context gets large, and match model tier to task complexity systematically rather than ad hoc.

Every dollar you claw back from token waste is a dollar you can put toward shipping more features, handling more traffic, or simply running a more sustainable AI-powered product. Start with observability, kill the obvious bloat, then work through the list — the improvements compound faster than you'd expect.

This article was originally published on qcode.in

A Developer's Guide to Generating Dynamic Open Graph Images with Laravel AI SDK

Saqueib Ansari — Mon, 30 Mar 2026 02:21:01 +0000

Open Graph images are the silent conversion killers most developers ignore — a compelling OG image can double click-through rates from social platforms, while a missing or generic one gets scrolled past without a second glance. Generating Dynamic Open Graph Images with Laravel AI SDK has become one of the most powerful techniques in a modern Laravel developer's toolkit, combining AI-driven content generation with real-time image rendering to produce visuals that actually match what's on the page.

Why Generating Dynamic Open Graph Images with Laravel AI SDK Changes Everything

Static OG images are a maintenance nightmare. You publish 200 blog posts, and either every post shares the same generic banner (bad for CTR) or someone has to manually design 200 images (bad for sanity). The smarter approach is generating them programmatically — and layering in AI means you're not just templating text onto a canvas, you're producing contextually relevant visuals that reflect the actual content.

The Laravel AI SDK (built on top of Vercel's AI SDK patterns, adapted for PHP environments) gives you structured, streaming, and tool-using AI calls directly inside your Laravel application. Paired with image generation libraries like Intervention Image or headless browser solutions like Browsershot, you get a full pipeline from "article published" to "compelling social card generated" with no human in the loop.

The Core Problem with Manual OG Images

Manual workflows break at scale for three reasons:

Consistency — Designers leave, brand guidelines shift, old images never get updated
Timeliness — By the time a human creates the image, the post is already indexed and shared
Relevance — A human can't read 2,000 words and distill the most compelling visual hook in seconds; an AI model can

The automated pipeline solves all three. When a post is published or updated, a queued job fires, calls the AI to generate a headline variant, accent color suggestion, or background concept, then renders the final image and stores it to S3 or Cloudflare R2.

Setting Up the Laravel AI SDK for Image Generation

Before touching image rendering, get the AI pipeline solid. As of 2026, the recommended way to work with AI models in Laravel is through the Prism PHP package — a first-class Laravel AI SDK that wraps OpenAI, Anthropic, Gemini, and other providers behind a clean, chainable API.

composer require echolabs/prism
php artisan vendor:publish --provider="EchoLabs\Prism\PrismServiceProvider"

Configure your provider in config/prism.php:

'default' => env('PRISM_PROVIDER', 'openai'),

'providers' => [
    'openai' => [
        'api_key' => env('OPENAI_API_KEY'),
        'model' => 'gpt-4o',
    ],
],

Generating the OG Image Copy with AI

The first AI call generates the text elements — a punchy headline, a short subheadline, and optionally a color palette suggestion based on the article's category or mood.

use EchoLabs\Prism\Facades\Prism;
use EchoLabs\Prism\Enums\Provider;

class GenerateOgImageData
{
    public function handle(Post $post): array
    {
        $response = Prism::text()
            ->using(Provider::OpenAI, 'gpt-4o')
            ->withSystemPrompt('You are a social media copywriter. Return JSON only.')
            ->withPrompt("
                Article title: {$post->title}
                Article excerpt: {$post->excerpt}

                Generate a JSON object with:
                - headline: A punchy 6-8 word headline for an Open Graph image
                - subheadline: A 10-12 word supporting line
                - accent_color: A hex color that fits the article's tone
            ")
            ->generate();

        return json_decode($response->text, true);
    }
}

This gives you structured data you can pipe directly into your image renderer. Notice the explicit JSON instruction — with gpt-4o in 2026, structured outputs are reliable, but being explicit in the system prompt still cuts down on edge cases. Don't assume the model will just figure it out.

Building the Image Renderer

With your AI-generated content ready, the rendering layer takes over. There are two solid approaches depending on your requirements:

Option A: Intervention Image (Fast, Server-Side)

Intervention Image v3 is the standard for PHP image manipulation. It's fast, has no external dependencies, and works great for template-based OG images.

use Intervention\Image\ImageManager;
use Intervention\Image\Drivers\Gd\Driver;

class OgImageRenderer
{
    public function render(array $ogData, string $templatePath): string
    {
        $manager = new ImageManager(new Driver());

        $image = $manager->read($templatePath); // 1200x630 base template

        // Draw accent bar
        $image->drawRectangle(0, 0, 8, 630, function ($draw) use ($ogData) {
            $draw->background($ogData['accent_color']);
        });

        // Add headline text
        $image->text($ogData['headline'], 80, 220, function ($font) {
            $font->file(storage_path('fonts/Inter-Bold.ttf'));
            $font->size(52);
            $font->color('#FFFFFF');
            $font->wrap(1040);
        });

        // Add subheadline
        $image->text($ogData['subheadline'], 80, 360, function ($font) {
            $font->file(storage_path('fonts/Inter-Regular.ttf'));
            $font->size(28);
            $font->color('#CBD5E1');
            $font->wrap(1040);
        });

        $filename = 'og/' . Str::uuid() . '.png';
        $image->save(storage_path('app/public/' . $filename));

        return $filename;
    }
}

Option B: Browsershot (Pixel-Perfect, HTML-Based)

For more design flexibility, Browsershot by Spatie renders a Blade template as a screenshot. This is the better choice if your designers live in HTML/CSS, not PHP drawing APIs. And honestly, most do.

use Spatie\Browsershot\Browsershot;

$html = view('og-templates.article', ['data' => $ogData])->render();

Browsershot::html($html)
    ->windowSize(1200, 630)
    ->deviceScaleFactor(2) // Retina output
    ->noSandbox()
    ->save(storage_path('app/public/' . $filename));

The Blade template approach is more maintainable for teams — your frontend devs can own the OG template design without touching PHP image code. I've seen this save hours of back-and-forth on design tweaks alone.

Wiring It All Together in a Laravel Job

The full pipeline lives in a queued job, triggered on the PostPublished event.

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

    public function __construct(public Post $post) {}

    public function handle(
        GenerateOgImageData $aiGenerator,
        OgImageRenderer $renderer,
        StorageService $storage
    ): void {
        // 1. Get AI-generated content
        $ogData = $aiGenerator->handle($this->post);

        // 2. Render the image
        $localPath = $renderer->render($ogData, resource_path('og-templates/base.png'));

        // 3. Upload to R2/S3
        $cdnUrl = $storage->uploadToCdn($localPath, "og/{$this->post->slug}.png");

        // 4. Update the post record
        $this->post->update(['og_image_url' => $cdnUrl]);

        // 5. Clean up local file
        unlink(storage_path('app/public/' . $localPath));
    }
}

Dispatch it from your event listener:

PostPublished::listen(function (PostPublished $event) {
    GeneratePostOgImage::dispatch($event->post)->onQueue('media');
});

Caching and Regeneration Strategy

Don't regenerate OG images on every page load — that's expensive and pointless. Generate once on publish, regenerate on significant content edits. Store the og_image_url directly on the post model and serve it from your CDN.

For your meta tags in the Blade layout:

<meta property="og:image" content="{{ $post->og_image_url ?? asset('images/og-default.png') }}" />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />

Generating Dynamic Open Graph Images with Laravel AI SDK in Production

Running this in production requires a few guardrails that don't show up in tutorials:

Rate limiting — Wrap your AI calls in Laravel's RateLimiter facade. If you publish 50 posts in bulk, you'll hammer your OpenAI quota. I've watched this take down a content pipeline on launch day. Not fun.

Fallback handling — AI calls fail. Always have a deterministic fallback renderer that uses the raw post title if the AI response is malformed or times out. This isn't optional; treat it like you'd treat any third-party dependency that can go dark.

Queue isolation — Run OG image generation on a dedicated queue worker with limited concurrency. Image rendering is CPU and memory intensive; you don't want it competing with your critical application jobs.

Cost tracking — Log token usage per generation. At scale, AI costs add up fast. Typical OG copy generation with gpt-4o runs around 200-400 tokens per image — cheap individually, but worth watching at volume. Why let surprise invoices be the thing that kills a good project?

The quality gap between AI-assisted dynamic OG images and static templates shows up immediately in your social analytics. Pages with contextually accurate, AI-generated OG images consistently outperform generic branded banners in click-through rate, and the pipeline pays for itself quickly at any meaningful content volume.

Generating Dynamic Open Graph Images with Laravel AI SDK isn't some future-state capability you need to wait on — the tooling is mature, the integration is straightforward, and the business impact is measurable right now. Start with a single content type, validate the CTR lift in your analytics, then roll it out across your full content catalog.

This article was originally published on qcode.in

Stop Overthinking: How GSD Helps Developers Actually Ship Faster

Saqueib Ansari — Thu, 26 Mar 2026 05:17:11 +0000

Every senior developer has watched a brilliant teammate spend three weeks architecting the perfect solution to a problem that needed a working answer in three days. That gap — between the ideal and the shipped — is where careers stall, products die, and teams burn out.

Stop Overthinking: How GSD Helps Developers Actually Ship Better Software

The GSD mindset (Get Stuff Done) isn't about writing sloppy code or skipping tests. It's a deliberate operating philosophy that prioritizes momentum, iterative value delivery, and ruthless scope management. In 2026, with AI-assisted development compressing timelines even further, the developers who thrive are those who've internalized one truth: a working feature in production beats a perfect feature in your head every single time.

Understanding Stop Overthinking: How GSD Helps Developers Actually Ship isn't just motivational fluff — it's a technical discipline with concrete practices, tooling choices, and decision frameworks that separate prolific engineers from perpetual planners.

The Overthinking Tax: What It Actually Costs You

Before you can fix a problem, you need to name it precisely. Overthinking in software development isn't vagueness — it has specific, measurable symptoms.

Analysis Paralysis in Architecture Decisions

You've seen it. A team spends four sprint planning sessions debating microservices versus a monolith before writing a single route. In 2026, this is particularly acute because the tooling options have exploded. Do you use Laravel Octane with FrankenPHP, a Go microservice, a serverless function on Cloudflare Workers, or a full Next.js API route? The abundance of genuinely good options makes the paralysis worse.

The overthinking tax here is real:

Opportunity cost: Every day spent deciding is a day competitors ship
Context switching cost: Revisiting the same decision drains cognitive bandwidth
Team morale cost: Engineers who joined to build start feeling like they joined to discuss

Premature Optimization as Intellectual Escape

// What overthinking looks like in a PR review
// "We should abstract this into a Strategy pattern 
// before we know if we even need more than one strategy"

class UserExporter {
    public function exportToCsv(Collection $users): string
    {
        // Just ship this. Refactor when you have a second format.
        return $users->map(fn($u) => "{$u->name},{$u->email}")->implode("\n");
    }
}

Premature abstraction is overthinking wearing an engineering hat. The YAGNI principle (You Aren't Gonna Need It) has been a known antidote since the XP movement, yet it violates something deep in a developer's instinct to build things that last. I've killed more good PRs over phantom future requirements than I care to admit.

Stop Overthinking: How GSD Helps Developers Actually Ship With AI in Your Stack

Here's where 2026 changes the calculus significantly. AI-assisted development — through tools like GitHub Copilot, Cursor, and Claude — has made it trivially easy to generate boilerplate, scaffold architectures, and prototype ideas. This cuts both ways.

The GSD developer uses AI as a velocity multiplier. The overthinking developer uses AI to generate five competing architectural proposals and then spends a week evaluating them. Same tools, completely opposite outcomes.

The GSD Developer's AI Workflow

The distinction is in how you prompt and when you commit:

# GSD approach: Ship the prototype, validate, then invest
# Step 1: Use AI to scaffold fast
cursor: "Generate a Laravel controller for user authentication 
         using Sanctum, with login, logout, and refresh endpoints"

# Step 2: Run it, test it, put it in front of a user
php artisan test --filter=AuthTest

# Step 3: ONLY THEN refactor based on actual friction

The GSD mindset with AI means setting a time-box on generation and evaluation. You give yourself 20 minutes with Cursor or Copilot to get something working. If it runs tests and solves the stated problem, you ship it to staging. Full stop.

Feature Flags as a GSD Superpower

One of the most underused practices in solo and small-team development is feature flagging. Tools like Laravel Pennant (now deeply integrated in Laravel 12) let you ship incomplete or experimental features to production behind a flag:

use Laravel\Pennant\Feature;

Feature::define('new-dashboard', fn (User $user) => (
    $user->isInBetaGroup()
));

// In your controller
if (Feature::active('new-dashboard')) {
    return view('dashboard.v2');
}

return view('dashboard.v1');

This is GSD philosophy encoded in infrastructure: ship the imperfect thing to real users, learn from real behavior, iterate. You've eliminated the overthinking loop entirely because production feedback replaces internal debate. Why argue about what users want when you can just ask production?

Concrete GSD Frameworks That Actually Work

Principles are useless without systems. Here are the specific frameworks that high-velocity developers use in 2026.

The Two-Day Rule

If a task has been in your backlog for more than two days without meaningful progress due to uncertainty or scope questions, you apply one of three actions:

Split it: Break into a version you can ship today
Kill it: Acknowledge it's not actually needed
Time-box a decision: Allocate 90 minutes maximum to resolve the blocker, then commit

There is no fourth option. There's no "needs more research" that isn't time-boxed. None.

Vertical Slices Over Horizontal Layers

Traditional development builds layers: database schema first, then models, then services, then controllers, then views. GSD developers build vertical slices — a thin, complete path through all layers for one user story.

# Horizontal (overthinking-prone)
Week 1: Complete all migrations
Week 2: All Eloquent models
Week 3: All service classes
Week 4: All controllers
Week 5: All views
# User sees nothing working for 5 weeks

# Vertical (GSD)
Day 1-2: User can create an account (full slice, all layers)
Day 3-4: User can log in
Day 5-6: User can view their dashboard
# User sees working software every two days

The vertical slice approach forces you to make architecture decisions just in time with actual context, rather than just in case with hypothetical context. That's not a subtle difference — it's the whole ballgame.

The "Embarrassingly Simple" First Pass

Before writing any feature, write the embarrassingly simple version in comments:

// PostService.php

// EMBARRASSINGLY SIMPLE VERSION:
// 1. Take title and body from request
// 2. Save to posts table
// 3. Return the post

// If this covers 80% of use cases, ship this version first.
// Add scheduling, categories, tagging, and SEO fields 
// only after a user actually asks for them.

public function createPost(array $data): Post
{
    return Post::create([
        'title' => $data['title'],
        'body'  => $data['body'],
        'user_id' => auth()->id(),
    ]);
}

Naming it "embarrassingly simple" isn't self-deprecation — it's a forcing function. You must consciously argue against shipping the simple version. Most of the time, you can't. And when you can't, that's your answer.

Building a GSD Culture on Your Team

Individual discipline only gets you so far. Shipping velocity is a team sport, and the practices that make GSD sustainable at the team level are different from individual habits.

Blameless Retrospectives on Scope Creep

The single most common source of overthinking is unspoken fear — fear that shipping the simple version will be criticized, that you'll be asked "why didn't you think of X?" in the retro. Teams that want to GSD need explicit psychological safety around intentional simplicity.

Run a monthly retro item called "What did we build that we didn't need?" This creates positive reinforcement for scope discipline and makes YAGNI a team value, not a personal quirk.

Definition of Done Includes a Ship Date

Every ticket in your project management tool — whether you use Linear, Jira, or GitHub Issues — should have a maximum age. If a ticket's been open for more than two weeks, the default action is to cut scope until it can ship, not to expand the deadline.

This isn't about cutting corners. It's about recognizing that a shipped 80% solution generates real feedback that a perfect 100% solution in development simply can't.

Stop Overthinking: How GSD Helps Developers Actually Ship Consistently

The developers who ship consistently in 2026 aren't smarter or more experienced. They've built systems that make shipping the path of least resistance. They use feature flags so "done enough" can go to production. They use vertical slices so there's always something demonstrable. They use AI tooling to accelerate the first pass, not to generate more options to evaluate.

The overthinking trap is seductive precisely because it feels like diligence. It feels like you're being responsible — considering all the edge cases, all the architectural implications, all the future requirements. But diligence that never ships is just a very elaborate form of avoidance. I've seen brilliant engineers convince themselves otherwise for entire careers.

The GSD mindset is a commitment: make the decision, write the code, ship the feature, learn from production. Repeat this cycle faster than your competitors. That's the entire strategy.

You don't need a better architecture. You need to press deploy.

This article was originally published on qcode.in

Build Real-Time AI Voice Transcription for Web Meetings Fast

Saqueib Ansari — Wed, 25 Mar 2026 05:19:16 +0000

Web meetings generate thousands of hours of spoken content every day, and most of it vanishes the moment the call ends — unless you build something to catch it.

Why Real-Time AI Voice Transcription for Web Meetings Has Become a Core Feature

A year ago, transcription was a nice-to-have. In 2026, it's table stakes. Users expect live captions, searchable meeting notes, and action-item extraction without any manual effort. The tools to deliver all of this have matured significantly — Whisper, Deepgram, and AssemblyAI now offer sub-300ms latency on streaming audio, and browser APIs have finally caught up to make capturing audio from a meeting tab genuinely feasible without native plugins.

What changed? A few things converged at once:

WebSockets and WebRTC became universally supported and well-documented
Transformer-based ASR models got small enough to run at the edge
Streaming transcription APIs stabilized with proper WebSocket endpoints
Browser MediaStream APIs became reliable enough to capture tab and microphone audio simultaneously

If you're building a meeting tool, a productivity extension, or an AI assistant for your organization, this is the stack you need to understand.

The Core Architecture

Before writing a single line of code, understand the data flow:

Browser Tab Audio → MediaStream → AudioWorklet → WebSocket → ASR API → Transcript

You're capturing raw PCM audio from the browser, chunking it into small frames (typically 100–250ms), sending those frames over a WebSocket to a streaming ASR endpoint, and receiving partial + final transcripts back in real time. The challenge isn't any one piece — it's keeping the pipeline low-latency and handling edge cases like network interruptions, speaker changes, and audio resampling.

Setting Up Audio Capture in the Browser

Most developers hit their first wall here. Capturing both the meeting audio (system/tab audio) and the user's microphone requires combining two MediaStream tracks.

Capturing Tab Audio with getDisplayMedia

async function captureAudio() {
  const displayStream = await navigator.mediaDevices.getDisplayMedia({
    video: false,
    audio: {
      echoCancellation: false,
      noiseSuppression: false,
      sampleRate: 16000,
    },
  });

  const micStream = await navigator.mediaDevices.getUserMedia({
    audio: {
      echoCancellation: true,
      noiseSuppression: true,
      sampleRate: 16000,
    },
  });

  const audioContext = new AudioContext({ sampleRate: 16000 });
  const dest = audioContext.createMediaStreamDestination();

  audioContext.createMediaStreamSource(displayStream).connect(dest);
  audioContext.createMediaStreamSource(micStream).connect(dest);

  return dest.stream;
}

Target 16kHz mono PCM — this is what every major ASR API expects, and resampling in the browser before sending is dramatically cheaper than doing it server-side at scale.

Using AudioWorklet for Zero-Copy Audio Processing

Avoid ScriptProcessorNode — it's deprecated and runs on the main thread. Use AudioWorklet instead:

// processor.js (loaded as a worklet module)
class PCMProcessor extends AudioWorkletProcessor {
  process(inputs) {
    const input = inputs[0][0];
    if (input) {
      this.port.postMessage(input.buffer, [input.buffer]);
    }
    return true;
  }
}
registerProcessor("pcm-processor", PCMProcessor);

// main.js
await audioContext.audioWorklet.addModule("/processor.js");
const workletNode = new AudioWorkletNode(audioContext, "pcm-processor");

workletNode.port.onmessage = (event) => {
  sendAudioChunk(event.data); // send to WebSocket
};

source.connect(workletNode);

This gives you raw Float32 PCM frames off the main thread. Before sending to the API, convert to Int16 — most APIs expect 16-bit PCM, not 32-bit float:

function float32ToInt16(buffer) {
  const int16 = new Int16Array(buffer.length);
  for (let i = 0; i < buffer.length; i++) {
    int16[i] = Math.max(-32768, Math.min(32767, buffer[i] * 32768));
  }
  return int16.buffer;
}

Choosing the Right ASR API for Real-Time AI Voice Transcription for Web Meetings

Not all ASR APIs are equal for live meeting use cases. Here's how the major players stack up in 2026:

Deepgram Nova-3

Deepgram's Nova-3 is currently the best balance of latency and accuracy for English. It supports speaker diarization (identifying who's speaking) in the streaming endpoint, which is critical for meeting transcripts — and honestly non-negotiable if you want the output to be readable. Enable it with:

wss://api.deepgram.com/v1/listen?model=nova-3&diarize=true&punctuate=true&language=en-US

Expect ~150–250ms for interim results and ~500ms for finals. The diarization adds about 50ms overhead — worth it every time.

AssemblyAI Universal-2

AssemblyAI's Universal-2 is the right call if you need strong multilingual support or you're processing meetings with heavy technical vocabulary. Their custom vocabulary feature lets you boost recognition of product names, acronyms, and jargon that would otherwise get mangled. I've seen it save transcripts that Deepgram turned into gibberish for domain-specific content.

OpenAI Whisper via Local Deployment

If you're running on-premises — common in enterprise and healthcare — Whisper large-v3-turbo on a GPU instance behind a WebSocket proxy is viable. Use faster-whisper with CTranslate2 for 4–6x faster inference than the original implementation. You won't match Deepgram's latency, but you own the entire data pipeline. For regulated industries, that trade-off is often mandatory, not optional.

Building the Server-Side WebSocket Relay

Your browser can't call the ASR API directly without exposing API keys. You need a lightweight relay server. Here's a minimal Node.js implementation using Fastify and the ws library:

import Fastify from "fastify";
import WebSocket, { WebSocketServer } from "ws";

const fastify = Fastify();
const wss = new WebSocketServer({ server: fastify.server });

wss.on("connection", (clientWs) => {
  const deepgramWs = new WebSocket(
    "wss://api.deepgram.com/v1/listen?model=nova-3&diarize=true&punctuate=true",
    { headers: { Authorization: `Token ${process.env.DEEPGRAM_API_KEY}` } }
  );

  deepgramWs.on("message", (data) => {
    const result = JSON.parse(data);
    const transcript = result.channel?.alternatives?.[0]?.transcript;
    if (transcript) {
      clientWs.send(JSON.stringify({
        text: transcript,
        speaker: result.channel?.alternatives?.[0]?.words?.[0]?.speaker,
        is_final: result.is_final,
      }));
    }
  });

  clientWs.on("message", (audioChunk) => {
    if (deepgramWs.readyState === WebSocket.OPEN) {
      deepgramWs.send(audioChunk);
    }
  });

  clientWs.on("close", () => deepgramWs.close());
});

await fastify.listen({ port: 3000 });

For Laravel/PHP backends, use Ratchet or delegate the WebSocket relay to a small Node.js sidecar. PHP's blocking I/O model makes it genuinely ill-suited for sustained bidirectional streaming — don't fight it. I've seen teams spend weeks trying to make it work before giving up and spinning up a tiny Node service that took an afternoon.

Handling Reconnection and Partial Results

Production pipelines need reconnection logic. Implement exponential backoff on the client side and treat partial transcripts as disposable — only persist is_final: true results to your database. Partial results are for display only. Storing them is how you end up with a database full of duplicate fragments and confused users:

let reconnectDelay = 1000;
function connectToRelay() {
  const ws = new WebSocket("wss://your-relay.example.com");
  ws.onclose = () => {
    setTimeout(connectToRelay, reconnectDelay);
    reconnectDelay = Math.min(reconnectDelay * 2, 30000);
  };
  ws.onopen = () => { reconnectDelay = 1000; };
  // ...
}

Post-Transcription: Turning Text Into Actionable Meeting Intelligence

Raw transcripts aren't the end goal — they're the input. Once you have a stream of final transcript segments with speaker labels and timestamps, pipe them to a downstream LLM for:

Action item extraction — pass the full transcript to GPT-4o or Claude 3.5 Sonnet with a structured extraction prompt
Meeting summarization — chunk transcripts into 5-minute windows and summarize progressively
Sentiment and engagement scoring — identify when discussions became tense or one-sided

Store transcript segments with speaker_id, start_time, end_time, and text in a time-series-friendly schema. If you're on PostgreSQL, use JSONB for the metadata and full-text search indexes on the transcript content. Don't skip the timestamps. You'll want them the first time someone asks "when did we decide that?" and you actually need to answer.

Conclusion: Real-Time AI Voice Transcription for Web Meetings Is Buildable Today

The architecture described here isn't theoretical — it runs in production. Real-Time AI Voice Transcription for Web Meetings is no longer a research problem; it's an engineering problem, and most of the hard parts have already been solved by the API providers. Your job is to wire up the audio pipeline correctly, pick an ASR API that matches your latency and accuracy requirements, and build the post-processing layer that makes the raw transcript genuinely useful.

Start with Deepgram Nova-3 if you want the fastest path to production. Add speaker diarization from day one — retrofitting it later is painful in ways that will make you regret the shortcut. And invest in the reconnection and error-handling logic before you go live. Audio streams are inherently flaky, and your users will notice every dropped word.

Why let thousands of hours of decisions, commitments, and ideas disappear at the end of every call? The meetings are happening. Build the system that remembers them.

This article was originally published on qcode.in

How to Master Prompt Engineering Basics for PHP Developers

Saqueib Ansari — Tue, 24 Mar 2026 05:34:52 +0000

PHP developers are sitting on a massive opportunity right now — AI APIs are mature, Laravel's ecosystem has excellent HTTP client tooling, and the gap between "I know PHP" and "I build AI-powered products" is mostly just prompt engineering knowledge. Understanding Prompt Engineering Basics for PHP Developers isn't optional anymore if you want to ship competitive applications in 2026.

Why Prompt Engineering Basics for PHP Developers Actually Matter

Most PHP developers approach AI APIs the same way they approached third-party REST APIs in 2018 — throw a request at it, parse the JSON, call it done. That works until you need reliable, structured, production-grade output. That's where prompt engineering earns its keep.

Prompt engineering is the practice of deliberately crafting inputs to language models to get predictable, useful outputs. It's not magic. It's closer to writing a precise SQL query than writing poetry. The better your prompt structure, the more consistent your results — and consistency is what production PHP applications actually need.

In 2026, the dominant models you'll be calling from PHP include OpenAI's GPT-4o, Anthropic's Claude 3.7, and Google's Gemini 2.0. Each has nuances, but the core prompt engineering principles translate across all of them.

The Three Layers Every PHP Dev Should Understand

Before writing a single line of PHP, understand these three conceptual layers:

System prompts — Define the model's role, persona, and constraints. This is your application's "configuration layer."
User prompts — The actual input driving the conversation or task.
Context injection — Dynamic data you insert into prompts at runtime (database records, user inputs, retrieved documents).

These three layers map cleanly onto how you'd structure a Laravel service class, which we'll get to shortly.

Setting Up Your PHP Environment to Call AI APIs

You don't need a framework to call AI APIs, but Laravel 11 makes this extremely clean with its built-in HTTP client. Install the OpenAI PHP client or use raw HTTP — both work fine.

composer require openai-php/laravel
php artisan vendor:publish --provider="OpenAI\Laravel\ServiceProvider"

Add your key to .env:

OPENAI_API_KEY=sk-your-key-here
OPENAI_ORGANIZATION=org-optional

Here's a minimal service class that encapsulates the three-layer model we discussed:

<?php

namespace App\Services;

use OpenAI\Laravel\Facades\OpenAI;

class ContentAnalysisService
{
    private string $systemPrompt = <<<PROMPT
    You are a content moderation assistant for a SaaS platform.
    Always respond in valid JSON with keys: "safe" (bool), "reason" (string), "confidence" (float 0-1).
    Never include markdown code blocks in your response.
    PROMPT;

    public function analyze(string $userContent, array $context = []): array
    {
        $contextBlock = empty($context) ? '' : 'Context: ' . json_encode($context);

        $response = OpenAI::chat()->create([
            'model' => 'gpt-4o',
            'temperature' => 0.1, // Low temp = more deterministic for structured output
            'messages' => [
                ['role' => 'system', 'content' => $this->systemPrompt],
                ['role' => 'user', 'content' => "{$contextBlock}\n\nContent to analyze: {$userContent}"],
            ],
        ]);

        $raw = $response->choices[0]->message->content;

        return json_decode($raw, true) ?? ['safe' => false, 'reason' => 'Parse error', 'confidence' => 0];
    }
}

Notice the temperature set to 0.1. Temperature controls randomness — lower values give you more predictable outputs, which is critical for structured data. For creative tasks, push it toward 0.8 or higher.

Core Prompt Engineering Techniques You Should Actually Use

This is where most tutorials go vague. Let's be specific about what works in production PHP applications.

Zero-Shot vs Few-Shot Prompting

Zero-shot prompting means you describe the task without examples. It works for simple, well-defined tasks. Few-shot prompting gives the model 2-5 examples of input/output pairs — dramatically improving accuracy for domain-specific tasks.

Here's a few-shot example for extracting structured invoice data:

$fewShotExamples = <<<PROMPT
Extract invoice data as JSON with keys: invoice_number, amount, currency, due_date.

Example 1:
Input: "Invoice #4521 for $1,200.00 USD due on March 15, 2026"
Output: {"invoice_number":"4521","amount":1200.00,"currency":"USD","due_date":"2026-03-15"}

Example 2:
Input: "Rechnung Nr. 0089 — €450 fällig am 01.04.2026"
Output: {"invoice_number":"0089","amount":450.00,"currency":"EUR","due_date":"2026-04-01"}

Now extract from this input:
PROMPT;

Few-shot examples are your most powerful tool for consistent output format. Don't skip them when precision matters.

Chain-of-Thought for Complex Reasoning

For tasks requiring multi-step reasoning — like eligibility checks, fraud detection logic, or legal compliance summaries — add "Think step by step" or structure a reasoning chain explicitly:

$prompt = "Evaluate whether this user qualifies for a premium discount.
First, list the qualifying criteria met. 
Then, list any criteria not met.
Finally, state your decision as JSON: {\"qualifies\": bool, \"reason\": string}.

User data: " . json_encode($userData);

This technique, known as Chain-of-Thought (CoT) prompting, forces the model to reason before concluding — measurably reducing errors on logic-heavy tasks. I've seen this single change drop error rates significantly on eligibility checks that were previously unreliable. It's not glamorous, but it works.

Prompt Injection Defense

If you're inserting user-supplied data into prompts (and you almost certainly are), you need to defend against prompt injection — where malicious users craft inputs designed to override your system prompt. Why do developers keep shipping this without any defense? It's the SQL injection of the AI era, and the fix isn't complicated.

public function sanitizeUserInput(string $input): string
{
    // Strip common injection patterns
    $patterns = [
        '/ignore\s+(all\s+)?previous\s+instructions/i',
        '/you\s+are\s+now\s+/i',
        '/system\s*:/i',
        '/\[INST\]/i',
    ];

    $sanitized = preg_replace($patterns, '[REMOVED]', $input);

    // Hard cap length to limit context manipulation
    return mb_substr($sanitized, 0, 2000);
}

This won't stop sophisticated attacks, but it's a necessary baseline. For high-stakes applications, use Llama Guard or OpenAI's Moderation API as an additional layer.

Structuring Prompts for Prompt Engineering Basics for PHP Developers in Production

Production prompt engineering is less about clever tricks and more about maintainability. Your prompts are essentially application logic — treat them like code. I'm serious about this. I've watched teams lose weeks of work because their prompts lived in random service classes with no versioning and no tests.

Store Prompts as Versioned Templates

Hardcoding prompts in service classes gets painful fast. Store them as Blade templates or dedicated .txt files in a resources/prompts/ directory:

resources/
  prompts/
    content-moderation.txt
    invoice-extraction.txt
    customer-support.v2.txt

Load them dynamically:

public function loadPrompt(string $name, array $variables = []): string
{
    $path = resource_path("prompts/{$name}.txt");
    $template = file_get_contents($path);

    foreach ($variables as $key => $value) {
        $template = str_replace("{{$key}}", $value, $template);
    }

    return $template;
}

This gives you version control on prompt changes, A/B testing capability, and a clean separation between business logic and AI configuration.

Logging and Observability

You can't improve what you don't measure. Log every prompt, response, token count, and latency:

Log::channel('ai_requests')->info('prompt_call', [
    'model'        => 'gpt-4o',
    'prompt_hash'  => md5($prompt),
    'tokens_used'  => $response->usage->totalTokens,
    'latency_ms'   => $latencyMs,
    'success'      => $parsed !== null,
]);

Tools like Helicone or LangSmith provide purpose-built observability for AI calls and are worth the setup time for any serious project.

Practical Next Steps for PHP Devs Getting Started

The gap from "PHP developer" to "PHP developer who ships AI features" is smaller than it looks. Start here:

Pick one real task in your current application that involves text processing, classification, or generation. Swap out the manual logic for an AI call.
Use structured output mode wherever possible. OpenAI's response_format: { type: "json_object" } parameter and Anthropic's tool use feature both enforce JSON output at the API level — more reliable than prompting for JSON alone.
Evaluate before you ship. Build a small test harness: 20-30 input examples with expected outputs. Run your prompts against it and score accuracy. Don't skip this.
Iterate on temperature and model selection together. GPT-4o is overkill for simple classification — gpt-4o-mini or Claude Haiku is faster and 10x cheaper for tasks that don't need deep reasoning.

The fundamentals covered here — system/user/context separation, few-shot examples, chain-of-thought, injection defense, and prompt versioning — are your practical foundation for Prompt Engineering Basics for PHP Developers that actually holds up when you move from a prototype to a system handling real user traffic.

Prompt engineering isn't a skill you learn once. Models improve, API features change, and what worked in testing sometimes degrades in production. Build observability in from day one, treat your prompts as first-class code artifacts, and iterate based on real data. That discipline, more than any single technique, is what separates developers who successfully ship AI features from those who stay stuck in the prototype stage.

This article was originally published on qcode.in