DEV Community: UCodeSoft

Caching in Laravel: What Actually Holds Up Once Real Traffic Hits It

UCodeSoft — Thu, 06 Aug 2026 17:43:27 +0000

"Just add Redis" solves the easy part of caching, and it solves it fast. Wrap a query in Cache::remember(), watch response times drop, ship it. The problem is that's maybe 80% of the work, and the remaining 20%, stale data, stampedes, invalidation bugs that only show up under real concurrency, ends up eating more engineering time than the original slow query ever cost.

We've shipped caching layers that held up fine in staging and fell over in production more than once, and every time, the cause was one of a small handful of patterns repeating itself. Here's what we've actually learned, the parts that bite.

A few terms first

Cache-aside, the default pattern most Laravel apps should reach for first. Check the cache, on a miss read from the database, and populate the cache. Cache::remember() implements this in one call.

Write-through, writes go to the cache and the database at the same time, synchronously. Reads stay fresh, writes get a little slower.

Cache stampede, what happens when a popular key expires, and a large number of requests hit the miss at the same moment. Without protection, all of them fall through to the database at once.

TTL, how long a cached value lives before it's considered stale. Simple to reason about, but it's a guess about how long data stays close enough to correct.

Tagged invalidation, grouping related cache entries under a shared label so you can clear all of them in one call. Only works on Redis and Memcached, not array or file.

The pattern that should be your default

For most reads, cache-aside via Cache::remember() is the right starting point, not the fanciest option, but the resilient one. Cache unreachable, cold, or empty, the app falls back to the database and keeps working, just slower.

use Illuminate\Support\Facades\Cache;

function getUser(int $userId): ?User
{
    return Cache::remember("user:{$userId}", now()->addMinutes(5), function () use ($userId) {
        return User::find($userId);
    });
}

That single call does the whole cache-aside dance: check cache, fall through on miss, store the result. Reach for this first on nearly every project, only move past it with a concrete reason.

The stampede problem nobody notices until it's a page at 3 am

A popular key expires. If it backs something with real traffic, dozens or thousands of requests can land on that exact miss window simultaneously. Every one falls through to the database and runs the same query at once, right when the database was least prepared for a burst.

The fix is a lock around the cache-population step, so only the first request through the door actually queries the database:

use Illuminate\Support\Facades\Cache;

function getUserSafe(int $userId): ?User
{
    $key = "user:{$userId}";

    if ($cached = Cache::get($key)) {
        return $cached;
    }

    return Cache::lock("lock:{$key}", 5)->block(3, function () use ($key, $userId) {
        // Re-check inside the lock; someone else may have populated it already
        return Cache::remember($key, now()->addMinutes(5), function () use ($userId) {
            return User::find($userId);
        });
    });
}

Needs a driver with atomic lock support: Redis, Memcached, DynamoDB, file and database won't work here. block() gives waiting requests a few seconds to pick up the freshly-cached value instead of failing outright.

Invalidation is where most caching bugs actually live

The most common caching bug we see: someone updates a record, forgets to invalidate the cached version, the app serves stale data with no error, nothing that looks broken until a user notices.

Manual invalidation works, until it doesn't:

function updateUser(int $userId, array $data): User
{
    $user = User::findOrFail($userId);
    $user->update($data);

    Cache::put("user:{$userId}", $user, now()->addMinutes(5));

    return $user;
}

Fine for this one path. Problem is the model probably gets updated from more than one place eventually: an admin panel, a background job, an import script, and everyone needs to remember this line exists. Miss one, quiet bug.

Hook invalidation into model events instead:

class UserObserver
{
    public function updated(User $user): void
    {
        Cache::forget("user:{$user->id}");
    }

    public function deleted(User $user): void
    {
        Cache::forget("user:{$user->id}");
    }
}

Register once, User::observe(UserObserver::class), invalidation stops being something a developer has to remember; it's structurally tied to the model itself, not any one call site.

For one change, clearing several related entries at once, tags handle it without tracking individual keys:

// Writing with tags
Cache::tags(['users', "user:{$userId}"])->put("user:{$userId}:profile", $profile, 300);

// Invalidate everything tagged 'users' in one call, e.g. after a bulk import
Cache::tags(['users'])->flush();

Tags only work on Redis and Memcached. On array or file this silently isn't doing what you think.

The pitfall that slips past even careful developers

Caching a query result that itself triggers lazy-loaded relationships doesn't solve your N+1 problem; it relocates it into the cache-population code. The cache entry ends up correct, but building it was just as expensive as never caching; you've only saved the cost on requests after the first.

Eager-load before you cache, always.

Takeaways

Cache-aside via Cache::remember() is the right default for most reads, resilient to cache failures by design.
Stampede protection matters the moment a cached key backs anything with real concurrent traffic; Cache::lock() is a small addition with an outsized payoff.
Prefer model observers over manual Cache::forget() calls scattered through the codebase; invalidation should be structurally hard to forget, not a discipline you're hoping every developer maintains.
Caching a lazy-loaded relationship just moves your N+1 problem into the cache-population step; eager-load first.
Never cache without a TTL, and never cache a failure or empty response; both turn caching from a performance win into an active bug.

Caching isn't a performance hack bolted on at the end; it's a data consistency problem with a performance benefit attached. Treat it that way and most of these pitfalls stop happening.

Full write-up with more context is on our Substack: https://ucodesoft.substack.com/p/caching-in-laravel-what-actually

The Repository Pattern in Laravel, When It's Worth It and When It's Just Extra Folders

UCodeSoft — Tue, 04 Aug 2026 04:23:42 +0000

Eloquent is genuinely good, expressive enough that you write a working query in one line and move on with your day. Which is exactly why the repository pattern question comes up so often: if Eloquent already reads this cleanly inside a controller, why wrap it in another layer?

We've built Laravel apps both ways, with a repository layer and without. Here's what it's actually solving, so you can tell when you need it.

A few terms first

The repository pattern, a class between your controllers and Eloquent models, whose only job is fetching and storing data. The controller asks the repository, never talks to Eloquent directly.

An interface, a contract, a list of methods a class promises to implement without saying how. UserRepositoryInterface says "something implementing me has a find() method," not whether that something hits MySQL, Redis, or an API.

Dependency injection, a class receives what it needs through its constructor instead of creating it itself. A controller taking UserRepositoryInterface $repository doesn't know or care which concrete class Laravel hands it.

Service container binding, how Laravel decides which concrete class to hand over when something asks for an interface. Bind once, usually in a service provider; every subsequent injection works.

A service, distinct from a repository, holds actual business logic, the workflow, not just data access. This distinction trips people up more than anything else here.

What it's actually solving

Not code organization for its own sake; it's about what happens when the same query needs to change, and it's been copy-pasted into five controllers.

