One of the easiest ways to create accidental “data migrations” is to put user-facing strings in places you later treat as stable identifiers.

A common example: storing uploaded files under a directory that includes a slug or title. It feels tidy… until someone renames the record and suddenly your storage path no longer matches reality.

The rule of thumb

Use an immutable identifier for storage paths. Keep human-readable names as metadata.

That usually means:

• A stable key (ULID/UUID/integer id) for file paths and URLs
• A separate column for the original filename / display name
• A separate column for the current “pretty” label (which can change)

A simple Laravel approach

Create a model that owns the upload, and give it a stable public identifier.

// database/migrations/xxxx_xx_xx_create_documents_table.php
Schema::create('documents', function ($table) {
    $table->id();
    $table->ulid('public_id')->unique();

    $table->string('display_name');      // can change
    $table->string('original_name');     // what the user uploaded
    $table->string('storage_path');      // immutable once set

    $table->timestamps();
});

On upload, generate the storage path from the immutable identifier (not the title):

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Storage;
use Illuminate\Support\Str;

public function store(Request $request)
{
    $file = $request->file('file');

    $publicId = (string) Str::ulid();
    $originalName = $file->getClientOriginalName();

    $path = "documents/{$publicId}/" . Str::random(16) . "-" . $originalName;

    Storage::disk('public')->put($path, file_get_contents($file->getRealPath()));

    $document = Document::create([
        'public_id' => $publicId,
        'display_name' => pathinfo($originalName, PATHINFO_FILENAME),
        'original_name' => $originalName,
        'storage_path' => $path,
    ]);

    return response()->json([
        'id' => $document->public_id,
    ]);
}

Why this pays off

• Renames are trivial: update display_name, nothing else.
• Downloads don’t break when labels change.
• You can safely rebuild “pretty URLs” later without moving files.

If you want tidy URLs, you can still add a slug — just don’t make your storage system depend on it.

<!-- SingleTaskEdit.vue -->
<StatusUpdateForm
    :defaultStatus="task.status"
    :defaultDueDate="task.due_date"
    :defaultAssignee="task.assignee_id"
    :tasks="[task]"
/>

<!-- BulkTaskEdit.vue -->
<StatusUpdateForm
    :defaultStatus="commonStatus"
    :defaultDueDate="commonDueDate"
    :defaultAssignee="commonAssignee"
    :tasks="selectedTasks"
/>

// StatusUpdateForm.vue
export default {
    props: {
        tasks: {
            type: Array,
            required: true
        },
        defaultStatus: {
            type: String,
            default: null  // Null = user must choose
        },
        defaultDueDate: {
            type: String,
            default: null
        },
        defaultAssignee: {
            type: Number,
            default: null
        }
    }
}

// BulkTaskEdit.vue
computed: {
    commonStatus() {
        const statuses = this.selectedTasks.map(t => t.status);
        const unique = [...new Set(statuses)];
        return unique.length === 1 ? unique[0] : null;
    }
}

if (auth()->user()->hasRole('super.admin')) {
    // Show advanced settings
}

function canViewAdvancedSettings(User $user, Report $report): bool
{
    // Layer 1: Tech team bypass (debugging)
    if ($user->hasRole('tech.team')) {
        return true;
    }
    
    // Layer 2: Base permission check
    if (!$user->hasPermission('view.advanced.settings')) {
        return false;
    }
    
    // Layer 3: Context-aware role check
    if ($report->isPublished()) {
        // Published reports: only executives
        return $user->hasRole('executive');
    }
    
    // Default: any user with base permission can view drafts
    return true;
}

@php
    $showAdvanced = (function($user, $report) {
        if ($user->hasRole('tech.team')) {
            return true;
        }
        
        if (!$user->hasPermission('view.advanced.settings')) {
            return false;
        }
        
        if ($report->isPublished()) {
            return $user->hasRole('executive');
        }
        
        return true;
    })(auth()->user(), $report);
@endphp

@if($showAdvanced)
    <div class="advanced-settings">
        {{-- Advanced settings UI --}}
    </div>
@endif

// app/Policies/ReportPolicy.php
public function viewAdvancedSettings(User $user, Report $report): bool
{
    if ($user->hasRole('tech.team')) {
        return true;
    }
    
    if (!$user->hasPermission('view.advanced.settings')) {
        return false;
    }
    
    if ($report->isPublished()) {
        return $user->hasRole('executive');
    }
    
    return true;
}

