Cron Event Laravel Package

Getting Started

• This is the first public release (v1.0), so treat the release notes as the primary documentation until more docs are available. The package is MongoDB-only and supports two schedule types: Event (recurring) and Timer (one-off/delayed), plus cron:run and cron:list commands.
• Install with Composer, then confirm the MongoDB PHP extension and Laravel MongoDB integration are configured. Check config/database.php for the mongodb connection and ensure the package config points at it.
• Publish any package config and run the package's install/migration step to create collections and indexes. Verify indexes on the due/next-run fields before loading production data.
• Add the system cron entry. The package is driven by cron:run, which is intended to be invoked every minute:

* * * * * cd /path/to/app && php artisan cron:run >> /dev/null 2>&1

• First use case: create a single Event with a cron expression (for example, every five minutes), then run php artisan cron:list to confirm it is registered and php artisan cron:run manually to observe execution before wiring in real handlers.
• Where to look first: the package config file, the service provider (to see command registration and bindings), the Event/Timer models or collections, and the cron:run/cron:list command classes.

Implementation Patterns

• Use Event for recurring work expressed as a cron expression (reports, cleanups, sync jobs). Use Timer for one-shot or delayed execution; do not model recurring work as a Timer unless you re-create it after each run.
• Keep schedule definitions in code (seeders or a dedicated scheduling service) for reviewability, and treat the MongoDB collections as runtime state. This avoids “mystery schedules” that exist only in production.
• Handlers should dispatch queued jobs rather than doing heavy work inside cron:run. This keeps the every-minute command fast and prevents overlapping invocations.
• For multi-node deployments, confirm how the package claims due schedules. If it uses atomic findOneAndUpdate-style locking, run cron:run on every node and let MongoDB arbitrate; otherwise designate a single runner or add an external lock.
• Operational workflow: cron:list for inventory and spot checks, application logs for execution history, and a heartbeat/alert on “no successful run in N minutes.”
• Local development: run php artisan cron:run manually, or invoke it from a wrapper scheduler process. Freeze time with Carbon::setTestNow() and use a dedicated test database to make schedule behavior deterministic.
• Integration tip: have handlers implement idempotency (unique job keys or “already processed” checks), since a delayed or retried run should not double-apply side effects.

Gotchas and Tips

• MongoDB only. There is no SQL/Redis/queue-table backend in v1.0. Budget for the MongoDB extension, connection configuration, and operational knowledge (backups, replica set, monitoring). If your infrastructure is SQL-only, this package is not a drop-in fit.
• Do not nest it in Laravel's scheduler. cron:run expects to be called every minute by system cron. Registering it inside Kernel::schedule() creates a confusing double-scheduling layer and makes timing harder to reason about.
• Overlap risk. If a run takes longer than the cron interval, invocations can stack. Keep handlers fast, dispatch to queues, and verify whether the package provides per-event locking; add withoutOverlapping-style protection at the handler level if not.
• Timezone and DST. Cron expressions are evaluated in the application timezone. Confirm the config value, and test behavior around DST transitions for jobs scheduled in the skipped or repeated hour.
• Timer semantics. Validate whether a Timer is consumed on fire or persists. Design one-shot jobs so a missed or duplicate fire is tolerable, and clean up completed timers to prevent collection growth.
• Indexes matter. With MongoDB, missing indexes on due-time fields turn every cron:run into a collection scan. Create them during deployment, not after the first production incident.
• Debugging. Use cron:list to confirm registration, run cron:run in the foreground to see output, and check the package's log channel. If nothing fires, verify the system cron entry, the PHP binary path, the working directory, and the MongoDB connection before suspecting the schedule expression.
• Testing. Isolate test collections and truncate them between tests; otherwise schedules leak across test cases and produce flaky “job ran twice” failures.
• Extension points. Favor wrapping schedule creation in your own service class and dispatching your own jobs from handlers. That keeps you insulated if event schemas or command names change in later 1.x releases.