Command Scheduler Laravel Package

Getting Started

• Install with composer require <vendor>/<package>; Laravel package auto-discovery registers the service provider, so no manual wiring is usually needed.
• Publish and run the migrations (php artisan vendor:publish --tag=... then php artisan migrate). The package creates a history table backing the ScheduledCommandHistory model.
• Confirm your scheduler actually runs (php artisan schedule:work locally, cron + schedule:run in production). History is only recorded for commands executed through the scheduler, not for ad-hoc php artisan <command> invocations.
• First use case: after a scheduled run, inspect ScheduledCommandHistory::latest()->first() in Tinker and check the recorded command, exit code, timestamps, duration, and captured output. That single query answers the most common day-to-day question — "did last night's job actually run, and did it succeed?"
• Where to look first: the ScheduledCommandHistory model (in v5 it is configured with PHP attributes rather than class properties), the package config file (table name, model override, retention), and the published migration to understand the schema you'll be querying.

Implementation Patterns

• Failure alerting. Schedule a small command or job that queries records with a non-zero exit code in the last N minutes and notifies your team. This is the highest-value use of the package: it turns silent scheduler failures into actionable alerts.
• Dashboards and reporting. Wrap history queries in a controller or Filament resource, filtering by command name and date range. Aggregate duration per command to spot slow jobs before they time out.
• Retention/pruning. The history table grows quickly on high-frequency schedules. Add a scheduled prune (delete records older than X days) — ideally scheduled through the same scheduler so pruning itself is visible in the history.
• Custom model extension. If you need extra scopes or accessors, extend ScheduledCommandHistory and point the config at your subclass. Because v5 configures the base model via attributes, mirror those attributes on your subclass or you'll lose table/fillable/connection settings that used to be inherited from properties.
• Testing. Use Schedule::fake() / event fakes to assert commands are scheduled, and seed history rows directly to test your alerting/dashboard code. If your test container binds Doctrine services, note that v5.0.6 specifically resolves a Doctrine service injection problem in the package's own tests — mirror that container setup if you copied their test scaffolding.
• Output capture. Long-running commands can produce large output. Truncate before persisting if you post-process it, and consider trimming output in your alert payloads so notifications stay readable.

Gotchas and Tips

• v5.0.6 is an internal patch (coding standards, PHPStan fixes, attribute refactor of ScheduledCommandHistory, Doctrine injection fix). It is safe to bump, but the attribute refactor is a signal: if you extended the model in a v4-style (properties) codebase, re-verify your subclass still resolves the right table and fillable fields.
• Doctrine service injection only affects tests; if you maintain a fork or copied test suite that binds Doctrine services, upgrade to ≥5.0.6 to avoid container resolution failures.
• Manual runs aren't recorded. If history is empty, first check that the command ran via the scheduler and that the service provider is registered — this is the most common false alarm.
• Exit codes matter more than output. 0 = success, 127 = command not found, 126 = permission denied. Alert on the code; use output as context.
• Overlapping runs and withoutOverlapping. Skipped runs may not appear as failures — decide explicitly whether skipped executions should surface in your alerting, otherwise genuinely stuck jobs can look healthy.
• Timestamps and timezones. Compare started_at/finished_at against a known timezone; mixing app timezone and UTC is an easy source of off-by-hours alerting bugs.
• Pruning is your responsibility. Treat retention as configuration you own from day one, not something to bolt on when the table hits millions of rows.
• Extension points: config (model class, table, retention), model attributes/observers for custom behaviour, and the underlying scheduler events if you want to hook recording or notification yourself.