Category: Laravel

Ever debug a bug where your financial reports showed negative margins, only to discover you were mixing cached and fresh data in the same transaction?

I hit this in an API endpoint that calculated order profitability. The method fetched product costs fresh from the database (good!), but the companion method that grabbed retail prices was still using Redis cache (bad!). When prices changed, we’d calculate margins using old cached prices and new costs. Hello, mystery losses.

The fix wasn’t just “disable cache everywhere” — Redis cache is there for a reason. The real issue was inconsistent cache behavior within the same transaction.

Here’s the pattern that saved us:

class OrderCalculator
{
    public function calculateMargin(Order $order, bool $useCache = true): float
    {
        $cost = $this->getCost($order->product_id, useCache: $useCache);
        $price = $this->getPrice($order->product_id, useCache: $useCache);
        
        return $price - $cost;
    }
    
    private function getCost(int $productId, bool $useCache = true): float
    {
        if (!$useCache) {
            return Product::find($productId)->cost;
        }
        
        return Cache::remember("product.{$productId}.cost", 3600, function() use ($productId) {
            return Product::find($productId)->cost;
        });
    }
    
    private function getPrice(int $productId, bool $useCache = true): float
    {
        if (!$useCache) {
            return Product::find($productId)->price;
        }
        
        return Cache::remember("product.{$productId}.price", 3600, function() use ($productId) {
            return Product::find($productId)->price;
        });
    }
}

// In write operations (order creation, updates):
$margin = $calculator->calculateMargin($order, useCache: false);

// In read operations (reports, dashboards):
$margin = $calculator->calculateMargin($order, useCache: true);

The key insight: make cache behavior explicit and consistent. When you’re writing data or making financial calculations, all related lookups should use the same freshness guarantee. Add a useCache parameter (default true for reads) and disable it for writes.

Your future self debugging production at 2am will thank you.

Here’s a pattern I reach for any time I need temporary file operations in an artisan command or queue job: Storage::build().

Most Laravel developers know about configuring disks in config/filesystems.php. But what happens when you need a quick, disposable filesystem rooted in the system temp directory? You don’t want to pollute your configured disks with throwaway stuff.

The Pattern

use Illuminate\Support\Facades\Storage;

$storage = Storage::build([
    'driver' => 'local',
    'root' => sys_get_temp_dir(),
]);

// Now use it like any other disk
$storage->makeDirectory('my-export');
$storage->put('my-export/report.csv', $csvContent);

// Clean up when done
$storage->deleteDirectory('my-export');

This creates a filesystem instance on the fly, pointed at /tmp (or whatever your OS temp directory is). No config file changes. No new disk to maintain.

Why This Beats the Alternatives

You might be tempted to just use raw PHP file functions:

// Don't do this
file_put_contents('/tmp/my-export/report.csv', $csvContent);

But then you lose all the niceties of Laravel’s filesystem API — directory creation, deletion, visibility management, and consistent error handling.

You could also define a temp disk in your config:

// config/filesystems.php
'temp' => [
    'driver' => 'local',
    'root' => sys_get_temp_dir(),
],

But that’s permanent config for a temporary need. Storage::build() keeps it scoped to the code that actually needs it.

A Real-World Use Case

This shines in artisan commands that generate files, process them, and clean up:

class GenerateReportCommand extends Command
{
    protected $signature = 'report:generate {userId}';

    private Filesystem $storage;

    public function __construct()
    {
        parent::__construct();
        $this->storage = Storage::build([
            'driver' => 'local',
            'root' => sys_get_temp_dir(),
        ]);
    }

    public function handle()
    {
        $dir = 'report-' . $this->argument('userId');
        $this->storage->makeDirectory($dir);

        try {
            // Generate CSV
            $this->storage->put("$dir/data.csv", $this->buildCsv());

            // Maybe encrypt it
            $encrypted = $this->encrypt("$dir/data.csv");

            // Upload somewhere permanent
            Storage::disk('s3')->put("reports/$dir.csv.gpg", 
                $this->storage->get($encrypted)
            );
        } finally {
            // Always clean up
            $this->storage->deleteDirectory($dir);
        }
    }
}

The try/finally ensures temp files get cleaned up even if something throws. The command’s temp filesystem stays completely isolated from the rest of your app.

Storage::build() has been available since Laravel 9. If you’re still using raw file_put_contents() calls for temp files, give this a try.

If you’re logging records to a database table that has a unique constraint — say, tracking processed job IDs or idempotency keys — you’ve probably hit this at some point:

SQLSTATE[23000]: Integrity constraint violation: 1062
Duplicate entry 'abc-123' for key 'jobs_uuid_unique'

This typically happens when two processes try to insert the same record at roughly the same time. Classic race condition. And it’s especially common in queue workers, where multiple workers might process the same failed job simultaneously.

The blunt solution is to wrap it in a try/catch:

