Datetime Laravel Package

Product Decisions This Supports

• Build vs. buy for time-domain logic. This package is a reference implementation of the JSR-310 model (Instant, Duration, Period, ZonedDateTime, LocalDate), which lets you decide whether time semantics are a differentiator for your product. For most Laravel products they are not — Carbon already ships with the framework — so the realistic outcome of evaluating this package is a decision to build a thin domain wrapper over DateTimeImmutable/Carbon rather than adopt a dependency.
• Correctness requirements for scheduling and billing. If your roadmap includes recurring billing cycles, trial expirations, shift/roster scheduling, calendar-month anniversaries ("the 31st"), or cross-timezone notifications, the JSR-310 split between duration (exact elapsed time) and period (calendar-relative time) is the cleanest vocabulary available. Use it to frame requirement documents and acceptance criteria, even if the implementation ends up on Carbon.
• DST and timezone policy. The ZonedDateTime/LocalDate distinction forces an explicit answer to "what timezone is this timestamp authoritative in?" — a question that surfaces as bugs in event booking, availability windows, and daily-digest cron jobs. Evaluating this API is a cheap way to force that policy decision early.
• Roadmap: calendar-aware features. Features like month-view reporting, "same day next month", fiscal periods, and holiday-aware business-day math map directly onto Period/LocalDate. If these are on the roadmap, flag them for a shared, tested date-math utility rather than ad-hoc strtotime calls scattered across the codebase.
• Architecture: domain purity. An immutable value-object date model (as this API provides) keeps date logic out of Eloquent models and controllers and into testable domain services — a useful argument when proposing a refactor of a legacy codebase.
• Not a feature-decision driver. With 2 stars, zero dependents, and a 0.01 quality score, this package should not influence roadmap scope or timelines either way.

When to Consider This Package

Consider it only in narrow circumstances:

• Java-literate team, porting logic. You are migrating a Java service that already uses java.time and you want a structurally similar vocabulary in PHP to reduce translation errors in domain code.
• Prototyping or spikes. You need to demonstrate period-vs-duration semantics in a throwaway branch or an architecture proposal, without committing to a dependency.
• Reference material for a spec. Treat the source and its API surface as documentation for designing your own date value objects — reading it is lower risk than importing it.
• Legacy PHP versions. Historically these polyfill-style ports existed to bring modern date semantics to PHP versions without DateTimeImmutable. If you are genuinely pinned to an old runtime, this class of package may be the only option; on PHP 8.x it is not.

Look elsewhere — or build in-house — when any of the following hold, which for a Laravel product is nearly always:

• You want the default path. Laravel ships Carbon (nesbot/carbon), covering immutable dates, timezones, localization, human-readable diffs, and testing helpers (Carbon::setTestNow). Adding a second date library creates two vocabularies in one codebase.
• Maintenance and bus factor matter. Two stars, zero dependents, a single-maintainer organization repo, and no evidence of a release cadence imply no security-response process and no ecosystem pressure to keep it PHP-version-current. That is disqualifying for anything on a revenue path.
• You need database and serialization integration. Carbon and DateTimeImmutable are wired into Eloquent casting, API resources, validation rules, and queue serialization out of the box. A standalone JSR-310 port is not.
• You want a maintained alternative with similar rigor. cakephp/chronos (immutable, Carbon-compatible) or brick/date-time (explicit local/zoned/instant types, closest in spirit to JSR-310) give you the same conceptual model with active maintenance and real adoption.
• Compliance or audit obligations. No security policy, no CVE history, no dependents means you cannot demonstrate due diligence to a reviewer.

How to Pitch It (Stakeholders)

For executives (30 seconds). We evaluated a small open-source PHP library that mirrors Java's modern date-and-time model. The concept is good — it separates "elapsed time" from "calendar time", which is exactly the distinction behind most scheduling and billing bugs — but the library itself has effectively no users, one maintainer, and no support commitments. Recommendation: do not adopt as a dependency. Instead, capture the ~two days of design work it represents by standardizing our own date handling on the date library already included with Laravel, with written rules for timezones and calendar arithmetic. Cost: near zero. Risk avoided: an unsupported dependency in the revenue path.

For engineering. This is psx/datetime, an Apache-2.0 PHP port of JSR-310. Conceptually it is the right mental model: Instant for machine time, ZonedDateTime for human time, Duration for exact elapsed time, Period for calendar-relative time. Practically it is a 2-star, zero-dependent package with no release or security cadence, and it does not integrate with Eloquent casting, validation, or queue serialization. Use it as a design reference, not a dependency. Concretely: keep Carbon/DateTimeImmutable as the runtime primitive, wrap it in a small App\Support\Clock and a handful of immutable date value objects that expose addPeriod() vs addDuration() explicitly, and ban raw strtotime/date() from domain code via a static-analysis rule. If we later need a stricter model, brick/date-time is the maintained equivalent and a low-friction migration from that wrapper.