Laravel Patcher

Laravel Patcher is a clean and predictable system for applying one-time patches to your Laravel application. It works similarly to migrations but is designed for operational, data-related, or procedural logic that you need to run once and track.

Inspired by Taylor Otwell’s patching concept, this package formalizes and extends the idea to support a wide variety of use cases, including conditionally skipped patches, tracking applied states, and batch rollback.

---

Features

• Runs patch classes similar to migrations
• Supports anonymous class patches using return new class extends Patch
• Automatically tracks execution via the patches database table
• Supports conditional execution via shouldRun()
• Distinguishes executed vs skipped patches using is_applied
• CLI output styled identically to php artisan migrate
• Allows rollback by batch

---

Installation

composer require danielemontecchi/laravel-patcher

Laravel will automatically register the service provider.

To create the required database table, run:

php artisan migrate

Patch Table Format

The patches table includes:

Column	Type	Description
id	bigint	Auto-increment primary key
name	string	Patch filename (without .php)
batch	int	Batch number (like migrations)
is_applied	boolean	Whether shouldRun() returned true and the patch was executed
applied_at	timestamp	When the patch was recorded

Skipped patches are still recorded, but with is_applied = false.

---

Creating a Patch

php artisan make:patch FixUsernames

This will generate a new file in database/patches/:

<?php

use DanieleMontecchi\LaravelPatcher\Contracts\Patch;

return new class extends Patch {
    public function shouldRun(): bool {
        return true; // Logic to determine if patch should run
    }

    public function up(): void {
        // Logic to apply
    }

    public function down(): void {
        // Logic to rollback
    }
};

Patches must return an anonymous class instance that extends Patch.

---

Executing Patches

php artisan patch

Executes all unapplied patches, skipping those already registered in the patches table. Patches for which shouldRun() returns false are marked as skipped and recorded accordingly.

---

Rolling Back Patches

php artisan patch:rollback

Rolls back the latest batch of applied patches (only those where is_applied = true).

Use the --step=N option to rollback multiple batches:

php artisan patch:rollback --step=2

---

License

Laravel Patcher is open-source software licensed under the MIT license. See the LICENSE.md file for full details.

---

Made with ❤️ by Daniele Montecchi