Josh Salway

Improving Queue Safety in Laravel

Josh Salway — Tue, 14 Apr 2026 00:00:00 GMT

A follow-up to Why Your Laravel Jobs Might Retry Forever After an OOM

Eight things every queued job needs before you ship:

Retry bounds -- $tries (count-based) or retryUntil() + $maxExceptions (time-based). Never both. Never platform defaults.
$timeout shorter than the connection's retry_after (default 90s on both database and Redis) to avoid duplicate execution.
Non-zero $backoff so retries pace themselves.
A failed() method so failures aren't silent.
Timeouts on every HTTP call inside the job.
An idempotency guard at the top of handle() if the job writes external state. Queues redeliver.
Explicit lock expiry -- $uniqueFor on ShouldBeUnique, ->expireAfter() on WithoutOverlapping. 0 means "never" in Laravel.
On serverless: tight queue-timeout and a hard cost kill switch. Lambda bills wall-clock including idle I/O.

The scaffold gives you none of them. You are responsible for the safety and reliability of your queues.

Using an AI coding agent? Review the prompts below and copy them into your tool (Claude Code, Cursor, Windsurf, Copilot, or similar) to audit and apply the spec across your jobs.

This post documents 23 queue safety findings -- 14 from my audit, 9 from the community. Verified against Laravel Framework v13.4.0 through v13.6.0 with links to real GitHub issues spanning 2015 to 2026.

Any changes you make to your application are your responsibility. Do your own research first.

How I found these

After two Vapor billing incidents ($140 in 2019, $218.90 in 2023), I traced my original application's git history commit by commit, cross-referenced support emails, and compared Worker.php across Laravel v10, v12, and v13. My code had gaps, but so did the framework and platform. That led to a broader question: how many other places in the queue system have the same pattern?

Using Claude Code, I audited the full queue system for unbounded behaviour, counters bypassed by process death, and unsafe defaults.

Packages examined:

laravel/framework (v13.4.0 original audit; spot-checks against v13.6.0): src/Illuminate/Queue/, src/Illuminate/Bus/, src/Illuminate/Pipeline/, src/Illuminate/Console/Scheduling/
laravel/vapor-core (v2.43.3): VaporWorkCommand.php, QueueHandler.php, VaporWorker.php, VaporJob.php
laravel/vapor-cli, laravel/cloud-cli, laravel/forge-cli, laravel/forge-sdk: checked for comparison

I also compared defaults across Sidekiq, BullMQ, Celery, Google Cloud Tasks, and AWS SQS native to find suitable guardrails and recommendations.

What likely caused my billing incidents

After investigating the original application's git history, support emails, and vapor.yml at the time of the incidents, the root cause of the August 2023 bill ($218.90 in 7 days) became clear.

This was not a literal infinite retry loop. The OOM bug in Finding #1 is a real framework bug and can produce unbounded retries in its specific trigger conditions, but the 2023 incident is a different mechanism. On Vapor, QueueHandler invokes vapor:work --tries=$SQS_TRIES ?? 3, so each problem email got up to 3 SQS redeliveries, each running to the full 15-minute queue-timeout: 900 ceiling because of uncapped file_get_contents() hanging on slow image origins. That's up to 45 minutes of billed 2048MB Lambda time per problem message (3 attempts x 900s x 2GB x $0.0000166667/GB-s ~= $0.09 per message). Multiply by roughly 350 problem emails per day over 7 days and the bill arrives at $218.90 without anything retrying forever. Same class of queue-safety failure as Finding #1, different mechanism. I cannot prove the OOM bug caused this specific bill, and on the Lambda pricing math I no longer think it did.

What was a skill issue

I set queue-timeout: 900 in vapor.yml "to be safe." This was the dominant cost multiplier. Lambda bills wall-clock time including idle I/O waits, and at 2048MB x 900s x $0.0000166667/GB-s each timed-out attempt cost roughly $0.03. With the same mistakes below but a default 60s queue-timeout, the same incident would have cost around $15 instead of $218. "To be safe" was the thing that wasn't.
I used file_get_contents() on arbitrary URLs with no timeout inside a queue job. One slow origin pinned the worker at the Lambda ceiling for the full 15 minutes per attempt.
I didn't set $tries on my job classes. That's in the docs. On Vapor the effective retry count was SQS_TRIES ?? 3 (bounded, not infinite), but three attempts at $0.03 each times inbound email volume is how the 2023 bill accrued in a week.
I didn't set up AWS budget alerts. The spend was invisible until the invoice arrived.

Those are real mistakes and I own them.

What wasn't a skill issue

