Time Laravel Package

Product Decisions This Supports

• Build vs. buy vs. adopt for the time/value-object layer. This is a zero-cost (MIT), zero-dependency utility that competes directly with Carbon — which Laravel already ships and wires into Eloquent casts, validation, factories, and Carbon::setTestNow() test helpers. The real decision isn't "should we use it" but "do we want a framework-agnostic domain time type, with Carbon confined to the framework edges?"
• Domain-layer extraction roadmap. The package has no Laravel coupling, which makes it a candidate primitive if the roadmap includes pulling billing, scheduling, or entitlement logic out of Eloquent models into plain-PHP packages that can be unit-tested and reused across services.
• Error-handling strategy as a product decision. "No exceptions" is an architectural stance, not a detail. Adopting it means parse/format failures become explicit return values the caller must handle — which pushes validation-message design and failure UX earlier into the code path rather than into a global handler. That's a good fit for anything user-facing and money-adjacent; it's friction for teams accustomed to try/catch at the controller boundary.
• Correctness bets in time-sensitive features. Immutability plus strict types directly reduce a class of production bugs PMs get paged for: accidental mutation of a shared DateTime in a loop, DST arithmetic in scheduling, and off-by-one in billing-period boundaries. If the roadmap has booking windows, subscription renewal dates, trial expiries, or timezone-dependent reporting, this is a defensible quality investment.
• Static-analysis maturity. Raising PHPStan/Psalm levels is often a quarterly engineering goal; strict-typed value objects are one of the cheapest ways to make that goal achievable in older parts of the codebase.

When to Consider This Package

Adopt (or, more precisely, trial) when all of the following hold:

• You are deliberately carving out a framework-agnostic domain layer and want a time primitive that doesn't drag Illuminate behind it.
• The team is already on declare(strict_types=1) and static analysis, and is comfortable with result-style APIs over exceptions.
• You are willing to wrap it behind your own interface — a thin internal Clock/Timestamp adapter — so the package is a swappable implementation detail, not a public dependency.
• The surface you need is small and well-understood: parse, format, compare, add/subtract intervals, timezone conversion. Not full calendar math.
• You can absorb the risk of a package with 0 stars, 0 dependents, and a single release history. That is fine for a 200-line utility behind an adapter; it is not fine for something you'd inherit in an acquisition review.

Look elsewhere (i.e., stay on Carbon / DateTimeImmutable) when:

• You need breadth: CarbonPeriod, interval math, human-readable diffs, localization and i18n formatting, Blade-friendly output, and the entire Laravel testing ergonomics around setTestNow().
• Your codebase already has hundreds of Carbon call sites; the migration cost vastly exceeds the benefit, and a partial migration produces two time idioms — the worst outcome.
• You need vendor assurance: documented support windows, security response, an audit trail, or a second maintainer. There is no social proof here to lean on, and "score 0.4 / opportunity 30.54" reflects that.
• Your team is unfamiliar with result types and would silently ignore returned failures — which reintroduces exactly the bug class this package is meant to remove.

Recommended path: a one-to-two day spike in an isolated module behind an adapter, with an explicit kill criterion. Don't standardize org-wide on a 0-star package in one move.

How to Pitch It (Stakeholders)

To executives: This is a free, MIT-licensed library that reduces a specific and expensive class of bug — incorrect dates in billing, scheduling, and reporting — by making time values immutable and making failures explicit instead of silently swallowed. Cost is zero and the blast radius is contained because we will hide it behind our own interface; if it disappoints, we swap the implementation without touching business logic. The honest caveat: it is an early, unproven package with one maintainer and no adoption, so this is a small, reversible bet rather than a platform commitment. We'll validate with a short spike and a written go/no-go criterion before it touches revenue-critical paths.

To engineering: It's the "make invalid states unrepresentable" option for time. Strict types, immutable values, and no exceptions means fewer hidden mutations, no try/catch pyramids, and a codebase that plays well with high static-analysis levels. It also decouples domain logic from Carbon, which is the main thing keeping our business rules welded to the framework. The trade-off is real: we lose Carbon's breadth and Laravel's testing conveniences, so the proposal is Carbon at the edges (Eloquent casts, validation, Blade) and this type in the domain core — with an adapter we own so the choice stays reversible.