Migration Checker Bundle Laravel Package

Getting Started

This is a Symfony bundle (roslov/migration-checker-bundle) that reports pending Doctrine migrations — there is no Laravel service provider and no extra.laravel block, so composer require will not auto-register anything in a Laravel app. Treat 1.0.0 as two separate things: (a) a small, reusable "are there unapplied migrations?" checker class you can call from Laravel, and (b) a Symfony console integration you will not use in Laravel.

Minimal steps for a Laravel developer:

1. composer require roslov/migration-checker-bundle:^1.0 --dev — dev-only; nothing here belongs in production runtime deps.
2. Look first at the source, not the README. The 1.0.0 notes only mention badge additions, so the README still tells you almost nothing about usage. Start at the checker service class and the console command class; the config tree (DependencyInjection/Configuration.php) is the authoritative list of options after the refactor.
3. Confirm the console command name with bin/console list if you are in a Symfony context — PR #36 ("Refactored code") is the most likely place a command name or namespace changed silently between 0.5 and 1.0.
4. First real use case: a pre-deploy / CI gate. In Laravel the equivalent is a tiny Artisan command that calls Artisan::call('migrate:status') and fails on Pending, or a migrate --pretend dry run. Use this package directly only if you are running Doctrine migrations (e.g. a legacy Symfony service, or a Doctrine-based sub-application) alongside your Laravel app.

If you are 100% Laravel-only with Eloquent migrations, this package will never see your migrations — see Gotchas.

Implementation Patterns

CI gate (the primary pattern). The whole value of the package is a non-zero exit code when migrations are outstanding. Wire it as a step that runs before deploy and after the new release is checked out but before traffic shifts:

- run: composer install --no-dev -o
- run: bin/console <checker-command>   # verify name after 1.0 refactor

Verify the exit code contract yourself on first run — refactors in a 1.0 bump frequently "improve" output while changing 0/1 semantics, and a gate that always returns 0 is worse than no gate.

Deploy-hook pattern. Run the check as a post-deploy smoke test against the deployed environment's connection, then alert rather than block if it fails. This catches the "migrations ran on staging but the wrong DB URL was injected into prod" class of bug, which a build-time check cannot see.

Bridging into Laravel. Wrap the checker service in a thin Artisan command so the rest of your team only ever types php artisan app:migrations:check:

public function handle(SomeCheckerContract $checker): int
{
    return $checker->hasPendingMigrations() ? self::FAILURE : self::SUCCESS;
}

Bind the checker in a service provider, do not resolve it via app() inside the command — the refactor in 1.0 makes constructor signatures the most likely breakage point, and a container binding confines that change to one file.

Reuse the class, skip the bundle. The pending-migrations decision is usually a handful of lines: read the migration versions table, diff against files on disk. Pulling in the bundle for that is only worth it if you also want the console plumbing and the config surface. If you only need the boolean, copy the logic and drop the dependency — you will own it, but you will also stop tracking a package whose changelog is three PR titles long.

Upgrade pattern for 0.5 → 1.0. Pin 0.5.0 in a branch, run your test suite, then bump to 1.0.0 and diff the two vendor/ trees (git diff --no-index on the extracted package directories) to surface renamed classes, moved namespaces, and removed config keys. With a three-line changelog, the diff is the documentation.

Gotchas and Tips

• 0.x → 1.0.0 is a major bump; assume breaking changes. "Refactored code" (#36) plus "Upgraded Migration Checker to 1.0" (#37) with no migration guide means renamed classes, moved namespaces, or changed config keys are all on the table. Read the upgrade as a fresh integration, not a patch.
• It reads Doctrine's doctrine_migration_versions table, not Laravel's migrations table. On a mixed app you will get a false "all clear" for your Eloquent migrations, or a false alarm if the Doctrine table does not exist. Confirm which connection and which table the checker queries before trusting a green result.
• No Laravel package discovery. There is no extra.laravel in composer.json, so no facade, no config publish, no auto-registration. Any config you want in a Laravel app has to be hand-wired through a service provider.
• Bundle naming is a tell. "Bundle" means Symfony Kernel registration via bundles.php; if you follow a Symfony tutorial you will edit files that do not exist in a Laravel app. Translate: config → config/*.php + a provider, console command → app/Console/Commands, service → container binding.
• Debugging: run with -vvv first; if the command is not found after upgrading, it was renamed — list will show it. If the checker reports pending when you believe there are none, check the connection resolution and the migrations path config before assuming a bug — path mismatches are the usual culprit.
• Thin README is the real risk. Badges were added (#35) but usage docs were not. Budget time to read the source; do not plan to "look it up in the docs" mid-incident.
• Extension points: the checker service is the seam — prefer decorating or wrapping it over injecting the bundle's command class. If 1.0 moved namespaces, only your wrapper needs editing.
• Pin the version. "roslov/migration-checker-bundle": "1.0.0" exactly, and review 1.0.1 before floating. A refactor-heavy major from a single maintainer is not a range you want to auto-advance in CI.