Download the PHP package cyberwizard/schedule-catchup without Composer

Schedule Catchup

Laravel's scheduler does nothing while your server is down. When it comes back, the slots it missed are simply gone, and nothing in the framework goes looking for them. This package does.

It records every scheduler tick, keeps a ledger of which cron slots actually ran, and replays the ones that were skipped while the app was offline. Replayed events run once, oldest first, with retries bounded so a command that fails every time can't block everything behind it.

Contents

• Requirements
• Installation
• Tagging events
• How it works
• Configuration
• Events and callbacks
• Commands
• Traits
• Tables
• Testing
• Changelog
• Contributing
• Security
• License

Requirements

• PHP 8.2 or newer
• Laravel 11, 12, or 13

Installation

The service provider is discovered automatically. It registers schedule-catchup:run and schedule-catchup:heartbeat, and puts both on a five-minute schedule with withoutOverlapping() and onOneServer().

If you want to change the defaults, publish the config file:

Tagging events

Only tagged events get replayed. Add replayOnCatchup() to the events where a missed run actually matters:

Leave high-frequency pollers alone. Replaying a sync that already runs every five minutes is rarely what you want, and tagging it just gives the catch-up run more work to skip.

How it works

schedule-catchup:heartbeat writes the current time to a checkpoint table every five minutes. That timestamp is the last moment the scheduler is known to have been running.

A listener on ScheduledTaskFinished records each normal run of a tagged event against the cron slot it satisfied. That ledger is what lets the package tell a missed slot apart from one that already ran, so a restart can't trigger work the scheduler had already done.

When schedule-catchup:run fires, it walks each tagged event's cron expression from the checkpoint up to now, drops the slots already in the ledger, and runs what's left oldest-first. The checkpoint only moves forward once nothing is pending, so a failure partway through doesn't lose the rest of the window and doesn't cause a double run on the next pass.

A failed occurrence keeps an attempt count and is retried on later runs. Once it hits max_attempts it's marked settled, which stops a command that fails every single time from holding the checkpoint back forever. If a run is skipped because the command was already running, it counts as deferred rather than successful, and gets picked up again once the overlap clears.

There's also a per-event cap (max_occurrences) on how much gets replayed in one pass. If a long outage produces more occurrences than the cap, the rest drain over subsequent runs instead of one run trying to do everything at once.

Configuration

Events and callbacks

If you'd rather not register a listener, the same two hooks can be set in config:

Order of operations is: replays finish, then ScheduleCatchupCompleted, then on_replay. If anything failed, ScheduleCatchupFailed and on_failure follow.

ScheduleCatchupFailed only fires for new failures and final give-ups. Intermediate retries stay quiet, so one broken command doesn't turn into an alert every five minutes.

Commands

--only does not advance the checkpoint, which makes it safe for a one-off replay of a single event.

Traits

ResolvesScheduledTime is for commands that need to know which slot they're standing in for. During a replay that's the missed occurrence, not the current clock time, so month and day arithmetic lands in the period the run was meant to cover:

RecordsScheduleRun runs a callback at most once per period, including across concurrent workers:

Tables

The package creates three tables, prefixed with cyber_ unless you change table_prefix:

• cyber_schedule_catchup_checkpoints holds the last_tick timestamp.
• cyber_schedule_catchup_logs is the run ledger: one row per (command, scheduled_at), with the source (catchup or scheduled), exit code, attempt count, and last error.
• cyber_schedule_command_runs backs the RecordsScheduleRun trait, unique on (command, period_key).

Testing

The suite runs on Orchestra Testbench with an in-memory SQLite database, so there's no setup beyond composer install.

Changelog

See CHANGELOG.md.

Contributing

Pull requests are welcome. Run composer test before opening one, and keep the change scoped to a single concern.

Security

If you find a security issue, report it through GitHub's private security advisories rather than a public issue.

License

MIT. See LICENSE.