laravel-patches

name	laravel-patches
description	Build and run one-off Artisan "patches" with the aaix/laravel-patches package — trackable, disposable commands for data migrations and one-time fixes (not schema changes — those are still migrations).

Laravel Patches

A patch is a hidden Artisan command that extends Aaix\LaravelPatches\Commands\PatchCommand and is logged in the patch_logs table after a successful run, so it isn't executed twice by accident.

Scaffolding

Always generate via Artisan — never hand-write the file:

php artisan make:patch FixUserEmails

Creates app/Console/Commands/Patches/Patch_{Y_m_d}_FixUserEmails.php with signature patch:{Y_m_d}_fix-user-emails. Implement logic in handle(): int and return self::SUCCESS / self::FAILURE. Wrap multi-step writes in DB::transaction(...); chunk large backfills.

Running

• php artisan patch — interactive checklist of pending patches (recommended).
• php artisan patch:{Y_m_d}_fix-user-emails — run a specific patch by signature.
• php artisan patch --patch=Patch_… / --all — non-interactive. Warn before suggesting --all in production.

Already-applied patches prompt for confirmation and increment run_count.

Status & sync

• php artisan patch:status — lists ran vs. pending.
• php artisan patch:sync — for onboarding an existing codebase: marks existing patch files as run without executing them. Never suggest patch --all for that case.

Config (config/patches.php, optional)

table (default patch_logs), path (default app/Console/Commands/Patches). The namespace of generated patches follows path automatically.

Pitfalls

• Don't use migrations for one-off data fixes — migrations re-run on fresh setups, patches don't.
• Don't rename a patch file after it has been logged — patch_logs.patch_class stores the FQCN, so it'll look pending again.
• Don't delete a pending patch to skip it — use patch:sync.