Laravel Data Migrations Laravel Package

Getting Started

The 2.0.2 release is a patch-level addition (a new --graceful CLI option), so there are no breaking changes to absorb from 2.0.x — the practical work is discovering which commands accept the flag and deciding whether your existing invocations should adopt it.

Minimal steps:

1. Bump and install:

   composer require <vendor>/<package>:"^2.0.2"
   php artisan vendor:publish --provider="<Vendor>\\<Package>\\<Package>ServiceProvider"   # if a config file ships
   

2. Find the entry point before reading source: run php artisan list and look for the command namespace, then php artisan <command> --help. The --help output is the authoritative answer to which commands registered the new flag — the release note does not enumerate them, so verify rather than assume it is global.
3. First use case: run the command once manually against a non-production connection, first without the flag, then with php artisan <command> --graceful -v, and compare exit codes (echo $?). The whole value of the flag is a behaviour change on failure, so confirm the failure semantics on day one rather than after it silently swallows an error in a cron job.

If the package is consumed as a library rather than a command, treat 2.0.2 as a no-op upgrade — a CLI flag has no effect on programmatic call sites unless you route through Artisan::call().

Implementation Patterns

Adopt it deliberately in scheduled work. The natural home for --graceful is anything cron-driven where a non-zero exit triggers alerting you do not want. Note that Laravel's scheduler invokes commands through the same signature string, so the flag is set there, not in PHP:

$schedule->command('<command> --graceful')->daily()->withoutOverlapping();

Mirror the flag through Artisan::call() when triggering from application code (controllers, jobs, other commands):

Artisan::call('<command>', ['--graceful' => true]);

Boolean options are passed as true; do not pass '--graceful=1' as a key.

Cover it in a feature test so the semantics are pinned when the next patch lands:

$this->artisan('<command> --graceful')->assertExitCode(0);
$this->artisan('<command>')->assertFailed();

Pair with quiet mode in cron (--graceful -q) and let the log channel, not the exit code, be your signal. If the package only downgrades errors to warnings under --graceful, confirm your configured log level and channel actually capture warnings rather than dropping them.

Keep your own guardrails outside the flag. Because graceful mode can turn a genuine misconfiguration into a successful-looking run, wrap destructive or financially significant invocations with your own preflight checks (connection reachable, expected row counts) rather than relying on the CLI to fail loudly.

Gotchas and Tips

• Exit codes are the contract. Verify with echo $? whether --graceful returns 0 on failure, or a distinct non-zero code. The former is convenient for cron and hostile to monitoring — it defeats ->onFailure() callbacks and most uptime checks.
• Scope is likely per-command, not per-package. Check --help on each command you use; a flag added to one command in 2.0.2 will not appear on siblings, and passing an unregistered option throws RuntimeException: The "--graceful" option does not exist.
• CLI-only means invisible to library callers. Refactoring a scheduled command into a queued job silently drops the flag's behaviour. If graceful degradation matters there, replicate it with try/catch and an explicit log.
• Scheduler interaction. withoutOverlapping() acquires its lock regardless of exit code, but onFailure()/emailOutputOnFailure() will not fire if graceful mode reports success. Audit any failure hooks before enabling the flag.
• No config fallback assumed. Do not expect a 'graceful' => true config key unless you find it in the published config or the package's source; the release note describes a CLI option only. If you need it everywhere, wrap invocations in your own command or a small helper rather than editing vendor config.
• Debugging a "successful" failure. Run without --graceful and with -vvv to recover the original exception and stack trace; graceful paths often log at warning level, which many default stack channels discard in production.
• Pin the constraint to ^2.0.2 (or ~2.0.2 if you want strict patch-level control). Since the change is additive within 2.0.x, an unpinned ^2.0 will pick it up implicitly on the next composer update — useful to know if behaviour changes appear "for free" in CI.
• Extension point: if the package resolves behaviour through a container binding or a Manager-style driver, check whether graceful mode is overridable there. Adding a decorator around the service is usually cleaner than threading the flag through call sites.