try {
    DB::table('processed_jobs')->insert([
        'uuid' => $job->uuid(),
        'failed_at' => now(),
    ]);
} catch (\Illuminate\Database\QueryException $e) {
    // Ignore duplicate
}

But there’s a cleaner way. Laravel’s query builder has insertOrIgnore() — available since Laravel 5.8:

DB::table('processed_jobs')->insertOrIgnore([
    'uuid' => $job->uuid(),
    'failed_at' => now(),
    'payload' => $job->payload(),
]);

Under the hood, this generates INSERT IGNORE INTO ... on MySQL, which silently skips the insert if it would violate a unique constraint. No exception thrown, no try/catch needed.

A few things to keep in mind:

• insertOrIgnore() will suppress all duplicate key errors, not just the one you’re expecting — so make sure your unique constraints are intentional
• On MySQL, it also bypasses strict mode checks, which means other data integrity issues might be silently swallowed
• If you need to update the existing record on conflict, use upsert() instead

Here’s the decision framework I use:

• “Skip if exists” → insertOrIgnore()
• “Update if exists” → upsert()
• “Fail if exists” → Regular insert() (and let the exception surface)

If you’re writing any kind of idempotent operation — event processing, job tracking, audit logging — insertOrIgnore() is the simplest way to handle the race condition without cluttering your code with try/catch blocks.

This one has bitten me and probably every Laravel developer at least once. You’re combining two collections and items silently disappear. No error, no warning — just missing data.

The Trap

Laravel’s merge() and concat() look interchangeable at first glance. They’re not. The difference is all about how they handle numeric keys.

merge() overwrites values when keys match. concat() appends items regardless of keys.

$dbJobs = collect([
    0 => ['name' => 'Send Weekly Report', 'schedule' => '0 9 * * 1'],
    1 => ['name' => 'Clean Temp Files', 'schedule' => '0 0 * * *'],
]);

$configJobs = collect([
    0 => ['name' => 'Sync Inventory', 'schedule' => '*/30 * * * *'],
    1 => ['name' => 'Generate Invoices', 'schedule' => '0 6 * * 1'],
]);

// ❌ merge() - overwrites keys 0 and 1, you get 2 items instead of 4
$all = $dbJobs->merge($configJobs);
// Result: Sync Inventory, Generate Invoices (DB jobs silently lost!)

// ✅ concat() - appends all items, you get all 4
$all = $dbJobs->concat($configJobs);
// Result: Send Weekly Report, Clean Temp Files, Sync Inventory, Generate Invoices

Why This Is Sneaky

This bug is particularly nasty because it usually passes your tests. Test fixtures tend to have unique keys or small data sets that don’t overlap. It’s only in production — when two data sources happen to produce the same numeric indices — that items start vanishing.

And since there’s no error or exception, you won’t know anything is wrong until someone notices the missing data downstream.

The Rule of Thumb

If you’re combining two collections and you want all items from both, use concat(). Full stop.

Only use merge() when you specifically want the overwrite behavior — for example, merging config arrays where later values should replace earlier ones (the same way PHP’s array_merge() works with string keys).

Quick Reference

• merge() — like array_merge(): string keys overwrite, numeric keys also overwrite (unlike native PHP!)
• concat() — like array_push(): just appends everything, keys don’t matter
• push() — adds a single item

One-line fix, saves you hours of debugging “where did my data go?”

Schema migrations are easy to plan and hard to deploy — especially when a column rename or consolidation touches dozens of call sites across the codebase. Here’s a trick I’ve used to make incremental migrations way less painful.

The Scenario

Imagine you have a model with numbered columns: price_1, price_2, all the way through price_60. A past design decision that seemed reasonable at the time but now just wastes space. You want to consolidate everything down to price_1.

The data migration is straightforward — copy the canonical value into price_1 for every row. But the scary part is all the existing code that reads $record->price_5 or $record->price_23 scattered across the app.

The Trick: Override getAttribute()

Instead of finding and updating every reference before deploying, override Eloquent’s getAttribute() to silently redirect old column access to the new consolidated column:

class PricingRecord extends Model
{
    public function getAttribute($key)
    {
        $consolidatedPrefixes = [
            'price_',
            'cost_',
            'fee_',
        ];

        foreach ($consolidatedPrefixes as $prefix) {
            if (preg_match('/^' . preg_quote($prefix) . '\d+/', $key)
                && $key !== $prefix . '1') {
                // Redirect any tier N access to tier 1
                return parent::getAttribute($prefix . '1');
            }
        }

        return parent::getAttribute($key);
    }
}

The Deployment Sequence

1. Run the data migration — consolidate all values into the _1 columns
2. Deploy the getAttribute() override — old code reading $record->price_5 transparently gets price_1
3. Clean up call sites at your own pace — update references one PR at a time, no rush
4. Remove the override once all references point to _1
5. Drop the old columns in a final migration

