Chaotic Schedule Laravel Package

Product Decisions This Supports

• Reliability / scalability hardening: Chaotic scheduling spreads recurring jobs across a time window instead of firing them all at the top of the hour — a cheap mitigation for thundering-herd and cron-spike incidents without standing up queue re-architecture.
• Feature work: Adds randomized-but-reproducible scheduling primitives (randomDays, randomTimeSchedule, RandomDateScheduleBasis::WEEK|MONTH|YEAR) usable for workload distribution, staggered notifications, and realistic test fixtures.
• Build vs. buy: Seeded determinism (same (uniqueIdentifier, basisDate, periodType) always yields the same runs) is the non-obvious value; reproducing that correctly in-house is more effort than adopting a small macro package. Lean adopt.
• Roadmap / platform upgrade: v3.0.0 hard-floors PHP >= 8.3 and Laravel >= 13. This packages a platform-upgrade decision into a dependency decision — confirm the platform upgrade lands first, or explicitly pin v2.x on legacy services and track it as tech debt.
• Test strategy: Deterministic seeds make scheduled-job behavior testable without sleeping or mocking clocks, reducing flaky CI.

When to Consider This Package

Adopt when:

• You are on (or committed to) Laravel 13+ and PHP 8.3+.
• You want jittered/randomized schedules with reproducible output for tests and audits.
• You accept macro-based scheduling layered on top of Laravel's scheduler rather than a full scheduling engine.

Look elsewhere / stay on v2.x when:

• Any service is still on PHP < 8.3 or Laravel < 13 — v3 is not installable there; pin ^2.0 and schedule the upgrade.
• You rely on raw integer period arguments or the removed static helpers (getString(), getDayCount(), validate(), isValid(), getAll()); migrate to enum cases / cases() / tryFrom() / ->periodString().
• You depend on catching InvalidScheduleBasisProvided or broad catch (\Exception $e) around these calls. v3 raises TypeError, which extends \Error, not \Exception — widen to catch (\Throwable $e) or a typed catch (\TypeError $e), otherwise invalid input will escape your error handling.
• You need cron-grade guarantees, persistence, or distributed coordination — this is not that product.

Compatibility note for planning: macro names, parameter order, and behavior are unchanged, and seed determinism is preserved, so existing schedules will not drift across v2 → v3. The upgrade risk is concentrated in the version floor and error-handling surface, not in scheduling output.

How to Pitch It (Stakeholders)

To executives: A low-cost reliability lever. It de-synchronizes recurring jobs so traffic and job load spread out instead of spiking, reducing incident risk and peak infrastructure pressure. Cost is effectively zero beyond a routine platform upgrade we already need to make.

To engineering: One small, well-scoped package that adds deterministic randomized scheduling as a Laravel macro. The v3 upgrade is mostly a version-floor bump — public API and generated schedules are stable. Two concrete migration tasks: (1) confirm PHP 8.3 / Laravel 13 readiness before bumping, and (2) audit any catch (\Exception) or reliance on InvalidScheduleBasisProvided around these calls, since invalid values now raise TypeError (\Error, not \Exception). Teams not yet on the floor should stay on v2.x — no functional loss.

Recommendation: Approve adoption contingent on the PHP 8.3 / Laravel 13 platform upgrade; sequence the exception-handling audit into the same change window.