Ezmigrationbundle2 Laravel Package

Getting Started

Install the package via Composer and publish its config so you can see the step definitions the mass_migrate command reads from:

composer require <vendor>/<package>
php artisan vendor:publish --tag=<package>-config

Look first at the published config file — it is the source of truth for which migration "steps" run and in what order. Each step maps to an executor (e.g. php, artisan calls). This is where you will spend most of your time.

Your first use case is almost certainly a deployment pipeline:

1. Define one or more steps in config (a php step that runs a closure/script, or an artisan invocation).
2. Run the batch with php artisan mass_migrate.
3. If migrations touch auth-guarded code paths, add --admin-login so the command executes with an authenticated admin context rather than failing mid-migration.

Verify the install by running mass_migrate on a scratch database and watching per-step output before wiring it into CI.

Implementation Patterns

Config-driven step pipelines. Treat the config as a declarative migration plan. Keep steps small and single-purpose; the php executor is the general-purpose escape hatch when no dedicated executor fits. Order matters — dependencies between steps are implicit in list order, so document them inline.

Wrap steps in idempotent operations. Because mass_migrate runs a batch, any step that is not idempotent will cause problems on retry after a partial failure. Guard data-mutating steps with existence checks.

Use --admin-login for auth-sensitive migrations. When a migration or step invokes application code that goes through authorization (policies, gates, auth()->user() assumptions), run:

php artisan mass_migrate --admin-login

This avoids the classic "works in tinker, fails in migration" auth failure. Note the 1.0.5 fix — this flag was silently broken for migrate commands since 1.0, so any prior workaround you built can likely be removed.

Integrate into deploy scripts, not manual runs. A typical pattern:

php artisan down --render="errors::503"
php artisan mass_migrate --admin-login
php artisan up

Capture the exit code — 1.0.5 improves error reporting after a migration failure in mass_migrate, so non-zero exits should now be reliable and meaningful.

Custom executors. If the built-in php executor is too coarse, extend it rather than stuffing logic into a mega-closure. Keeping custom executor classes testable in isolation pays off because they run inside the migration transaction boundary.

Gotchas and Tips

• Upgrade to 1.0.5 if you rely on --admin-login with migrate. It has been broken since 1.0; scripts that "worked" were likely running unauthenticated without you noticing. Re-audit any auth-dependent migration after upgrading.
• The php executor now catches PHP Errors, not just Exceptions. Prior to 1.0.5, a TypeError, Error, or similar would bubble past the executor's error handling and could leave a batch in an inconsistent state. If you previously wrapped steps in defensive try/catch (\Throwable) blocks as a workaround, retest and consider removing them.
• Post-migration error reporting was fixed in mass_migrate. Previously, failures after the migration phase could produce misleading output. If you parse command output in CI (grep for "failed"), recheck your matchers — the wording/exit behavior may now differ.
• Debugging a failing step: run with maximum verbosity (-vvv) and isolate the step by commenting out other steps in config. Because steps share a process, a failure in step N can be a side effect of step N-1.
• Config caching: if you use php artisan config:cache in deploy, remember to re-run it after changing step definitions — mass_migrate will read the cached config, not your edits.
• Transactions and DDL: steps that run DDL implicitly commit on MySQL, so a failure mid-batch is not rolled back. Design for resume, not rollback.
• Extension points: the step executor is the right seam for custom behavior; avoid subclassing the command itself, since command internals (option handling, error reporting) are exactly what changed in 1.0.5 and may change again.