Time Overlap Calculator Laravel Package

Technical Evaluation

Architecture fit. v-matsuk/time-overlap-calculator is a single-purpose utility library — it computes the intersection of time ranges. That is a leaf dependency, not an architectural component. In a Laravel codebase it belongs behind the domain layer (scheduling, billing periods, shift/booking logic, SLA windows), never called directly from controllers or models. The fit is good in principle because the responsibility is narrow and stateless; the concern is that a package this small provides almost no architectural leverage — the same behavior is 50–100 lines of Carbon/DateInterval arithmetic that we could own outright.

Integration feasibility. Install is a one-line Composer require if constraints resolve. The real gate is the 2017 release date: the package was published in the Laravel 5.x era and almost certainly constrains illuminate/support and nesbot/carbon to major versions that a modern Laravel 10/11 application will not satisfy. Composer will either refuse to resolve or, worse, silently downgrade Carbon across the whole application — a change with blast radius far beyond this feature. Expect to vendor/fork rather than install cleanly.

Technical risk. Bounded but real:

• Abandonment. Last release 2017-08-24, 11 stars, 0 dependents, no evidence of active maintenance. There will be no security patches, no PHP 8+ compatibility work, and no response to issues.
• Correctness surface is deceptively large. Overlap logic is where boundary bugs live: adjacent-but-not-overlapping intervals, zero-length intervals, inclusive vs. exclusive endpoints, multi-interval merging vs. pairwise intersection, timezone offsets and DST transitions. A package with this little adoption has almost certainly not been exercised against those cases.
• Auditability is a mitigation. The entire codebase is small enough for one engineer to read end-to-end in an hour and certify. That substantially reduces supply-chain risk compared with a large transitive dependency tree, but it does not remove the ownership burden.
• Opportunity score is low (20.77) and the composite score is 0.115. Read as: negligible ecosystem momentum. There is no community to inherit bug fixes from.

Key questions to answer before any commitment.

1. What is the exact public API surface — classes, facade, service provider, auto-discovery? How much of it would we actually call?
2. What are the declared php, illuminate/*, and carbon constraints, and do they resolve against our target stack without downgrades?
3. Does it support multi-interval sets, or only pairwise comparison? What is the complexity for n intervals?
4. How are boundary conditions defined — does a meeting ending at 10:00 and one starting at 10:00 count as overlapping?
5. Is timezone/DST handling delegated to Carbon, or hand-rolled with strtotime/integer math?
6. Is there a test suite, and what does it cover? Are there open issues or PRs indicating known defects?
7. Who is the maintainer, and is there any signal of intended future maintenance?

Integration Approach

Stack fit. Poor on a current Laravel release, plausible on a legacy Laravel 5.x–6.x application where the dependency graph is already frozen. The decision should be driven by the host application's version, not by the package's feature set — the feature set is reproducible in an afternoon.

Migration path. Two viable routes, in preference order:

1. Build in-house. A TimeInterval value object plus an OverlapCalculator service using CarbonImmutable and DateInterval. This gives us explicit, documented boundary semantics, first-class timezone handling, and a test suite we control. Cost: roughly one engineer-day including tests.
2. Vendor-fork. Copy the source into app/Support/TimeOverlap/ (or a private Composer path repository), pin it, add PHP 8 compatibility and characterization tests. Only worth it if the package's semantics are already embedded in existing production behavior we must preserve.

If the package is adopted as-is, wrap it behind an internal OverlapCalculatorInterface so the call sites never reference the vendor namespace. That keeps the replacement cost at one class if we later swap it out.

Compatibility. Do not trust the declared constraints — verify empirically. Run composer why-not against the target app, then execute the package against the target PHP version in a scratch branch. Pay specific attention to Carbon 1 vs. Carbon 2/3 differences in diffInSeconds sign conventions and Carbon::between behavior, which are common silent-breakage points.

Sequencing.

1. Spike (0.5 day). Install in a throwaway branch; confirm resolution, run a boundary-case script (adjacent, zero-length, reversed ranges, cross-DST).
2. Characterization tests (0.5 day). Codify the observed behavior as tests before integration, so any later fork preserves semantics or documents intentional divergence.
3. Decision gate. Adopt-fork vs. build. Default to build unless step 1 reveals non-trivial semantics we'd struggle to replicate.
4. Abstract and integrate (1–2 days). Implement behind the internal interface; wire into the consuming feature.
5. Regression pass. Add the boundary cases to the application's permanent suite so the behavior is guarded regardless of which route was taken.

Operational Impact

Maintenance. Effectively zero upstream maintenance. Whichever route is chosen, we become the maintainer — either of a vendored fork or of our own implementation. The fork route carries a standing tax: every future Laravel and PHP upgrade requires re-validating a dependency nobody else is testing. The in-house route pays once and then tracks the framework naturally.

Support. No vendor, no SLA, no security disclosure process. A single maintainer with an eight-year-old release and 11 stars implies a bus factor of one and effectively no community backstop. Internal escalation path must be "the owning team reads the source," which is feasible only because the source is tiny.

Scaling. Computational cost is negligible at realistic volumes: pairwise comparison is O(1) per pair, naive all-pairs is O(n²), and interval-sorting approaches are O(n log n). This is fine for scheduling a handful of resources; it becomes a concern only if someone applies it to large calendars (thousands of intervals per request) inside a hot path. Memory footprint is trivial. The scaling risk here is organizational, not computational — the package will not be the bottleneck, but it will be the thing nobody remembers exists during an upgrade.

Failure modes. Ranked by likelihood and severity:

• Silent semantic error at boundaries (highest concern). Adjacent intervals misclassified as overlapping or non-overlapping. Produces wrong business results — double-booked resources, mis-billed periods — with no exception thrown. Mitigated only by explicit characterization tests.
• Composer resolution conflict or forced downgrade. Blocks framework upgrades or destabilizes Carbon application-wide. Surfaces loudly, which is the good news.
• PHP 8+ deprecation/fatal. Dynamic properties, strtotime edge cases, or removed functions. Surfaces loudly at deploy.
• Timezone/DST drift. Overlaps computed in local time across a DST boundary can be off by an hour. Manifests as rare, hard-to-reproduce production incidents — the worst failure profile.
• Fork rot. The vendored copy diverges from any future upstream fix. Low impact given upstream is dormant.

Ramp-up. Very low for an individual engineer — an hour to read the source, an afternoon to be productive. The hidden cost is discoverability: a low-profile third-party package in a codebase invites duplicated logic, because the next engineer to need overlap math will not know it exists and will write their own. Any adoption should be paired with a short internal note naming the canonical implementation and its boundary semantics.

Recommendation. The package solves a small problem adequately but brings abandonment risk disproportionate to its value. Treat it as a reference implementation, not a dependency: read it, confirm the semantics you need, and own a tested in-house equivalent behind an internal interface. Reserve the vendored fork for the case where existing production behavior must be preserved byte-for-byte — and even then, schedule its replacement.