public function index()
{
    $users = User::where('status', 1)
        ->orderBy('created_at', 'desc')
        ->paginate(10);

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

Fine on its own. But User::where('status', 1)->latest()->get() shows up in more than one place once an app grows, and when the business rule changes- active users now also need a verified email, say, you're hunting down every place that query got duplicated. Miss one, you've got a bug that only shows up in production.

A repository turns that into one method everything else calls:

public function activeUsers()
{
    return User::where('status', 1)
        ->where('email_verified_at', '!=', null)
        ->latest()
        ->get();
}

Change it once, and every controller calling $this->userRepository->activeUsers() picks up the new behavior.

Setting one up

Interface first, the contract every implementation honors:

interface UserRepositoryInterface
{
    public function all();
    public function find($id);
    public function create(array $data);
    public function update($id, array $data);
    public function delete($id);
}

The class that implements it:

class UserRepository implements UserRepositoryInterface
{
    public function all()
    {
        return User::all();
    }

    public function find($id)
    {
        return User::findOrFail($id);
    }

    public function create(array $data)
    {
        return User::create($data);
    }
}

Bind the interface to the implementation:

$this->app->bind(
    UserRepositoryInterface::class,
    UserRepository::class
);

Inject it wherever needed:

public function __construct(
    UserRepositoryInterface $repository
)
{
    $this->repository = $repository;
}

The controller genuinely doesn't know or care whether find() hits MySQL, reads from a cache, or calls another service. That's the point.

The caching example is where it actually clicks

Testing is the usual pitch, and it's real, but caching lands better in practice. Decide to cache user lookups, and without a repository you're editing every place User::findOrFail() gets called. With one, you change exactly one method:

public function find($id)
{
    return Cache::remember(
        "user_$id",
        600,
        fn () => User::findOrFail($id)
    );
}

Every controller calling $this->userRepository->find($id) is now cached; none of them changed. A decision that used to touch a dozen files now touches one.

Where we see this actually go wrong

Not skipping repositories, blurring the line between a repository and a service.

A repository fetches and stores data, full stop. A service orchestrates a workflow, calling several repositories, sending emails, firing events, whatever the process needs.

// Repository: data access
$productRepository->find($id);

// Service: the actual workflow
$orderService->placeOrder($request);

Write business logic inside a repository, validate input there, inject Request, return an HTTP response, and it's turned into something else wearing a repository's name. It still compiles; it just stops meaning anything.

When to actually reach for this

Not automatic on every project, and shouldn't be.

Earns its place on medium to large applications, more than one developer touching the same models, a query genuinely reused across controllers, automated tests actually part of the plan, or a real possibility of swapping the data source down the line.

Usually not worth it on a small CRUD app with one or two developers, a query used in exactly one place, or where Eloquent's own expressiveness already gets you there. Adding this structure to a small project purely because it's "best practice" just adds files to navigate for the same functionality.

Takeaways

Repositories earn their place when a query is reused, a team is more than one person, or swapping data sources is a real possibility, not by default on every project.
The caching use case makes the value obvious faster than the testing pitch does; a change that used to touch a dozen controllers touches one method instead.
Keep repositories and services separate. Repository fetches and stores. Service orchestrates. Blur that line and both stop meaning anything.
Interfaces plus dependency injection are what make a repository swappable; without the interface you've just moved the query, not decoupled anything.

Full writeup with more of the reasoning is on our Substack: https://ucodesoft.substack.com/p/the-repository-pattern-in-laravel

Why Timely Upgrades Matter, a Laravel and Backpack Story

UCodeSoft — Tue, 28 Jul 2026 19:34:50 +0000

"If it's working, don't touch it." We've all heard some version of that advice, and it's tempting to actually follow it. Why go anywhere near a stable application when everything's already fine?

We took on a project a while back that changed our answer. A Laravel admin panel built on Backpack, and it reminded us the real risk was never upgrading. The real risk is waiting so long that upgrading stops being an option.

A few terms first

A major version bump, an upgrade where the maintainers are telling you, explicitly, things might break. Patch releases are safe, major releases come with a list of things that changed on purpose.

A breaking change, something that worked one way in the old version and works differently, or not at all, in the new one. Deprecated methods, renamed classes, changed signatures.

An incremental upgrade path, moving through major versions one at a time instead of jumping straight to the target. Slower on paper, much faster once something breaks and you need to know why.

Regression testing, checking that everything that used to work still works, after a change that wasn't supposed to touch it. Not new feature testing, making sure you didn't quietly break something three steps removed.

Technical debt, the growing gap between the version you're running and the version that's actually supported. Costs nothing the day you skip an upgrade. Costs a lot more years later, when skipping stops being an option.

Where this one started

The application was on Laravel 8, Backpack 4, an older PHP version. Nothing broken, just old. The client wanted everything current, Laravel 12, Backpack 7, PHP 8.2+.

The tempting move: point composer at the newest versions, run the update, fix whatever complains. Laravel 8 to 12 in one shot, Backpack 4 to 7 in one shot, done. Except it's not done, it's deferred to whenever things start breaking, and by then you're debugging four major versions of change at once with no idea which one caused it.

Why we didn't take the shortcut

Lesson learned the hard way over the years: never jump multiple major versions in one move if you can help it. Every Laravel release carries its own breaking changes. Every Backpack release improves the admin panel, but also deprecates APIs, bumps dependencies, sometimes restructures how packages are organized.

Skip straight from Backpack 4 to 7 and the moment something breaks, you're stuck. Was that Laravel? Backpack? The PHP version change underneath both? Three major changes landing at once turns root-causing into guesswork.

So we followed the official upgrade path instead, one version at a time, testing at every stop.

Phase one: Laravel 8 to 9, Backpack 4 to 5

composer require backpack/crud:^5.0
composer update

Republished Backpack's assets after:

php artisan vendor:publish \
--provider="Backpack\CRUD\BackpackServiceProvider" \
--tag=public

Then, before touching anything else, went through every CRUD screen, relationship field, filter, permission, widget, and custom operation by hand. Only once that was clean did we move on.

Phase two: Laravel 9 to 10, Backpack 5 to 6

composer require backpack/crud:^6.0
composer update

Less about surviving the upgrade, more about improving the code while we were already in there. Refactored controllers that had gotten messy, tightened dependency injection, updated CRUD operations to current conventions, ran the same testing pass again.

Each upgrade wasn't just a version bump, it was a real chance to clean up cruft that had been quietly accumulating.

Phase three: Laravel 10 to 12, Backpack 6 to 7, PHP to 8.2+

Biggest jump, most structural change. Backpack 7 went modular on a lot of optional fields, rich text editors aren't bundled by default anymore:

composer require backpack/tinymce-field

composer require backpack/ckeditor-field

File uploads needed their own step:

php artisan backpack:upgrade-dropzone

Backpack ships an upgrade helper for a chunk of the mechanical changes:

php artisan backpack:upgrade

Never treated automated helper output as the finish line. After every automated step, went back through the code by hand and re-ran the full feature test again.

What actually mattered more than the upgrades themselves

The workflow stayed the same across all three phases:

composer update
php artisan optimize:clear
php artisan migrate
php artisan route:list

Then, every time: CRUD operations, relationship fields, upload fields, custom operations, filters, widgets, authentication, permissions. Not a skim, an actual walkthrough of each one. Only after that, the next major version. The upgrades themselves were mostly mechanical. The testing discipline is what kept any of it safe.

Takeaways

Never skip major versions in one jump if you can avoid it, isolating a breaking change across four version bumps at once is close to guesswork.
Automated upgrade helpers save time on mechanical changes, they're not a substitute for manually re-testing every feature.
Test the same full checklist after every phase, not just once at the end, regressions introduced in phase one can hide until phase three.
Technical debt is invisible day to day and expensive all at once, the longer an upgrade waits, the more versions stack up between where you are and where you need to be.

Don't be afraid of the upgrade, be more afraid of the day the application's fallen so far behind that upgrading feels impossible. One version at a time, test everything, keep the client in the loop. Full writeup with more context is on our Substack: https://ucodesoft.substack.com/p/why-timely-upgrades-matter-a-laravel

Upgrading Legacy Laravel and Moving Millions of Rows Without Taking the Site Down

UCodeSoft — Tue, 28 Jul 2026 03:41:00 +0000

A while back, we got the email every team dreads a little: a payment processor we'd been integrated with for years announced it was killing its old API. Not eventually, a hard date. Move to their new SDK or lose the integration.

That should've been contained. It wasn't because the new SDK wanted a different data shape underneath, not just a different way of calling the same endpoints. Customer profiles, payment methods, transaction logs, all of it had been sitting in one sprawling users table for years, and the new provider needed that normalized into proper tables with external ID mappings. The SDK had also quietly dropped PHP 7 support, so the Laravel upgrade wasn't optional anymore; it was bundled into the same deadline.

So the real task: upgrade the framework across several major versions, restructure a production database with millions of rows, and never take the site down while doing it. Here's how that went.

A few terms first

cursor() and LazyCollection, Laravel's way of reading a huge result set without loading it all into memory. Stream rows one at a time instead of buffering a million-row array first.

Chunking, processing a big dataset in smaller batches. Here it also means turning those batches into background jobs instead of working through them inline.

Keyset pagination (chunkById), paging with where('id', '>', $lastId) instead of skip()->take(). Sounds like a small difference, turned out to be the single biggest fix in this project.

Upsert, one statement that inserts a new row or updates an existing one. Makes a job safe to retry, a worker dying mid-batch and running again doesn't create duplicates.

Idempotent jobs, jobs that produce the same result no matter how many times they run. At this scale, something will eventually fail or get interrupted, and if jobs aren't idempotent, a retry becomes its own bug.

Why we didn't write one big migration script

The instinct is to write a single script and let it run overnight. We didn't, on purpose. A blocking ALTER TABLE or a big INSERT INTO ... SELECT on a multi-million row table locks things up, and with live traffic hitting the site, that's an outage with extra steps, not a maintenance window.

Instead, three stages that could each ship independently. Add the new schema alongside the old one, fully non-blocking. Backfill the new tables in the background, in small pieces, while both schemas stay live. Once the backfill is verified, flip the application code to the new tables, then clean up the old columns.

Stage one was a normal migration:

// Phase 1 Migration: non-blocking schema creation for the new provider
Schema::create('user_profiles_v2', function (Blueprint $table) {
    $table->id();
    $table->foreignId('user_id')->constrained()->cascadeOnDelete();
    $table->string('provider_customer_id')->nullable()->index();
    $table->json('preferences')->nullable();
    $table->string('formatted_phone', 32)->index();
    $table->timestamps();
});

Deliberately unexciting. Additive, doesn't touch anything the running app depends on.

Streaming the backfill instead of loading it all at once

The obvious way to write this command is to grab every user that needs migrating and loop over them. At a million-plus rows, that's an instant Allowed memory size exhausted, before any real work even starts.

We built the command around cursor() instead:

namespace App\Console\Commands;

use App\Models\User;
use App\Jobs\MigrateUserProfileChunkJob;
use Illuminate\Console\Command;

class MigrateUserProfilesCommand extends Command
{
    protected $signature = 'data:migrate-profiles';
    protected $description = 'Dispatches async backfill jobs for profile normalization';

    public function handle(): void
    {
        // Unbuffered streaming keeps memory consumption under 15MB
        User::query()
            ->whereNull('migrated_at')
            ->cursor()
            ->chunk(1000)
            ->each(function ($chunk) {
                dispatch(new MigrateUserProfileChunkJob($chunk->pluck('id')->toArray()));
            });
    }
}

That command's job is small on purpose: read a chunk of IDs, hand them off, move on. The transformation happens elsewhere.

One upsert instead of a thousand writes

Each dispatched job takes its chunk of IDs, builds the new payload, and writes it as a single upsert:

namespace App\Jobs;

use App\Models\User;
use App\Models\UserProfileV2;
use App\Helpers\PhoneHelper;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;

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

    public function __construct(public array $userIds) {}

    public function handle(): void
    {
        $payload = User::whereIn('id', $this->userIds)
            ->get()
            ->map(fn ($user) => [
                'user_id'         => $user->id,
                'preferences'     => json_encode($user->legacy_preferences),
                'formatted_phone' => PhoneHelper::sanitize($user->phone),
                'created_at'      => $user->created_at,
                'updated_at'      => now(),
            ])
            ->toArray();

        UserProfileV2::upsert(
            $payload,
            ['user_id'],
            ['preferences', 'formatted_phone', 'updated_at']
        );
    }
}

