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:

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

danielemontecchi / laravel-patcher

Maintainers

Details