No big-bang refactor. No merge conflicts from a 40-file PR. No “please don’t deploy anything until my branch lands.”

One Caveat

This adds a regex check on every attribute access for that model. For a model you load a few times per request, it’s negligible. But if you’re hydrating thousands of records in a loop, profile it first. The regex is cheap, but “cheap × 10,000” can add up.

For most real-world use cases though, this buys you a safe, incremental migration path with zero downtime and zero broken features.

Here’s one of those Laravel features that’s been around forever but still doesn’t get the love it deserves: prepareForValidation().

If you’ve ever written gnarly conditional validation rules just because the incoming form data was messy, this one’s for you.

The Problem

Say you have a pricing form where users can pick different plan tiers. The form sends data keyed by the tier number they selected. But your validation rules really only care about the final, normalized value — always stored against tier 1.

You could write a pile of conditional rules to handle every possible tier. Or you could just normalize the data before validation even runs.

The Fix

Laravel’s FormRequest class has a prepareForValidation() method that fires right before your rules() are evaluated. Use it to reshape incoming data so your rules only deal with a clean, predictable structure:

class UpdatePricingRequest extends FormRequest
{
    protected function prepareForValidation(): void
    {
        $tiers = (array) $this->get('tiers');
        foreach ($tiers as $tierName => $tierData) {
            $selectedTier = $tierData['selected_tier'] ?? 1;
            if ($selectedTier > 1) {
                // Copy the selected tier's value to tier 1
                $this->merge([
                    "prices.{$tierName}.1" => $this->input("prices.{$tierName}.{$selectedTier}"),
                ]);
            }
        }
    }

    public function rules(): array
    {
        return [
            'prices.*.1' => 'required|numeric|min:0',
        ];
    }
}

Why This Works

Your validation rules only need to care about one shape: prices.*.1. The real-world messiness — users picking tier 3 on one plan and tier 7 on another — gets handled upstream, before rules even see it.

This keeps your rules dead simple and your normalization logic in one obvious place. No more spreading data transformation across rules, controllers, or middleware.

When to Reach For It

Any time your incoming data doesn’t match the shape your rules expect. Common cases:

• Trimming or lowercasing string fields
• Remapping aliased keys from different API consumers
• Setting defaults for optional fields
• Normalizing nested data like the tier example above

The official docs cover it briefly, but once you start using it, you’ll wonder how you ever managed without it.

We recently had to bulk-process a batch of records — update statuses, add notes, trigger some side effects. The kind of thing you write a one-off artisan command for.

The first instinct is to just loop and execute. But what happens when the command fails halfway through? Or the queue worker restarts? You need to run it again, and now half your records get double-processed.

The fix: Make every step check if it’s already been done.

public function handle()
{
    $orders = Order::whereIn('reference', $this->references)->get();

    foreach ($orders as $order) {
        // Step 1: Always safe to repeat
        $order->addNote('Bulk processed on ' . now()->toDateString());

        // Step 2: Skip if already done
        if ($order->status === OrderStatus::CANCELLED) {
            $this->info("Skipping {$order->reference} — already cancelled");
            continue;
        }

        // Step 3: Do the actual work
        $order->cancel();
        $this->info("Cancelled {$order->reference}");
    }
}

Key patterns:

• Check before acting — If the record is already in the target state, skip it
• Log what you skip — So you can verify the second run did nothing harmful
• Add a --dry-run flag — Always. Test the logic before committing to production changes

$this->addOption('dry-run', null, InputOption::VALUE_NONE, 'Run without making changes');

// In your handle method:
if ($this->option('dry-run')) {
    $this->info("[DRY RUN] Would cancel {$order->reference}");
    continue;
}

The rule is simple: if you can’t safely run it twice, it’s not ready for production.

When you’re debugging a complex Eloquent query, toSql() gives you the query with ? placeholders. Not super helpful when you need to paste it into your database client.

Since Laravel 10.15, you can use toRawSql() instead:

// Before — placeholders, not useful for debugging
$query->toSql();
// SELECT * FROM users WHERE status = ? AND role = ?

// After — actual values inline
$query->toRawSql();
// SELECT * FROM users WHERE status = 'active' AND role = 'admin'

Works on both the Eloquent builder and the base query builder:

// Eloquent builder
User::where('status', 'active')->toRawSql();

// Base query builder (useful for complex joins)
User::where('status', 'active')->toBase()->toRawSql();

I use ->toBase()->toRawSql() constantly when comparing old vs new query approaches during refactors. Paste both into your DB client, compare the execution plans, and you know exactly what changed.

Bonus: If you’re on an older Laravel version, the query log approach still works:

DB::enableQueryLog();
// ...run your query...
dd(DB::getQueryLog());

But toRawSql() is cleaner when you just need one query.