Laravel Patches Laravel Package

Getting Started

• Install with composer require rappasoft/laravel-patches, then follow docs/installation.md — it now documents two paths: the migration set for existing v4.0.x users (unchanged in 4.1.0) and the upgrade path from v3. Read the one that matches your install before running anything.
• Look at these three things first, in order: the published config (for stop_on_error), the patch-execution table migration (this is your audit/history surface), and docs/error-handling.md, which is the doc most affected by this release.
• Verify your runtime matrix before anything else: Laravel 11/12 on PHP 8.2 is fine; Laravel 13 requires PHP 8.3+. If you're on Laravel 11, treat it as a legacy target (see Gotchas).
• First real use case: a one-off data patch — a backfill, a normalization pass, a corrected row set that doesn't belong in migrations/. Write a patch class with up()/down(), run it, confirm the execution record lands in the table, then roll the batch back in staging to prove down() actually works. Do that drill before you ship a patch that touches production data.

Implementation Patterns

• Separate schema from data. Keep migrations/ for structure and this package for one-off data movement. The value of the package is the execution record and batch semantics, not schema versioning — don't blur the two or you'll fight both systems' rollback ordering.
• Treat down() as production code. As of 4.1.0 a throwing down() stops the rollback, rethrows the original exception, and keeps the patch execution record. That's a safer default, but it means your down() is now on the critical path for rollback ordering. Write it deliberately; if it's genuinely irreversible, make it fail loudly rather than silently no-op.
• Wrap partial changes in a transaction. The release notes are explicit: preserving the execution record does not undo partial database changes made before down() threw. If your down() deletes then re-inserts, wrap it in DB::transaction() so a failure leaves nothing half-applied.
• Group work into batches per deploy. Batch-scoped rollback is the natural unit — one batch per release — so a single rollback command reverses exactly what that deploy introduced. Listen for the rollback completion/failure events for alerting; in 4.1.0 they carry the original batch, so you can map a failure straight back to the deploy that created it.
• Rely on stop_on_error only for forward runs. It governs running patches. Rollback now always stops on failure, by design, to preserve rollback order. Don't try to configure your way around that — it's an invariant, not a setting.
• Make patches idempotent. After a failed rollback the record survives, so a patch can plausibly be re-attempted. Guard with existence checks or updateOrCreate rather than blind inserts.
• CI/deploy integration: run patches as an explicit step after migrate, never interleaved, and run rollbacks only as a deliberate operator action — not automatically as part of a failed deploy hook.

Gotchas and Tips

• A failed rollback no longer looks "clean." Before this release a failed patch could be reported as rolled back and its history discarded. Now the record stays. If your dashboards or deploy scripts assumed "rollback finished ⇒ history is empty," they will now see a leftover record — that's the fix working, not a bug.
• Correct the failure first, then retry. The documented upgrade guidance is unambiguous: fix whatever made down() throw before re-running the rollback. Retrying against a half-reverted dataset is how you get inconsistent data.
• Don't disable Composer security audits. Four advisories are allowlisted only in the temporary Laravel 11 compatibility CI. Production composer audit remains enabled by design — leave it that way.
• Laravel 11 is compatible but out of security support with unresolved upstream framework advisories. For production, target Laravel 12.69+ or 13.30+; staying on 11 is a compatibility bridge, not a destination.
• Upgrading from 4.0.x needs no new migrations — but v3 → v4 does, and the old install instructions conflated the two. 4.1.0 corrected the docs and version metadata; re-read them rather than trusting cached instructions from an earlier release.
• Debugging a stuck rollback: query the patch execution table for records left behind after the failure, then check the log for the original exception — it's rethrown, so it surfaces normally rather than being swallowed. That pairing (retained record + rethrown exception) is the debugging trail.
• Testing: 154 tests / 403 assertions cover the new rollback-history and original-event-batch behaviour. If you write your own integration tests around rollback, assert on batch identity in the events, not just that an event fired — batch propagation is the specific thing this release changed.