Download the PHP package faerber/laravel-kernel-cadence without Composer

Laravel Kernel Cadence

Give your every-N-minutes scheduled tasks an explicit phase, so they stop stacking on the top of the hour.

The problem

Laravel's everyFiveMinutes(), everyTenMinutes(), everyFifteenMinutes() and friends all phase-lock to minute 0. The hour-based helpers already take an offset — hourlyAt(17), everySixHours(18), everyTwoHours(25) — but the minute-based ones do not, so the only way to stagger sub-hourly work is to drop out of the fluent API into raw cron:

That matters because scheduled commands are usually thin dispatchers onto one queue, which fans straight out to every worker and lands on the database at once. Reaching for the default helper silently signs your task up for the :00 stampede.

laravel/framework#59966 proposed adding the offset parameter upstream and was declined, with the suggestion to release it as a package. This is that package, grown out of the Cadence class posted in that thread.

Getting started

The service provider is auto-discovered. There is nothing to publish and nothing to configure.

Three ways to phase a task

Pick whichever reads best in your Kernel; they produce identical cron expressions.

1. everyMinutes(), the offset parameter the framework helpers do not take:

2. offsetBy(), re-phasing a framework helper you already wrote:

3. Cadence, when you want the expression itself:

A zero offset fires on exactly the same minutes as the helper it replaces, so switching a task over is not a behaviour change until you pass an offset.

Spreading a fan-out across lanes

When several related tasks share one cadence, let the package place them:

Lanes are guaranteed never to share a minute. When the lane count does not divide the interval the phases round down, since cron cannot resolve finer than a minute.

Guarding the whole schedule

Offsetting one task is easy to remember; keeping the whole Kernel spread out is not. ScheduleLoad measures how many tasks land on each minute of the hour, so a test or a CI step can fail when one minute gets overloaded.

As an artisan command

Exits non-zero when any minute exceeds --max, so it works as a CI check with no test to write. By default only tasks that repeat every hour are counted, since a daily 03:00 report is not part of the stampede the rest of the day; pass --all to count everything.

As a test

Use ApplicationSchedule::resolve() rather than resolving Schedule from the container yourself. On Laravel 11 and 12 the schedule lives in a withSchedule() callback that only runs once artisan starts, so a test that reads the container binding directly measures an empty schedule and passes without checking anything. ApplicationSchedule starts artisan first, so both the Laravel 10 kernel style and the newer callback style are present. As a backstop, the budget assertions themselves fail if the schedule they were handed carries no tasks at all.

A failure prints the minute, the count and the whole histogram, so you can see where the room is:

If your Kernel gates tasks behind an environment check or a kill switch, build the schedule the way production builds it before asserting — the assertions take any Schedule or list of Events.

Directly

What is rejected, and why

Misconfiguration throws at definition time, during deploy, rather than silently never running. Every exception extends InvalidArgumentException.

Migrating from the standalone class

If you copied the Cadence class out of the pull request thread, the only change is that the factories now return a Cadence rather than a string:

Every interval and offset rule is unchanged, including the exception messages.

Compatibility

PHP 8.2+, Laravel 10, 11 and 12.

The everyMinutes, offsetBy and cadence macros are only registered if Event has no method of that name. If a future Laravel ships its own, core wins and nothing here shadows it.

Development

License

MIT. See LICENSE.