@can('viewAdvancedSettings', $report)
    <div class="advanced-settings">
        {{-- Advanced settings UI --}}
    </div>
@endcan

<UpdateStatusForm
    :defaultStartDate="task.start_date"
    :defaultEndDate="task.end_date"
    :defaultPriority="task.priority"
    :tasks="[task]"
/>

<UpdateStatusForm
    :tasks="selectedTasks"
/>

computed: {
    commonStartDate() {
        const dates = this.selectedTasks.map(t => t.start_date);
        const unique = [...new Set(dates)];
        return unique.length === 1 ? unique[0] : null;
    },
    
    commonEndDate() {
        const dates = this.selectedTasks.map(t => t.end_date);
        const unique = [...new Set(dates)];
        return unique.length === 1 ? unique[0] : null;
    },
    
    commonPriority() {
        const priorities = this.selectedTasks.map(t => t.priority);
        const unique = [...new Set(priorities)];
        return unique.length === 1 ? unique[0] : null;
    }
}

<UpdateStatusForm
    :defaultStartDate="commonStartDate"
    :defaultEndDate="commonEndDate"
    :defaultPriority="commonPriority"
    :tasks="selectedTasks"
/>

props: {
    defaultStartDate: { type: String, default: null },
    defaultEndDate: { type: String, default: null },
    defaultPriority: { type: String, default: '' }
}

When you have complex boolean conditions, don’t cram them into one giant expression. Break them into named variables that explain what you’re checking, not just how.

Before (hard to read)

if ($record->getConfig()?->getKey() === null && is_string($record->api_plugin) && app(ConfigRepository::class)->configsFor($record->api_plugin)->containsOneItem() && method_exists($record->api_plugin, 'getClients') && app($record->api_plugin)->getClients()->contains(fn (Client $client) => !$client->getConfig() instanceof DynamicConfig) === false) {
    $record->setConfig(app(ConfigRepository::class)->configsFor($record->api_plugin)->first());
}

This works, but it’s a wall of logic. What are we actually checking?

After (self-documenting)

if ($record->getConfig()?->getKey() === null && is_string($record->api_plugin)) {
    $configs = app(ConfigRepository::class)->configsFor($record->api_plugin);
    
    $hasOnlyOneConfig = $configs->containsOneItem();
    $pluginSupportsClients = method_exists($record->api_plugin, 'getClients');
    
    $allClientsUseDynamicConfigs = $pluginSupportsClients
        && app($record->api_plugin)->getClients()
            ->contains(fn (Client $client) => !$client->getConfig() instanceof DynamicConfig) === false;
    
    if ($hasOnlyOneConfig && $pluginSupportsClients && $allClientsUseDynamicConfigs) {
        $record->setConfig($configs->first());
    }
}

Now it’s obvious:

• We’re checking if there’s only one config
• We’re checking if the plugin supports clients
• We’re checking if all clients use dynamic configs

The variable names document the intent, not just the implementation. Future-you (or your teammates) will thank you.

Bonus: This makes debugging easier. You can dump individual conditions to see which one is failing.

Sometimes UI state and database state get out of sync – especially with single-option dropdowns in Vue.js where the UI shows a selected value but v-model is actually null. Instead of forcing users to manually fix this, detect and auto-correct it in the backend.

The Scenario

A form dropdown shows one option (e.g., “Production API”), it appears selected visually, but because there’s no “–Select One–” empty option, the v-model is still null. The form submits, and the backend receives null for a required field.

Backend Auto-Fix

public function forRecord(Record $record)
{
    // Auto-assign when UI shows single option but v-model is null
    if ($record->getConfig()?->getKey() === null && is_string($record->api_plugin)) {
        $configs = app(ConfigRepository::class)->configsFor($record->api_plugin);
        
        $hasOnlyOneConfig = $configs->containsOneItem();
        $pluginSupportsClients = method_exists($record->api_plugin, 'getClients');
        
        $allClientsUseDynamicConfigs = $pluginSupportsClients
            && app($record->api_plugin)->getClients()
                ->contains(fn (Client $client) => !$client->getConfig() instanceof DynamicConfig) === false;
        
        if ($hasOnlyOneConfig && $pluginSupportsClients && $allClientsUseDynamicConfigs) {
            $record->setConfig($configs->first());
        }
    }
    
    $dynamic = $record->configs->unique()?->first();
    return $dynamic ? new DynamicConfig($dynamic) : $this->getDefault();
}