Fast, and also what makes retries safe. If this job dies and Laravel's queue retries it, the same upsert overwrites the same rows with the same values. No duplicates, nothing to clean up by hand.

Three things that only showed up at real scale

Testing on a smaller slice of data, everything looked fine. Against the real dataset, three separate problems showed up that never would have surfaced any earlier.

Offset pagination degrading with depth. Plain skip($offset)->take(1000) was fast for the first few batches and got progressively worse the deeper in we went. At offset 500,000, a single batch took over 4 seconds. MySQL has to actually read and discard every row before your offset just to know where to start counting, half a million rows read and thrown away, every batch. Switching to keyset pagination, where('id', '>', $lastProcessedId), fixed it completely. 4,200ms down to 12ms, flat regardless of depth. Biggest single win in the whole project.

PDO's placeholder ceiling. Upserting rows with more than 30 columns started throwing PDOException: SQLSTATE[HY000]: General error: 1390 Prepared statement contains too many placeholders. MySQL's PDO driver caps prepared statements at 65,535 placeholders total, rows times columns, not just rows. A chunk size fine for a narrow table blew past that on a wider one. Fix: stop hardcoding chunk size, calculate it from column count, max chunk size is 65,535 divided by column count, rounded down.

Queue workers slowly eating all available memory. Left running for hours against millions of records, workers gradually consumed enough RAM that Linux started killing processes. Long-lived queue:work processes hang onto query logs, event listeners, and cached Eloquent state across every job, none of it clears automatically. Fixed with --max-jobs=1000 --max-time=3600 so workers recycle themselves, plus an explicit DB::disconnect() at the end of every chunk.

Takeaways

Write every migration job assuming it'll fail partway through, because eventually one will. Upsert instead of insert, it's what makes retries safe instead of dangerous.
Never load a big Eloquent collection in one step if it might grow past a few thousand rows. cursor(), chunkById(), or raw streaming, something that doesn't try to hold it all in memory.
Keep deployment separate from schema change: add new structures first without touching anything live, backfill in the background on its own schedule, only flip the app over once the backfill is verified, and only then touch the old columns.
Offset pagination looks fine in early testing and quietly falls apart at depth, test paginated queries against realistic offsets, not just page one.

