When Laravel Package

Technical Evaluation

• Architecture fit: tplaner/when is a framework-agnostic PHP date-recursion library, so it can fit a Laravel application as a domain/service dependency rather than an Eloquent or controller concern. It is best used for recurrence calculation—e.g., “next occurrence of a custom schedule”—not as a replacement for Laravel’s scheduler. Wrap it behind an application-owned interface such as RecurrenceCalculator to avoid leaking package types across the codebase.
• Integration feasibility: Likely low-friction via Composer, with a manual container binding or small service provider. No database schema is inherently required; persistence is an application design choice. The main integration work is not installation but defining recurrence inputs, timezone behavior, storage format, and safe iteration bounds.
• Technical risk: Medium. The package has moderate star count but “repository unknown” and a middling score are provenance/maintenance red flags. Key risks are PHP-version compatibility, undocumented recurrence semantics, DST/timezone correctness, unbounded or expensive iteration, and divergence from standards such as iCalendar RRULE if interoperability is needed. MIT licensing is favorable, but license alone does not establish maintenance health.
• Key questions: Is the repository actively maintained and compatible with current PHP/Laravel versions? What recurrence syntax does it support, and is it documented and stable? How are timezones and DST transitions handled? Can iteration be bounded and validated to prevent infinite or excessive loops? Does it interoperate with RFC 5545/RRULE or Carbon? What is the test coverage and release history? Can we fork or vendor it if abandoned? What is the exact Composer package name and supported version range?

Integration Approach

• Stack fit: Suitable for Laravel services, jobs, and domain modules that need custom recurrence beyond cron expressions. Keep Laravel Scheduler/queues responsible for execution; use the package only to calculate occurrence dates. Bind it through the service container and expose an application-owned service API.
• Migration path: Introduce the library behind an adapter first. Add feature flags and dual-run the new calculator against existing logic for a sample of schedules. Persist recurrence definitions plus timezone and a computed next_run_at; backfill or recompute only after validation. Cut over by schedule type, starting with low-risk reminders or reports before billing-critical flows.
• Compatibility: Verify PHP version constraints, Laravel version support, Carbon/DateTime interoperability, timezone database assumptions, and queue/scheduler behavior. Pin a tested version, run CI on the target PHP matrix, and avoid exposing package-specific recurrence strings directly to end users without validation.
• Sequencing: 1) Time-boxed spike against real recurrence cases, including DST and month-end edge cases. 2) Build adapter, validation, and tests. 3) Define persistence and next_run_at strategy. 4) Pilot one low-risk schedule class. 5) Roll out with monitoring and fallback. 6) If the spike fails, substitute an RRULE-capable library or implement a narrower internal calculator rather than forcing adoption.

Operational Impact

• Maintenance: Low day-to-day code footprint but non-trivial dependency risk. Pin versions, track upstream activity, retain an internal fork/escape plan, and keep recurrence regression tests in the application repo. Treat the wrapper as the stable contract.
• Support: Document supported recurrence patterns, timezone rules, invalid-rule behavior, and escalation paths. Assign an internal owner for scheduling semantics. Support burden will concentrate on “why did this occurrence fire/skip?” investigations rather than package installation.
• Scaling: Recurrence calculation is CPU-bound. Precompute and cache next occurrences, process due schedules via queued jobs, index next_run_at, and cap evaluation horizons. Avoid calculating long recurrence ranges synchronously in request paths.
• Failure modes: Infinite or expensive recurrence loops, invalid user-supplied rules, DST duplicate/missed occurrences, timezone configuration drift, duplicate jobs from retries, queue backlog, and inconsistent persisted next_run_at values. Mitigate with bounded iteration, validation, idempotent job design, and monitoring for schedule lag and recurrence errors.
• Ramp-up: Low-to-moderate for PHP developers; the API surface is likely small. The real ramp-up is domain knowledge: recurrence semantics, timezone/DST behavior, and safe scheduling operations. Allocate time for a spike, test fixtures, and a runbook before production use.