When to Use This Pattern

• Only one logical choice exists
• UI appears to show it as selected
• Missing value causes errors downstream
• You want graceful degradation instead of hard failures

When NOT to Use

• Multiple valid options exist
• Selection is genuinely optional
• You want strict validation

This pattern mimics the UI’s apparent behavior in the backend, making the system more forgiving of common UI/UX patterns.

When using Laravel collections with strict return types, be careful with first() – it returns null when the collection is empty, which can cause TypeErrors with strict return type declarations.

The Problem

public function getDefault(): ConfigInterface
{
    return $this->filter(fn ($config) => $config instanceof DefaultConfig)->first();
}

If the filtered collection is empty, first() returns null, but the method signature promises ConfigInterface. PHP 8+ strict types will throw a TypeError.

Solution Options

1. Nullable return type (safest)

public function getDefault(): ?ConfigInterface
{
    return $this->filter(fn ($config) => $config instanceof DefaultConfig)->first();
}

2. Throw exception (fail-fast)

public function getDefault(): ConfigInterface
{
    $config = $this->filter(fn ($config) => $config instanceof DefaultConfig)->first();
    
    if ($config === null) {
        throw new \RuntimeException('No default config found');
    }
    
    return $config;
}

3. Provide default value

public function getDefault(): ConfigInterface
{
    return $this->filter(fn ($config) => $config instanceof DefaultConfig)
                ->first() ?? new NullConfig();
}

Choose based on your use case:

• Nullable for optional values
• Exception for required values
• Default object for null object pattern

The Problem

Your users request a large CSV export of 50,000 orders. You build the file synchronously in a controller:

public function export()
{
    $file = fopen('php://temp', 'w+');
    
    Order::chunk(1000, function ($orders) use ($file) {
        foreach ($orders as $order) {
            fputcsv($file, [$order->id, $order->total, $order->status]);
        }
    });
    
    rewind($file);
    return response()->stream(function() use ($file) {
        fpassthru($file);
    }, 200, [
        'Content-Type' => 'text/csv',
        'Content-Disposition' => 'attachment; filename="orders.csv"',
    ]);
}

The request times out after 30 seconds. The user sees a 504 Gateway Timeout error.

The Fix

Dispatch a queued job that emails the file when it’s ready:

// Controller
public function export(Request $request)
{
    GenerateOrdersReport::dispatch($request->user());
    
    return back()->with('success', 'Report is being generated. We\'ll email you when it\'s ready.');
}

// app/Jobs/GenerateOrdersReport.php
class GenerateOrdersReport implements ShouldQueue
{
    public $timeout = 600; // 10 minutes
    public $tries = 1;
    
    public function __construct(
        private User $user
    ) {}
    
    public function handle()
    {
        ini_set('memory_limit', '512M');
        
        $filename = 'orders-' . now()->format('Y-m-d-His') . '.csv';
        $path = storage_path('app/exports/' . $filename);
        
        $file = fopen($path, 'w');
        fputcsv($file, ['Order ID', 'Total', 'Status']); // header
        
        Order::chunk(1000, function ($orders) use ($file) {
            foreach ($orders as $order) {
                fputcsv($file, [$order->id, $order->total, $order->status]);
            }
        });
        
        fclose($file);
        
        $this->user->notify(new ReportReady($filename));
    }
}

The notification email includes a download link:

// app/Notifications/ReportReady.php
class ReportReady extends Notification
{
    public function __construct(
        private string $filename
    ) {}
    
    public function via($notifiable)
    {
        return ['mail'];
    }
    
    public function toMail($notifiable)
    {
        $url = route('reports.download', $this->filename);
        
        return (new MailMessage)
            ->subject('Your report is ready')
            ->line('Your export has been generated.')
            ->action('Download Report', $url)
            ->line('This link expires in 24 hours.');
    }
}

Why It Works

• No timeout — The job can run for minutes without hitting HTTP limits
• User feedback — Instant response (“We’re working on it”) instead of a hanging request
• Memory control — Explicit ini_set('memory_limit') prevents runaway processes
• Retry safety — $tries = 1 prevents duplicate reports if the job fails midway

Best Practices

1. Set explicit timeouts — Don’t let jobs run forever
2. Clean up old files — Schedule a daily job to delete exports older than 7 days
3. Rate limit export requests — Prevent users from queuing 10 exports at once
4. Track job status — Store $job->getJobId() in the database so you can show “In Progress” UI