None of this needed a third-party ETL platform. Artisan commands, queue workers, and Laravel's own collection primitives were enough to move millions of rows through a live production database without anyone outside the team noticing. Full writeup with more of the backstory is on our Substack: https://ucodesoft.substack.com/p/upgrading-legacy-laravel-and-moving

Importing a Million Products From S3 Into Laravel, What Six Hours Taught Us

UCodeSoft — Mon, 27 Jul 2026 03:45:26 +0000

First time we ran this import, we kicked it off at 9 am, and it was still going when we packed up for the day. Six hours, and that wasn't a bad run; that's just what it did every time.

The data was diamond and jewelry inventory for a client, a bit over a million SKUs, carat weight, cut, color, clarity, dimensions, pricing tiers, image references, all of it. CSV on S3, needed to land in the product database with an admin panel on top for search and filtering.

Six hours means the catalog's stale for a quarter of every day. Not something we could live with long term, so we fixed it. Here's the whole thing, warts and all.

Quick vocabulary check

Chunking, splitting a huge dataset into smaller batches instead of one giant unit. "Do a thousand rows, a thousand times" instead of "do a million at once."

A queue job, work handed off to happen later, or somewhere else entirely, instead of making the thing that triggered it sit and wait.

Streaming, reading a file as it arrives, bit by bit, instead of waiting for the whole thing to land first.

Upsert, one statement that inserts a new row or updates an existing one, in a single round trip instead of two or three.

Turning off indexes for a bulk write, temporarily stopping MySQL from maintaining every index on every row, then rebuilding once the big write finishes. Only worth it for genuinely large batches.

What we started with

One artisan command doing everything in a straight line: pull the CSV from S3, parse row by row, find or create the product, update it, save it. No chunking, no queue, one PHP process, one database connection, start to finish. A million rows, a million individual Eloquent calls, each its own trip to the database.

Memory gave out first, around 200,000 rows, because we were loading the whole CSV into an array before processing even started. Bumped the limit, kept going, and then the database started struggling instead; a million INSERT and UPDATE statements with zero batching means constant fsync activity. On top of that, we were downloading the entire file before touching a single row; 15 to 20 minutes gone on a bad day before anything real happened.

Everything sequential, everything blocking on the last step, everything slow for its own reason. Six hours wasn't one bottleneck; it was four or five standing in line.

Actually looking at what we had

The real first move wasn't code; it was admitting this wasn't one job, it was three stitched together: get the data off S3, transform and validate a million rows, write it all to the database without falling over. Different bottleneck each time. Cram them into one process and the slowest one sets the pace for everything.

The command stayed the same, php artisan import: products. What happens once you run it changed almost completely.

Streaming instead of downloading

$s3Stream = Storage::disk('s3')->readStream('products/latest.csv');
$csv = Reader::createFromStream($s3Stream);
$csv->setHeaderOffset(0);

$chunk = [];
$chunkSize = 1000;

foreach ($csv->getRecords() as $record) {
    $chunk[] = $record;

    if (count($chunk) === $chunkSize) {
        ProcessProductChunk::dispatch($chunk);
        $chunk = [];
    }
}

if (!empty($chunk)) {
    ProcessProductChunk::dispatch($chunk);
}

The command finishes in a couple minutes now, just reading a stream and firing off jobs. The real work moved to the background.

1,000 rows per chunk came from actually testing sizes, not a guess. Too small and queue overhead eats you alive. Too big and one failure means redoing real work. A thousand landed us at just over a thousand jobs per run, each done in under 30 seconds.

Batching the writes

Original, inside each job:

foreach ($records as $record) {
    Product::updateOrCreate(
        ['sku' => $record['sku']],
        $this->mapAttributes($record)
    );
}

Reads nicely, brutal at scale, one query per row, SELECT to check, then INSERT or UPDATE. A thousand rows, up to two thousand queries in one job.

Swapped for a single upsert:

$mapped = array_map(fn($record) => $this->mapAttributes($record), $records);

Product::upsert(
    $mapped,
    ['sku'],                       // unique key to match on
    $this->updatableColumns()      // columns to update if row exists
);

One query, the whole batch. MySQL sorts out new vs. existing on its own. A chunk that took 18 seconds dropped to under 3. Bigger win than we expected.

Running jobs in parallel

php artisan queue:work redis --queue=product-import --sleep=1 --tries=3 --timeout=120

Dedicated queue, kept away from notifications, PDFs, order processing, so the import doesn't starve production traffic of workers. We spin up extra workers for the duration of a run and let them wind down after.

8 workers on 1,000-row chunks, roughly 8,000 rows every 3 seconds at peak. Same total work, just happening 8 at a time instead of 1.

Turning off indexes for the big runs

MySQL updates every index on every write. A million rows landing with all indexes active adds real overhead. For a full re-import specifically:

// Before import
DB::statement('ALTER TABLE products DISABLE KEYS');

// ... run the import ...

// After import
DB::statement('ALTER TABLE products ENABLE KEYS');
DB::statement('OPTIMIZE TABLE products');

Strictly for the full refresh case. Day-to-day incremental updates go through with indexes active the whole time, not enough volume there to justify it.

The admin panel had its own unrelated problem

Filter combinations against a million-row table with plain where chains were taking 4 to 8 seconds per query, import running or not. Fixed with composite indexes matching how people actually filter:

// Migration
Schema::table('products', function (Blueprint $table) {
    $table->index(['status', 'cut', 'carat_weight'], 'idx_admin_filters');
    $table->index(['status', 'price'], 'idx_price_filter');
});

Full table scans became index lookups. 4 to 8 seconds became under 200ms. Search is still a basic LIKE, fine for admin use, full-text search is still on the table for the customer-facing side.

Where we landed

Six hours down to three or four. What's left is mostly S3 read speed and the queue's throughput ceiling, both pushable further if it ever actually matters.

Takeaways

A slow bulk job is usually several bottlenecks stacked together, not one, treat it that way from the start.
updateOrCreate in a loop doesn't scale, a batch upsert() does, same intent, one query instead of thousands.
Stream large files instead of downloading them fully first, especially when processing can start before the download's done.
Disabling indexes for bulk writes is a real win, but scope it to genuinely large batches, not your everyday write.
A slow admin panel and a slow import can share a table without sharing a cause, profile them separately, don't assume.

Full writeup with more of the backstory is on our Substack: https://ucodesoft.substack.com/p/importing-a-million-products-from

Sanctum and Passport: Why We Stopped Rolling Our Own Token Auth

UCodeSoft — Wed, 22 Jul 2026 16:06:09 +0000

For a while we did what a lot of teams do when a project needs API auth: knock together a token scheme in an afternoon. Random string, a column in the users table, check it on the way in, maybe an expiry column if someone thought of it. Works fine, until the day it doesn't. For us that day showed up as a vendor breach that had nothing to do with our own code and everything to do with a decision we'd made two years earlier.

Here's what happened, and why ability scoping isn't optional on anything we ship now.

A few terms first

Ability (scope), a label on a token describing what it can do, reports:read for example. The part that matters isn't the label, it's that your code actually checks for it before doing anything sensitive, instead of assuming a valid token means "go ahead."

Revocation, killing one token without touching the rest of the account. Sounds obvious, plenty of homegrown systems can't actually do it cleanly.

