- What is skywarth/chaotic-schedule used for in Laravel?
- It is a small package that adds macros to Laravel's task scheduler so you can generate random but realistic execution times and date intervals instead of fixed cron cadences. Typical uses are test fixtures, database seeders, demo environments, load simulations, and jittered polling jobs such as webhook drainers or cache warmers. It only changes when a scheduled task fires, not how the job executes, so it adds no migrations, queue driver assumptions, or background service to operate.
- How do I install chaotic-schedule in a Laravel application?
- Install it with Composer using composer require skywarth/chaotic-schedule; the package is auto-discovered so no manual service provider registration or publishing step is needed. Once installed, the randomDays and randomTimeSchedule macros become available on the Schedule facade inside your console kernel or routes/console.php definitions. Verify your PHP and Laravel versions satisfy the package requirements before installing, since v3 pins a fairly recent platform floor.
- Which PHP and Laravel versions does chaotic-schedule require?
- Version 3.0.0 requires PHP 8.3 or newer and Laravel 13.x or newer. If your application is on Laravel 11 or 12, or on PHP 8.2, you cannot use v3 and must stay on the v2.x line. Confirm the general availability status of Laravel 13 in your environments and check the maintainer's backport and security policy for v2.x before deciding which branch to pin.
- How do I generate a random schedule between two dates with randomTimeSchedule?
- You call randomTimeSchedule on the Schedule facade with an identifier and a date range, and the macro computes a randomized firing moment inside that window. Because the generated schedules are derived from a seed rather than pure randomness, the same identifier and basis date produce the same result, which keeps runs predictable once configured. Use it when you want a plausible but non-obvious execution time for a one-off or low-frequency job.
- How do I pass a week, month, or year basis to randomDays()?
- In v3.0.0 the period basis is expressed with enum cases such as RandomDateScheduleBasis::WEEK, RandomDateScheduleBasis::MONTH, and RandomDateScheduleBasis::YEAR. Pass the enum case directly to randomDays rather than a raw integer, which was the older style. If you need the string form for logging or comparisons, use the periodString() method, and use cases() or tryFrom() when converting stored or configured values.
- Are chaotic-schedule results deterministic and reproducible in tests?
- Yes. The behavioural contract is deterministic across the combination of uniqueIdentifier, basisDate, and periodType, so the same inputs yield the same generated schedule. That means assertions in tests stay stable and existing generated fire times do not drift when you upgrade, provided you keep those three inputs unchanged. The package is not a cryptographically unpredictable random source, so do not rely on it for anything requiring true unpredictability.
- What are the breaking changes when upgrading chaotic-schedule to v3.0.0?
- The release is a platform-floor bump plus a typed API cleanup rather than a feature release. Period bases are now enum cases, and the static helpers getString(), getDayCount(), validate(), isValid(), and getAll() have been removed in favour of enum cases, cases(), tryFrom(), and periodString(). The InvalidScheduleBasisProvided exception was also removed in favour of a native TypeError, so audit any catch blocks around schedule macros before deploying.
- Why does chaotic-schedule now throw a TypeError instead of InvalidScheduleBasisProvided?
- Passing an invalid period basis now fails with a native TypeError rather than the package's former InvalidScheduleBasisProvided exception. That is cleaner design, but TypeError extends Error, not Exception, so any catch (\Exception $e) guard that was written to stop bad config from breaking a scheduler run will no longer catch it. Search your codebase for such guards and either catch Throwable, catch the specific TypeError, or wrap the call in a small helper that restores an exception-typed boundary.
- Can I constrain random schedules to specific hours, days, or cron expressions?
- Yes. Chaotic Schedule lets you apply constraints for hours, days, and cron expressions so randomized firing windows stay within realistic or permitted boundaries. That keeps generated schedules plausible for business-hours work while still spreading execution across a window. If you need calendar-exact timing or sub-minute precision, this package is not the right tool and you should define fixed cron expressions instead.
- Is chaotic-schedule suitable for production schedules that need exact timing?
- No. It is designed for jitter, load spreading, and realistic synthetic schedules, not for calendar-exact SLAs, sub-minute precision, or cryptographic unpredictability. Its operational risk is low because it only influences when a task fires, but it is a small, single-primary-maintainer project, so it fits a scheduling convenience role rather than anything in the compliance or data path. Pin to a minor range and assign clear ownership for the next major upgrade.