Sla Timer Laravel Package

Technical Evaluation

What this package is: a business-hours / SLA duration calculator for Laravel — schedule definitions (from('22:00:00')->to('02:00:00')), weekly agendas, pauses and holidays, and breach evaluation. It answers "how much SLA clock elapsed between A and B, excluding non-covered time."

Architecture fit: Strong for any Laravel service that owns SLA timers — ticket/incident management, contract entitlement, support desk, order fulfilment. It is a pure computation library (Carbon + Collections only), so it slots in as a domain dependency with no infrastructure footprint: no queue worker, no storage, no external service. It is not a scheduler, a persistence layer, or a breach-notification system — those remain ours. That is the right boundary, but it means the surrounding machinery (storing clock state, running breach sweeps, auditing) is our build, not theirs.

Release assessment (v0.2.0): This is a substantial, credible release. Three categories of change matter:

1. Correctness fixes (highest business value). Two silent-wrong-answer bugs are fixed: SLA durations dropping the final day when the subject ended before the start time-of-day, and overnight/midnight-crossing schedules returning zero. For an SLA system these are the worst class of defect — no error, no alert, just a contractually wrong number flowing into credits, penalties, or reporting. If we are on 0.1.x in production, we should assume historical calculations are suspect and scope a recalculation.
2. Performance fix (highest architectural value). The quadratic blow-up (a year-long SLA with a daily holiday exhausted 128MB; now ~30ms, 10-year in ~90ms) converts this from a batch-only tool into something usable inline in a request path, and makes year-plus recomputation and backfills tractable. That materially widens the design space.
3. Breaking changes (highest planning cost). PHP floor ^8.3; Carbon ^2 → ^3; illuminate/collections ^11|^12|^13; and AgendaInterface::toPeriods() now returns start/end Carbon pairs rather than CarbonPeriod[].

Integration feasibility: Feasible but gated. The Laravel 11+ and PHP 8.3+ requirements are the binding constraints — if we run Laravel 10 or PHP 8.1/8.2, this release is unreachable without a platform upgrade. Carbon 3 is a major with its own breaking surface, so this is not a drop-in patch; it is a coordinated platform move. The toPeriods() change is narrow and only bites direct consumers; teams that use the higher-level duration/breach API are likely unaffected.

Technical risk:

• Pre-1.0 API volatility. At 0.x, semver permits breaking changes in minor bumps. A 0.3.0 could break us again. Pin exactly and treat every bump as a review event.
• Semantic change hiding in a bug fix. Equal from/to (e.g. 09:00:00→09:00:00) now means 24/7 coverage. Any existing config that used equal times as a de facto "no coverage" or placeholder will now silently grant full coverage — an over-credit risk that no test will catch for us.
• Silent-zero class of bug. The overnight fix confirms this library can return plausible-looking zeros. Output validation, not just unit tests, is warranted.
• Supply chain. Single-maintainer-style package, no stated security or deprecation policy visible in these notes. Bus factor and long-term maintenance are unassessed.
• Timezone/DST behaviour is not addressed in the notes and is the usual failure point for wall-clock schedules.

Key questions for engineering:

• Do we call toPeriods() directly anywhere, or only through higher-level APIs?
• Are we on 0.1.x in production or still evaluating? If in production, how many historical SLA records need recomputation, and what is the remediation owner?
• Do any schedule configs use equal from/to times today, and what did we intend them to mean?
• What is our current Laravel/PHP baseline, and is a Laravel 11+ / PHP 8.3 upgrade already on the roadmap?
• How do we validate schedule configuration at authoring time so a bad window cannot reach production silently?
• What is the package's maintenance posture (release cadence, issue responsiveness, security disclosure path)?

Integration Approach

Stack fit: Native fit for Laravel 11/12/13 on PHP 8.3–8.5. Anything older is out of scope for this release and effectively pins us to 0.1.x, which carries the known correctness and memory bugs. That trade-off should be an explicit, recorded decision rather than an accident of inertia.

Migration path: Treat this as a platform upgrade that happens to include a package bump, not the reverse.

1. Land PHP 8.3+ across dev, CI, and runtime images first — it is a prerequisite for everything else and is independently testable.
2. Move Carbon 2 → 3 in isolation (it touches our own date handling too), verifying SLA reporting output before and after.
3. Upgrade Laravel to 11+ where needed.
4. Adopt the package at 0.2.*, pinned exactly.
5. Only then re-enable/adjust schedule behaviour.

Compatibility: The toPeriods() signature change is a compile-time break — cheap to detect, cheap to fix, and likely irrelevant if we consume the higher-level API. The dangerous compatibility item is behavioural, not structural: equal from/to becoming 24/7. Run an audit query over stored schedule definitions for from == to before deploying and decide each case deliberately. Also re-verify any schedule crossing midnight, since its computed coverage changes by design.

Sequencing: The performance fix makes inline calculation viable, so resist the temptation to adopt it mid-quarter on a live SLA path. Do it behind a feature flag with a shadow-mode period: compute durations both ways for a fixed window, diff the outputs, and only cut over when the deltas are explained. Given that the previous release produced silently wrong numbers, a parallel-run comparison is the cheapest possible insurance and doubles as our historical-remediation evidence.

Effort shape: Small code change, moderate platform work, non-trivial validation and data-remediation work. Budget for the last two; they are the actual project.

Operational Impact

Maintenance: Low ongoing code maintenance — it is a dependency, not a service. The real maintenance cost is version discipline: at 0.x, pin exactly, review every changelog, and assume each minor release may break us. Assign a named owner for that review; unattended pre-1.0 dependencies drift into unplanned emergency upgrades.

Support: Support burden sits with our team, not the package, because the failure modes are ours: bad schedule config, wrong timezone, misunderstood coverage semantics. The 98.4% coverage and PHPStan level-8 cleanup in this release are meaningful signals of engineering quality and reduce the odds we are debugging someone else's arithmetic — but they do not substitute for our own contract tests.

Scaling: Transformed by this release. The quadratic-to-linear fix removes the memory ceiling that made year-long and multi-year calculations impractical. Expect this to unlock use cases previously ruled out on cost — real-time SLA clocks in request handlers, nightly multi-year recomputation, backfill of historical breaches. Capacity planning for those now shifts to wherever we store and query results, not to the calculation itself.

Failure modes to design against:

• Silent misconfiguration — equal from/to now yields 24/7. Validate at authoring time and reject ambiguous schedules.
• Silent zero — the class of bug this release fixed. Add assertions that a covered interval yields a non-zero duration, and alert on unexplained zeros.
• Historical inconsistency — records computed pre-upgrade differ from post-upgrade. Maintain an "SLA engine version" stamp on computed records so any number can be traced to the engine that produced it and recomputed on demand.
• Timezone/DST edge cases — untested by this release and untested by most teams; verify explicitly for any customer in a DST-observing region.
• Version-pin drift — an unpinned transitive bump silently reintroducing a fixed bug.

Ramp-up: Low for engineers. The API is small, expressive, and reads like the domain (from()->to(), weekly agendas, pauses, holidays). The genuine ramp-up cost is conceptual, not technical: getting the team fluent in coverage semantics — overnight windows, holidays versus pauses, what a breach means — so that schedule definitions are reviewed by someone who understands the contract they encode. Pair the adoption with a short internal write-up of our schedule conventions and the equal-time rule. That document, not the library, is what prevents the next silent wrong number.