Sanctum, Laravel's lightweight option for tokens going to things you control, your own SPA or app. No OAuth dance needed, you already trust both ends.

Passport, the real OAuth2 implementation, for when a third party you don't control needs credentials. Grant types, refresh rotation, the works.

Blast radius, what someone can actually do with a token once they have it. Decided the day you issue it, not the day it leaks.

What this looks like in code

Issuing a token with an actual scope on it:

// Only grant what this integration actually needs
$token = $user->createToken(
    name: 'reporting-integration',
    abilities: ['reports:read'],
    expiresAt: now()->addDays(30),
);

return response()->json(['token' => $token->plainTextToken]);

Checking that ability where it matters:

public function export(Request $request)
{
    if (! $request->user()->tokenCan('reports:read')) {
        abort(403);
    }

    // proceed with export
}

Pulling one token without touching the rest of the account:

// Revoke exactly one device's token, nothing else on the account
$user->tokens()->where('name', 'reporting-integration')->delete();

What actually happened to us

A couple years back, a client had us hook their platform up to a third-party analytics vendor. We issued that vendor one API token, full account access, because at the time it was the only integration they had and nobody scoped it down. Got dropped into the vendor's server config and, honestly, we forgot about it. Sat there doing its job for two years.

Then the vendor got breached. Not us, them, one of their internal servers got popped, and whatever was on it went with it, our token included. Since we'd never scoped it, that token wasn't "can read some analytics." It was read every customer record, touch billing, mint new tokens.

We couldn't just revoke it and move on either, killing the token meant killing the whole integration, nothing narrower underneath to fall back to. And when someone asked "what could they actually have done with this," we didn't have a fast answer, we had to go endpoint by endpoint figuring out what that token's role could reach, on the clock.

The breach itself wasn't on us, the vendor's infrastructure was their problem. What stuck with us was that we'd left the blast radius question wide open until the worst possible time to be answering it. So we changed the default. Every external integration now gets a token scoped to exactly what it needs, with an expiry that forces someone to look at it again down the line.

Why we don't roll this ourselves anymore

Token auth has plenty of ways to quietly break that you won't notice until you're under load or under attack, timing issues on comparison, no real revocation path, tokens that live forever. We were carrying all of that ourselves, auditing it as Laravel kept moving underneath.

Handing it to Sanctum and Passport made things simpler, not more complicated. They ship alongside Laravel's own security releases, they've been through the same scrutiny as the rest of the framework, and scoping, expiry, revocation, it's just there. We didn't have to design any of it.

Scoping is the bit everyone skips, us included

The thing we see teams skip most is scoping tokens properly at the start. The excuse is always "we'll tighten it up later." Later rarely comes, because tightening it up later means auditing every consumer of that token to figure out what it's actually using, and that's not a task anyone schedules until something forces it. We were exactly that team.

Every token we issue now gets explicit abilities from the start, even for a client that only exists for one narrow integration. Costs nothing extra. Means the next leak, whenever it happens, was already capped before anyone knew there was a problem.

Picking between Sanctum and Passport

Not a taste call. Sanctum makes sense when you own both ends, your SPA, your app. Passport earns its weight when there's an actual outside party, real grant types, refresh tokens, client credentials for machine-to-machine.

Passport on a first-party SPA is over-built. Sanctum on a public third-party integration is under-built, in a way that tends to surface at the worst time. Ask who's actually holding the token on the other end, not which package you like more.

// Third-party client authenticates itself, not a user
Route::post('/oauth/token', [AccessTokenController::class, 'issueToken']);

// grant_type=client_credentials&client_id=...&client_secret=...&scope=orders:read

// Protecting a route with the granted scope
Route::middleware(['auth:api', 'scope:orders:read'])->get('/api/orders', [OrderController::class, 'index']);

Passport models an actual client with its own credentials, not just a token handed to one of your users.

What we got out of it

The payoff isn't in the initial setup. It shows up months later, when a client's laptop gets stolen and you need to kill that one device without logging out the other eleven, or a security review asks you to prove an integration can only read. With Sanctum or Passport that's a quick check. With what we had before, it's a migration and a scramble.

That's the real case for not building this yourself, not that it's faster up front, but that it still holds up months later, under pressure, when whoever's dealing with it might not be the person who set it up.

If you've got a token floating around with more access than it needs, worth twenty minutes to go check before it becomes an incident. Full version of this story, with more of the background, is over on our

Substack: https://ucodesoft.substack.com/p/sanctum-and-passport-why-we-stopped

The Index Won't Save You: Debugging a Slow Derived Table in MySQL

UCodeSoft — Mon, 20 Jul 2026 12:54:03 +0000

Twenty rows. Over 500ms. That's the kind of mismatch that makes you stop what you're doing and open EXPLAIN. Our team ran into exactly this while working on a client's Laravel application, and it's a good enough example that we wanted to share the process.

Before we dive in

If you're already comfortable with EXPLAIN, derived tables, and correlated subqueries, skip ahead to the query. If not, here's everything you need going in.

EXPLAIN shows you MySQL's intended plan for a query before it runs: which indexes it's considering, roughly how many rows it expects to touch, and an Extra column that flags trouble. Two phrases matter here: Using filesort means it had to sort manually because no index gave it the order for free, Using temporary means it had to build a scratch table to hold intermediate results.

A derived table is a subquery in the FROM clause, wrapped so it acts like its own temporary table for the rest of the query. MySQL sometimes has to fully build that table before it can apply any filtering from the outer query, that disconnect is the core problem in this post.

A correlated subquery references a column from the surrounding query, so it can't be evaluated once for the whole statement, it has to run per row. Where you place it matters a lot: inside a JOIN, it may resolve for every joined row before anything else happens. In the SELECT list, MySQL can wait until WHERE and LIMIT have already narrowed things down first.

GROUP_CONCAT with ORDER BY is grouped, ordered string aggregation, folding many rows into one value per group in a specific order. That ordering requirement is why it needs a temp table, no index gets around it.

A covering index contains every column a query needs, so MySQL can answer from the index alone without a second trip back to the table row.

The setup

Here's the query, using a generic schema so it's easy to map onto your own. A task-management system, where every assignment has "fields," dynamic values tied to specific steps in a template, but only the steps before that template's first decision branch.

Here's how the relevant tables connect:

SELECT
  Assignment.id,
  Assignment.status,
  Assignment.modified,
  Fields.field_name,
  Fields.field_value
FROM assignments AS Assignment
LEFT JOIN (
  SELECT
    AF.assignment_id,
    GROUP_CONCAT(FieldDef.name ORDER BY Step.sort_order) AS field_name,
    GROUP_CONCAT(AF.value ORDER BY Step.sort_order) AS field_value
  FROM assignment_fields AF
  INNER JOIN template_steps Step ON Step.id = AF.step_id
  INNER JOIN (
    SELECT template_id, MIN(sort_order) AS first_decision
    FROM template_steps
    WHERE step_type = 'decision'
    GROUP BY template_id
  ) AS decision_start ON decision_start.template_id = Step.template_id
  INNER JOIN field_defs FieldDef ON FieldDef.id = AF.field_def_id
  WHERE Step.sort_order < decision_start.first_decision
  GROUP BY AF.assignment_id
) AS Fields ON Fields.assignment_id = Assignment.id
WHERE Assignment.team_id = 58
  AND Assignment.status = 'pending'
