README

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:

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