Sofre Laravel Package

Product Decisions This Supports

• Build vs. buy for availability logic. Opening-hours evaluation looks trivial in a spec ("is it open now?") but is where teams quietly burn weeks: overnight spans (22:00–02:00), split shifts, holiday exceptions, "closes next day" semantics, DST transitions, and timezone-per-location. A maintained package shifts that from bespoke code to configuration, letting the team spend its budget on the storefront experience instead.
• Feature feasibility for "Open now" / "Closing soon" / pickup-slot surfaces. This release is specifically a correctness fix to opening-hour detection, which is the primitive behind the highest-visibility features: store locators with live open/closed badges, "order for pickup in 20 min" gating, delivery cutoff messaging, and support-tool "is this branch open?" lookups. The existence of a detection bug in a 0.x line is a direct input to whether these can ship customer-facing this quarter or must stay behind an internal flag.
• Roadmap sequencing and risk. A patch release that fixes detection defects tells you the edge cases are still being shaken out. That argues for sequencing: internal/admin use first (low blast radius), then customer-facing badges, then anything financially binding (cutoffs that stop orders, SLA clocks, billing by business hours).
• Data-model and integration scoping. Adoption implies hours are stored and evaluated in one canonical place. That's a decision about whether hours live in a config file, a business_hours table, or per-location records — and whether exceptions (holidays, one-off closures, seasonal hours) are in scope now or deferred. Cheap to decide before launch, expensive after three surfaces each invent their own parser.
• Support and trust posture. Every "the app said we were open" complaint is a support ticket with a screenshot. Deciding whether correctness is guaranteed by the package, by our test suite, or by a human override toggle is a product decision, not an engineering one.

When to Consider This Package

Adopt when:

• You need evaluation of hours (is-open-now, next-open, closing-soon), not just storage and display of a schedule.
• Hours are per-location and multiple locations must be evaluated in a single request (store locator, availability filtering).
• You want the edge cases — overnight ranges, exceptions, timezones — handled by code somebody else maintains, and you're willing to pin a version and own the integration tests.
• The domain is advisory rather than financially binding: badges, sorting, messaging, internal tooling.

Look elsewhere, or wrap heavily, when:

• You need contractual stability. At 0.12.x, minor bumps may carry behavior changes; a patch-level fix to core detection means the semantics are still settling. If your roadmap can't absorb a re-verification pass on each upgrade, prefer a 1.x+ package or an in-house module.
• Correctness is revenue-critical and unauditable. Order cutoffs, SLAs, or billing that depend on "open" should not rest on a dependency whose detection logic is actively being fixed, unless you own a regression suite covering your specific edge cases.
• Requirements go beyond weekly hours plus exceptions — appointment slot generation, capacity, per-service hours, staff-level rosters. Those need a scheduling engine, not an hours evaluator.
• Timezones are per-user rather than per-location, or you need sub-day precision across DST boundaries with defined behavior; confirm the package's model matches before committing.

Regardless of choice: pin the version, and write tests for the exact cases your business hits (overnight, holiday, DST, midnight boundaries) before the first customer-facing surface ships.

How to Pitch It (Stakeholders)

For executives: This is a small, focused dependency that answers one question — "is this location open, and when does it next open?" — so we don't hand-build and hand-maintain the tricky parts (overnight hours, holidays, timezones) on every surface that shows availability. The release we're reviewing is a bug-fix patch to that core detection logic. That's good news (someone is actively fixing real-world edge cases) and a caution (the logic is still maturing at version 0.12). Recommendation: adopt it for internal tooling and non-blocking UI now, hold financially binding use cases until we've validated our specific edge cases against it.

For engineering: Pre-1.0 package, patch release fixing opening-hours detection defects — treat as "improving but not settled." Pin the version, add a regression suite covering our real schedules (overnight, split shifts, holiday exceptions, DST, midnight boundaries), and keep the evaluation behind a thin internal interface so it can be swapped or replaced if the 1.0 line diverges from our needs. Do not let hours parsing leak into more than one place in the codebase.