ORDER BY Assignment.modified DESC
LIMIT 20;

Step 1: EXPLAIN shows two separate problems

Not one problem, two, stacked on top of each other.

The outer scan on Assignment was filesorting on modified after filtering. The index in use didn't cover the sort column.
The derived table (Fields) was scanning its own inner decision_start subquery cold, flagged with Using temporary; Using filesort.

Treat every row of EXPLAIN as its own issue. One big index thrown at the whole query rarely fixes a compound problem like this.

Here's roughly what that looked like in the plan itself:

Step 2: index the inner subquery

decision_start computes MIN(sort_order) grouped by template_id, filtered on step_type = 'decision'. Unindexed, that's a full scan and sort of every step in every template.

CREATE INDEX idx_decision_lookup
  ON template_steps (step_type, template_id, sort_order);

Now the grouped MIN() reads straight off the index in order. No temp table, no filesort, for that piece.

Step 3: cover the join columns

Inside the derived table, the joins on AF and FieldDef were each doing an index lookup followed by a row lookup for value. A covering index removes the second trip.

CREATE INDEX idx_af_covering
  ON assignment_fields (step_id, assignment_id, field_def_id, value);

Small per-row win, but it's inside logic that reruns per group, so it adds up fast.

Step 4: fix the outer filesort

Assignment had (team_id, status) indexed, but nothing covering ORDER BY modified. Extending the index let MySQL walk it pre-sorted and stop at LIMIT 20, instead of sorting the whole filtered set afterward.

ALTER TABLE assignments
  DROP INDEX idx_team_status,
  ADD INDEX idx_team_status (team_id, status, modified);

Four legitimate, measurable wins. Query still slow.

The ceiling indexing can't get past

Fields has GROUP BY AF.assignment_id with an ordered GROUP_CONCAT inside it. In MySQL, grouped ordered string aggregation has to materialize a temp table, there's no index that skips that. Index every join feeding into it and the aggregation step will still show Using temporary; Using filesort, because that's inherent to the operation.

The bigger issue: this derived table has zero awareness of team_id = 58. It doesn't run after the outer WHERE narrows things down, it's built first, aggregating fields for every assignment in the system, and only afterward joined down to the 20 rows you wanted. Its cost scales with total row count, not your filtered result. Indexing speeds up how each row is read on the way in, it can't stop the aggregate from running for rows you're about to throw away.

Side note: the optimizer got weird after ALTER TABLE

Adding modified to the composite index should have been a clean win. Instead, EXPLAIN showed MySQL dropping the composite index entirely for index_merge, intersecting old single-column indexes, filesort and all.

ANALYZE TABLE assignments; didn't change anything on its own. What worked was removing the alternative:

ALTER TABLE assignments
  DROP INDEX idx_status,
  DROP INDEX idx_team_only;

With the redundant single-column indexes gone, index_merge wasn't an option anymore, and the composite index got used as intended. Redundant indexes cost more than write overhead, they give the optimizer worse choices, and it sometimes takes them.

The actual fix: bound the aggregate to the filtered rows

Two ways to do this. They're not equivalent.

Option A, correlated subquery in the join. Looks reasonable, often isn't:

LEFT JOIN (
  SELECT AF.assignment_id, GROUP_CONCAT(...) AS field_value
  FROM assignment_fields AF ...
  WHERE AF.assignment_id = Assignment.id
) AS Fields ON ...

MySQL 5.7 often runs this as a dependent join, re-executing the inner query once per outer row via a join buffer. Can end up slower than the original derived table, since you've traded one big aggregation for many small dependent ones with no early cutoff benefit.

Option B, correlated scalar subqueries in the SELECT list. This one works:

SELECT
  Assignment.id,
  Assignment.status,
  Assignment.modified,
  (
    SELECT GROUP_CONCAT(FieldDef.name ORDER BY Step.sort_order)
    FROM assignment_fields AF
    INNER JOIN template_steps Step ON Step.id = AF.step_id
    INNER JOIN field_defs FieldDef ON FieldDef.id = AF.field_def_id
    WHERE AF.assignment_id = Assignment.id
      AND Step.template_id = Assignment.template_id
      AND Step.sort_order < (
        SELECT MIN(sort_order) FROM template_steps
        WHERE template_id = Assignment.template_id AND step_type = 'decision'
      )
  ) AS field_name
  -- field_value mirrors the same shape
FROM assignments AS Assignment
WHERE Assignment.team_id = 58 AND Assignment.status = 'pending'
ORDER BY Assignment.modified DESC
LIMIT 20;

A scalar subquery in the SELECT list runs per output row, after WHERE has narrowed things, and after LIMIT has already decided which rows need it at all. MySQL can often stop once it has its 20 rows. A join-based correlated subquery gets no such benefit, it resolves for every row the join touches before LIMIT is applied.

Same core idea, per-row correlation instead of a global aggregate, very different execution shape.

Takeaways

Treat every EXPLAIN row as its own problem. A slow query can have several unrelated causes stacked together, fixing one won't even register in the timing until the rest are gone too.
Grouped, ordered aggregation (GROUP_CONCAT(... ORDER BY ...) GROUP BY x) always materializes. No index removes that, it's a property of the operation.
A derived table with GROUP BY is a wall the optimizer can't see through, your outer WHERE filters won't get pushed into it no matter how selective they are.
Redundant single-column indexes aren't free even when unused for writes, they widen the optimizer's (sometimes worse) options.
"Correlated subquery" isn't a single technique, where you put it (JOIN vs SELECT list) decides whether LIMIT can help you.

Indexing gets you most of the way there, right up until the operation itself is the bottleneck. At that point the fix isn't a better index, it's changing what you're actually asking MySQL to compute.

We work through problems like this regularly on Laravel and MySQL systems at scale. If you've hit a similar wall, drop a comment, we're always up for talking through a gnarly query.

We also cover this kind of debugging in more depth over on our Substack: https://ucodesoft.substack.com/p/the-index-wont-save-you-a-slow-query

The "Laravel Isn't Secure Enough for Enterprise" Myth is Dead

UCodeSoft — Thu, 16 Jul 2026 16:46:15 +0000

Every backend engineer has heard it: "Laravel is great for MVPs and small projects, but it’s just not secure enough for enterprise scale."

Usually, this critique comes from people who haven't looked at the modern ecosystem, or who are judging the framework based on a poorly configured legacy codebase they inherited from a junior team.

The reality? Laravel bakes in more native security defaults than most backend frameworks require you to configure manually. If an application suffers from basic vulnerabilities like SQL injection or Cross-Site Scripting (XSS), it is almost always a result of explicit implementation choices—not framework limitations.

