Sla Timer Laravel Package

Product Decisions This Supports

• SLA/OLA commitment modeling. The package computes deadlines against real business schedules (open hours, overnight windows, holidays, pauses) rather than naive wall-clock durations. This directly underpins support-desk, incident-management, and customer-success roadmaps where response and resolution targets are contractual.
• Build vs. buy. The edge cases here — midnight-crossing windows, equal from/to meaning 24/7, pause and holiday exclusion, breach detection — are exactly the calendar arithmetic teams underestimate. The v0.2.0 fixes (overnight schedules returning zero, the final day being dropped when a subject ends before the start time-of-day) are the kind of defects that surface as SLA disputes in production, so buying a maintained implementation removes a class of financial and reputational risk.
• Feature roadmap. Reliable overnight and 24/7 coverage unlocks follow-the-sun support tiers, multi-region rotations, and on-call schedules that previously had to be special-cased or avoided. Correct breach calculation supports automated escalation, credit/penalty calculation, and compliance reporting dashboards.
• Volume and reporting workloads. The quadratic-runtime fix is a decision-enabler, not just a patch: a year-long SLA with a daily holiday went from exhausting 128MB to ~30ms, and 10-year calculations run in ~90ms. That moves the package from "safe for a single ticket timer" to "safe for batch SLA audits, backfills, and analytics jobs."
• Platform currency. Raising the floor to PHP ^8.3 and Carbon ^3 with illuminate ^11|^12|^13 aligns the dependency with currently supported Laravel and PHP releases, making adoption a low-friction decision on modern stacks and a forcing function for teams still on EOL runtimes.

When to Consider This Package

Consider adoption when:

• Deadlines must respect business hours, timezones, holidays, or pause windows — anything a simple now()->addHours() cannot express correctly.
• You operate overnight or 24/7 schedules. As of v0.2.0 these are correct; on earlier versions, midnight-crossing windows silently returned zero, which is a silent-failure mode in exactly the scenarios that matter most.
• You need breach detection and repeatable SLA calculations across many records, where the new performance profile makes bulk computation practical.
• Your stack is PHP 8.3+ and Laravel 11, 12, or 13. v0.2.0 requires this and will not install otherwise.
• You value maintainability evidence: 28 new tests, 98.4% coverage, PHPStan level 8 clean, and a modern CI matrix covering PHP 8.3–8.5 are reasonable proxies for a project that will not quietly rot.

Look elsewhere when:

• You only need fixed-duration timers with no calendar semantics — a native date library is sufficient and this adds unnecessary concepts.
• You are pinned to PHP 8.1/8.2 or Laravel 10 or earlier. The v0.2.0 dependency bumps make this a hard blocker, not a soft preference.
• You require a stable public API. This is pre-1.0, and v0.2.0 contains a genuine breaking change: AgendaInterface::toPeriods() now returns start/end Carbon pairs instead of CarbonPeriod[]. Any direct consumer of that interface needs a migration.
• You need general calendar or recurrence functionality (RRULE expansion, event scheduling, UI calendars). This package is scoped to SLA/business-time calculation and should not be stretched into a calendar engine.
• You cannot absorb a major Carbon upgrade (^2 → ^3) across the wider application. That transitive impact is usually larger than the package change itself.

How to Pitch It (Stakeholders)

For executives: This is a small, focused dependency that makes our SLA commitments computable and auditable. It replaces bespoke date arithmetic — historically a source of disputed breach determinations — with a tested implementation. The v0.2.0 release materially de-risks it: two silent-failure bugs affecting overnight and end-of-window calculations are fixed, and a memory-exhaustion path in long-running calculations is resolved (a year-long SLA now computes in ~30ms instead of failing outright). That converts SLA reporting from a nightly batch concern into something we can run on demand. Cost of adoption is one dependency; cost of getting this wrong is contractual exposure.

For engineering: v0.2.0 is a quality release with one breaking change. The toPeriods() signature change from CarbonPeriod[] to start/end Carbon pairs eliminates per-period object construction on the hot path and is the source of the performance win; scope the migration to direct consumers of AgendaInterface. Dependency floors move to PHP ^8.3, Carbon ^3, and illuminate ^11|^12|^13 — verify the Carbon 3 upgrade across the wider codebase before scheduling. Positives: PHPStan level 8 clean (50 findings fixed, including a latent Weekly::addTimePeriods flattening bug), 28 new tests at 98.4% coverage, CI on PHP 8.3–8.5 with first-party actions. Recommended path: adopt behind our scheduling abstraction, pin the version, and budget a short spike to confirm the Carbon 3 and toPeriods() impact before committing to a rollout.