The tries configuration has three layers that contradict each other (see finding #4).
There is no global default_tries config. One missed property on one job class and the behaviour depends on which layer wins.
Retries are completely silent. No warning, no log entry, no event.
Support responded to both incidents with "check your AWS invoice" and "set up budget alerts." Neither response mentioned $tries, queue-timeout, retry limits, or the Vapor tries default. Even a basic triage question in 2019 ("what is your queue-timeout, do your jobs have $tries and $timeout set, do your HTTP calls have timeouts?") would have turned the 2023 incident into a background-noise bill instead of an alarm-bell one.

Whose fault is it?

In the previous post I wrote that the framework, hosting platform, and application code should all have seatbelts in place to reduce the likelihood of infinite retries in serverless environments. All three failed:

Mine: A 15-minute queue-timeout (the dominant cost multiplier on the evidence), unbounded HTTP calls inside jobs, and jobs without $tries. In that order of impact.

The framework: Unsafe defaults -- make:job stub is bare, $tries null (see #4), backoff 0 (see #2), WithoutOverlapping lock infinite (see #3), maxExceptions bypassed by OOM (see #1) -- meant my mistakes had no guardrails at the layer I actually wrote.

The platform (Vapor): Three layers of tries configuration that contradict each other, none clearly documented (see #4). Support didn't flag the root cause in either incident.

The git log from August 20, 2023 (private repository) tells the story: 11 commits in a single day, reverts of reverts, and the first $tries = 5 added mid-crisis. The fix that actually turned off the money hose was the file_get_contents HTTP timeout added the next day (commit e6f7cb5, Aug 21), which stopped attempts from hanging to the Lambda ceiling; that change alone dropped per-attempt cost by roughly 30x. The $tries = 5 + idempotency guard + queue-timeout reduction landed the night before were supporting fixes, not the dominant one. No single layer caused this alone. My bad code, combined with unsafe framework defaults, on a platform with inconsistent and undocumented tries configuration, turned a coding mistake into $358.90 across two separate incidents four years apart.

Lambda is for short bursts, not long-running work

The same code, same bugs, same SQS redeliveries would have cost very different amounts on different platforms. The 2023 mechanism was 3 attempts x up to 15 minutes x 2GB x pay-per-millisecond billing. Run the same scenario on:

Non-serverless environments (Forge, Ploi, Laravel Cloud, DigitalOcean droplet): $0 incremental. The worker was already paid for. You'd see a backed-up queue, a slow server, and possibly dropped jobs. No excessive bill.
Laravel Cloud with a capped queue worker: bounded to the worker's provisioned compute regardless of retry behaviour. Slow queue, predictable ceiling.
Cloudflare Workers: CPU-time-gated (10 seconds on free, configurable up to 5 minutes on paid). Tasks are tied to the HTTP request lifecycle -- client disconnect cancels them with a 30-second waitUntil grace. Pay-per-request plus CPU time keeps costs predictable. Caveat: a hung fetch() does not count against CPU time, so slow-origin I/O can still wait longer than the CPU cap implies.
Vercel Functions: 10 seconds default on Hobby, 60 seconds on Pro, configurable up to 800 seconds on Pro with Fluid Compute. The low default is the safety net; raising maxDuration near 800s recreates the Lambda shape.
Lambda with a default 60 second queue-timeout (same Vapor, different config): about $15 instead of $218 on the same code.

This shape of problem isn't framework-specific; the same unsafe patterns cause problems on every platform. The lesson is that Lambda's pricing model rewards short bursts and punishes long-running work. A 15-minute queue-timeout inverts Lambda's value proposition: per-millisecond billing is great for the 30-second happy path and catastrophic on the 15-minute unhappy path.

For background work that's inherently quick -- parsing an inbound email, saving an attachment to storage, rendering a small PDF, calling an API -- Cloudflare Workers or Vercel Functions give you low default timeout caps and pay-per-request billing that keeps costs predictable. The low default is the safety net; raise the cap and you give it up. For longer or memory-heavy tasks, non-serverless environments (Forge, Ploi, Laravel Cloud) absorb the mistake class entirely: bugs produce slow queues, not excessive bills. Lambda via Vapor is best reserved for bursty request-response work, not for queues where one hung HTTP call means minutes of billed idle time.

Do we actually need seatbelts or guardrails?

Nobody plans to have a car accident. You don't put on a seatbelt because you expect to crash. You put it on because if something goes wrong, the seatbelt is the difference between a bad day and a catastrophic one.

Fun fact: When Volvo invented the three-point seatbelt in 1959, they made the patent available to every car manufacturer for free because they believed safety should be a shared standard, not a competitive advantage. It still took decades for seatbelts to become mandatory worldwide.

Queue safety is the same. Most jobs work fine. Most deployments don't have runaway billing. Most developers go years without a serious queue incident. But when one hits, the difference between a job with the eight properties set and a job without them is the difference between a failed job in your failed_jobs table and a surprise bill on the invoice.

Guardrails on a road don't slow you down. They're invisible until the moment you need them. $tries, $backoff, $timeout, and failed() are the same. They cost nothing in normal operation. They save you when something unexpected happens: an API goes down, a payload is larger than expected, a memory limit is hit, a deploy goes wrong.

On serverless platforms, a runaway job shows up as a bill. In non-serverless environments (Forge, Ploi, Laravel Cloud, etc.), there's no excessive bill to trigger an investigation. The signal is quieter: a job retrying in a tight loop consumes CPU and memory, your server gets slower, other jobs back up, and some jobs may be dropped. Without monitoring or logging, you might never know it's happening. Queue safety is a shared discipline across every platform. Serverless just surfaces the cost quickly in dollars, while non-serverless hides it in slower throughput and dropped work.

If you've never had a queue incident, that's great. Add the guardrails anyway. They're free insurance. Regardless of the safety angle, these recommendations will likely make your queue jobs more reliable. And if you already knew all of this, pat yourself on the back.

Recommendations you can do today

Even after writing this audit, I checked my own applications and found jobs without $tries set -- including the exact job that caused my billing incident. That's how easy this is to miss. Safe defaults would catch it for everyone.

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\Log;
use Throwable;

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

    public $tries = 3;
    public $maxExceptions = 0;
    public $backoff = [30, 60, 300];
    public $timeout = 120;

    public function retryUntil()
    {
        return now()->addHours(2);
    }

    public function failed(Throwable $exception)
    {
        // Log, notify, or alert. Don't let failures be silent.
        Log::error('ProcessEmailJob permanently failed', [
            'exception' => $exception->getMessage(),
        ]);
    }
}

Pick one retry policy, not both. Laravel's Worker treats $tries and retryUntil() as mutually exclusive: if retryUntil() returns a timestamp, $tries is ignored completely (Worker.php line 612 on 13.x, behaviour introduced in framework PR #35214, Nov 2020). So pick one:

Count-based -- $tries + $backoff + $maxExceptions, no retryUntil(). Bounds by attempt count.
Time-based -- retryUntil() + $maxExceptions, no $tries. Bounds by wall-clock. Taylor's own guidance on #35199: "When using retryUntil I would use maxExceptions if you want to determine how many uncaught exceptions are allowed."

The example above sets both so you can see the properties in one place, but in production use one or the other. See Finding #11 for the source-level proof.

Why each property matters: five properties, set explicitly on every queued job. The caveats under each item explain scope and edge cases, they don't weaken the rule.

$tries = 3 -- hard cap on total attempts (count-based policy). Don't rely on platform defaults, set this explicitly on every job. Use 3 if multiple tries are useful and don't cause side effects, or 1 if you want to be strict and only run once. Don't use $tries = 0: in Laravel that means infinite retries, not zero. Use a positive integer. Ignored when retryUntil() is set. $tries on the job class wins over every worker-level default, which matters because those defaults differ by platform (queue:work uses 1, vapor:work uses 0 but is runtime-overridden to SQS_TRIES ?? 3). See Finding #4 for the three-layer diagnosis.
$maxExceptions = 0 -- fails the job on the first catchable exception. See note below. Works with either policy.
$backoff = [30, 60, 300] -- exponential delays between retries. Without this, retries are immediate (0 seconds). Applies when exceptions propagate to the worker's handleJobException. Middleware that catches and releases internally (ThrottlesExceptions, RateLimited) bypasses $backoff and uses its own delay parameter; chain ->backoff($minutes) on the middleware in that case. See Finding #8 for the source-level proof.

Why $maxExceptions = 0? This is deliberately aggressive because of finding #1: the maxExceptions counter never increments during OOM, so any value above 0 allows infinite retries when OOM and catchable exceptions alternate. Setting it to 0 means the first catchable exception stops the loop. Retry tolerance is handled by $tries and $backoff instead, which work across process restarts.

$timeout = 120 -- kills the job after 2 minutes. Without this, jobs can run until Lambda's 15-minute ceiling. $timeout must be shorter than the connection's retry_after config value (default 90 on both database and Redis); if $timeout exceeds retry_after, the same job can be picked up and executed twice. See Finding #10 for the duplicate-execution scenario.
retryUntil() -- time-based circuit breaker (time-based policy). Negates $tries completely when set. Use alongside $maxExceptions, not $tries.
failed() -- get notified when a job permanently fails. Silent failures are what cause $200 bills.

On WithoutOverlapping middleware

public function middleware()
{
    return [
        (new WithoutOverlapping($this->key))
            ->expireAfter(minutes: 30)
            ->releaseAfter(seconds: 30),
    ];
}

Always set expireAfter. The default is 0 (never expires). If your worker crashes while holding the lock, the job is permanently blocked without this.

On ShouldBeUnique jobs

class ImportDataJob implements ShouldQueue, ShouldBeUnique
{
    public $uniqueFor = 3600; // seconds
}

Always set $uniqueFor. The default is 0, which means the lock never expires (same pattern as WithoutOverlapping). On a normal exception, CallQueuedHandler::failed() releases the lock via ensureUniqueJobLockIsReleased() (source). The leak case is when failed() never runs: the worker is terminated mid-handle() (OOM, SIGKILL, container eviction), or the $deleteWhenMissingModels = true + missing-model path from Issue #49890 reported by @naquad (closed as "no-fix for us"). In those cases the lock persists until cache TTL, blocking all future dispatches of that unique key.

If you want the lock released as soon as the job starts processing rather than when it completes or fails, implement ShouldBeUniqueUntilProcessing instead. Narrower window, less leak risk, but allows the job to run concurrently with another dispatch of the same unique key after processing begins.

Laravel 13.6.0 introduced #[DebounceFor] as an attribute-driven alternative (PR #59507, merged April 2026). It uses last-writer-wins cache-token semantics over a debounce window, no interface required, and fires a JobDebounced event when a dispatch is superseded. Use #[DebounceFor] when you want to deduplicate a burst of dispatches and run only the last one; use ShouldBeUnique when you want the first to run and the rest to be silently dropped while the lock is held.

Prune failed jobs

// In app/Console/Kernel.php or routes/console.php
Schedule::command('queue:prune-failed --hours=168')->daily();

The failed_jobs table grows unbounded. At 300k+ records, queue:retry --all will OOM (Issue #49185 reported by @arharp). Prune weekly.

On external HTTP calls inside jobs

// Bad: no timeout, no size limit
$content = file_get_contents($url);

// Good: bounded timeout, exception on failure
$response = Http::timeout(10)->get($url);
$response->throw();
$content = $response->body();

Every external call inside a queue job should have a timeout. One slow or unresponsive endpoint can hold a Lambda invocation running for minutes.

Hard limits

These catch problems regardless of whether individual jobs are configured correctly, ordered by leverage:

queue-memory and queue-timeout in vapor.yml -- these set your per-attempt cost ceiling on Lambda: memory-gb x timeout-seconds x $0.0000166667/GB-s. At 2048MB and queue-timeout: 900 that is roughly $0.03 per stuck attempt, multiplied by your retry count and your volume. Keep both as low as your jobs actually need. If you take one thing from this section, take this: the dominant cost control on serverless queues is how long each failed attempt is allowed to burn, not how many retries you allow.
queue:work --tries=3 -- set this on your worker command or supervisor config. Acts as a floor even if a job class forgets $tries. On Vapor, set SQS_TRIES=3 in your environment. If you run an SQS dead letter queue with maxReceiveCount as your retry ceiling, set SQS_TRIES=0 instead so Laravel releases the message back and the DLQ handles the cap at the infrastructure layer.
SQS dead letter queue -- configure a redrive policy with maxReceiveCount in AWS. After N receive attempts, SQS moves the message to a DLQ automatically, even if your application crashes. This is your infrastructure-level circuit breaker and works independently of Laravel.
Ideally, a cost-based kill switch -- a soft limit sends you an email when spend hits a threshold. A hard limit actually stops the workload. Vapor and most serverless platforms only offer soft limits today. A hard limit that pauses queue processing when spend exceeds a configurable amount (e.g. $30/month) would have prevented both of my incidents entirely. The alert told me the house was on fire. A hard limit would have put it out.
AWS budget alerts -- won't stop the spend, but tells you early. Set via the Vapor UI.
Monitor queue depth -- as of Laravel 13.4.0, Queue::pendingJobs(), Queue::delayedJobs(), and Queue::reservedJobs() (PR #59511) let you inspect queue state natively. On AWS, you can also use CloudWatch alarms on ApproximateNumberOfMessagesVisible.
Lambda concurrency limits -- set reserved concurrency on your queue Lambda to cap how many concurrent invocations can run. Limits the burn rate during a runaway.

A base job class

If you want to apply safe defaults across all your jobs without repeating yourself:

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\Log;
use Throwable;

abstract class SafeJob implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public $tries = 3;
    public $maxExceptions = 0;
    public $backoff = [30, 60, 300];
    public $timeout = 120;

    public function failed(Throwable $exception)
    {
        Log::error(static::class . ' permanently failed', [
            'exception' => $exception->getMessage(),
        ]);
    }
}

Then extend it:

class ProcessEmailJob extends SafeJob
{
    // Inherits all safe defaults
    // Override any property if this job needs different limits
}

The Findings

Critical: Unbounded retries and permanent resource locks

These findings can cause infinite retry loops, permanent job lockout, or runaway costs on serverless platforms. They are the highest priority for anyone running queues in production.

1. maxExceptions counter only increments inside the catch block

File: src/Illuminate/Queue/Worker.php - process() and markJobAsFailedIfWillExceedMaxExceptions()

This is the bug documented in my previous blog post. The maxExceptions counter is incremented inside handleJobException(), which is called from the catch (Throwable) block. When the process is killed by an out-of-memory error, the catch block never executes. The counter is never incremented. The job retries with a counter of zero indefinitely.

There is a pre-fire check for maxTries via markJobAsFailedIfAlreadyExceedsMaxAttempts, but no equivalent pre-fire check for maxExceptions.

Real-world: Issue #58207 (Dec 2025) reported by @pingencom -- 31 comments from production users independently building workarounds.

Suggested fix: Increment the exception counter before fire(), decrement after successful completion. If the worker dies during fire(), the increment persists. On the next pickup, a pre-fire check can fail the job if the counter meets the threshold.

2. Default backoff is 0 seconds

File: src/Illuminate/Queue/Worker.php - calculateBackoff()

When a job fails and has no backoff property, the default is 0 seconds. The job is immediately re-queued. Combined with a high or unlimited retry count, this creates a tight failure loop where the same job fails and retries as fast as the worker can process it.

Real-world: Issue #44680 (Oct 2022) reported by @hjeldin -- backoff ignored after timeout kill, job retries immediately.

Suggested fix: Default backoff to a small positive value (e.g. 3 seconds) instead of 0.

3. WithoutOverlapping middleware defaults to an infinite lock

File: src/Illuminate/Queue/Middleware/WithoutOverlapping.php

$expiresAfter is unset by default (null). When passed to Cache::lock() with no TTL, most drivers (Redis, Database) produce a lock that never expires. If a job using this middleware is killed (OOM, SIGKILL, server crash), the lock is never released. All future instances of that job are permanently blocked, either released back to the queue indefinitely or silently dropped.

Real-world: Issue #37060 (Apr 2021) reported by @lasselehtinen -- lock not released on failed jobs.

Suggested fix: Default $expiresAfter to a reasonable value (e.g. 3600 seconds) instead of leaving it unset.

4. $tries defaults to null (unlimited) in job payload

Files: src/Illuminate/Queue/Queue.php - getJobTries(), src/Illuminate/Queue/Worker.php - markJobAsFailedIfAlreadyExceedsMaxAttempts()

When a job class does not define a $tries property, the payload contains maxTries: null. Null does not itself mean unlimited: Worker.php line 578 replaces null with the worker's --tries argument before the unlimited-if-zero check at line 586. So null delegates to the worker layer, and unlimited only happens when that layer also resolves to 0. The queue:work command defaults to --tries=1 (safe). On Laravel Vapor, VaporWorkCommand defines --tries=0 (unlimited) in its command signature, but the QueueHandler runtime that invokes it passes $_ENV['SQS_TRIES'] ?? 3, so in practice the default is 3 unless explicitly overridden. This inconsistency between the command definition and the runtime invocation is confusing and not documented.

The interaction between job-level, command-level, and runtime-level tries configuration is complex. A global default in config/queue.php would provide a single, visible safety net.

Real-world: PR #29385 (Aug 2019) by @SjorsO -- changed the queue:work default from 0 to 1 in Laravel 6.0. The PR states: "Changing the default solves the problem of broken jobs getting stuck in an infinite loop when you forget to pass the queue worker a --tries flag." This partially addressed the issue but didn't unify the other layers: job-level $tries still defaults to null, VaporWorkCommand still defines --tries=0 in its signature, and SQS_TRIES is a separate runtime concern. Issue #58207 (Dec 2025) reported by @pingencom -- jobs retried endlessly with $tries=0. PR #59718 (Apr 2026, merged in Laravel 13.6.0) -- a developer hit the TINYINT 255-attempts limit on a unique job retrying every minute for a full day; the column was widened to SMALLINT. The schema fix addresses the symptom; the underlying gap (unbounded retries running to the column's range) remains.

The real gap is the scaffold. php artisan make:job generates from job.queued.stub. That template has been touched nine times since 2020 -- formatting, imports, PHP type declarations, ShouldBeUnique added and removed. Never $tries. Never $backoff. Never $timeout. Never failed(). Every queued job generated in every new Laravel app since 2020 ships with nothing.

Suggested fix: Add a default_tries option to config/queue.php that applies when neither the job class nor the command line specifies a value. And update job.queued.stub to include $tries, $backoff, and $timeout -- commented out if you want, just so the developer sees them.

5. Race condition in maxExceptions counter initialization

File: src/Illuminate/Queue/Worker.php - markJobAsFailedIfWillExceedMaxExceptions()

The counter initialization uses a non-atomic get/put sequence. When multiple workers process retries of the same job UUID simultaneously, both workers can see a missing key and reset the counter, causing the exception count to be lost. An atomic Cache::add() call would prevent this race condition.

Real-world: Silent bug -- users see the symptom (jobs retrying forever) without understanding the cause. Compounds Issue #58207 (Dec 2025) reported by @pingencom.

Suggested fix: Replace the Cache::get() / Cache::put() initialization sequence with Cache::add(), which only sets the key if it doesn't already exist. The subsequent Cache::increment() is already atomic.

6. handleJobException releases when failure checks are bypassed

File: src/Illuminate/Queue/Worker.php - handleJobException()

The finally block in handleJobException releases the job back to the queue if it hasn't been deleted, released, or marked as failed. These three guards are correct and work well when maxTries or maxExceptions properly mark the job as failed. However, when those checks are bypassed (because maxTries is 0 or maxExceptions fails to increment due to OOM), the job is never marked as failed, and the release always proceeds. This amplifies the unlimited retry issue in those specific scenarios.

Real-world: PR #45876 (Jan 2023) by @khepin, closed without merging -- "jobs that fail because of high memory usage all stay on the queue and accumulate there. If enough of them have accumulated, the workers keep spinning on jobs that can never go through."

Suggested improvement: Resolving finding #1 (pre-fire maxExceptions check) would address this for jobs with maxExceptions set. For the broader case, consider logging a warning when a job is released back to the queue with a high attempt count and no maxTries or maxExceptions configured. This wouldn't change behaviour but would make the problem visible instead of silent.

Important: Unsafe defaults and resource exhaustion risks

These findings involve default values or missing limits that could cause problems under load, after outages, or with specific configuration combinations. They are less likely to cause immediate damage but represent gaps that production systems can hit.

7. Redis migrationBatchSize defaults to unlimited

File: src/Illuminate/Queue/RedisQueue.php

The migrationBatchSize defaults to -1, which means unlimited. The Lua script that migrates expired delayed and reserved jobs fetches all of them in a single call. If a large number of delayed jobs expire simultaneously (for example, after an outage or server restart), this single Lua operation can block Redis for all clients, consume significant memory in the Lua execution context, and potentially trigger the lua-time-limit threshold.

Real-world: PR #43310 (Jul 2022) by @AbiriAmir -- "scheduling a large number of jobs for a specific time causes Redis to halt since migrate script is a heavy script." This PR added the migrationBatchSize config but defaulted it to -1 (unlimited).

Suggested fix: Default migrationBatchSize to a bounded value (e.g. 1000).

8. ThrottlesExceptions retryAfterMinutes defaults to 0

File: src/Illuminate/Queue/Middleware/ThrottlesExceptions.php

When an exception triggers the throttle, the job is released with a delay of retryAfterMinutes * 60. The default for retryAfterMinutes is 0, meaning the job is immediately re-queued after an exception. Combined with a high retry count, this creates a tight failure loop similar to the 0-second backoff issue.

The middleware's handle() method catches the exception and calls $job->release($this->retryAfterMinutes * 60) directly, then returns. The exception never propagates out, so the worker's handleJobException never runs and calculateBackoff() never consults the job's $backoff property. A job-level $backoff is ignored on this path. Setting ->backoff($minutes) on the middleware construction is the only way to pace these retries (e.g. (new ThrottlesExceptions(1, 600))->backoff(10)).

Real-world: Issue #36637 (Mar 2021) reported by @tairau -- backoff docblock says seconds but value is used as minutes. Issue #56087 (Jun 2025) reported by @michaeldzjap -- ThrottlesExceptions overrides FailOnException, causing jobs to retry despite being told to fail.

Suggested fix: Default retryAfterMinutes to a small positive value (e.g. 5).

9. RateLimited middleware release loop

File: src/Illuminate/Queue/Middleware/RateLimited.php

When a job is rate-limited, it is released back to the queue. Each release counts as an attempt. In high-concurrency environments with many workers competing for the same rate limit, a job can be released and re-attempted many times without ever executing its actual logic. If the job has a high or unlimited retry count, this consumes worker capacity without doing useful work.

Real-world: Issue #53157 (Oct 2024) reported by @amir9480 -- RateLimiter perSecond not working as expected for queue jobs.

Suggested improvement: Consider not counting rate-limited releases as attempts, or providing an option to distinguish between "failed" and "deferred" releases.

10. Database queue reserved-but-expired can cause duplicate execution

File: src/Illuminate/Queue/DatabaseQueue.php - getNextAvailableJob() + isReservedButExpired()

Jobs where reserved_at is older than retry_after seconds are treated as available. The default retry_after is 90 seconds. If a job legitimately takes longer than 90 seconds to process, another worker can pick it up while it is still running. The same job executes concurrently in two workers.

Real-world: Issue #8577 (Apr 2015) reported by @m4tthumphrey -- multiple Redis workers picking up the same job. Issue #7046 (Jan 2015) reported by @easmith -- database queue deadlocks from concurrent execution.

Suggested improvement: Document this interaction clearly and consider a longer default retry_after, or add a mechanism for long-running jobs to extend their reservation.

11. retryUntil can override maxTries

File: src/Illuminate/Queue/Worker.php - markJobAsFailedIfAlreadyExceedsMaxAttempts()

If retryUntil() returns a future timestamp, the maxTries check is skipped entirely. A job with retryUntil() returning a far-future date (e.g. one year) will retry for the entire window regardless of how many times it has failed. Combined with a 0-second backoff, this is a sustained failure loop for the duration of the window.

I tested this. Job with retryUntil(10s) and no $tries, run against queue:work --tries=1: 275 retries in 3 seconds. The worker's --tries flag is ignored when retryUntil() is set. Setting job-level $tries alongside retryUntil() does not help either: the !$job->retryUntil() guard in Worker.php line 612 on 13.x short-circuits the attempt check whenever retryUntil() is set. Worker-level safety is no protection here, and neither is job-level $tries. When retryUntil() is set, the only bound is wall-clock time.

Real-world: Issue #35199 (Nov 2020) reported by @trevorgehman -- "Queue worker ignores job's maxTries setting if using retryUntil()." Closed by PR #35214 which unified the behaviour: if retryUntil is set, maxAttempts is ignored in every path. Taylor's position on the issue: "retryUntil and maxTries are sort of mutually exclusive. When using retryUntil I would use maxExceptions if you want to determine how many uncaught exceptions are allowed." Follow-up comments in 2022 and 2024 show users still hitting this and filing it as broken, which suggests the docs gap remains.

Suggested improvement: Surface this interaction prominently in the queues docs. A one-line note under $tries ("ignored when retryUntil() is set") and under retryUntil() ("pair with $maxExceptions, not $tries") would close the comprehension gap. The behaviour itself is deliberate and shipped in Laravel 8.x (November 2020), so changing it would break every app that depends on the current semantics.

12. Pipeline memory retention between jobs

File: src/Illuminate/Pipeline/Pipeline.php

The Pipeline retains references to $passable and $pipes after execution. In long-running queue workers, this means the previous job's data is held in memory until the next job overwrites it. While the retention is bounded to one job's worth of memory, it contributes to gradual memory growth in workers, increasing the likelihood of OOM events.

Real-world: Issue #56395 (Jul 2025, OPEN) reported by @momala454 -- job objects retain large data in memory after processing. A related issue I filed, Issue #59402, was closed once I verified that the $passable/$pipes cleanup in PR #59415 and PR #59330 makes the Job::$instance chain GC-eligible indirectly -- but those Pipeline PRs were themselves closed, so the underlying retention still ships in v13.4.0.

Suggested fix: Null $passable and $pipes after pipeline execution.

Improvement: Edge cases and documentation gaps

These findings are lower risk but represent real gaps that specific configurations can hit.

13. Reserved job migration ignores attempt count

File: src/Illuminate/Queue/RedisQueue.php - migrate()

When reserved jobs expire (worker died mid-processing), they are moved back to the ready queue without checking their attempt count. The attempt check only happens when the worker next pops and processes the job. This means a job that has already exceeded its max tries can be re-enqueued and picked up before being failed.

Real-world: Issue #32103 (Mar 2020) reported by @mfn -- job retried despite still running, reserved timeout expired mid-execution.

Suggested improvement: The pre-fire check via markJobAsFailedIfAlreadyExceedsMaxAttempts already handles this when the worker pops the job. The gap is the brief window where an over-limit job sits in the "available" queue before being popped. Checking attempts inside the Lua migration script would be expensive. A lighter approach: log or emit an event when a reserved job is migrated back, so monitoring tools can flag jobs that are cycling.

14. No timeout enforcement on Windows

File: src/Illuminate/Queue/Worker.php - registerTimeoutHandler()

The timeout handler relies on pcntl_alarm, which is only available on systems with the pcntl extension (Linux/Mac). On Windows, Laravel deliberately throws an error if you set a timeout, forcing you to pass --timeout 0 to acknowledge you're running without timeout protection. This is the right design choice (silently ignoring the timeout would be worse), but it means Windows workers have no timeout enforcement at all. A job that enters an infinite loop or deadlock will block the worker process forever.

Real-world: Issue #15002 (Aug 2016) reported by @StevenBock -- queues require explicit --timeout 0 on Windows. Issue #14909 (Aug 2016) reported by @ac1982 -- PHP requires --enable-pcntl for queue timeouts.

Suggested improvement: Add a fallback timeout mechanism for environments without pcntl support.

What the community found

The following issues were reported by other developers. I didn't find these in my audit -- they found them first. I'm including them here so everything is in one place.

Worker enters infinite silent loop on non-database exceptions

Issue #59517 (Apr 2026, OPEN) reported by @thuggins-engrain. stopWorkerIfLostConnection() only checks for database connection errors. If SQS SDK, Redis auth, or HTTP errors occur in getNextJob(), the worker catches the exception, sleeps 1 second, and retries forever with no exit condition. PR #59553 by @webpatser proposed --max-pop-exceptions to address this; closed by maintainers.

Batch deadlocks under high concurrency

Issue #39722 (Nov 2021) reported by @gm-lunatix. Issue #36478 (Mar 2021) reported by @murphatron. Issue #40574 (Jan 2022) reported by @walkonthemarz. The job_batches table uses SELECT FOR UPDATE, causing row-level lock contention with high-concurrency workers.

Batch never finishes when jobs fail

Issue #36180 (Feb 2021) reported by @stephenstack. Issue #35711 (Dec 2020) reported by @nalingia. When a batch job fails, pending_jobs may never reach 0, so then/finally callbacks never fire. Batch hangs forever. Closed as completed but no linked fix PR found.

ShouldBeUnique lock not released

Issue #49890 (Jan 2024) reported by @naquad -- lock not released when dependent model is deleted before processing. Closed with "this is a no-fix for us right now." Issue #37729 (Jun 2021) reported by @rflatt-reassured -- lock only releases after timeout, not after successful completion.

Failed jobs table causes OOM when retrying

Issue #49185 (Nov 2023) reported by @arharp. Issue #52129 (Jul 2024) reported by @godwin-loyaltek. RetryCommand and FailedJobProviderInterface::all() load the entire failed_jobs table into memory. At 300k+ records, it OOMs.

Chain jobs silently terminate on queue restart

Issue #45426 (Dec 2022) reported by @Monilsh. If queue:restart is issued mid-chain, remaining jobs are silently dropped. No error, no failed job record. Closed as "expected behavior."

Timed-out worker kill leaks resources

Issue #30351 (Oct 2019) reported by @halaei. Worker::kill() sends SIGKILL, which prevents cleanup of temp files, connections, and locks.

No backpressure on dispatch

PR #57787 (Nov 2025) by @yousefkadah -- community attempt to add queue depth notifications via a maxPendingJobs property. Not merged. There is no queue depth checking in the dispatch path. If the dispatch rate exceeds the consumption rate, the queue grows without limit.

Failed job providers crash on corrupted payload

Issue #59635 (Apr 2026, OPEN) reported by @ruttydm. UUID-based failed job providers use json_decode($payload, true)['uuid'] without null check. Corrupted payloads crash the provider and the failure record is permanently lost.

Current status

Across the 14 findings in this audit and the 9 community-reported issues above, the resolution status as of April 2026:

3 partially addressed: migrationBatchSize config added but defaults to unlimited (#7, PR #43310), ThrottlesExceptions docblock corrected but default remains 0 (#8, PR #36642), Windows timeout workaround documented but no auto-detection (#15002)
3 closed as intentional design decisions: ShouldBeUnique lock behaviour (#49890, "no-fix for us"), chain jobs dropped on restart (#45426, "expected behavior"), retryUntil/maxTries mutual exclusion (#35199, by design)
4 currently open: OOM infinite retry (#58207), worker silent loop (#59517), corrupted payload crash (#59635), job memory not released (#56395)
13 closed without framework code changes

Some of the closed issues are from older Laravel versions and may have been addressed indirectly through major version changes. Some reflect intentional design trade-offs that reasonable people can disagree on. I've included them because the safety implications exist regardless of whether the behaviour is intentional.

I verified all 14 findings and 9 community reports against v13.4.0 source, with spot-checks against v13.6.0 (April 2026). The oldest linked issues date back to January 2015 (#7046) and August 2016 (#15002). The same code patterns, same defaults, and same behaviours are still present.

What the docs and support could improve

Documentation

Add a "Queue Safety" section to the queue docs. The eight job-level properties (retry bounds, timeout, backoff, failed() handler, HTTP timeouts, idempotency guard, lock expiry, platform cost ceiling) are scattered across different sections. A single page showing them together with a recommended safe configuration would help.
Document the Vapor tries configuration. VaporWorkCommand defines --tries=0, but the QueueHandler runtime passes SQS_TRIES ?? 3. queue:work defaults to --tries=1. Three layers, three different values, none documented together.
Document the queue-timeout cost model on Vapor. On pay-per-millisecond Lambda billing, queue-timeout is the cost ceiling per failed attempt: memory-gb x timeout-seconds x $0.0000166667/GB-s. At 2048MB x 900s that is ~$0.03 per stuck attempt, multiplied by retry count and volume. The Vapor docs name queue-timeout as a configuration option but don't explain the cost model, and setting it high "to be safe" is the dominant shape of runaway bills.
Document the $timeout vs retry_after interaction. When a job's $timeout exceeds its connection's retry_after (default 90s on both database and Redis), the reservation can expire mid-flight and a second worker can pick up the same job. This is the single most-cited queue gotcha in community writeups and is not explained in the queue docs.
Document the retryUntil / maxTries mutual exclusion. When retryUntil() returns a future timestamp, maxTries is skipped entirely.
Document the maxExceptions OOM limitation. It only works for catchable exceptions. Fatal errors bypass the counter entirely.
Document the ShouldBeUnique lock lifecycle. $uniqueFor is unset by default, which on Redis and Database drivers produces a lock with no TTL that persists until manually released. Issue #49890 was closed as completed, but the safety implication of the default remains. Laravel 13.6.0 added #[DebounceFor] (PR #59507) as an attribute-driven alternative with last-writer-wins semantics; document it alongside the interface-based options.
Add a serverless queue checklist to the Vapor docs covering the eight job-level properties above, the queue-timeout cost model, AWS budget alerts, an SQS dead letter queue with maxReceiveCount, and a cost-based kill switch.

Support

Offer a job review when customers report unexpected queue costs. Ask: "Can we review your jobs to see if they are producing long-running expensive invocations that will rack up an excessive bill?" Walk through them in order of cost impact: queue-timeout first (the dominant cost multiplier, commonly set high "to be safe"), HTTP timeouts inside job bodies second (a hung call pins the worker at the ceiling), and the eight-property checklist at the top of this post third. Note that Lambda is built for short bursty request-response work, not long-running queue jobs; a 15-minute queue-timeout on pay-per-millisecond billing inverts Lambda's value proposition. If the work is inherently slow or I/O-heavy, Lambda is the wrong shape for it.
Link to safe configuration examples in cost-related support replies -- the SafeJob base class and the apply-spec prompt at the top of this post are both drop-in references.
Consider proactive dashboard warnings for the cost-shape signals, not just one property. Useful alerts: a job's SQS ApproximateReceiveCount crossing N without a class-level $tries; queue-timeout multiplied by attempt count exceeding a per-job cost threshold; $timeout greater than the connection's retry_after. A single-property alert catches some incidents; the shape of the 2023 billing incident required several layers to align.

Disclaimer

This audit was AI-assisted using Claude Code against Laravel Framework v13.4.0 with later spot-checks against v13.6.0. Every finding includes the exact file path and method name so you can verify it yourself.
I have not tested every suggested fix in production. Some may have trade-offs or edge cases I haven't considered.
Some findings may have been addressed in ways I haven't identified. I have not used Laravel Vapor since 2023 and do not currently have an account, so Vapor-specific observations are based on the public vapor-core source code, not runtime testing. Things may have changed.
These are starting points, not finished PRs. Published in good faith for the benefit of the community.

There is a reasonable design philosophy where the framework intentionally leaves these guardrails to the developer. The tools exist ($tries, $maxExceptions, $backoff, $timeout) and it's the developer's responsibility to configure them. Changing defaults is a breaking change for anyone relying on current behaviour, and some of these suggestions would need careful migration paths.

Where I respectfully disagree is on the scaffold. Sidekiq ships with 25 retries and exponential backoff. Symfony Messenger, Go Asynq, and Google Cloud Tasks all bake in retry config by default. Laravel's make:job generates a class with nothing. The tools exist. The scaffold doesn't tell you to use them.

If any of these findings are inaccurate or have already been addressed, I'm happy to update this post with corrections.

Why Your Laravel Jobs Might Retry Forever After an OOM

Josh Salway — Sat, 11 Apr 2026 00:00:00 GMT

In December 2019, I deployed an app on Laravel Vapor and received a bill for $140 USD after one week. I contacted support. The response was that the issue was on my end.

In August 2023, it happened again. $218.90 USD in 7 days. The support emails referenced queued jobs as the cause, but the exact root cause was never identified. Same response from support.

Both times I accepted it and moved on. I didn't have the tools or the time to investigate what actually went wrong.

In March 2026, while reviewing the Laravel org repos and codebase, I came across an issue that described a bug that could contribute to exactly this kind of problem. I can't say for certain it caused my specific billing incidents, but the symptoms match: runaway queued jobs with no circuit breaker.

The Bug

Issue #58207 on the Laravel framework repository, filed in December 2025, describes the problem: jobs with $maxExceptions retry infinitely when killed by an out-of-memory error.

The reason is straightforward. Laravel's exception counter for maxExceptions is only incremented inside markJobAsFailedIfWillExceedMaxExceptions(), which is called from handleJobException(), which is called from the catch (Throwable) block in Worker::process().

When PHP hits its memory limit, the process is killed by a fatal error. Fatal errors are not catchable exceptions. The catch block never executes. The counter is never incremented. The job goes back to the queue with a counter of zero. The next worker picks it up and the cycle repeats.

Worker starts -> fire() -> OOM -> process killed
Worker restarts -> same job -> counter still 0 -> fire() -> OOM
Worker restarts -> counter still 0 -> fire() -> OOM
... forever

On serverless platforms where you pay per invocation, each retry can cost money. As far as I'm aware, there is no circuit breaker for this scenario.

The Evidence

I verified this against the actual source code in Laravel Framework 13.4.0:

markJobAsFailedIfWillExceedMaxExceptions() is the only place the job-exceptions:{uuid} counter is incremented (Worker.php, line 636)
It is called from handleJobException() (line 538)
handleJobException() is called from the catch block (line 505)
There is no pre-fire check on the exception counter anywhere in the codebase

I then ran a subprocess test that allocates memory until OOM at 32M. The result:

SHUTDOWN FUNCTION: OOM detected
CATCH BLOCK EXECUTED: NO

PHP's register_shutdown_function runs after OOM. The catch block does not.

End-to-End Reproduction

To prove this isn't theoretical, I built a full end-to-end test:

Created a fresh Laravel 13.4.0 app with SQLite database queue
Dispatched an OomJob with $tries = 0 and $maxExceptions = 3
Ran php artisan queue:work --once with a 64M memory limit, 10 times
Checked the job state and exception counter after each run

Stock Laravel 13.4.0

| Run | Pending | Failed | Exception Counter | DB Attempts | |-----|---------|--------|-------------------|-------------| | 1 | 1 | 0 | not set | 1 | | 2 | 1 | 0 | not set | 2 | | 3 | 1 | 0 | not set | 3 | | ... | 1 | 0 | not set | ... | | 10 | 1 | 0 | not set | 10 |

The job retried 10 times. The exception counter was never set. The job would continue retrying forever.

With Fix Applied

| Run | Pending | Failed | Exception Counter | DB Attempts | |-----|---------|--------|-------------------|-------------| | 1 | 1 | 0 | 1 | 1 | | 2 | 1 | 0 | 2 | 2 | | 3 | 1 | 0 | 3 | 3 | | 4 | 0 | 1 | cleared | n/a |

The job was correctly failed after 4 runs with MaxExceptionsExceededException. The workers were freed.

The Fix

PR #59329 uses an optimistic increment pattern:

Increment the exception counter before $job->fire()
Decrement it after successful completion
Add a pre-fire check that fails the job if the counter already meets maxExceptions

If the worker dies during fire(), the increment persists in cache. On the next pickup, the pre-fire check catches it.

This is the same approach that community members independently built as a job middleware and validated in production, as discussed in the issue thread.

A companion fix (PR #59330) addresses the upstream cause: Pipeline retains references to completed job data between jobs, inflating worker memory and increasing the likelihood of OOM in the first place. Together, one reduces the chance of OOM and the other ensures graceful failure when it does happen.

A Note on Responsibility

No framework can guardrail against every possible runaway job caused by application code. There will always be edge cases where a developer's code consumes more resources than expected. That's the nature of software.

But the framework, hosting platform, and application code should all have seatbelts in place to reduce the likelihood of infinite retries in serverless environments. The maxExceptions feature exists specifically for this purpose. It just doesn't work when the failure mode is OOM, because of where the counter lives in the code. This fix doesn't solve every possible cause of runaway bills, but it closes one gap that the framework can reasonably address.

Current Status

The issue was filed in December 2025. It has 31 comments from multiple production users discussing the bug and independently developing workarounds.

PR #59329 was closed with the reason: "To preserve our ability to adequately maintain the framework, we need to be very careful regarding the amount of code we include."

PR #59330 (the companion Pipeline memory fix) was closed as a breaking change, because calls to getResolvedJob would return null post fire. A follow-up PR #59415 was submitted that removed the breaking change and only nulled $passable and $pipes. It was closed with no maintainer response.

The bug still exists in Laravel Framework 13.4.0.

Reproducibility

All benchmark scripts, reproduction code, and the end-to-end test app are publicly available:

github.com/JoshSalway/laravel-memory-benchmarks

The repository includes:

reproduce_oom_infinite_retry.php -- three-step proof of the bug
oom-retry-test/ -- full end-to-end test app with setup instructions
test_oom_128.php -- proves OOM occurs with realistic workloads at 128M
test_oom_prevention.php -- proves Pipeline memory retention triggers OOM
test_memory_real.php -- real-world queue workload benchmarks
test_memory_usecases.php -- PDF, image, CSV, and API sync benchmarks

Anyone can clone the repo, follow the instructions, and verify the results independently.

This fix has been tested end-to-end but has not been through a formal code review process. The reproduction scripts are publicly available for independent verification.

Rebuilding joshsalway.com: From Statamic to Astro

Josh Salway — Thu, 09 Apr 2026 00:00:00 GMT

I rebuilt this site from the ground up. The old stack was Statamic CMS running as a static site generator with Alpine.js, Tailwind CSS, and Vite, deployed on Netlify. The new stack is Astro 6 with React islands, Tailwind CSS 4, and the same Netlify deployment.

The core design is identical: same WebGL hero, same 8 colour themes, same Spotify-inspired dark palette. But the architecture is fundamentally different, and the site picked up a lot of new features along the way.

Why the rebuild

Three reasons:

Statamic is overkill for a static blog. I was running a full Laravel application with a CMS control panel, PHP runtime, and Composer dependencies just to generate HTML files. The content is markdown files in a folder.
JavaScript budget. The old site loaded Alpine.js on every page even though most pages had no interactivity. The About page doesn't need a JavaScript framework.
Developer experience. I wanted type-safe content schemas, better markdown handling, and a faster build pipeline.

The new stack

Astro 6 with islands architecture
React only for interactive components (theme switcher, search, contact form)
Tailwind CSS 4 via the Vite plugin, no PostCSS config needed
Astro Content Collections with type-safe Zod schemas
Netlify same host, same domain, same form handling

What ships zero JavaScript

This is the key architectural win. In Astro, pages are static HTML by default. JavaScript only loads for components that explicitly opt in with client: directives.

Pages that ship zero JavaScript:

About
Projects
Articles index
404 page

Pages that ship only the JavaScript they need:

Home: WebGL canvas + theme initializer
Article pages: reading progress bar, table of contents, code copy button
Contact: form submission handler
Every page: nav (search modal, theme picker, dark mode toggle)

The nav components hydrate with client:load (immediately) while the Konami code easter egg uses client:idle (when the browser is idle). This is granular control you don't get with a full SPA framework.

View Transitions

The site uses Astro's ClientRouter for SPA-like navigation between pages. Page transitions are smooth with no full reload flash. The inline <head> script handles theme persistence before paint, so accent colours never flicker between pages, even on Windows where the scrollbar gutter is reserved with scrollbar-gutter: stable to prevent layout shifts.

New features

Command palette search (Ctrl+K)

A Fuse.js-powered search modal accessible via Ctrl+K, Cmd+K, or the search icon in the nav. Searches across all pages, articles, and topic tags with fuzzy matching. Clickable tag filter chips let you browse by topic (Laravel, React, Tutorial, etc.). Shows all content on open with keyboard navigation (arrow keys + enter).

Article metadata

Each article card shows topic tags, depth and length bars (1-5 scale), and reading time. The depth bar indicates how technical the article is, the length bar shows how long it is. Inspired by the complexity bars on the projects page.

Reading progress bar

A thin accent-coloured bar fixed to the top of the viewport that tracks scroll position on article pages. Uses a passive scroll listener for performance.

Auto-generated from article headings (h2/h3). Only appears when an article has 3 or more headings. Highlights the current section using IntersectionObserver.

Code copy button

Hover over any code block to reveal a copy button. Provides visual feedback ("Copied!" / "Failed") and matches the dark code block aesthetic. Inline code elements break words on mobile instead of overflowing the page.

Previous/next article navigation

Links to adjacent articles at the bottom of each article page, ordered chronologically.

RSS feed

Available at /feed.xml. RSS readers auto-detect it via the <link rel="alternate"> tag in the HTML head. There's an RSS link inline with the Articles heading on the articles page.

Sitemap

Auto-generated by @astrojs/sitemap at /sitemap-index.xml with priority weighting for each page type.

JSON-LD structured data

Every article page includes Schema.org Article markup for better search engine results.

Dynamic text selection colour

Text selection colour in dark mode now matches the active theme accent. Switch to Ocean theme and your selection highlight turns blue. Switch to Gold and it turns yellow.

Custom 404 page

A styled error page matching the site design with links back to the home page and articles.

Short links

Every article has a short URL for sharing. For example, this post-mortem can be shared as joshsalway.com/post-mortem-pr-59323.

Projects page redesign

Project cards now show the project icon (FragHub's yellow PUBG helmet, Barcoder's barcode scan icon, Poker Timer's clock), full tech stack tags, a complexity bar, hosting info, pill-style action buttons, and "Read Article" links to the matching blog post. FragHub gets a rotating rainbow border as the featured project. Non-featured cards have a green border, background lift, and shadow glow on hover. The whole card is clickable. Tech filter pills at the top let you filter projects by stack (React, Laravel, Tailwind CSS, etc.).

Animated logo

The "JS" logo in the nav has a blinking cursor. Hover over it and it deletes "JS", then types a random word from a list of 180+ options (Zigzagging, Brewing, Flibbertigibbeting...) in red with a spinning asterisk. Move away and it types "JS" back.

Clickable tags

Topic tags on article cards and article headers open the search modal pre-filtered to that tag. The articles page has a tag filter bar that filters articles in place without a page reload. Same for the tech filter on the projects page.

About page

Profile photo pulled from GitHub, open source contribution mention, and links to get in touch.

Konami code

There's a hidden easter egg on the site. Press Up, Up, Down, Down, Left, Right, Left, Right, B, A on your keyboard (the classic Konami code from 1986) and watch what happens. You'll get a confetti cannon in all 8 theme colours, followed by a playable Space Invaders game. Use arrow keys to move, space to shoot, ESC to close. A small nod to the gaming roots that got me into programming.

SEO and redirects

The old Statamic site served articles at root-level URLs (/laravel-pr-59323-post-mortem). The new site uses /articles/ as a prefix. All 14 old URLs have 301 permanent redirects configured in netlify.toml so existing links from X, Google, and backlinks resolve correctly.

Canonical URLs, Open Graph tags, X/Twitter cards, and Google Analytics carry over from the old site.

Build performance

The full site builds in under 2 seconds. The old Statamic SSG pipeline took 8-10 seconds including the PHP runtime, Vite asset compilation, and static generation step.

Performance and accessibility

Lighthouse scores: 91 performance, 95 accessibility, 100 best practices, 100 SEO on the home page.

A few things that helped get there:

Lazy-loaded highlight.js: instead of bundling the full 969KB library on every page, it only loads via dynamic import() when the page actually has code blocks. Non-article pages ship zero highlight.js.
Touch targets: tag filter pills and nav buttons meet the 44px minimum on touch devices for WCAG compliance.
Service worker: the site works offline. A network-first strategy caches pages as you browse. Core pages (home, about, articles, projects, contact) are precached on first visit. If you lose connection, cached pages still load. Useful on dodgy mobile connections.
Image preloads: profile photo and project icons are preloaded in the HTML head so they render instantly without a pop-in flash.

No CMS, better security

There's no CMS. No admin panel, no database-backed editor, no login screen. When I want to write or edit an article, I open Claude Code and work directly with .md files. It commits to git, Netlify auto-deploys, and the article is live. The entire content workflow is the terminal.

Statamic's control panel was nice, but I never used it. I was always editing markdown files directly anyway. Removing the CMS removed an entire category of complexity and security surface: no PHP runtime, no authentication, no session management, no database, no admin panel to exploit, no plugins to patch. The attack surface is a CDN serving static HTML files. The attack surface is about as small as it gets.

What I'd do differently

If I were starting from scratch today, I'd skip the intermediate step. I initially rebuilt in Next.js before realising a static blog doesn't need a full React SPA framework. The Astro rebuild was the right call: it's the purpose-built tool for content sites with selective interactivity.

The Next.js version still exists on the master branch if I ever need it. The Astro version is on feat/astro-rebuild.

Blameless Post-Mortem: Laravel SessionManager Clone Removal

Josh Salway — Wed, 08 Apr 2026 13:59:00 GMT

Not every PR lands cleanly. This one got reverted, and it was worth understanding why.

The change

PR #59323 targeted a reported performance problem (#58377): SessionManager::createCacheHandler() was cloning the entire cache Repository on every request. For Redis, that clone triggered Repository::__clone(), which deep-cloned the underlying Store. The original issue reported that this was creating duplicate Redis TCP connections.

The fix removed the clone and added conditional Store cloning only when session.connection was explicitly configured. The tests passed. The reasoning looked sound.

It was in 13.x for eight days before it was reverted.

What broke

Two bugs, both caused by the same fundamental mistake.

Bug 1: Sessions silently switched Redis databases. When SESSION_CONNECTION is null (the default), the old clone inherited the default Redis connection (DB 0). By removing the clone and sharing the cache Repository directly, sessions started using the cache Redis connection (DB 1) instead. Session data moved to the wrong database. Any user with an existing session in DB 0 would appear logged out after upgrading.

Bug 2: Cache contamination. When SESSION_CONNECTION is explicitly configured, setStore() mutated the shared cache Repository singleton. After session middleware ran, every Cache::get() call in the application was reading from the session database instead of the cache database. Rate limiting, job deduplication, cache locks, everything that depends on cache would return null.

Both bugs were reported by the community within days. stancl filed issue #59515 identifying the connection switch, and webpatser identified the cache contamination in the same thread and provided a workaround. The PR was reverted shortly after.

Worst case and real-world impact

For apps using Redis sessions with separate default and cache connections, Bug 1 would cause existing sessions in DB 0 to become invisible when the app reads from DB 1, along with any session data including CSRF tokens, flash messages, and cart contents. For apps with an explicit session.connection, Bug 2 would break any feature that depends on cache: rate limiting would stop working, queue job deduplication would fail, cache-based locks would break, and any cached config or feature flags would return null.

The bug shipped in a tagged release:

v13.2.0 (Mar 24) - last clean release
PR #59323 merged (Mar 27) - the broken code enters 13.x branch
v13.3.0 (Apr 1) - released with the bug. Anyone who ran composer update got it.
Issue #59515 filed (Apr 3) - stancl reports it
PR #59542 reverts (Apr 5) - fix merged to 13.x
v13.4.0 (Apr 7) - clean release with the revert

In practice, only two people reported the regression during the six days v13.3.0 was the latest release. No other issues were filed describing symptoms consistent with it.

The root cause

The concept that best describes this mistake is Chesterton's Fence: don't remove something until you understand why it was put there.

I looked at the clone and asked the wrong question. I asked: "Does CacheBasedSessionHandler mutate the Repository?" The answer was no, it only calls get, put, and forget. So I concluded the clone was unnecessary.

The right question was: "What invariant does this clone maintain?" The answer: isolation between subsystems. The session needs its own Repository instance so that operations on it (like setStore() for connection rebinding) don't contaminate the cache singleton that the rest of the application depends on.

The clone wasn't protecting against mutation of the Repository's data. It was protecting against mutation of the Repository as a shared object in the service container.

What the PR description got wrong

My PR stated "No behavior change" for the common case. That was wrong. I reasoned about it instead of proving it. The tests I wrote validated that sessions could read and write (the happy path), but never asserted which Redis connection was being used or whether the cache singleton remained clean after session initialization.

If I'd spun up Redis with separate default (DB 0) and cache (DB 1) connections and written a test that checked which database the session was actually writing to, both bugs would have been caught before the PR was ever opened.

What I changed in my process

I use AI to help find issues with my fixes, and I verify its analysis myself before submitting. That means asking questions, thinking about edge cases, and looking for concerns that could break the code. The goal is to fix it without introducing regressions, while making minimal changes that are impactful and useful, without taking shortcuts.

I maintain a PR Preflight checklist that I run through before marking any Laravel PR ready for review. After this revert, I added six new items. These are the kinds of checks AI can help with, as long as you verify the answers:

Reproduce the problem first. Before writing any fix, reproduce the reported issue with a test and confirm it is an actual problem. If you can't reproduce it, the fix may not be needed. This PR was based on a reported performance problem that could not be reproduced with real connection counts.
Chesterton's Fence check. For every removal (clone, copy, guard, wrapper), answer: "What invariant does this maintain? What breaks if two subsystems share state without it?" If I can't answer confidently, the removal isn't safe.
"Prove, don't claim." If a PR description says "no behavior change", there must be a test that would fail if behavior did change. Reasoning is not proof.
Test with real multi-service configs. Single-connection test setups hide routing bugs. For anything touching sessions, cache, or Redis, test with configs that use separate connections on different databases.
Singleton contamination audit. When removing isolation around a shared singleton, trace every code path that could mutate the shared object after the change. The blast radius of singleton mutation is the entire request.
Verify reasoning empirically. Confident analysis can be wrong. Any claim about behavior needs to be tested, not reasoned about.

Does the original problem actually exist?

The original issue (#58377) claimed that the clone creates duplicate Redis TCP connections. After the revert, I looked more carefully at what the clone actually does.

Repository::__clone() deep-clones the Store, creating a new RedisStore object. But RedisStore doesn't hold a connection directly. It holds a reference to the RedisManager factory, which is shared by reference (not cloned). When the cloned Store calls $this->redis->connection($this->connection), it hits the same RedisManager singleton:

// RedisManager::connection() - caches by name
public function connection($name = null)
{
    $name = enum_value($name) ?: 'default';

    if (isset($this->connections[$name])) {
        return $this->connections[$name];
    }

    return $this->connections[$name] = $this->configure(
        $this->resolve($name), $name
    );
}

The manager caches connections by name. Both the original and cloned Store resolve to the same cached connection. No duplicate TCP connection is created.

To confirm this, I tested connection counts against a real Redis instance. Session alone opens 1 connection (default). Cache adds 1 more (cache). Total: 2 connections, one per named connection, both necessary. The clone doesn't add a third. I could not reproduce the duplicate connections that the original issue reported. The actual cost of the clone is one extra PHP object per request, not a TCP connection.

I also used the same CLIENT INFO approach that stancl used in his issue report to independently verify the connection routing. All states produced identical results: correct routing, no contamination, no duplicate connections. I could only work that out by trying to reproduce the original bug and testing it properly. The code analysis suggested the connections were cached. The real-world tests proved it.

This changes the risk-reward calculus. The clone provides valuable isolation between the session and cache subsystems, as this revert demonstrated. The performance cost is one object allocation per request. Removing it risks the kind of regression we saw here, for a gain that doesn't appear to exist.

I've drafted an alternative approach that preserves the clone for isolation while sharing the Store. Benchmarking shows it offers no measurable performance benefit over stock Laravel for Redis sessions, which reinforces the conclusion that the original issue may not be a real problem. The value of the draft PR is the regression tests and documentation it adds, which may be useful as a reference for anyone revisiting this area in the future.

Between stancl's findings and the testing here, the duplicate connection claim in the original issue does not appear to be reproducible. The issue may no longer need to remain open.

Not every attempt lands on the first try. What matters is understanding what happened, improving the process, and applying those lessons to the next contribution. Sometimes solving a hard problem takes multiple attempts - each one reveals something the previous approach missed. That's not necessarily a complete failure, that's how difficult problems get solved. The best response is better work next time.

14 More PRs Merged Into Laravel -- Serializable Closure, Cloud CLI, and More

Josh Salway — Wed, 08 Apr 2026 02:00:00 GMT

Since my last post, another 14 pull requests have been merged across 5 Laravel repositories. That brings the total to 34 merged PRs across 16 repos since mid-March.

This time the focus shifted to a single package that needed serious attention: laravel/serializable-closure.

Serializable Closure (9 merged)

I found a chain of bugs in the v2.x closure serialization engine. Each fix uncovered the next one. Here's the full list:

#129 -- Fix v2.0.9 regression: Bus::chain breaks with nested closures [severity: critical, size: medium] This was the critical one. The v2.0.9 release introduced a regression that broke Bus::chain() when using nested closures. Queue jobs using closure chains were failing silently.

#128 -- Fix crash with method-only attributes on serialized closures [severity: high, size: small] PHP 8 attributes that target only methods were causing serialization to crash when applied to closures.

#135 -- Fix SerializableClosure as class property being unwrapped during deserialization [severity: high, size: small] When a SerializableClosure was stored as a class property, deserialization was unwrapping it prematurely, breaking the expected type.

#137 -- Fix operator precedence bug in scope detection for class keywords [severity: medium, size: tiny] An operator precedence issue in the AST analysis was causing incorrect scope detection when class keywords like self, static, and parent appeared in certain expressions.

#140 -- Fix instanceof with parenthesized expressions [severity: medium, size: small] instanceof checks with parenthesized expressions were being parsed incorrectly during serialization.

#141 -- Add true to builtin types list for PHP 8.2+ [severity: medium, size: small] PHP 8.2 added true as a standalone type. The serializer didn't recognize it, causing type resolution failures.

#146 -- Bypass property hooks during serialization traversal on PHP 8.4+ [severity: high, size: medium] PHP 8.4 property hooks were interfering with the serialization traversal. This fix bypasses them safely.

#139 -- Remove dead code and fix docblock errors. [severity: low, size: tiny] #143 -- Register missing test in phpunit.xml.dist. [severity: low, size: tiny] #153 -- Update README caveats. [severity: low, size: tiny]

Cloud CLI (2 merged, more in progress)

#111 -- Fix Font::load crash on Windows [severity: high, size: tiny] The Cloud CLI was crashing on Windows because font loading assumed Unix paths.

#117 -- Fix browser and file manager commands on Windows and Linux [severity: medium, size: small] cloud open and cloud browse weren't working on Windows or Linux. Now they use the correct platform-specific commands.

I've put a lot of work into Cloud CLI. I originally opened a bunch of individual PRs, then consolidated them into one larger PR. A lot of the fixes were interconnected and didn't make sense in isolation, and having them together made it possible to run proper live integration tests against the Cloud API with all the changes in place. That turned out to be too much to review in one go, which is fair. So now I'm going back through the individual issues and PRs one by one, finding where I can help the maintainers with what they're already working on without getting in the way of their direction. It's their project and they know best how they want to build it. I'm just happy to see some of the same problems I flagged getting addressed in recent merges.

Telescope (1 merged)

#1710 -- Fix npm audit vulnerabilities (lodash, axios, rollup) [severity: medium, size: large] Security dependency updates for the Telescope frontend assets.

Installer (1 merged)

#497 -- Fix Boost install on Windows: quote version constraint to protect caret [severity: high, size: tiny] The ^ in version constraints was being interpreted as an escape character by the Windows shell. Quoting it fixes the install.

The bigger picture

34 merged PRs, 16 repos, three weeks. What started as a handful of bug fixes turned into a deep audit of serializable-closure -- a package that underpins queued jobs, event listeners, and anything that serializes closures in Laravel. The v2.0.9 regression fix alone was affecting anyone using Bus::chain() with closures.

Beyond what's merged, there's still a lot in the pipeline. Right now I have 29 PRs open for review and 43 drafts across repos including cloud-cli, forge-cli, serializable-closure, framework, installer, reverb, horizon, echo, ai, cashier-paddle, and cashier-stripe. Each draft needs a fresh look against the latest code, updated tests, and sometimes a complete rework based on how the package has changed since I first opened it. I'm working through them one by one. It's not fast work, but it's worth doing right.

If you've got feedback on any of my PRs, good or bad, I genuinely appreciate it. And if any of my drafts cover something you want to take on yourself, go for it. I'd rather see the fix land than hold onto it. I've already got plenty to work through.

I'm going to keep contributing. There's always more to fix.

Windows vs Mac for Claude Code: The Benchmark That Changed How I Work

Josh Salway — Wed, 08 Apr 2026 00:00:00 GMT

I use Claude Code heavily - it's become central to how I work on Laravel contributions, building apps, and exploring codebases. I have two machines: a Ryzen 9 9950X3D desktop with 64GB RAM running Windows 11, and an M1 MacBook Pro with 16GB. The desktop has significantly more raw power, but something always felt off. The Mac felt snappier when running Claude Code.

To put the hardware gap in perspective, here are the Geekbench 6 scores. The "My" columns are from my actual machines (9950X3D result, M1 Pro result), and the "Typical" columns are published averages:

| Benchmark | Typical 9950X3D | My 9950X3D | My M1 Pro | Typical M1 | 9950X3D vs M1 Pro | |---|---|---|---|---|---| | Geekbench 6 Single-Core | ~3,200 | 3,380 | 2,254 | ~2,400 | 1.5x | | Geekbench 6 Multi-Core | ~23,000 | 22,160 | 10,422 | ~7,700 | 2.1x |

The 9950X3D is roughly 2x faster in multi-core versus the M1 Pro I actually use. On paper, it should demolish the Mac at everything. That's what made the next part so surprising.

So I built a benchmark to find out why.

What I tested

Not synthetic CPU scores - the actual operations that happen hundreds of times during a Claude Code session:

Process spawning - every Read, Grep, Glob, and Bash call spawns a new process
PHP execution - running tests, artisan commands, composer
Disk I/O - reading and writing thousands of small files (like vendor/)
File search - ripgrep and git grep across the Laravel framework
Git operations - status, log, diff, branch listing
Node.js - JSON processing and startup (Claude Code's internals)

I ran the benchmark three ways: Windows with Git Bash (what I'd been using), WSL2 on the same machine, and the Mac.

The results

| Environment | Total Time | |---|---| | Windows Git Bash | 11.9 seconds | | WSL2 (same PC) | 2.8 seconds | | Mac M1 | 2.6 seconds |

The Windows PC - with a 16-core, 32-thread 9950X3D and 64GB of RAM - was 4.3x slower than the same hardware running through WSL.

The smoking gun: process spawning

The single biggest bottleneck was process creation. Claude Code shells out constantly - git, php, grep, find, node - sometimes hundreds of times in a single conversation. Here's what 50 PHP process spawns looked like:

| Environment | 50x PHP Spawn | |---|---| | Windows Git Bash | 3,244ms | | WSL2 | 457ms | | Mac M1 | 31ms |

That's not a typo. Windows was 100x slower than the Mac at spawning PHP processes, and 7x slower than WSL on the same CPU.

This isn't a CPU problem - it's fundamental to how Windows creates processes. Linux and macOS use fork(), which is nearly free because it shares the parent process's memory pages until they're modified. Windows uses CreateProcess(), which has to load DLLs, set up security tokens, and initialize the environment from scratch every time. Add the Herd .bat wrapper on top and each PHP invocation carries real overhead.

Git spawning showed the same pattern - 791ms on Git Bash, 36ms on WSL. That's a 22x difference.

Where WSL actually beats the Mac

Once I switched to WSL, the PC didn't just match the Mac - it won in several categories:

| Test | WSL | Mac M1 | Winner | |---|---|---|---| | Write 2000 files | 24ms | 215ms | WSL (9x) | | Read 2000 files | 17ms | 50ms | WSL (3x) | | 50x git spawn | 36ms | 371ms | WSL (10x) | | 50x node spawn | 576ms | 1,575ms | WSL (2.7x) | | Node JSON 50k | 76ms | 92ms | WSL | | Composer validate | 105ms | N/A | - | | PHPUnit (2 suites) | 123ms | N/A | - |

WSL's ext4 filesystem crushed APFS on small file operations. Git spawning was 10x faster. The 9950X3D's raw power finally showed through once the Windows overhead was removed.

The Mac still wins on raw PHP execution - 2ms vs 33ms for the workload test. ARM silicon is remarkably efficient at this. But PHP execution speed matters less for Claude Code since it's the process spawning, not the execution, that's the bottleneck.

The RAM advantage

This is the other half of the story. The M1 MacBook has 16GB. My desktop has 64GB.

While running the benchmark, I checked task manager. I had three Claude Code instances running alongside Chrome, Discord, Spotify, NVIDIA Broadcast, and Steam - using 20GB total with 41GB still free.

On the Mac, running three Claude Code sessions simultaneously would mean swapping to disk. On the PC, I'm at 33% utilisation. I could run 4-5 Claude Code sessions in parallel without thinking about it. For multi-repo work - fixing a framework PR in one terminal while building a feature in another and running tests in a third - that headroom matters.

What I changed

The bottleneck was never the hardware. It was Windows.

For those unfamiliar, WSL (Windows Subsystem for Linux) is a feature built into Windows that lets you run a full Linux environment directly on your machine - no virtual machine setup, no dual booting. You can access it from any terminal on Windows: open PowerShell, Windows Terminal, or even Git Bash and type wsl to drop into a Linux shell. From there, you get native Linux performance for all your CLI tools.

I now default to WSL for all CLI-heavy operations - not just git (which I was already doing for CRLF reasons). Tests, composer, file search, anything that involves repeated process spawns. The key detail: keep repos on WSL's native ext4 filesystem (~/Herd/framework), not on the mounted Windows drive (/mnt/c/...). The 9P filesystem bridge between Windows and WSL adds its own overhead.

I also updated Claude Code's persistent memory with recommendations based on these benchmarks - telling it to prefer WSL for all CLI-heavy operations on Windows. Now when I start a new session, Claude Code already knows to route commands through WSL where possible, without me having to remind it every time. It's a small thing, but it means the performance gains carry forward automatically across every future conversation.

Build your own benchmark

The benchmark script is portable - it auto-detects your OS, finds PHP/Composer/Node/ripgrep, and tests against a Laravel framework checkout if one exists. If you want to test your own setup:

git clone git@github.com:JoshSalway/dev-workflow-benchmark.git
cd dev-workflow-benchmark
bash dev-workflow-benchmark.sh

It saves results to a file, and there's a compare.sh script for side-by-side comparison with colour-coded output.

The takeaway

If you're a developer on Windows using Claude Code (or any tool that shells out frequently), and things feel slower than they should - try WSL. The CPU isn't the problem. Windows process creation is. WSL gives you Linux-native speeds on the same hardware, and if your machine has decent RAM, you get parallelism that a MacBook can't match.

My 9950X3D went from the slowest machine in this test to effectively tied for fastest - just by changing which shell I run things in.

Update: a second speedup, same bottleneck

Added 2026-04-21.

The finding above is about process creation. Every shell-out Claude Code makes pays the Windows CreateProcess tax, and WSL removes it. fff-mcp attacks the same bottleneck from the other side: keep a single long-lived process alive, and stop shelling out for search entirely.

fff is a Rust MCP server that indexes a repo once, then answers grep and file-find queries from a warm in-memory cache. Claude Code spawns it at session start and keeps it alive for the whole conversation. Every search after the first is a round-trip to a warm daemon, not a fresh rg invocation.

I re-ran a focused benchmark on the same Windows machine, still under Git Bash so the original Windows spawn penalty is still in play. Test repo: the Filament framework, 7,794 git-tracked files. Workload: five bare-identifier grep queries (Filament, TableAction, HasForms, Livewire, Authorize), median of three runs.

| Metric | ripgrep (before) | fff-mcp (after) | |---|---|---| | Per-query, warm | 91.4ms | 6.6ms | | 5-query session total | 458ms | 83ms |

That is 14.0x faster per warm query and 5.5x faster over the full 5-query session, after including fff's one-time startup cost (10ms handshake plus 48ms initial scan). Startup amortises after the second query. A real session makes dozens.

The two fixes stack. WSL gives you Linux-native process creation, so every remaining shell-out is cheap. fff removes the shell-out entirely for search, so the cheapest launch is the one that never happens. Combined, agent search feels interactive rather than batched.

Install is one line plus one registration:

curl -fsSL https://raw.githubusercontent.com/dmtrKovalenko/fff.nvim/main/install-mcp.sh | bash
claude mcp add -s user fff -- ~/.local/bin/fff-mcp --no-update-check

The --no-update-check flag keeps the server from phoning GitHub on startup. Source is MIT, over 5,000 stars, and actively maintained (stable v0.6.1 shipped two days before I ran this benchmark, nightly the day before).

If you want a video walkthrough of the same tool, this one covers the install and rationale in more depth:

On Mac (M1, macOS), the gap is narrower but still real. I re-ran the same five-query workload against a larger repo (a private project, 36,347 files). The win is smaller because macOS process creation is already fast (Unix fork vs Windows CreateProcess), but over a full session with dozens of searches the savings still add up.

| | Windows (Git Bash, 7,794 files) | Mac (M1, 36,347 files) | |---|---|---| | ripgrep per query | 91.4ms | ~950ms | | fff-mcp per query (warm) | 6.6ms | ~229ms | | Speedup | 14x | ~4x | | 5-query session | 458ms vs 83ms | ~4,750ms vs ~1,150ms |

The Windows speedup is larger because CreateProcess is the bottleneck there, and fff removes it entirely. On Mac, process creation is cheap already, so the gain comes from skipping the disk scan rather than avoiding spawn overhead.

Same pattern as the WSL change above: I updated Claude Code's persistent memory so future sessions default to fff for content search in git repos. The speedup carries forward without me having to think about it.

20 PRs Merged Into Laravel In 12 Days

Josh Salway — Tue, 31 Mar 2026 00:00:00 GMT

Over the past couple of weeks I went deep into the Laravel ecosystem -- hunting bugs, fixing CI pipelines, patching Windows compatibility, and squashing memory leaks. 20 pull requests were merged across 12 Laravel repositories between March 18-29. Around 1,000 lines of code added.

Here's everything that landed.

Framework (4 merged)

#59376 -- Fix incrementEach/decrementEach to scope to model instance This was the big one. incrementEach and decrementEach weren't scoping to the model instance -- they were updating every row in the table. A data corruption bug hiding in plain sight.

#59331 -- Fix sub-minute scheduling skips at minute boundaries A Carbon mutation bug. endOfMinute() was mutating the shared $startedAt instance instead of a copy, causing sub-minute scheduled tasks to skip executions at minute boundaries. A minimal fix with full test coverage, zero breaking changes.

#59323 -- Remove unnecessary clone in SessionManager to prevent duplicate Redis connections An unnecessary clone in SessionManager was silently creating duplicate Redis connections.

#59309 -- Bound error page query listener to prevent memory bloat in Octane The debug error page's query listener was storing unbounded SQL strings and bindings. A single bulk insert could inflate an Octane worker's memory by 120MB+. Only affects local dev (APP_DEBUG=true), but three previous PRs had tried and failed to fix it.

Windows Compatibility (2 merged)

Prompts #232 -- Fix trailing newline calculation for Windows PHP_EOL Windows uses \r\n -- the newline calculation wasn't accounting for that. 87 lines added with proper test coverage.

Installer #478 -- Fix interactive subprocess stdin on native Windows The Laravel installer's interactive subprocesses weren't working on native Windows. This makes the onboarding experience work properly for Windows devs.

Dusk (3 merged)

#1189 -- Fix findButtonByText to prefer exact text match over contains When you have buttons with similar text, Dusk was matching the wrong one. Now it prefers exact matches.

#1192 -- Fix typo in teardown method name. #1193 -- Fix docblock typo in assertVueContains.

Reverb (1 merged)

#374 -- Include server path in broadcasting connection config Important for anyone running Reverb behind a reverse proxy with a path prefix.

CI & Test Compatibility (9 merged)

Several packages needed their CI pipelines and test suites updated for Laravel 13, Livewire v4, and PHPUnit 12:

Pulse -- #499, #500, #501, #502
Telescope -- #1703
Socialite -- #769
Envoy -- #291
Cashier Paddle -- #315
Vapor Core -- #201

Sentinel (1 merged)

#4 -- Fix typo in CI workflow exclusion matrix

Reflecting on it

What I love about this batch is the range -- from a data corruption bug in the framework core, to Windows compatibility fixes, broadcasting config, and CI pipelines across a dozen repos. The big framework fixes all have proper tests, and I tested the Windows-specific fixes across both Windows 11 and macOS because the Laravel team is predominantly on Mac and some platform edge cases slip through.

20 PRs, 12 repos, 12 days. I use Laravel every single day and being able to give back to the framework and help the team out is genuinely one of the most rewarding things I do.

Still got a few more open -- keeping at it.

Day 2 Update: Unblocked -- Full PR List, Confidence Ratings, and What's Next

Josh Salway — Thu, 19 Mar 2026 00:00:00 GMT

This is a follow-up to yesterday's post. I was unblocked from the Laravel GitHub organisation yesterday -- thank you.

Since being unblocked, I've been submitting the fixes I had queued up. The scope has grown well beyond the original 25 patches. Here's the full accounting of everything that's been submitted, what still lives on forks/gists, confidence levels for each fix.

Master tracking gist: GitHub Gist

The numbers

91 PRs submitted to upstream laravel/* repos
39 open, 45 closed, 1 merged
26 repos touched
30 gists with standalone patches
Plus 100 PRs on my personal forks (many overlap with upstream submissions)

I know that's a lot. Apologies for the influx -- I've been trying to submit gradually and push to my own forks first to avoid overwhelming maintainers. Many of the closed ones were closed by maintainers (understandably), and the fixes for those still live on my forks if anyone wants to pick them up.

Context

I've been using Claude Code to systematically work through open issues across the Laravel ecosystem. Every fix targets an existing open issue that already has community reports. The process was:

Find issues with multiple reports or long comment threads
Have Claude Code analyse the root cause and write a fix
Run the repo's full test suite
Test on my Windows machine (and macOS where applicable)
Document before/after results

I develop sometimes on Windows 11 Pro (AMD Ryzen 9 9950X3D, PHP 8.4 via Herd, WSL2, Docker Desktop). A lot of the Windows-specific issues I have experienced first hand from using it. The Laravel team is predominantly on macOS, so some Windows edge cases are easy to miss -- it is a different testing surface that I happen to cover. I've also verified the cross-platform fixes on macOS (Darwin 25.3.0, PHP 8.4.19) Mac 2021 M1 16gb which is getting old now but still good.

These PRs may still need proper review and testing and need to consider edge cases that I may not be aware of. Laravel team also have to consider if they want to support the features and changes I have added. I'm not expecting anything to be merged on faith. Some may need adjustments, and I'm happy to iterate. Anyone can replicate what I've done by pointing Claude Code at these same issues -- the fixes themselves aren't special, but hopefully the testing and documentation saves some review time.

Already merged (1)

This one made it in:

| Repo | PR | Title | |------|-----|-------| | laravel/dusk | #1189 | Fix findButtonByText to prefer exact text match over contains |

Open upstream PRs -- by repo

laravel/cloud-cli (29 open)

This was the deepest dive. The cloud CLI is relatively new and had a lot of low-hanging fruit -- bug fixes, missing features, and test coverage. It also adds some additional features (nice to haves). I have combined all these efforts into 1 big PR on my own fork and will be testing and reviewing the forked cloud-cli and reporting on any bugs or issues I find from actual real world testing.

| PR | Title | Confidence | Notes | |----|-------|:----------:|-------| | #25 | Fix token deduplication and stale token accumulation | 85% | Straightforward data cleanup | | #32 | Add --hide-secrets flag to redact env var values | 80% | New feature, clean implementation | | #33 | Add --token flag and LARAVEL_CLOUD_API_TOKEN env var support | 80% | Standard CLI auth pattern | | #34 | Fix inconsistent error handling between commands and resolvers | 75% | Touches many files -- needs careful review | | #35 | Fix token validation performance with cached org names | 80% | Performance improvement | | #36 | Enable commented-out application command tests | 70% | Tests may have been disabled for a reason | | #37 | Improve resolver error messages with specific failure context | 85% | UX improvement, additive | | #42 | Fix wrong RequestException import in 7 commands | 90% | Clear bug -- wrong class imported | | #43 | Comprehensive test coverage -- 87 files, 378 tests, 3% to 100% | 65% | Massive -- needs thorough review | | #52 | Fix 5 bugs found during test coverage work | 85% | Found while writing tests | | #53 | Add missing CLI options for non-interactive create commands | 75% | Feature addition | | #54 | Refactor: decompose Ship.php from 788 to 152 lines | 60% | Major refactor -- may not match team's vision | | #58 | Fix database command bugs -- restore, snapshot, cluster update | 80% | Multiple targeted fixes | | #63 | Add --hide-secrets flag to redact connection credentials | 80% | Security feature | | #64 | Add global --application and --environment flags | 70% | Opinionated UX change | | #70 | Add environment:start and environment:stop commands | 70% | New commands -- depends on API support | | #71 | Add deployment:logs command | 75% | New command | | #72 | Add env:variables delete and metrics commands | 70% | New commands | | #74 | Fix 8 reliability issues in cloud ship command | 80% | Bug fixes in critical path | | #75 | Auto-show deployment logs on failure | 85% | UX improvement | | #80 | Add command aliases and cloud use context command | 70% | Opinionated UX | | #81 | Add env:pull and env:push commands for .env file sync | 75% | New feature | | #82 | Add --dry-run flag for deploy and ship commands | 80% | Safety feature | | #87 | Fix credential leak in DatabaseOpen and remove dead code | 90% | Security fix | | #90 | Fix InstanceDelete return constant and AuthToken empty tokens guard | 85% | Small targeted fixes | | #92 | Fix incorrect documentation in markdown files | 90% | Docs only | | #95 | Fix hardcoded URLs for private Cloud compatibility | 85% | Makes self-hosted work | | #101 | Add cloud status command | 75% | New command | | #102 | Add debug, health check, and ci:setup commands | 70% | New commands |

laravel/forge-cli (4 open)

| PR | Title | Confidence | Notes | |----|-------|:----------:|-------| | #109 | Fix critical bugs: missing DB types, null references, path logic | 85% | Multiple clear bugs | | #110 | Fix typo, password exposure, version check error handling | 85% | Security + UX | | #111 | Hide unimplemented command, centralise DB types, null safety | 75% | Code quality | | #125 | Fix php_uname() ValueError on PHP 8.4+ | 95% | Clear PHP version compat fix |

laravel/forge-sdk (2 open)

| PR | Title | Confidence | Notes | |----|-------|:----------:|-------| | #206 | Fix missing return values, URL inconsistencies, comparison operators | 80% | Multiple small fixes | | #207 | Fix incorrect and inconsistent docstrings | 75% | Docs |

laravel/forge-monitor (2 open)

| PR | Title | Confidence | Notes | |----|-------|:----------:|-------| | #76 | Fix critical bugs: incorrect import, null returns, SQL interpolation | 85% | Security + correctness | | #77 | Improve error handling in commands, notifications, config validation | 75% | Hardening |

laravel/forge-database-backups (1 open)

| PR | Title | Confidence | Notes | |----|-------|:----------:|-------| | #10 | Fix security vulnerabilities and improve reliability | 80% | Security fixes in backup script |

laravel/larachat (1 open)

| PR | Title | Confidence | Notes | |----|-------|:----------:|-------| | #6 | Migrate to Laravel AI SDK with conversation memory | 60% | Large migration -- may not match direction |

Fixes on forks (not yet submitted upstream)

These are ready to submit gradually. All live on my GitHub forks with full PR descriptions and test results.

Windows Fixes

| Fork PR | Issue | Title | Confidence | Notes | |---------|-------|-------|:----------:|-------| | JoshSalway/sail #1 | sail #850 | Windows/WSL detection in sail script | 85% | Tested on Git Bash + Windows PHP | | JoshSalway/sail #2 | sail #843 | .sh -> .sql for testing DB init | 95% | Matches existing PostgreSQL approach | | JoshSalway/sail #3 | sail #815 | xvfb-run for headed browser tests | 80% | Works in Docker, transparent for non-browser | | JoshSalway/sail #4 | sail #809 | Update sail share default host/port | 90% | Config fix | | JoshSalway/octane #1 | octane #1100 | POSIX signal constant fallbacks for Windows | 90% | defined() checks are safe, zero behaviour change on Linux/macOS | | JoshSalway/octane #3 | octane #1077 | Propagate #[Singleton] attribute bindings | 75% | Needs real Octane testing | | JoshSalway/octane #4 | octane | Fix null worker crash in Swoole during reload | 80% | Edge case fix | | JoshSalway/prompts #1 | prompts #201 | Static spinner for --no-ansi | 85% | Fallback rendering | | JoshSalway/prompts #2 | prompts #189 | Fix nested Symfony style tags | 80% | Regex fix | | JoshSalway/installer #1 | installer #410 | Only run post-root-package-install if exists | 90% | Guard check | | JoshSalway/installer #2 | installer #465 | Apply package manager to GitHub workflows | 85% | Template fix | | JoshSalway/installer #3 | installer #441 | Remove unsupported formatting tags | 90% | Simple removal | | JoshSalway/installer #4 | installer #471 | Prevent infinite loop on self-update failure | 85% | Guard against edge case | | JoshSalway/wayfinder #1 | wayfinder #160 | Fix TypeError on inline variable assignment | 80% | Edge case in TS generation | | JoshSalway/wayfinder #2 | wayfinder #190 | Fix array_is_list TypeError on overlapping paths | 85% | Clear bug | | JoshSalway/wayfinder #3 | wayfinder #195 | Emit generic type parameters in TS conversion | 75% | TypeScript edge case |

Cross-Platform Fixes

| Fork PR | Issue | Title | Confidence | Notes | |---------|-------|-------|:----------:|-------| | JoshSalway/framework #2 | framework #56652 | Fix memory leak in query log for Octane workers | 85% | Clear leak | | JoshSalway/framework #4 | framework #58377 | Remove unnecessary clone in SessionManager | 95% | One-line fix, 93 tests pass | | JoshSalway/framework #5 | framework #57456 | Fix previousPath() for external referrers | 85% | URL handling fix | | JoshSalway/framework #6 | framework #59012 | Fix TypeError in Http::retry() with null callback | 90% | Type safety fix | | JoshSalway/framework #7 | framework #57961 | Catch UniqueConstraintViolationException in session | 85% | Race condition guard | | JoshSalway/framework #8 | framework #59024 | Locale-independent MySQL lost connection detection | 80% | Internationalisation fix | | JoshSalway/framework #9 | framework #53278 | Skip maintenance.php with cache driver | 85% | Logic fix | | JoshSalway/framework #10 | framework | Fix File::types() discarding chain config | 80% | Validation fix | | JoshSalway/framework #11 | framework | Fix inconsistent accessor attribute name conversion | 75% | Edge case | | JoshSalway/framework #12 | framework | Add configurable key prefix to ThrottleRequestsWithRedis | 70% | Feature addition | | JoshSalway/framework #13 | framework | Fix FileStore cache deserialization with sub-10-digit timestamps | 80% | Edge case fix | | JoshSalway/framework #14 | framework | Set working directory for schedule:work subprocess | 85% | Path resolution fix | | JoshSalway/cashier-stripe #1 | cashier-stripe #1817 | Webhook reconciliation for failed swap payments | 75% | Has a consistency window -- needs review | | JoshSalway/cashier-stripe #3 | cashier-stripe #1773 | Fix subscription type race condition | 80% | Concurrency fix | | JoshSalway/cashier-stripe #4 | cashier-stripe #1824 | Fix webhook failing to clear trial_ends_at | 90% | Clear null-handling bug | | JoshSalway/cashier-paddle #1 | cashier-paddle #310 | Webhook race conditions in subscription creation | 80% | Same pattern as Stripe fix | | JoshSalway/horizon #1 | horizon #1678 | Release unique job locks when clearing queues | 85% | Lock cleanup | | JoshSalway/horizon #2 | horizon #1704 | Scope WaitTimeCalculator to supervisor queues | 80% | Metric accuracy | | JoshSalway/horizon #3 | horizon #1698 | Fix null access in JobPayload::id() for corrupt jobs | 90% | Null guard | | JoshSalway/horizon #4 | horizon #1668 | Fix 'delayed until' showing wrong time | 85% | Display bug | | JoshSalway/horizon #5 | horizon #1647 | Fix AutoScaler not respecting minProcesses on startup | 80% | Scaling logic | | JoshSalway/telescope #1 | telescope #1691 | Fix 401 behind Docker/reverse proxy after Sentinel | 80% | Proxy detection | | JoshSalway/telescope #2 | telescope #1693 | Fix ExtractTags crash for listeners with event-typed tags() | 85% | Type handling | | JoshSalway/telescope #3 | telescope | Fix crash recording events for composite key models | 80% | Edge case | | JoshSalway/telescope #4 | telescope | Prevent duplicate migrations on telescope:install | 85% | Idempotency | | JoshSalway/echo #1 | echo #475 | Fix WebSocket channel leak on React unmount | 85% | Resource cleanup | | JoshSalway/folio #1 | folio #148 | Fix route() helper positional parameters | 80% | Routing fix | | JoshSalway/pail #1 | pail | Fix crash on malformed JSON log lines | 90% | Error handling | | JoshSalway/pail #2 | pail | Show deprecation warnings with deprecation logging | 80% | Feature | | JoshSalway/passport #1 | passport #1894 | Fix session serialisation with JSON format | 80% | Serialisation fix | | JoshSalway/socialite #1 | socialite #754 | Fix PKCE session crash in stateless mode | 85% | Session/state handling | | JoshSalway/socialite #2 | socialite #740 | Make redirect config key optional | 90% | Config flexibility | | JoshSalway/pulse #1 | pulse #476 | Replace md5() with sha2() for MySQL 9.6 | 90% | Forward compat | | JoshSalway/scout #1 | scout | Use model primary key for database queries | 80% | Query correctness | | JoshSalway/serializable-closure #1 | serializable-closure | Fix crash with method-only attributes | 80% | Edge case | | JoshSalway/fortify #1 | fortify | Fix lowercase_usernames not respected on password reset | 85% | Consistency fix | | JoshSalway/jetstream #1 | jetstream | Fix hasTeamRole() TypeError when pivot role is null | 90% | Null guard | | JoshSalway/nightwatch #1 | nightwatch | Fix duplicate assignment, double Clock, incorrect uInt32 max | 85% | Multiple small bugs | | JoshSalway/nightwatch #8 | nightwatch | Remove unused Number class | 90% | Dead code | | JoshSalway/nightwatch #9 | nightwatch | Add NotificationFailed event support | 75% | Feature addition | | JoshSalway/nightwatch #10 | nightwatch | Add unit tests for utility and infrastructure classes | 70% | Test coverage | | JoshSalway/mcp #1 | mcp #138 | Prevent OAuth routes overriding existing routes | 85% | Route conflict | | JoshSalway/mcp #2 | mcp #143 | Render tool exceptions as MCP errors | 85% | Error handling |

Gist-only patches (original 25 from day 1)

These are the original patches from yesterday's post, all verified on both Windows and macOS with full test suites. Many have since been submitted as fork PRs above or are ready to submit upstream.

| Issue | Title | Confidence | Gist | Fork PR | |-------|-------|:----------:|------|---------| | wayfinder #128 | Replace DIRECTORY_SEPARATOR with / in TS imports | ~~95%~~ | Patch | Fixed upstream (repo restructured) | | installer #472 | proc_open with inherited stdio for Windows TTY | 80% | Patch | Fork #5 | | vs-code-extension #575 | Detect absolute paths before base_path() | 80% | Patch | Fork #1 | | prompts #191 | Regex newline counting for Windows PHP_EOL | 95% | Patch | Fork #3 | | octane #1034 | Respect --poll flag for FrankenPHP watcher | 85% | Patch | Fork #2 (closed) | | vite-plugin-wayfinder #10 | Pass Vite root as cwd, shell:true | 70% | Patch | Fork #1 | | cashier-stripe #1759 | Webhook race condition duplicate subscriptions | 85% | Patch | Fork #2 (closed) | | framework #58207 | OOM jobs retry infinitely with maxExceptions | 75% | Patch | Fork #16 | | framework #56395 | Pipeline memory leak -- two-line fix | 95% | Patch | Fork #17 | | reverb #344 | TypeError crash -- operator precedence bug | 90% | Patch | Fork #1 | | serializable-closure #126 | v2.0.9 regression breaks Bus::chain | 85% | Patch | Fork #2 | | horizon #1535 | Silent 60-second queue stalls -- add logging | 90% | Patch | Fork #6 | | cashier-stripe #1817 | swapAndInvoice free upgrade -- webhook reconciliation | 75% | Patch | Fork #1 (open) | | pulse #461 | Multi-server deadlocks -- atomic Redis lock | 80% | Patch | Fork #2 | | framework #57070 | Sub-minute scheduling skips at boundaries | 90% | Patch | Fork #18 | | reverb #273 | Presence channels wrong user list at scale | 65% | Patch | Fork #2 | | octane #1004 | Zero-downtime deployment with symlinks | 70% | Patch | Fork #5 | | framework #57262 | incrementEach() updates ALL rows -- data corruption | 90% | Patch | Fork #3 (closed) | | framework #58377 | SessionManager duplicate Redis connections | 95% | Patch | Fork #4 (open) | | wayfinder #161 | Dashed route names produce invalid TS identifiers | 75% | Patch | Fork #4 | | wayfinder #178,#159 | Inertia imports + parameter shadowing | ~~75%~~ | Patch | Fixed upstream (repo restructured) | | scout #957 | Timeout jobs block queue forever | 95% | Patch | Fork #2 | | framework #56652 | Query log memory leak in Octane workers | 85% | Patch | Fork #2 (open) |

Last thoughts

If any maintainers are reading this -- sorry again for the volume. I try to ensure every fix is documented with before/after test results and links back to the original issue.

If there are problems with any of these fixes or you'd prefer a different approach, I'm happy to adjust. The full details for every fix are in the master gist.

Previous post: 25 Laravel Bug Fixes -- Tested, Verified, Ready to Merge

19 Laravel Bug Fixes -- Tested, Verified, Ready to Merge

Josh Salway — Wed, 18 Mar 2026 00:00:00 GMT

Update (2026-03-19): This has grown to 91 PRs across 27 repos. See the Day 2 update for the full list with confidence ratings.

I found and fixed 19 bugs across the Laravel ecosystem -- 10 Windows-specific and 9 cross-platform. Every fix has been tested on Windows 11 Pro and independently verified on macOS (Darwin 25.3.0, PHP 8.4.19) with bug reproduction, concurrency testing, and full test suite runs.

~~I'm currently blocked from the Laravel GitHub organisation, so I can't submit PRs or comment on issues.~~

All patches and PRs are linked below and in the gist -- feel free to use them directly. I can't push these upstream because submitting too many at once gets you blocked, and the contribution guide states that AI-generated pull requests will be closed without review. These are 100% AI-generated using Claude Code -- every fix was found, written, and tested by AI on my machine.

Full details and patches: GitHub Gist

The Fixes

Cross-Platform (Production Critical)

laravel/cashier-stripe #1759 -- Webhook race condition creates duplicate subscriptions. When customer.subscription.created and customer.subscription.updated webhooks arrive simultaneously, both handlers insert a new row. Active data corruption in production. Fix catches UniqueConstraintViolationException and recovers gracefully. Verified with real concurrent processes on both SQLite and PostgreSQL -- race triggered 10/10 times, fix recovered every time. Patch

laravel/framework #58207 -- OOM jobs retry infinitely. When a job causes an out-of-memory kill, the exception counter never increments because the catch block never executes. Jobs with $maxExceptions retry forever. 31 comments. Fix uses optimistic increment -- counter goes up before fire(), down on success. Verified with real OOM kills (PHP exit code 255). Patch

laravel/framework #56395 -- Pipeline memory leak. Pipeline::then() retains references to job objects after completion, preventing garbage collection. Workers hold 254MB instead of 4MB after processing 50 jobs. Two-line fix. 22 comments. Patch

laravel/reverb #344 -- TypeError crash. Operator precedence bug in isWebSocketRequest() means any non-null Upgrade header is treated as a websocket request. Plus no guard when reverse proxies strip headers. 17 comments, users switching to Soketi. All 126 tests pass including Redis. Patch

laravel/serializable-closure #126 -- v2.0.9 regression breaks Bus::chain. Objects with __serialize skip closure wrapping entirely, causing serialization failures. Fix scopes the skip to only Closure-typed properties. 338 tests pass. Patch

laravel/cashier-stripe #1817 -- swapAndInvoice gives free upgrades. When payment fails during a plan swap, users end up on the expensive plan for free. Fix adds pendingIfPaymentFails() as the default. Patch

laravel/horizon #1535 -- Silent 60-second queue stalls. Memory-exceeded workers restart, die again, then cooldown for 60 seconds with zero logging. Impossible to diagnose. Fix adds logging at 3 critical points. 169 tests pass. Patch

laravel/pulse #461 -- Multi-server deadlocks. Concurrent pulse:work processes read the same Redis stream entries and deadlock on MySQL upserts. Fix adds atomic Redis lock around digest. Patch

laravel/framework #57070 -- Sub-minute scheduling skips. endOfMinute() mutates the Carbon instance used in the loop condition. Fix uses copy()->endOfMinute(). 68 scheduling tests pass. Patch

Windows-Specific

laravel/octane #1100 -- FrankenPHP crashes on Windows. POSIX signal constants don't exist. PR

laravel/wayfinder #128 -- Backslash import paths. DIRECTORY_SEPARATOR produces \ in TypeScript. Patch

laravel/sail #843 -- Testing database never created. Bash shebang fails in MySQL containers. PR

laravel/sail #850 -- Installation fails on Windows. Unrecognised OS. PR

laravel/installer #472 -- laravel new crashes with Boost. No TTY support. Patch

laravel/vs-code-extension #575 -- Symlinked packages break. Double path construction. Patch

laravel/prompts #191 -- Terminal rendering glitches. PHP_EOL newline miscounting. Patch

laravel/octane #1034 -- File watcher ignores --poll. FrankenPHP overrides parent watcher. PR

laravel/sail #815 -- Headed browser tests fail. No virtual display. PR

laravel/vite-plugin-wayfinder #10 -- Wayfinder fails in Vite. Working directory resolution. Patch

Verification

Every fix was tested on Windows 11 Pro 26200 and macOS Darwin 25.3.0 (PHP 8.4.19). Cross-platform fixes include:

Bug reproduction with before/after proof
Full test suite runs (2,500+ tests total across all repos)
Concurrency testing with pcntl_fork and barrier synchronisation
Real OOM kills (PHP memory limit exhaustion, exit code 255)
Memory leak measurement (WeakReference + memory profiling)
PostgreSQL and Redis integration testing via Docker

All patches, verification data, and test results are in the gist.

EDIT (2026-03-19): The count has grown from 19 to 25 fixes across 11 Laravel repos. Here's what was added:

New Cross-Platform Fixes

laravel/framework #57262 -- incrementEach() updates ALL rows in the table. DATA CORRUPTION -- calling $model->incrementEach() on an Eloquent model updates every row, not just that model. Multiple reports of near-production data loss. Fix adds explicit incrementEach()/decrementEach() methods to Eloquent Builder that call toBase() to apply scopes. All 195 builder tests pass. Patch

laravel/framework #58377 -- SessionManager creates duplicate Redis connections. Every request with Redis sessions opens 2 connections instead of 1 due to an unnecessary clone. Causes RedisException: Connection limit reached in strict environments. 12 comments. One-line fix -- remove the clone. All 93 session tests pass. Patch

laravel/reverb #273 -- Presence channels return wrong user list when scaling with Redis. Each Reverb instance maintains its own local member list. Presence events never propagated via Redis pub/sub to other instances. Completely breaks presence channels at scale. Fix routes member events through the Redis event dispatcher and adds a new PRESENCE_DATA metric type for cross-instance member gathering. 237 tests pass. Patch

laravel/octane #1004 -- No zero-downtime deployment. octane:reload doesn't work with symlink-based deployments (Deployer, Envoyer). 23 comments, 5-30s downtime per deploy. New ResolvesSymlinks trait detects symlinked directories and ensures all three server types (Swoole, RoadRunner, FrankenPHP) use the symlink path. clearstatcache(true) on reload. 180 tests pass. Patch

laravel/scout #957 -- Timeout jobs block queue forever. Scout's MakeSearchable jobs don't set failOnTimeout, so timed-out jobs silently hang in Horizon. One-line fix. All 211 Scout tests pass. Patch

New Windows Fixes

laravel/wayfinder #178, #161, #159 -- Three TypeScript generation bugs. #178: Generated .d.ts breaks Inertia type merging (missing import). #161: Dashed route names produce invalid TS identifiers. #159: Route action named "options" shadows the routeOptions parameter. Patch

Updated Fixes

Cashier #1817 (swapAndInvoice) was redesigned. The original pendingIfPaymentFails() approach was incompatible with Stripe's API (rejects tax_rates with pending_if_incomplete -- verified with real Stripe test key, 8 API errors). The new fix uses webhook reconciliation: a handleInvoicePaymentFailed() handler detects failed subscription update payments and syncs the local DB back to Stripe's actual state. All 44 feature tests pass with real Stripe API key. PR

Cashier #1759 (duplicate subscriptions) now also has a PR on my fork with the race condition fix verified against real Stripe API -- all 44 tests pass. PR

Current Totals

25 fixes across 11 repos (was 19)
7 PRs on forks: sail (3), octane (2), cashier-stripe (2)
18 gists with patches for repos I can't fork
All fixes in the master gist

FragHub.gg

Josh Salway — Sat, 07 Mar 2026 00:00:00 GMT

I launched fraghub.gg -- a PUBG stats and match replay tool.

Search any PUBG player by name across Steam, Xbox, or PlayStation and get their full stat breakdown: K/D ratio, win rate, average damage, headshot percentage, ranked rating, and weapon mastery data. Browse their recent match history and open any match to watch a full 2D replay.

The replay viewer renders actual match telemetry on the map -- player movement trails over the entire match, the blue zone shrinking in real time, red zone pulses, care package drop locations, and a live kill feed with timestamps. You can scrub to any point in the match.

Built with Laravel, React, and Three.js. Match data comes from the official PUBG Developer API.

Try it: fraghub.gg

Barcoder - A Free Barcode Scanner & Creator

Josh Salway — Wed, 18 Feb 2026 00:00:00 GMT

I built a free barcode scanner and creator. It's a PWA that lets you scan barcodes with your camera, upload a photo of a damaged barcode, or type in the digits manually to generate a scannable barcode on your phone screen.

I originally built it for situations where product barcodes are damaged, missing, or hard to scan at the register. Instead of manually typing long barcode numbers, you can save frequently-needed barcodes and pull them up instantly.

It supports 27+ barcode formats including EAN-13, UPC-A, EAN-8, Code 128, and QR codes. It works offline, is installable on your phone, and has built-in check digit validation.

Try it out: barcoder.joshsalway.com

The source code is on GitHub: github.com/JoshSalway/barcoder

Free Poker Timer

Josh Salway — Mon, 16 Feb 2026 00:00:00 GMT

I built a free poker timer for home games. No ads, no sign-ups, just open it and go.

Check it out: pokertimer.joshsalway.com

The source code is on GitHub: github.com/JoshSalway/FreePokerTimer

Why I Chose to Build My Own Apps Instead of Taking a Traditional Job (for now)

Josh Salway — Tue, 07 Jan 2025 00:00:00 GMT

Recently, a friend suggested that I should get a traditional full-time job at a big company, work on my side projects in my spare time, and play it safe. While their advice was well-meaning, after thinking it through, I realized that this path doesn't align with where I want to be right now.

Instead, I've decided to focus on building and launching my own apps. This choice is rooted in my years of experience as a Laravel developer and my desire to create something meaningful that's entirely mine.

The Importance of Building My Own Apps

For years, I've worked hard developing apps for other people. While that was valuable, I'm now ready to channel that energy into my own ideas. Building apps for myself isn't just about creating income. It's about mastering the skills required to build a successful business, which is a much bigger win in the long run.

Laravel plays a huge role in enabling this journey. Its creator, Taylor Otwell, famously designed Laravel with the philosophy of building a framework that could help solo developers succeed. Laravel's "batteries included" approach means it comes with powerful built-in features like authentication, routing, queues, and more, allowing me to focus on the big picture rather than getting bogged down in repetitive, low-level tasks.

For a solo developer like me, this philosophy resonates deeply. It empowers me to work efficiently and build ambitious projects on my own without relying on a team. It's one of the reasons I love Laravel and continue to use it as the backbone for my apps.

The Lessons From Failed Projects

This isn't my first time building personal projects. I've started and failed at several side projects in the past, and each one has taught me valuable lessons. For example, I recently decided to take one of my projects offline because I realized I didn't care about it anymore. While building it, I learned a lot about development, hosting, and launching apps. But in the end, it wasn't something I was passionate about, and it wasn't generating income.

As developers, it's completely normal to build many apps and example projects, including things that never get released. These projects are part of the learning process. They're opportunities to try new tools, test ideas, and gain experience, even if they don't lead to a finished product.

What I've learned is that starting and failing is part of the process. Much like exercising, it's not always about the end result. It's about the act of doing it and the growth that comes with it. Every failed project sharpens my skills and prepares me for the next one. In that sense, no project is truly a failure.

Build What You Care About

One of the most important lessons I've learned from working on my own projects is the importance of alignment. If you don't genuinely care about what you're building, it's hard to stay motivated, especially when you hit roadblocks. Building something you're passionate about makes it easier to push through the hard stuff, solve tricky problems, and see the project through to completion.

That alignment between what you want and what you're working on is what keeps the process enjoyable. If you care about your app, every task, no matter how challenging, feels purposeful, and the reward of seeing it live is so much greater.

The Importance of CI/CD Early On

Another lesson I've picked up recently is the value of setting up Continuous Integration and Continuous Deployment (CI/CD) early in the development lifecycle. I heard this advice in a YouTube video, and it really clicked with me.

Having a CI/CD pipeline in place ensures that as soon as your app is ready, you can deploy it with confidence. It streamlines the process and allows you to focus on refining and improving your app without worrying about the technicalities of going live. Early setup of CI/CD is one of those things that might take a bit of time initially, but it pays off massively when you're ready to launch.

Why Now Is the Right Time

I'm fortunate to have some savings and a casual job to support myself, giving me the flexibility to pursue this. While job opportunities are always out there, sometimes it's best to take a chance on your own ideas and see where they lead.

Of course, I'd love for one of my apps to make money, that's always the dream. But what's even more valuable is the education I'm gaining by doing this. Building apps teaches me not just technical skills, but also how to manage projects, market ideas, and solve real-world problems. Education and self-learning have always been important to me, and I believe focusing on personal growth is just as rewarding as financial success.

This is about investing in myself and gaining the skills to create opportunities in the future, whether they come through my own ventures or other career paths.

Open to Opportunities, Especially Contract Work

That's not to say I'm completely closed off to other opportunities. I really enjoy contract work as a developer. It allows me to stay sharp, work on exciting projects, and connect with other businesses while still leaving room for my personal pursuits.

If the right contract or even full-time role came along, something exciting and aligned with my goals, I'd absolutely consider it. But for now, my main focus is on my own projects and working casually or part-time in roles that suit me.

Check Out My Projects

If you're curious about what I'm working on, check out my Projects Page. I regularly update it with new ideas, apps in progress, and tools I've built. It's an evolving showcase of the work I'm passionate about, and I'm excited to share it with others.

What's Your Dream?

I want to close with an important question inspired by Simon Squibb, an entrepreneur who challenges people to think deeply about their purpose and whose book, What's Your Dream?: Find Your Passion. Love Your Work. Build a Richer Life. is set to release on February 16, 2025: What's your dream? What do you want to build or create in this world?

For me, my dream is clear: I love to create. The thrill of taking an idea from my head and turning it into something real, whether it's an app, a tool, or a solution to a problem, is what keeps me motivated. Building something that didn't exist before is deeply rewarding, not just because of the end result, but because of the process itself.

Simon Squibb emphasizes that when your work aligns with your passion, even the hard parts feel worthwhile. That's a lesson I've learned firsthand. When you care about what you're building, it's easier to tackle tough challenges, stay consistent, and see the project through to completion.

So, what's your dream? Whether it's launching a product, learning a new skill, or pursuing an entirely different path, the key is taking action. Start small, build consistently, and enjoy the process, because building something you care about is always worth it.

Why KPIs Work Best When People and Customers Come First

Josh Salway — Mon, 06 Jan 2025 00:00:00 GMT

Key Performance Indicators (KPIs) are essential in modern businesses. They provide measurable ways to track progress, guide decision-making, and improve efficiency. But there's often a critical element missing: people and customers are the most important metrics.

It might sound counterintuitive, but the truth is simple: if you take care of your employees and customers, the numbers will take care of themselves. Businesses like Trek Bicycle exemplify this philosophy, proving that prioritizing people leads to long-term success. Here's why a people-first approach to KPIs isn't just ideal, but essential.

1. People-First: The Secret to KPIs That Matter

Businesses are built on relationships, whether it's between a brand and its customers or a company and its employees. Yet, KPIs often focus narrowly on speed, cost, or output without considering the human element behind those numbers.

When I purchased my Trek bike, I was struck by something the staff told me: "We're a customer-service business that just happens to sell bikes." That philosophy wasn't just words. It was reflected in every interaction I had. Whether I needed help with an issue or simply wanted to praise their products, I was always treated with care and professionalism.

What Trek Gets Right: Their customer-first philosophy creates loyalty and satisfaction. Customers feel valued, encouraging repeat business and positive word-of-mouth.
The Key Lesson: Focus on making people happy, whether they're employees or customers, and the metrics will naturally improve.

2. KPIs Are Tools, Not Goals

KPIs are there to guide progress, not dictate it. The danger of overly rigid KPIs is that they can lead to short-term thinking and counterproductive behaviors, like rushing to meet speed targets at the expense of quality.

For instance, in a retail setting, a KPI might measure the number of orders packed per hour. While this emphasizes speed, it often overlooks other crucial factors like accuracy or customer satisfaction. Workers might rush to meet the target, leading to mispacked or damaged goods, a short-term win that creates long-term problems.

Trek approaches this differently. Their "Make the Call" handbook encourages employees to understand and resolve customer concerns thoroughly, even if it takes longer.

Why This Matters: A people-first approach ensures that KPIs like customer satisfaction and loyalty metrics stay high without pressuring employees to cut corners.
The Key Lesson: KPIs should reflect outcomes that matter to people, not just numbers on a spreadsheet.

3. The KPI Triangle: Speed, Quality, and Cost!

One of the biggest challenges in KPI design is balancing speed, quality, and cost. Businesses often try to maximize all three but quickly find it's rarely possible. You can optimize for two, but the third will inevitably suffer.

Speed and Quality: Achieving both usually requires higher costs, like investing in faster technology or more staff.
Quality and Cost: Maintaining high standards while minimizing expenses often slows operations due to limited resources.
Speed and Cost: Prioritizing efficiency at a low cost often compromises quality, leading to errors and dissatisfied customers.

Example: A delivery service might prioritize speed, offering same-day delivery, but neglect proper packaging, leading to damaged goods. While delivery times look great, customer complaints and returns skyrocket, a prime example of focusing on one metric at the expense of others.

The Key Lesson: Businesses must choose their priorities. KPIs should reflect those priorities while acknowledging trade-offs.

4. Technology: The Backbone of Success

In today's workplaces, technology drives nearly every aspect of operations. Whether it's tools for managing workflows, customer interactions, or inventory systems, the efficiency of these tools can make or break KPI performance.

What I've Learned: When technology is slow, buggy, or prone to crashing, inefficiencies ripple through the operation. Workers waste time on glitches, customers are left waiting, and KPIs suffer.
The Bigger Issue: Software teams are often the first to face budget cuts, but underinvesting in technology leads to long-term inefficiencies and frustrations for employees and customers alike.

A Better Way

Treat technology as a core investment, not an afterthought. Regular updates ensure systems meet the needs of both workers and customers.
Gather feedback from frontline employees to identify inefficiencies and prioritize improvements.

5. Happy Employees Drive Happy Customers

Employees who feel valued and supported naturally deliver better customer experiences. Yet, many KPIs focus solely on output, ignoring the well-being of the people doing the work.

Trek understands that employee satisfaction is just as important as customer satisfaction. Their supportive culture motivates employees to go above and beyond for customers.

What Companies Can Learn: Incorporate employee satisfaction into KPIs. Metrics like retention rates, engagement surveys, and team feedback provide insight into how well a company supports its staff.
The Key Lesson: Happy employees are more likely to create loyal customers.

6. Flexibility Is Key to Effective KPIs

Rigid KPIs fail in the face of real-world challenges. For instance, expecting the same productivity targets during a system outage or supply chain disruption ignores the reality of the situation.

Trek avoids this pitfall by focusing on outcomes rather than rigid metrics. Their priority is quality service and relationships, even if it means bending traditional measures of success.

What Businesses Can Do: Build flexibility into KPIs to account for challenges and shifting priorities. This fosters trust and empowers employees to make the best decisions for customers.
The Key Lesson: Adaptable KPIs keep teams focused on what matters, people and quality, without sacrificing long-term goals.

Final Thoughts: People and Customers Are the Real Metrics

KPIs are essential, but they should never overshadow the people they're meant to serve. Businesses like Trek Bicycle show that prioritizing employees and customers leads to metrics that improve organically.

By focusing on customer satisfaction, valuing employees, and investing in technology, companies can create environments where everyone thrives. The result? Happier customers, more engaged employees, and KPIs that reflect true success.

What do you think? Have you experienced workplaces where KPIs were designed with people and customers in mind? I'd love to hear your insights!

Disclaimer: This article reflects my personal opinions and experiences and is not intended to critique any specific company or organization.

How to Add a Dark Mode Switcher to Your Alpine.js and Tailwind CSS App

Josh Salway — Mon, 23 Dec 2024 00:00:00 GMT

Enhance your application's user experience by seamlessly integrating a dark mode feature using Alpine.js and Tailwind CSS.

Demo GIF

Why Implement Dark Mode

Incorporating a dark mode into your application offers numerous benefits that enhance user experience and accessibility:

User Preference

Aesthetic Appeal: Many users favor dark mode for its sleek and modern look.
Reduced Eye Strain: Especially in low-light settings, dark mode minimizes eye fatigue, making prolonged usage more comfortable.

Battery Efficiency

Energy Savings: On OLED and AMOLED screens, dark mode can significantly extend battery life by decreasing the number of bright pixels displayed.

Accessibility

Enhanced Readability: Offering both light and dark themes caters to users with visual impairments, ensuring better contrast and readability.
Inclusive Design: Providing multiple theme options makes your application more accessible to a diverse user base.

Requirements

Before diving into the implementation, ensure you have the following set up:

Tailwind CSS: Initialize Tailwind CSS in your project by following the official installation guide.
Alpine.js: Integrate Alpine.js into your project by following the official installation instructions. You can include it via CDN or install it using npm.

Step-by-Step Implementation

1. Tailwind CSS Configuration

To enable dark mode using the 'class' strategy, you'll need to update your tailwind.config.js file. This approach allows you to manually toggle dark mode by adding or removing the dark class on a parent element, typically the tag.

Update tailwind.config.js Open tailwind.config.js: Locate and open your project's tailwind.config.js file.

Configure Dark Mode: Set the darkMode property to 'class'. This configuration enables manual control over dark mode by toggling the dark class.

// tailwind.config.js
export default {
  darkMode: 'class', // Enables manual dark mode toggling
  // ...
}

Explanation:

darkMode: 'class': This setting tells Tailwind CSS to apply dark mode styles when the dark class is present on a parent element.

2. Add the Dark Class to Your HTML Template

To activate dark mode by default or based on user preference, add the dark class to the element in your HTML template.

<!doctype html>
<html lang="en" class="dark">
  <head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Your Site Title</title>
    <!-- Your other head elements -->
  </head>
  <body class="bg-white dark:bg-gray-900 dark:text-gray-300 font-sans leading-normal text-gray-800 px-4 sm:px-10">
    <!-- Your site content -->
  </body>
</html>

Explanation:

class="dark" on <html>: Adding the dark class to the <html> tag activates dark mode styles throughout your application.
Tailwind Utility Classes:
- bg-white dark:bg-gray-900: Sets a white background in light mode and a dark gray background in dark mode.
- dark:text-gray-300 text-gray-800: Sets dark gray text in dark mode and darker gray text in light mode.

Note: Initially adding the dark class sets the default theme to dark mode. To allow users to toggle between light and dark modes, you'll manage this class dynamically using JavaScript or Alpine.js in subsequent steps.

3. HTML Template Modifications

To ensure that your application respects the user's theme preference from the moment the page loads, you'll need to integrate an inline script within your HTML. This script is crucial for applying the user's selected theme immediately, thereby preventing any unwanted flashes of incorrect styling (FOUC).

<!doctype html>
<html lang="en" class="dark">
  <head>

    <!-- Inline Script to Apply Theme -->
    <script>
      (function() {
        const theme = localStorage.getItem('theme') || 'system';
        const isSystemDark = window.matchMedia('(prefers-color-scheme: dark)').matches;

        // Apply the dark class to prevent FOUC
        if (theme === 'dark' || (theme === 'system' && isSystemDark)) {
          document.documentElement.classList.add('dark');
        } else {
          document.documentElement.classList.remove('dark');
        }

        // Store the initial system preference
        localStorage.setItem('isSystemDark', isSystemDark);

        // Listen for system theme changes
        window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', (event) => {
          localStorage.setItem('isSystemDark', event.matches);
          if (theme === 'system') {
            document.documentElement.classList.toggle('dark', event.matches);
          }
        });
      })();
    </script>

    <!-- Your compiled CSS & JS file goes here -->
    
    <!-- Alpine JS CDN goes here -->
    <script src="//unpkg.com/alpinejs" defer></script>
  </head>
  <body>
	<!-- Content goes here -->
  </body>
</html>

What This Code Does

Retrieve User Preference:
- Functionality: The script first checks localStorage for a saved theme preference ('light', 'dark', or 'system').
- Fallback: If no preference is found, it defaults to 'system', meaning the application will follow the system's current theme setting.
Determine System Theme:
- Functionality: Utilizes the window.matchMedia API to detect if the user's operating system prefers a dark color scheme.
- Result: Stores this preference in the isSystemDark variable as a boolean (true if the system is in dark mode, false otherwise).
Apply Dark Mode Class:
- Functionality: Based on the retrieved theme and system preference, the script adds or removes the dark class on the element.
- Purpose: Ensures that the correct theme styles are applied before the CSS fully loads, effectively preventing a Flash of Unstyled Content (FOUC).
Store System Theme Status:
- Functionality: Saves the system's dark mode status (isSystemDark) in localStorage.
- Purpose: Allows the application to remember the system preference across browser sessions and page reloads, ensuring consistency in theme application.
Listen for System Changes:
- Functionality: Sets up an event listener using window.matchMedia to detect any changes in the system's color scheme preference.
- Action on Change: If the user has selected 'system' mode, the script automatically updates the application's theme by toggling the dark class on the element based on the new system preference.
- Purpose: Keeps the application's theme in sync with the system's theme settings in real-time, enhancing user experience without requiring manual intervention.

4. Add the Darkmode Drop Down Selector to Your Page

The following code snippet adds a dropdown selector that allows users to toggle between Light Mode, Dark Mode, and System Mode. This switcher uses Alpine.js for state management and interactivity.

<div class="relative"
     x-data="{
        dropdownOpen: false,
        theme: localStorage.getItem('theme') || 'system',
        isSystemDark: localStorage.getItem('isSystemDark') === 'true',
        init() {
            // Watch for system dark mode changes
            const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
            this.isSystemDark = mediaQuery.matches;
            mediaQuery.addEventListener('change', (event) => {
                this.isSystemDark = event.matches;
                if (this.theme === 'system') {
                    this.updateTheme();
                }
            });

            // Set the initial theme
            this.updateTheme();
        },
        updateTheme() {
            const isDark = this.theme === 'dark' || (this.theme === 'system' && this.isSystemDark);
            document.documentElement.classList.toggle('dark', isDark);
        },
        setTheme(newTheme) {
            this.theme = newTheme;
            localStorage.setItem('theme', newTheme);
            this.updateTheme();
            this.dropdownOpen = false; // Close dropdown after selection
        },
        currentIcon() {
            if (this.theme === 'light') return 'light';
            if (this.theme === 'dark') return 'dark';
            return 'system'; // For 'system', decide based on system preference
        },
        systemIconColor() {
            return this.isSystemDark ? 'dark' : 'light';
        }
    }"
     @click.away="dropdownOpen = false"
>
    <!-- Trigger Button -->
    <button
            @click="dropdownOpen = !dropdownOpen"
            class="p-1 border dark:border-gray-700 rounded-full hover:bg-gray-50 dark:hover:bg-gray-800 text-gray-700 dark:text-gray-300">
        <!-- Dynamic Icons -->
        <template x-if="currentIcon() === 'light'">
            <svg xmlns="http://www.w3.org/2000/svg" class="w-6 h-6 text-yellow-500" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor">
                <path stroke-linecap="round" stroke-linejoin="round" d="M12 3v2.25m6.364.386l-1.591 1.591M21 12h-2.25m-.386 6.364l-1.591-1.591M12 18.75V21m-4.773-4.227l-1.591 1.591M5.25 12H3m4.227-4.773L5.636 5.636M15.75 12a3.75 3.75 0 11-7.5 0 3.75 3.75 0 017.5 0z" />
            </svg>
        </template>
        <template x-if="currentIcon() === 'dark'">
            <svg xmlns="http://www.w3.org/2000/svg" class="w-6 h-6 text-blue-500" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor">
                <path stroke-linecap="round" stroke-linejoin="round" d="M21.752 15.002A9.718 9.718 0 0118 15.75c-5.385 0-9.75-4.365-9.75-9.75 0-1.33.266-2.597.748-3.752A9.753 9.753 0 003 11.25C3 16.635 7.365 21 12.75 21a9.753 9.753 0 009.002-5.998z" />
            </svg>
        </template>
        <template x-if="currentIcon() === 'system'">
            <svg xmlns="http://www.w3.org/2000/svg" :class="systemIconColor() === 'dark' ? 'text-gray-300' : 'text-gray-400'" class="w-6 h-6" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor">
                <path :d="systemIconColor() === 'dark' ? 'M21.752 15.002A9.718 9.718 0 0118 15.75c-5.385 0-9.75-4.365-9.75-9.75 0-1.33.266-2.597.748-3.752A9.753 9.753 0 003 11.25C3 16.635 7.365 21 12.75 21a9.753 9.753 0 009.002-5.998z' : 'M12 3v2.25m6.364.386l-1.591 1.591M21 12h-2.25m-.386 6.364l-1.591-1.591M12 18.75V21m-4.773-4.227l-1.591 1.591M5.25 12H3m4.227-4.773L5.636 5.636M15.75 12a3.75 3.75 0 11-7.5 0 3.75 3.75 0 017.5 0z'" />
            </svg>
        </template>
    </button>

    <!-- Dropdown Content -->
    <div
            x-show="dropdownOpen"
            x-cloak
            class="absolute origin-top-right right-0 mt-2 py-2 w-48 bg-white dark:bg-gray-800 rounded-md shadow-lg z-10">
        <!-- Light Mode Button -->
        <button
                class="w-full px-4 py-2 text-left text-sm text-gray-700 hover:bg-gray-100 dark:text-gray-300 dark:hover:bg-gray-700 flex items-center gap-2"
                @click="setTheme('light')">
            <!-- Light Mode Icon -->
            <svg xmlns="http://www.w3.org/2000/svg" class="w-5 h-5" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor">
                <path stroke-linecap="round" stroke-linejoin="round" d="M12 3v2.25m6.364.386l-1.591 1.591M21 12h-2.25m-.386 6.364l-1.591-1.591M12 18.75V21m-4.773-4.227l-1.591 1.591M5.25 12H3m4.227-4.773L5.636 5.636M15.75 12a3.75 3.75 0 11-7.5 0 3.75 3.75 0 017.5 0z" />
            </svg>
            Light Mode
        </button>

        <!-- Dark Mode Button -->
        <button
                class="w-full px-4 py-2 text-left text-sm text-gray-700 hover:bg-gray-100 dark:text-gray-300 dark:hover:bg-gray-700 flex items-center gap-2"
                @click="setTheme('dark')">
            <!-- Dark Mode Icon -->
            <svg xmlns="http://www.w3.org/2000/svg" class="w-5 h-5" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor">
                <path stroke-linecap="round" stroke-linejoin="round" d="M21.752 15.002A9.718 9.718 0 0118 15.75c-5.385 0-9.75-4.365-9.75-9.75 0-1.33.266-2.597.748-3.752A9.753 9.753 0 003 11.25C3 16.635 7.365 21 12.75 21a9.753 9.753 0 009.002-5.998z" />
            </svg>
            Dark Mode
        </button>

        <!-- System Mode Button -->
        <button
                class="w-full px-4 py-2 text-left text-sm text-gray-700 hover:bg-gray-100 dark:text-gray-300 dark:hover:bg-gray-700 flex items-center gap-2"
                @click="setTheme('system')">
            <!-- System Mode Icon -->
            <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor" class="w-5 h-5">
                <path stroke-linecap="round" stroke-linejoin="round" d="M9 17.25v1.007a3 3 0 01-.879 2.122L7.5 21h9l-.621-.621A3 3 0 0115 18.257V17.25m6-12V15a2.25 2.25 0 01-2.25 2.25H5.25A2.25 2.25 0 013 15V5.25m18 0A2.25 2.25 0 0018.75 3H5.25A2.25 2.25 0 003 5.25m18 0V12a2.25 2.25 0 01-2.25 2.25H5.25A2.25 2.25 0 013 12V5.25"></path>
            </svg>
            System Mode
        </button>
    </div>
</div>

Overview of the Dark Mode Dropdown Selector

The following code implements a dark mode switcher using Alpine.js and Tailwind CSS. This switcher allows users to toggle between Light Mode, Dark Mode, and System Mode, providing a seamless and user-friendly experience. Here's a breakdown of what the code does and why each part is essential.

What It Implements

State Management

Alpine.js Component:

Purpose: Manages the state of the theme (light, dark, system) and controls whether the dropdown menu is open (dropdownOpen).
Functionality: Utilizes reactive data properties to ensure that changes in the theme state automatically reflect in the UI.

Reactive Data:

theme: Tracks the current theme preference, retrieved from localStorage or defaults to 'system'.
isSystemDark: Determines if the system's theme preference is dark, based on localStorage and media queries.
dropdownOpen: Controls the visibility of the dropdown menu for theme selection.

Persistent Preferences:

localStorage:
- Functionality: Stores the user's theme preference (theme) and the system's dark mode status (isSystemDark).
- Benefit: Ensures that the user's selection persists across browser sessions and page reloads, providing a consistent experience.

Dynamic Icons

Visual Feedback:
- Icons: The switcher displays different icons (sun for light mode, moon for dark mode, and a neutral system icon) based on the current theme selection.
- Color Highlights: Light and dark modes feature color highlights (yellow for light, blue for dark) to indicate active selection. System mode displays a neutral icon without highlights, signaling that the theme is controlled by system settings.

Dropdown Menu

User Control:
- Options: Provides clear options for users to select their preferred theme mode: Light, Dark, or System.
- Accessibility: Designed to be intuitive and accessible, ensuring that all users can easily navigate and select their desired theme.

Default to System Mode

System Integration:
- Default Setting: The switcher defaults to the system's theme preference ('system'), aligning the application's appearance with the user's device settings.
Dynamic Adaptation:
- Real-Time Updates: If the system's theme changes and the user is in system mode, the application automatically updates the theme without requiring any additional user action.

Explanation of Alpine.js Directives and Methods

To fully understand how Alpine.js manages the dark mode functionality, let's break down the key directives and methods used in the dropdown switcher component.

x-data: Initializes the component's reactive state, including dropdownOpen, theme, and isSystemDark.
x-init="init": Calls the init method when the component is initialized, setting up initial theme preferences and event listeners.
@click.away="dropdownOpen = false": Closes the dropdown when a click occurs outside the component.

Methods:

init(): Sets up media query listeners to detect system theme changes and applies the initial theme.
updateTheme(): Toggles the dark class on the element based on the current theme and system preference.
setTheme(newTheme): Updates the theme, stores the preference in localStorage, and closes the dropdown.
currentIcon(): Determines which icon to display based on the current theme.
systemIconColor(): Sets the color of the system icon based on the system's theme preference.

Visual Flow

Initial Load

Theme Initialization:
- Check localStorage: On page load, the component checks localStorage for any saved theme preference.
- Default to System: If no preference is found, it defaults to 'system', adopting the system's current theme.
Apply Theme:
- Toggle dark Class: Based on the determined theme, the dark class is added or removed from the element to apply the appropriate styles, preventing any Flash of Unstyled Content (FOUC).

User Interaction

Toggle Dropdown:
- Button Click: When the user clicks the trigger button, the dropdown menu toggles open or closed, allowing access to theme selection options.
Select Theme:
- Choose Mode: Selecting a mode ('light', 'dark', or 'system') updates the theme state, saves the preference to localStorage, and closes the dropdown menu.
Icon Update:
- Dynamic Icons: The switcher icon updates to reflect the selected theme, providing immediate visual feedback to the user.

System Theme Changes

Listen to Changes:
- Media Query Listener: The component listens for changes in the system's color scheme using the window.matchMedia API.
Automatic Update:
- System Mode Active: If the user is in 'system' mode and the system's theme changes, the application automatically updates the theme to match the new system preference.

5. Test Theme Toggling

Use the dark mode switcher to toggle between light, dark, and system modes.
Refresh the page to verify that the selected theme persists.
Switch your system's theme settings and ensure the application responds accordingly when in system mode.
Resize your browser or test on different devices to ensure the dark mode feature works consistently across various screen sizes.
Reload the page multiple times to ensure that the inline script effectively prevents any flash of the wrong theme (FOUC).
Check Styling Consistency: Browse through various sections to ensure consistent styling and design for both light mode and dark mode.

Conclusion

Implementing a dark mode selector in your Alpine.js and Tailwind CSS application not only modernizes your user interface but also caters to user preferences for accessibility and aesthetics. By following this guide, you've integrated a responsive and persistent dark mode feature that enhances the overall user experience.

Next Steps:

Advanced Customizations: Explore adding smooth transitions between themes for a more polished effect.
Custom Selection Styles: Enhance user experience by customizing text selection styles using CSS pseudo-elements like ::selection.
User Preferences Panel: Consider creating a dedicated settings page where users can manage their theme preferences alongside other personalized settings.
Accessibility Audits: Regularly perform accessibility audits to ensure that both light and dark modes meet accessibility standards.

Additional Resources

Feel free to share your thoughts or ask questions. Happy coding!

Using Laravel Enums in React with Inertia.js: A Modern Update

Josh Salway — Fri, 20 Dec 2024 00:00:00 GMT

When building modern web applications, ensuring consistent data structures between your backend and frontend is essential. In a previous post, I demonstrated how Laravel constants could be used to share data seamlessly with React through Inertia.js. However, with the introduction of PHP 8.1 Enums (further enhanced in PHP 8.3), I've refined my approach to fully leverage this powerful feature.

Enums offer type safety, cleaner syntax, and encapsulated behavior that surpasses the simplicity of constants. In this updated post, I'll walk you through the benefits of using enums, how to implement them in Laravel, and why they're a better alternative to constants for most use cases.

Why Share Data Between Laravel and React?

Sharing data like dropdown options, validation rules, and configuration values between the backend and frontend ensures:

Consistency: Both layers use the same source of truth, reducing discrepancies.
Maintainability: Updates to shared data propagate seamlessly across the application.
Developer Productivity: Eliminates redundant code and reduces errors.

Traditionally, constants were the go-to solution for this, but enums now provide an improved alternative.

What Are Enums and How Are They Different from Constants?

Constants

Constants are static values defined in a class or file. They're simple, lightweight, and great for defining unchanging data. For example:

class Platform
{
    public const PLATFORMS = [
        'steam' => 'Steam',
        'psn' => 'PlayStation Network',
        'xbox' => 'Xbox',
        'kakao' => 'Kakao',
        'stadia' => 'Stadia',
    ];
}

Limitations:

No type safety: You need custom validation to ensure only valid keys are used. Static behavior: You can't add methods or encapsulate related logic.

Enums:

Enums are a newer feature in PHP that represent a finite set of values with built-in type safety and encapsulated logic. Example:

enum PlatformEnum: string
{
    case Steam = 'steam';
    case PlayStationNetwork = 'psn';
    case Xbox = 'xbox';
    case Kakao = 'kakao';
    case Stadia = 'stadia';
}

Advantages:

Type Safety: Only defined enum cases are allowed. Encapsulated Behavior: Enums can include methods for transformations or additional data. Cleaner Code: Eliminates boilerplate and reduces the risk of errors.

Why I Switched to Enums

Here are the key reasons I moved from constants to enums:

Type Safety: With enums, you can ensure only valid values are used throughout your application:

$request->validate([
    'platform' => 'required|in:' . implode(',', PlatformEnum::values()),
]);

This reduces the risk of errors caused by typos or outdated constants.

Centralized Behavior: Enums allow you to group related logic in one place. For example, you can define dropdown options directly in the enum:

public static function options(): array
{
    return array_map(
        fn($case) => ['value' => $case->value, 'label' => self::labels()[$case->value]],
        self::cases()
    );
}

Better Validation: With enums, validation is more robust and concise, as enum values are inherently valid.

Future-Proofing: Adding new platforms or modifying behavior is easier with enums. Constants often require updating multiple locations.

Cleaner Syntax: Enums reduce boilerplate code by combining data and behavior in a single structure.

Implementing Laravel Enums

Here's how I updated my application to use enums instead of constants:

Step 1: Define the Enum

Create the PlatformEnum under app/Enums:

<?php

namespace App\Enums;

enum PlatformEnum: string
{
    case Steam = 'steam';
    case PlayStationNetwork = 'psn';
    case Xbox = 'xbox';
    case Kakao = 'kakao';
    case Stadia = 'stadia';

    public static function labels(): array
    {
        return [
            self::Steam->value => 'Steam',
            self::PlayStationNetwork->value => 'PlayStation Network',
            self::Xbox->value => 'Xbox',
            self::Kakao->value => 'Kakao',
            self::Stadia->value => 'Stadia',
        ];
    }

    public static function options(): array
    {
        return array_map(
            fn($case) => ['value' => $case->value, 'label' => self::labels()[$case->value]],
            self::cases()
        );
    }

    public static function values(): array
    {
        return array_map(fn($case) => $case->value, self::cases());
    }
}

Step 2: Share Data with React Using Inertia

In your web.php file, pass the enum data to your React component:

use App\Enums\PlatformEnum;
use Illuminate\Support\Facades\Route;
use Inertia\Inertia;

Route::get('/', function () {
    return Inertia::render('Home', [
        'platforms' => PlatformEnum::options(),
    ]);
});

Step 3: Use Enums in React

Access the platforms prop in your React component and generate the dropdown options:

const { platforms } = usePage().props;

<select>
    {platforms.map(({ value, label }) => (
        <option key={value} value={value}>
            {label}
        </option>
    ))}
</select>

Step 4: Validation Made Easy

Enums simplify validation by providing a definitive list of valid values:

$request->validate([
    'platform' => 'required|in:' . implode(',', PlatformEnum::values()),
]);

When to Use Constants Instead

While enums are ideal for structured, finite sets of values, constants still have their place:

For Static Data: If the values won't change and don't require additional behavior.
For Simplicity: In cases where you don't need the added functionality of enums.
For Backward Compatibility: If your project needs to support PHP versions before 8.1.

Conclusion

By switching from constants to enums, I've made my application:

More Type-Safe: Reducing errors caused by invalid data. Easier to Maintain: Centralizing logic and behavior within enums.
Cleaner: Streamlining validation and frontend integration.

If you're using PHP 8.1 or later, enums are a fantastic way to modernize your codebase. If you're stuck on older versions, constants remain a reliable option. This transition reflects my journey as a developer and my commitment to improving both my code and my learning process.

Let me know your thoughts or share your experience with enums!

Using Laravel Constants in React with Inertia.js

Josh Salway — Thu, 19 Dec 2024 00:00:00 GMT

Consider Reading the Newer Post

This post covers using Laravel constants with React through Inertia.js effectively. However, we've now updated our approach to leverage PHP Enums for greater type safety, maintainability, and cleaner code. If you're looking for a modern alternative, check out the newer blog post that explores these enhancements in depth.

There are many ways to share data between your Laravel backend and your JavaScript frontend. Today, we'll focus on one particularly powerful method: sharing constants between Laravel and JavaScript using Inertia.js. This approach is especially useful for managing dropdowns, form options, or validation rules, ensuring consistency and reducing repetition across your application.

By centralizing constants in Laravel, you create a single source of truth that can be used throughout your backend and frontend. In this post, we'll walk through a practical example of defining platform constants in Laravel and using them seamlessly in a React component.

Why Use Constants?

Constants are essential for maintaining consistency, reducing errors, and improving maintainability. Defining them in Laravel allows you to:

Share Consistent Data Structures: Share the same data structure between your backend and frontend seamlessly.
Avoid Duplication: Reduce redundancy and ensure updates propagate across the application effortlessly.
Simplify Validation and Forms: Make validation rules and dropdown creation in your forms straightforward and error-free.

Step 1: Define the Constants in Laravel

Create a Platform class under app/Constants:

<?php

namespace App\Constants;

class Platform
{
    public const PLATFORMS = [
        'steam' => 'Steam',
        'psn' => 'PlayStation Network',
        'xbox' => 'Xbox',
        'kakao' => 'Kakao',
        'stadia' => 'Stadia',
    ];

    public static function getPlatforms(): array
    {
        // Transform into a key-value array suitable for frontend use
        return collect(self::PLATFORMS)
            ->map(function ($label, $key) {
                return [
                    'value' => $key,
                    'label' => $label,
                ];
            })
            ->values()
            ->toArray();
    }
}

How It Works

In this example, the Platform class defines a centralized list of platforms and formats them.

Using Laravel Collections to Format the Data

The getPlatforms() method in the Platform class leverages Laravel Collections to format the PLATFORMS data into a reusable structure. Let's break down how this works:

Wrap the Data in a Collection

The collect() function takes the PLATFORMS constant and wraps it in a Laravel collection. This allows for easy manipulation of the data.

collect(self::PLATFORMS)

Transform the Data

The map() method iterates over each platform key-value pair and transforms it into an array with the following structure:

value: The platform's key (e.g., steam, psn). label: The platform's human-readable name (e.g., Steam, PlayStation Network).

->map(function ($label, $key) {
    return [
        'value' => $key,
        'label' => $label,
    ];
})

Flatten the Structure

The values() method resets the array keys to ensure a clean, sequentially indexed array.

->values()

Convert to Plain Array

Finally, the toArray() method converts the collection into a plain PHP array, ready to be passed to the frontend.

->toArray();

What getPlatforms() Produces...

The final output of getPlatforms() is a structured array like this:

[
    ['value' => 'steam', 'label' => 'Steam'],
    ['value' => 'psn', 'label' => 'PlayStation Network'],
    ['value' => 'xbox', 'label' => 'Xbox'],
    ['value' => 'kakao', 'label' => 'Kakao'],
    ['value' => 'stadia', 'label' => 'Stadia'],
]

Step 2: Pass the Constants to the Frontend Using Inertia

In your web.php file, pass the platforms to the React component:

use App\Constants\Platform;
use Illuminate\Support\Facades\Route;
use Inertia\Inertia;

Route::get('/', function () {
    return Inertia::render('Home', [
        'platforms' => Platform::getPlatforms(),
    ]);
})->name('home');

Step 3: Use the Constants in Your React Component

In this step, we make use of the usePage hook provided by Inertia.js to access the constants passed from Laravel. The usePage hook is a powerful utility that allows you to directly access the page's props in your React component. These props are passed down from your Laravel backend via Inertia when rendering the page.

For more details, check out the official documentation on shared data with Inertia.

Here's how usePage is useful in this scenario:

• Seamless Data Sharing: The usePage hook enables seamless sharing of data between the backend and frontend without the need for additional API calls. In our case, the platforms constant is passed as a prop from Laravel, and we access it directly in the React component using usePage. • Centralized State Management: Since usePage provides access to all props sent with the current Inertia response, it serves as a centralized way to manage and access state or configuration data required for a specific page. • Dynamic and Flexible: With usePage, any data passed from Laravel, such as the platforms list, is dynamically available in the React component. This flexibility ensures that updates to the backend logic (e.g., enabling/disabling platforms) are automatically reflected in the frontend.

import React from "react";
import { Head, useForm, usePage } from "@inertiajs/react";

export default function Home() {
    // Access platforms from the page props
    const { platforms } = usePage().props;

    // Form state using Inertia's useForm hook
    const { data, setData, post, processing, errors } = useForm({
        username: "", // Input for the username
        platform: platforms?.[0]?.value || "steam", // Default to the first platform
    });

    // Handle form submission
    const handleSubmit = (e) => {
        e.preventDefault();
        post(route("search"));
    };

    return (
        <>
            <Head title="Platform Selector" />
            <div className="min-h-screen bg-gray-100 flex items-center justify-center">
                <div className="w-full max-w-md bg-white shadow rounded p-6">
                    <h1 className="text-2xl font-bold mb-4">Select Your Platform</h1>
                    <form onSubmit={handleSubmit}>
                        {/* Platform Dropdown */}
                        <select
                            className="w-full p-2 border border-gray-300 rounded mb-4"
                            value={data.platform}
                            onChange={(e) => setData("platform", e.target.value)}
                        >
                            {platforms.map((platform) => (
                                <option key={platform.value} value={platform.value}>
                                    {platform.label}
                                </option>
                            ))}
                        </select>
                        {errors.platform && (
                            <div className="text-red-500 text-sm">{errors.platform}</div>
                        )}

                        {/* Username Input */}
                        <input
                            type="text"
                            placeholder="Enter Username"
                            className="w-full p-2 border border-gray-300 rounded mb-4"
                            value={data.username}
                            onChange={(e) => setData("username", e.target.value)}
                        />
                        {errors.username && (
                            <div className="text-red-500 text-sm">{errors.username}</div>
                        )}

                        {/* Submit Button */}
                        <button
                            type="submit"
                            className="w-full bg-blue-500 text-white p-2 rounded"
                            disabled={processing}
                        >
                            {processing ? "Submitting..." : "Submit"}
                        </button>
                    </form>
                </div>
            </div>
        </>
    );
}

Step 4: Reuse Constants Anywhere

Want to use these platforms elsewhere, like in validation? The Platform constant is ready to go:

use App\Constants\Platform;
use Illuminate\Http\Request;

Route::post('/search', function (Request $request) {
    $request->validate([
        'username' => 'required|string|max:255',
        'platform' => 'required|in:' . implode(',', array_keys(Platform::PLATFORMS)),
    ]);

    // Handle the search logic here
    return response()->json(['message' => 'Search successful']);
})->name('search');

Conclusion

By centralizing your constants in Laravel and using Inertia.js, you can easily share data between your backend and frontend:

Write Once: Define your constants in Laravel.
Reuse Everywhere: Use them in React, validation, or other backend logic.
Keep it Simple: Laravel and Inertia make the data flow seamless.

This approach ensures consistency and makes your codebase easier to maintain. Happy coding!

Josh Salway

Improving Queue Safety in Laravel

How I found these

What likely caused my billing incidents

What was a skill issue

What wasn't a skill issue

Whose fault is it?

Lambda is for short bursts, not long-running work

Do we actually need seatbelts or guardrails?

Recommendations you can do today

On WithoutOverlapping middleware

On ShouldBeUnique jobs

Prune failed jobs

On external HTTP calls inside jobs

Hard limits

A base job class

The Findings

Critical: Unbounded retries and permanent resource locks

1. maxExceptions counter only increments inside the catch block

2. Default backoff is 0 seconds

3. WithoutOverlapping middleware defaults to an infinite lock

4. $tries defaults to null (unlimited) in job payload

5. Race condition in maxExceptions counter initialization

6. handleJobException releases when failure checks are bypassed

Important: Unsafe defaults and resource exhaustion risks

7. Redis migrationBatchSize defaults to unlimited

8. ThrottlesExceptions retryAfterMinutes defaults to 0

9. RateLimited middleware release loop

10. Database queue reserved-but-expired can cause duplicate execution

11. retryUntil can override maxTries

12. Pipeline memory retention between jobs

Improvement: Edge cases and documentation gaps

13. Reserved job migration ignores attempt count

14. No timeout enforcement on Windows

What the community found

Worker enters infinite silent loop on non-database exceptions

Batch deadlocks under high concurrency

Batch never finishes when jobs fail

ShouldBeUnique lock not released

Failed jobs table causes OOM when retrying

Chain jobs silently terminate on queue restart

Timed-out worker kill leaks resources

No backpressure on dispatch

Failed job providers crash on corrupted payload

Current status

What the docs and support could improve

Documentation

Support

Disclaimer

Why Your Laravel Jobs Might Retry Forever After an OOM

The Bug

The Evidence

End-to-End Reproduction

Stock Laravel 13.4.0

With Fix Applied

The Fix

A Note on Responsibility

Current Status

Reproducibility

Rebuilding joshsalway.com: From Statamic to Astro

Why the rebuild

The new stack

What ships zero JavaScript

View Transitions

New features

Command palette search (Ctrl+K)

Article metadata

Reading progress bar

Table of contents

Code copy button

Previous/next article navigation

RSS feed

Sitemap

JSON-LD structured data

Dynamic text selection colour

Custom 404 page

Short links

Projects page redesign

Animated logo

Clickable tags