As Certified Laravel Partners (https://laravel.com/partners/ucodesoft), doing deep-dive security audits is a standard baseline for every enterprise migration and build we take on. Here is what Laravel provides out of the box, and how to leverage it properly at scale.

1. Hardened Front-End Defaults (XSS & CSRF)

Many frameworks leave Cross-Site Request Forgery (CSRF) and Cross-Site Scripting (XSS) up to manual configuration or third-party middleware. Laravel treats them as non-negotiable baselines:

Blade Output Escaping: The {{ $variable }} syntax automatically routes data through PHP’s htmlspecialchars function. To introduce an XSS vulnerability, a developer must intentionally use raw tags ({!! $variable !!}).
Mandatory CSRF: Every state-changing HTTP request (POST, PUT, DELETE) is intercepted by native CSRF middleware.

2. First-Party API Authentication

Enterprise apps require robust, scalable token authentication. Instead of gambling on unmaintained open-source packages, Laravel provides two native, first-party, continuously patched solutions:

Laravel Sanctum: Lightweight token/cookie authentication perfect for SPAs and mobile apps.
Laravel Passport: A full OAuth2 server implementation built on top of the League OAuth2 server package.

Because these are first-party utilities, they integrate seamlessly with the framework's authentication guards and receive immediate security patches.

3. Native Protection Against SQL Injection

SQL injection remains a massive threat to enterprise databases. Laravel’s Eloquent ORM and Query Builder mitigate this entirely by using PDO parameter binding for all database operations.

Input data is bound to parameters rather than being directly concatenated into raw SQL strings. A developer has to explicitly bypass Eloquent and deliberately misuse raw queries (e.g., DB::raw()) to expose the database.

4. Isolated, Testable Authorization Policies

In legacy enterprise codebases, permission checks often become a tangled mess of if/else statements scattered across controllers and views. This fragmentation makes it incredibly easy to miss a check.

Laravel solves this architecturally through Policies. By isolating authorization rules into discrete, dedicated classes mapped to specific models, you can unit-test your permission logic in complete isolation:


php
// Clean, isolated, and highly testable enterprise authorization
public function update(User $user, Order $order)
{
    return $user->id === $order->user_id
        ? Response::allow()
        : Response::deny('You do not own this order.');
}

**Security Requires Configuration Discipline**

A framework can provide the most secure foundation in the world, but it still requires team discipline to maintain. In our enterprise engagements, the most critical vulnerabilities we uncover are rarely framework flaws. They are human errors:

* Leaving `APP_DEBUG=true` in production environments.
* Broad, insecure CORS header configurations (`*`).
* Failing to rotate or protect the `APP_KEY`.

Laravel doesn't eliminate the need for skilled, disciplined engineers—but it ensures your team doesn't waste hundreds of hours reinventing basic security compliance.

**Let's discuss in the comments:**
If you've audited an inherited Laravel codebase at scale, what was the most terrifying security configuration oversight you uncovered?

*Need an architectural or security review for your application? Get in touch with our team at (https://ucodesoft.com/contact-us).*

Seven things production taught me that no tutorial did

UCodeSoft — Tue, 14 Jul 2026 16:57:56 +0000

I spent the last few months building out a shipping integration on top of Shippo, and along the way, I kept running into the same lesson: the "quick" way to write Laravel code almost always works — right up until it doesn't. This isn't a theory post. Every pattern below came from something that actually broke, or almost broke, in this codebase.

Here are seven things I'd tell a past version of myself before writing another shipment controller.

1. Stop passing raw arrays to third-party APIs.
The ticket says "wire up Shippo shipment creation." The fastest way to close it is to grab a few fields off the order, throw them into an array, and fire it at the HTTP client. It works on the first try. It works in the demo. So what's wrong with it?

Nothing — until six months from now, when a new dev who's never opened Shippo's docs calls your method, forgets that parcels need a distance_unit key, and finds out the hard way via a 422 in staging. The array approach doesn't fail where the mistake happens. It fails at the network boundary, with a stack trace pointing at your HTTP client instead of the line that actually got it wrong.

My first instinct was "Shippo owns this shape, so a DTO is just re-describing their API." That's backwards. The DTO isn't there to constrain Shippo — it's there to constrain me. It makes it structurally impossible to send Shippo something malformed, and it gives the next person a single file that answers "what does a shipment request actually need?"

phpfinal readonly class ShippoParcel
{
public function __construct(
public float $lengthCm,
public float $widthCm,
public float $heightCm,
public float $weightKg,
) {}

public function toPayload(): array
{
    return [
        'length' => (string) $this->lengthCm,
        'width' => (string) $this->widthCm,
        'height' => (string) $this->heightCm,
        'distance_unit' => 'cm',
        'weight' => (string) $this->weightKg,
        'mass_unit' => 'kg',
    ];
}

}

toPayload() is doing something specific: it's the one place in the codebase that knows Shippo wants distance_unit and mass_unit as separate string keys instead of floats. That's a Shippo quirk, not a domain concept, and it deserves to live exactly once — at the edge — instead of being copy-pasted into every place that builds a parcel array.

Do the same thing on the response side. If a successful transaction contains a tracking_number buried three levels deep, don't make every consumer memorize that. Wrap it in a response DTO and throw a domain exception right there if a field you depend on is missing, instead of discovering it three calls later when something null-derefs.

2. Contextual binding: stop putting environment checks inside your classes.

Most of the time, one global container binding is exactly right. Don't reach for contextual binding before you need it — that's its own flavor of overengineering. But there's a specific smell that tells you when you've outgrown it: a service class that checks config() or does an instanceof check to decide its own behavior. That class just took on a second job — deciding which implementation it should be — and that job belongs to the container.

Here's a real one from this project: staging needs to hit Shippo's actual sandbox API so QA can test the full flow. But the internal support tool — the one an ops person uses to reprint a lost label — needs live credentials even when it's deployed next to staging, because a support agent reprinting a real label needs a real tracking number. An APP_ENV check can't express that; both consumers live in the same deployment.

php$this->app->when(QaShipmentController::class)
->needs(ShippoClient::class)
->give(SandboxShippoHttpClient::class);

$this->app->when(SupportLabelController::class)
->needs(ShippoClient::class)
->give(ShippoHttpClient::class);

Both controllers just type-hint ShippoClient. Neither has an if branch. Neither can drift onto the wrong credentials because someone forgot an env check.

One thing I'd flag: when you use the closure form of give() to resolve something like a region-specific storage driver, make the unmatched case throw instead of silently falling back to a default region.

php$this->app->when(LabelArchiver::class)
->needs(StorageDriverInterface::class)
->give(function ($app) {
return match (config('services.region')) {
'eu' => $app->make(S3EuStorageDriver::class),
'us' => $app->make(S3UsStorageDriver::class),
default => throw new RuntimeException('Unconfigured region: no storage driver bound.'),
};
});

A misconfigured deployment failing loudly at boot is a five-minute fix. The same misconfiguration that silently archives EU customer data to a US bucket for three weeks is a very different conversation with legal.

3. API versioning: the database doesn't get an opinion

The tempting shortcut when a mobile endpoint needs to change: just change it, ship a new app version, tell stragglers to update. It's less work than standing up parallel routes and resources for what might be a one-field difference.

Here's why that doesn't survive contact with mobile clients: you can't force an update. A web deploy hits everyone within minutes. A phone with your app from fourteen months ago, sitting in a drawer half the year, hits your API tomorrow with the same confidence as someone on today's build. You can't patch that client — you can only decide, in advance, how long you're willing to keep talking to it.

The rule I hold myself to now: version at the boundary, never inside business logic. The second a version check shows up inside a service class, that check is going to outlive the version it was written for.

phpfinal class ShipmentController extends V1\ShipmentController
{
protected function resource(Shipment $shipment): JsonResource
{
return ShipmentResource::make($shipment);
}
}

If v2 only changes the response shape, don't fork the whole controller — fork the resource and let v2 inherit the rest. Duplicating the entire controller feels safer in the moment, but now every bug fix has to be applied twice by someone who has to remember both files exist.

And tell clients a version is dying using something machine-readable, not a changelog nobody on the client side reads:

php$response->headers->set('Deprecation', 'true');
$response->headers->set('Sunset', 'Wed, 01 Oct 2026 00:00:00 GMT');

Then actually count requests against the old version after your sunset date. That count is the only honest answer to "can we turn this off yet" — not a guess from support tickets.

The part that actually burns teams isn't the routing layer; it's migrations. Add new columns as nullable, write to both old and new during the transition, confirm traffic on the old version has actually dropped to zero, and only then drop the legacy column in a separate deploy. "Low" traffic isn't zero traffic — one enterprise customer's warehouse scanner still hitting v1 nightly is enough to turn a routine cleanup into an on-call incident.

4. Real-time dashboards: broadcasting demos beautifully and then lying to you

Before reaching for WebSockets at all — just poll. setInterval, a fetch call, done. For a lot of internal dashboards, that's genuinely the right answer, not a lesser one. Broadcasting earns its complexity when both the update volume and the number of watchers climb.

What the "add a trait, save a model, watch it update live" demo doesn't show you: broadcasts that silently never arrive, events that land out of order, and clients that missed a whole window of updates because their laptop slept for two minutes.

A shipment tracking dashboard hits all three because "label purchased" and "in transit" webhooks can land milliseconds apart, and normal network jitter is enough to flip that order by the time it reaches a browser. The fix is a version field that the client can compare against:

phppublic function broadcastWith(string $event): array
{
return match ($event) {
'updated' => [
'id' => $this->id,
'status' => $this->status,
'version' => $this->updated_at->getTimestampMs(),
],
default => [],
};
}
jsEcho.private(shipments.${shipmentId}).listen('.ShipmentUpdated', (e) => {
if (e.version <= (lastSeenVersion[e.id] || 0)) return; // stale, ignore
lastSeenVersion[e.id] = e.version;
updateDashboard(e.status, e.trackingNumber);
});

The one everybody skips: reconnects. A dropped socket has zero memory of what it missed — there's no replay buffer. On reconnect, refetch the current state from a plain REST endpoint before trusting the next broadcast. If you skip this, you'll eventually get a bug report that reads "the dashboard says pending but it actually shipped hours ago," and it'll take you a minute to realize it's not a broadcasting bug at all — it's a missing REST call.

5. N+1 queries hide behind conditionals, not in obvious loops

Nobody writes an obvious N+1 loop and misses it in review. The ones that ship are nested two or three levels deep inside a branch that only fires for a subset of rows:

php$shipments = Shipment::with('customer')->get();
foreach ($shipments as $shipment) {
if ($shipment->customer->isHighVolume()) {
// N+1 fires here — parcels were never eager loaded
$shipment->parcels->each(fn ($p) => $p->carrier->name);
}
}

with('customer') only reaches one level deep. This is invisible in review unless someone mentally traces every branch two relations deep, and invisible in local dev because your ten-seeded shipments run ten queries instead of ten thousand. It shows up as connection pool exhaustion in production, during your busiest hour — not as a comment in a PR.

The actual fix isn't "remember to eager load" — memory isn't an engineering control. Make the framework refuse to ship the mistake:

phpModel::preventLazyLoading(! $this->app->isProduction());
Model::handleLazyLoadingViolationUsing(function (Model $model, string $relation): void {
logger()->warning("Attempted to lazy load [{$relation}] on model [" . get_class($model) . "].");
});

Throw in local and staging, where a broken deploy costs nothing. Log-and-allow in production, where throwing on a lazy load would turn a performance bug into an outage on the spot. And enable this in your test suite too — a test that seeds exactly one shipment with one parcel will never trip an N+1, because there's nothing to multiply.

For the fix itself, reach for loadMissing() instead of sprinkling with() everywhere defensively. It costs nothing if the caller already did the right thing, and acts as a safety net at every controller/job boundary if they didn't.

6. Cache::flush() is a sledgehammer with a hair trigger

A carrier's negotiated rate changes, something needs invalidating, and Cache::flush() is sitting right there — one line, guaranteed correct, impossible to get subtly wrong. It also wipes every unrelated cached value in your app and triggers a stampede as every concurrent request misses at once and hits the database simultaneously.

Cache tags scope the blast radius to exactly what changed:

phpCache::tags(['rates', "carrier:{$carrierId}"])->put(
"rate.{$originZip}.{$destZip}", $rateQuote, now()->addHours(6)
);

Cache::tags(["carrier:{$carrierId}"])->flush();

Wire the flush to the model lifecycle so it's correct by construction instead of by every developer remembering to add an invalidation line next to every write:

phpprotected static function booted(): void
{
static::saved(function (CarrierAccount $account): void {
if ($account->wasChanged('negotiated_rate_table')) {
Cache::tags(["carrier:{$account->id}"])->flush();
}
});
}

Two things worth knowing before you build around this: cache tags require Redis or Memcached — the file and database drivers throw at runtime, not fail gracefully. And flush after your transaction commits, not before. Flush too early, and a request landing in that window reads the pre-update row, caches it, and now you're serving stale data for the full TTL with nothing telling you it happened.

Laravel 13 also adds Cache::touch(), which is worth knowing about for the more common case: a key is still valid, and you just want to push the TTL out without paying to rewrite the payload.

7. Model::all() works fine until your table grows

It's one call, it reads clean, and it's the answer in every tutorial. On a few hundred rows, it's genuinely correct. On a table with hundreds of thousands of open shipments, it's an OOM before your loop runs a single iteration — and the failure has nothing to do with your loop logic. It happens at the query level.

The choice comes down to two questions: does your loop mutate the column you're filtering on, and is each iteration doing slow I/O?

Read-only, fast → chunk()
Mutates the filtered column → chunkById() — pages by primary key instead of offset, so a row changing status mid-loop can't silently shift what the next page fetches (this is the one that bites people: chunk() under mutation doesn't error, it just quietly skips rows)
Slow outbound I/O → lazyById() — same generator ergonomics as cursor(), but doesn't hold a database connection open for the full duration of every outbound API call

phpShipment::where('status', 'in_transit')
->lazyById(500)
->each(function (Shipment $shipment): void {
$shipment->refreshTrackingStatus();
$shipment->save();
});

Get the second question wrong, and you trade an OOM for silently under-processing your table — which is arguably worse, because nothing throws to tell you it happened.

None of these is exotic. They're all things Laravel gives you out of the box. The theme across all seven, if there is one, is the same: local dev and a small seed dataset will hide every one of these problems from you, and production will find every single one at the worst possible time. Building the guardrail in — a DTO, a container binding, a lazy-loading exception, a version header — beats trying to remember not to make the mistake.

If you've hit a different version of any of these, I'd genuinely like to hear it — drop it in the comments.