Task Schedule Laravel Package

Getting Started

• Install with composer require dagasmart/task-schedule, then publish the package assets (config and migrations) via php artisan vendor:publish --provider="DagasMart\\TaskSchedule\\TaskScheduleServiceProvider" (check the provider/tag names in the package README — tags are often task-schedule-config and task-schedule-migrations).
• Run php artisan migrate. This creates the table that stores task definitions (command, cron expression, active flag, timestamps/output columns).
• Look first at the published config file (config/task-schedule.php) and the package's Task model. These tell you what fields are available for scheduling, enabling/disabling, and monitoring.
• Wire the package runner into Laravel's scheduler. The typical pattern is a single entry in app/Console/Kernel.php (or routes/console.php in Laravel 11+): $schedule->command('task-schedule:run')->everyMinute()->withoutOverlapping();. The package then evaluates your DB-stored tasks and dispatches the ones whose cron expressions are due.
• Minimal first use case: create one row representing an existing artisan command (e.g. inspire or a custom reports:daily), set its cron expression to * * * * *, confirm it is active, and watch it execute on the next scheduler tick. This validates the install end-to-end before migrating real jobs into the table.

Implementation Patterns

• DB-driven schedules as the source of truth. Move recurring jobs out of hard-coded Kernel entries and into rows, so operators can pause, reschedule, or add tasks without a deploy. Keep a small number of infrastructure schedules (the package runner, queue workers, backups) in code.
• Wrap logic in invokable/command classes, not closures. Store the command signature (or a class reference) in the task record so tasks remain reviewable, testable, and safe to serialize. Closures stored in the DB are fragile across deploys.
• Environment seeding. Seed a baseline set of task rows per environment (TaskSeeder) and treat the table as configuration: idempotent updateOrCreate keyed on a stable task name/slug.
• Enable/disable workflow. Use the package's active flag rather than deleting rows, so history and cron expressions survive. Pair with an admin UI or a simple artisan command (tasks:enable, tasks:disable) for day-to-day operations.
• Monitoring hook. Persist last_run_at, last_exit_code, and captured output where the package exposes them, and add a scheduled alert (or Laravel Pulse/health check) for tasks that are active but haven't run within their expected window.
• Layered scheduling. Let the package's per-minute runner act as a dispatcher, and push long-running work onto the queue (->onQueue(...) or a queue-backed command) so the scheduler tick stays fast and doesn't block other due tasks.
• Local development. Either run php artisan schedule:work or trigger php artisan task-schedule:run directly to test a single task record without waiting for a tick.

Gotchas and Tips

• Overlapping executions. The single per-minute runner can start a new task before the previous one finishes. Use withoutOverlapping() on the runner and/or the package's own mutex support, and keep long jobs on the queue.
• Multi-server mutexes. withoutOverlapping and onOneServer rely on a shared cache store. In multi-node deployments, set CACHE_DRIVER to Redis/Memcached/database — the file driver silently breaks "only run once" guarantees.
• Timezone and DST. Cron expressions are evaluated in the app timezone unless the package exposes a per-task timezone. Confirm the behaviour around DST transitions; schedules like 0 2 * * * can be skipped or duplicated. Test with Carbon::setTestNow() around the boundary.
• Cron validation. Invalid expressions can be stored without error and then silently never match. Validate on save (the package typically uses dragonmantank/cron-expression); add a test that every seeded task parses.
• Config/migration publishing after upgrades. When updating to a new patch (2.0.11 is a patch release, so no breaking changes are expected from 2.0.x), re-publish and diff the config/migrations to pick up new options; run php artisan config:clear and php artisan optimize:clear after changing scheduling config.
• Output and exit codes. Capture command output to the DB/logs; without it, a failing task is invisible once the scheduler tick returns. Ensure non-zero exit codes are surfaced and alerted on.
• Disabled ≠ paused mid-flight. Toggling a task off prevents future dispatches but does not stop an in-progress run; design tasks to be idempotent and interruptible.
• Permissions and deploy order. If the runner writes run history, ensure the deploy user owns the cache/storage paths, and run migrations before the scheduler ticks after a deploy to avoid querying a missing table.
• Extension points. Prefer the package's events/model hooks (e.g. TaskStarting/TaskFinished style events, if present) for logging and alerting rather than editing vendor code; keep customisations in a service provider or a subclassed Task model bound via the container.