Download the PHP package simone-bianco/laravel-patches without Composer

Laravel Data Patches

This package provides a migration-like system for incremental Laravel data changes. It is designed for data that should be ordered, replayable, reversible, and easier to review than a large monolithic seeder.

Use it for:

• Replacing bulky Laravel seeders with small, ordered data patches.
• Seeding initial application data such as roles, settings, content, sources, reference data, or demo/domain records.
• Deploying controlled production data changes that need a rollback path.
• Keeping large seed payloads close to their patch without making every support file executable.

Installation

Publishing creates:

• config/sb-patches.php
• a migration for the sb_patches tracking table

Configuration

config/sb-patches.php can define global hooks around patch execution and rollback. Each hook must be a fully qualified class with an __invoke method.

Patch formats

The package supports two executable patch formats under database/patches.

1. Classic file patch

This is best for small data changes where the full patch fits cleanly in one file.

2. Module patch directory

The runner executes only patch.php. Any other file inside the module directory is support material and is ignored by discovery, even if it is PHP.

Module patches are the recommended format for substantial seed data. Keep patch.php focused on behavior and put large arrays, JSON payloads, localized copy, source maps, or helper data next to it.

Identifiers and order

Patch identifiers are normalized paths relative to database/patches.

Classic file:

identifier:

Module patch:

identifier:

Execution order is alphabetical/natural by identifier. This keeps ordering based on names and timestamp prefixes, regardless of whether a patch is a direct file or a module directory.

A duplicate classic/module identifier is invalid. For example, these two cannot coexist:

Creating patches

Create a classic patch file:

Create a module patch directory:

Create a module patch with an empty data.php file:

--data implies --module.

Patch structure

A patch returns an anonymous class extending Patch.

For module patches, patch.php may read local support files.

Applying patches

Run all pending patches:

Limit the number of applied patches:

The runner discovers executable entries only:

• timestamped direct PHP files: YYYY_MM_DD_XXXXXX_name.php
• patch.php inside timestamped module directories: YYYY_MM_DD_XXXXXX_name/patch.php

Non-timestamped PHP files and module support files are ignored.

Forcing a single patch

Run one patch by identifier without recording it in sb_patches:

This resolves both classic and module formats. It is useful for compatibility seeders and explicit replay/debug checks, not for normal deploy tracking.

Rolling back patches

Roll back the last batch:

Roll back a number of recently applied patches:

Roll back every applied patch:

Rollback in production asks for confirmation. Use --force only in controlled deployment scripts.

Re-apply from scratch:

Using the facade

Seeder best practices

Large seeders should be split into patch modules rather than kept as one huge seeder class.

Recommended split examples:

Keep each patch responsible for one reversible concern. Avoid broad deletes, truncates, or unrelated data cleanup inside seed patches.

Testing

License

The MIT License (MIT). Please see the license file for more information.