Datetime Laravel Package

Product Decisions This Supports

• Build vs. buy on date/time plumbing. Date math is a classic "small but deceptively expensive" build: month-end rollovers, leap years, DST boundaries, inclusive vs. exclusive range ends, and interval-to-seconds conversions each look like a one-liner and each generate a bug report. This package is a cheap way to buy correctness for those specific gaps rather than funding a sprint of bespoke helpers.
• Roadmap scoping for date-dependent features. Any of the following can be scoped with less engineering uncertainty: reporting periods and date-range filters, trial/grace-period expiry, subscription or billing cycle calculations, tenure/age/duration display, "is this today / this week / weekend" routing and notification logic, and business-day counting for SLAs.
• Consolidating utility debt. If the codebase already has a app/Support/DateHelper.php that three teams have edited, this is a credible target for replacing hand-rolled helpers with a versioned, tested dependency — which is a maintainability decision, not a feature decision.
• Dependency posture / exit-cost decisions. MIT license, small surface area, and a single-purpose API mean the realistic exit cost is "copy the file." That makes adoption a reversible decision, which is the kind of dependency a PM can approve without an architecture review cycle.
• Decisions it does not support. This is not a replacement for Laravel's date stack. It does not displace Carbon, does not provide timezone-database management, ORM casting, validation rules, or human-readable formatting (diffForHumans). Do not use it to justify deferring a broader "consolidate our date handling" initiative — it is additive, not foundational.

When to Consider This Package

Adopt when:

• You are on a modern PHP/Laravel codebase already using DateTimeImmutable and/or Carbon, and you have a specific, enumerable list of missing helpers (range objects, interval math, day/month difference, calendar predicates).
• The work is internal-facing or low-blast-radius — internal tooling, admin panels, reporting utilities — where a small, single-maintainer dependency is an acceptable risk profile.
• Your team is willing to read the source before adopting. At ~18 stars and 0 dependents there is no ecosystem validation signal; the review is the due diligence.
• You can isolate it behind a thin internal wrapper (one DateMath facade or interface) so swapping to Carbon, nesbot/carbon, or in-house code later is a one-file change.

Look elsewhere when:

• You need recurrence rules (RRULE/iCal), business-hours calendars, or complex scheduling — reach for rlanvin/php-rrule, spatie/opening-hours, or sabre/vobject instead.
• Timezone-heavy or multi-locale requirements dominate; that is Carbon/Chronos territory, and mixing two date libraries is a net negative.
• Your dependency policy gates on adoption metrics, maintainer count, or security-review maturity. One maintainer is a bus-factor risk regardless of how clean the code is.
• You still support PHP versions the library has dropped, or you need framework-integrated pieces (casts, validation rules, Blade directives) — this package is framework-agnostic by design.
• The need is one or two functions. Vendoring two helpers is cheaper than the ongoing cost of tracking a dependency, and this package's value proposition scales with how many of its helpers you actually consume.

Watch item before committing: pin the version, confirm the release cadence holds (the January 2026 release is a positive signal), and confirm the maintainer responds to issues. Because dependents are at zero, you are an early adopter — budget a fork under MIT as the standing contingency rather than as an emergency measure.

How to Pitch It (Stakeholders)

To executives (30 seconds): This is a small, MIT-licensed utility library that handles the tedious parts of date arithmetic — ranges, intervals, business days, calendar checks. It replaces hand-written helper code that is a recurring source of subtle bugs, at the cost of a single lightweight dependency. It is not a platform commitment: it is small enough to fork or remove in a day, so the downside is bounded and the upside is engineering days returned to the roadmap.

To engineering (the real argument): It fills gaps that Carbon and DateTimeImmutable deliberately leave open, without asking you to change how you handle dates today. Framework-agnostic, no service provider magic, no opinion about your models. Adopt it behind a thin internal interface so the rest of the codebase never imports it directly — that keeps the exit cost at roughly zero and keeps the decision reversible.

Risk framing to name out loud: low adoption (~18 stars, 0 dependents) and a single maintainer. Mitigations are cheap and should be stated upfront — version pinning, source review before merge, an internal wrapper, and a standing fork option. A PM who names this risk and prices the mitigation at hours, not weeks, is making a stronger case than one who omits it.