Time Overlap Calculator Laravel Package

Getting Started

composer require v-matsuk/time-overlap-calculator

• This is a plain PHP library, not a Laravel package. There is no service provider, no facade, no config file to publish, and nothing to add to bootstrap/providers.php. composer require is the entire setup.
• First place to look: vendor/v-matsuk/time-overlap-calculator/src/. The public surface is tiny — expect one calculator class, possibly a small value object for a time range. Confirm the real namespace and method names from its composer.json and class docblocks; you can read the whole thing in five minutes.
• Typical first use case: "does this new booking/shift/maintenance window collide with an existing one?" — i.e. taking two start/end pairs and asking for the overlap.

A minimal call, shaped like most such libraries:

// Confirm exact class + method names by reading src/
$overlap = (new TimeOverlapCalculator())
    ->setStart('2024-06-01 09:00:00')
    ->setEnd('2024-06-01 12:00:00')
    ->setCompareStart('2024-06-01 11:00:00')
    ->setCompareEnd('2024-06-01 13:00:00');

// returns overlap duration / bool depending on the method you call

Implementation Patterns

• Wrap it in one service. Don't scatter library calls across controllers. Bind a small TimeRangeOverlapService in the container and inject it; this gives you the only real "extension point" the package lacks.
• Normalize inputs at the boundary. Convert Carbon / Eloquent date casts to DateTimeImmutable (or whatever the package expects — string vs. timestamp matters) in exactly one place, always in UTC, before handing off.
• Pre-filter in SQL, compute in PHP. For a conflict check against many existing rows, run a cheap Eloquent query first — WHERE start < :newEnd AND end > :newStart — then use the library only on the small candidate set for the precise result.
• Use it for ratio/threshold logic. Where the package earns its place over a raw comparison is duration or percentage overlap: e.g. reject a booking that overlaps more than 50% of an existing slot, or flag double-booked shifts.
• DTO + predicate. Define a TimeRange value object with startsAt(), endsAt(), and overlaps(TimeRange $other): bool; keep the third-party call in one method so it's swappable.
• Test the boundaries, not the class. Write one test per case — touching endpoints, full containment, partial overlap, zero-length range — so an upgrade or replacement stays safe.

Gotchas and Tips

• Unmaintained since 2017, zero dependents. Treat it as frozen code. Pin the exact version, and if you depend on it long-term, consider vendoring the one class into app/Support.
• No Laravel integration whatsoever. No auto-discovery, no facade, no config, no DI hints. All wiring is your own.
• Timezones are entirely on you. Naive string comparison will be silently wrong across DST or mixed-offset inputs. Store and pass UTC everywhere.
• Boundary semantics are the classic bug. Is [09:00, 10:00) overlapping [10:00, 11:00)? Most overlap libraries say no, but confirm against this one with an explicit test — this is where production incidents come from.
• Guard inverted and zero-length ranges (start < end) before calling; behaviour on bad input is likely undefined rather than an exception.
• Precision mismatch. If the DB stores seconds and the library reasons in minutes, expect off-by-a-minute surprises; normalize precision before comparison.
• Debugging: there's no logging or exception layer. When a result looks wrong, dd() the four normalized timestamps you pass in — that catch 95% of "library bugs."
• When to skip it. For a simple boolean overlap, the whole algorithm is $aStart < $bEnd && $bStart < $aEnd with Carbon. Reach for this package only if you genuinely need the duration/percentage helpers; otherwise use spatie/period, which is actively maintained and Laravel-friendly.