For any operation that takes more than 5 seconds, move it to a queue. Users appreciate instant feedback more than waiting for a loading spinner.

The Problem

Your admin panel has a product filter form. Every controller method that renders this view needs to pass the same dropdown data:

// ProductController@index
public function index()
{
    $categories = Category::pluck('name', 'id');
    $brands = Brand::pluck('name', 'id');
    $statuses = ['active', 'draft', 'archived'];
    
    return view('products.index', compact('categories', 'brands', 'statuses'));
}

// ProductController@create
public function create()
{
    $categories = Category::pluck('name', 'id');
    $brands = Brand::pluck('name', 'id');
    $statuses = ['active', 'draft', 'archived'];
    
    return view('products.create', compact('categories', 'brands', 'statuses'));
}

// ProductController@edit
public function edit($id)
{
    $product = Product::findOrFail($id);
    $categories = Category::pluck('name', 'id');
    $brands = Brand::pluck('name', 'id');
    $statuses = ['active', 'draft', 'archived'];
    
    return view('products.edit', compact('product', 'categories', 'brands', 'statuses'));
}

Duplicated logic across multiple methods. When you add a new filter dropdown, you update 5+ methods.

The Fix

Use a view composer to bind data automatically:

// app/Providers/ViewServiceProvider.php
use Illuminate\Support\Facades\View;
use App\Models\Category;
use App\Models\Brand;

public function boot()
{
    View::composer('products.*', function ($view) {
        $view->with([
            'categories' => Category::pluck('name', 'id'),
            'brands' => Brand::pluck('name', 'id'),
            'statuses' => ['active', 'draft', 'archived'],
        ]);
    });
}

Now your controllers stay thin:

public function index()
{
    return view('products.index');
}

public function create()
{
    return view('products.create');
}

public function edit($id)
{
    $product = Product::findOrFail($id);
    return view('products.edit', compact('product'));
}

How It Works

The composer runs before every view that matches products.*. The data is automatically injected, so your Blade templates can access $categories, $brands, and $statuses without the controller passing them.

When to Use It

• Shared dropdown data across multiple views (categories, statuses, countries)
• Default filter values that every page needs
• Navigation menus or sidebars that appear on many pages
• Current user permissions for conditional UI elements

Trade-Offs

The data is fetched on every view render, even if the template doesn’t use it. If your composer queries are expensive, cache them or use class-based composers with dependency injection for better control.

But for simple dropdown data, view composers eliminate duplication and keep your controllers focused on actions, not view preparation.

The Problem

You’re building a CSV export feature for your admin panel. Users can download product catalogs with thousands of rows. You write this:

$products = Product::with(['category', 'brand', 'variants'])
    ->get();

foreach ($products as $product) {
    $row = [
        $product->name,
        $product->category->name,
        $product->brand->name,
        $product->variants->count(),
    ];
    fputcsv($file, $row);
}

The job runs for 2 minutes, then crashes with “Allowed memory size exhausted.” You’re loading 10,000 Eloquent models with all their relationships into memory.

The Fix

Use the query builder directly. Fetch only the columns you need:

DB::table('products')
    ->leftJoin('categories', 'products.category_id', '=', 'categories.id')
    ->leftJoin('brands', 'products.brand_id', '=', 'brands.id')
    ->select([
        'products.name as product_name',
        'categories.name as category_name',
        'brands.name as brand_name',
        DB::raw('(SELECT COUNT(*) FROM variants WHERE variants.product_id = products.id) as variant_count')
    ])
    ->chunk(1000, function ($rows) use ($file) {
        foreach ($rows as $row) {
            fputcsv($file, [
                $row->product_name,
                $row->category_name,
                $row->brand_name,
                $row->variant_count,
            ]);
        }
    });

Why It Works

• Chunking — Processes 1,000 rows at a time instead of loading all 10,000
• Raw arrays — No Eloquent model overhead (attributes, casts, accessors, relationships)
• Selective columns — Fetches only what the CSV needs, not every database column
• Manual joins — One query instead of N+1 queries for each relationship

Trade-Offs

You lose Eloquent’s conveniences (accessors, casts, automatic timestamps). But for batch exports and reports, raw performance matters more than elegant code.

Save Eloquent for interactive UIs where you’re displaying 10-50 records at a time. For bulk operations that touch thousands of rows, drop down to the query builder.