Datetime Laravel Package

Technical Evaluation

Architecture fit

• psx/datetime is a value-object datetime model modeled on JSR310: Instant, LocalDate, LocalDateTime, ZonedDateTime, Duration vs. Period, and an injectable Clock. That is a genuinely better semantic model than DateTime for anything involving explicit time zones, calendar arithmetic, or testable "now".
• The architectural problem is that Laravel's entire datetime spine runs on DateTimeInterface and Carbon. Eloquent casts, Illuminate\Support\Carbon, validation rules (date, after_or_equal), Blade format()/diffForHumans(), queue payload serialization, Model::freshTimestamp(), and most first-party and third-party packages all assume native datetime objects. psx/datetime objects almost certainly do not implement DateTimeInterface, which makes them non-interchangeable with that spine.
• Therefore the only defensible fit is sidecar domain model inside one bounded context (scheduling/recurrence, SLA or business-calendar calculation, cross-timezone billing cutoffs, retention windows) — never a framework-wide replacement for Carbon.
• An anti-corruption layer is mandatory. The dominant failure mode is leakage: a ZonedDateTime escaping into a controller, cast, or event payload and forcing every downstream consumer to learn the library.

Integration feasibility

• Installation is trivial and low-blast-radius: a PSR-4 library with no service provider, no facade, no config, and a unique PSX\DateTime namespace. Conflict risk is near zero.
• Real feasibility work is version compatibility. Verify composer.json's require.php constraint, whether it drags in psx/common, and whether the test suite runs green on the PHP version your Laravel release requires (8.2/8.3/8.4). A JSR310-era port plausibly predates typed properties, return types, and str_contains-era refactors, and may hit PHP 8.1+ deprecations (implicit nullable parameters, dynamic properties) or fatal errors on newer runtimes.
• The absence of a Laravel integration surface is both a plus (nothing to break on upgrade) and a minus (you write every adapter, cast, and validation bridge yourself).

Technical risk

• Ecosystem signal is the headline risk. 2 stars, 0 dependents, single maintainer, opportunity score 44.28. There is effectively no community exercising this code, which means edge cases in DST gaps/folds, leap seconds, and tz-database drift have no external bug reports backing them.
• The capability is commoditized. brick/date-time is a mature, actively maintained JSR310 port with broad adoption; Carbon 3 and native DateTimeImmutable cover the rest. Adopting this specific package over those needs a reason beyond "it's a JSR310 port".
• Boundary conversion is code you own forever. Every persistence, API, and logging boundary needs a mapper, and each mapper is a place where a timezone or precision bug can hide.
• Precision and semantics divergence. Microsecond handling, Duration vs. Period in month arithmetic, and DST resolution rules may not match what your DB driver or Carbon produces for the same input.
• Serialization. These objects will not round-trip cleanly through Laravel's queued-job payloads or cache without a custom serializer; an unserializable value object in a job is a production incident waiting to happen.

Key questions

1. What is the actual require.php constraint, and does the suite pass on the PHP versions our Laravel release supports?
2. Which single bounded context has a semantic need that Carbon/native datetime demonstrably fails — with a failing test case to prove it?
3. Does the package implement DateTimeInterface anywhere, or is every boundary conversion ours to write?
4. Why this port and not brick/date-time?
5. Are we prepared to fork and own it under Apache-2.0, including a PHP-version CI matrix?
6. Can we guarantee these types never appear in a controller signature, Eloquent cast, or queued payload?

Integration Approach

Stack fit

• Assume Laravel 10+ on PHP 8.2+. The package is framework-agnostic, so "fit" is entirely a function of how tightly we fence it.
• Recommended topology: Carbon/DateTimeImmutable at the edges, psx/datetime in the domain core. Persistence stays timestamp/timestamptz columns with standard Eloquent casts. API resources emit ISO-8601/RFC 3339 strings. Only the domain service touches PSX\DateTime.
• If the team is not prepared to maintain the adapter layer, the correct answer is to skip this package entirely and use brick/date-time or Carbon 3's immutable API.

Migration path Not a migration — an isolated adoption with an exit ramp.

1. Spike (1–2 days): install in a scratch branch; port one real, currently-buggy calculation; run it against the existing Carbon implementation on historical data. Gate: does it produce different results, and is the difference correct?
2. Adapter module (2–3 days): app/Support/Time/ containing fromNative() / toNative() / toIso() mappers, a Clock binding in the container for deterministic tests, and an Eloquent custom cast if persistence is unavoidable.
3. Contract tests: property-based or table-driven tests over the native↔psx boundary, including DST boundaries for every timezone in our customer base, plus a serialization round-trip test for anything queue-adjacent.
4. Bounded rollout: one service class, one feature flag, no public API changes.
5. Decision gate at 30 days: if the adapter surface is still growing, that is the signal to abandon and reimplement on brick/date-time.

Compatibility

• No Laravel version coupling and no config surface means framework upgrades won't break it — but PHP upgrades will, and that is the compatibility axis to monitor.
• Namespace collision risk is negligible; Composer resolution risk is limited to transitive psx/* requirements.
• Do not expose these types in public PHP interfaces, events, or API DTOs. That converts a reversible decision into an irreversible one.

Sequencing

Operational Impact

Maintenance

• Treat this as fork-and-own, not dependency consumption. Apache-2.0 permits it; vendor the code into a private Composer VCS repo so you control the PHP-version floor.
• Budget roughly 1–2 engineer-days per quarter for PHP compatibility fixes, plus the initial CI matrix (8.2/8.3/8.4) and a static-analysis baseline. That is the true cost, and it recurs.
• Pin the version exactly. Never use a floating constraint on a single-maintainer, zero-dependent package.

Support

• There is no maintainer SLA, no security advisory path, and no downstream users to surface defects. You are the support organization, the CVE-response team, and the bug tracker.
• Onboarding documentation is not optional: a one-page "when to use psx vs. Carbon" rule is the difference between a contained domain model and an architectural infection.

Scaling

• This is a pure computation library; it will not be a throughput bottleneck. Expect modest per-object allocation overhead relative to native DateTimeImmutable in hot loops — measurable at millions of operations, irrelevant at typical business-logic volumes.
• The real scaling concern is correctness at scale: timezone-database version drift between app servers, and any place where a converted value is cached or persisted without an explicit zone.

Failure modes

• Silent DST arithmetic errors — the highest-severity failure; wrong results, no exception.
• PHP upgrade breakage — a routine base-image bump turns into an unplanned fork-and-patch sprint.
• Serialization loss in queued jobs or cache, surfacing as intermittent, environment-specific bugs.
• Type leakage into controllers, casts, or events, which converts a reversible local decision into an org-wide migration.
• Abandonment — the maintainer moves on and there is no successor, which is the default expectation given the adoption signal.

Ramp-up

• Assume 1–2 engineer-days of learning for engineers fluent in Carbon to become productive with JSR310 semantics (Instant vs. LocalDateTime vs. ZonedDateTime, Duration vs. Period).
• Ongoing cognitive cost is the real tax: two datetime mental models in one codebase, with a conversion boundary that every new engineer must be taught to respect.
• Mitigation: keep the API surface tiny (three or four adapter functions), name them unambiguously, and forbid direct imports outside the domain folder via a static-analysis rule.

Verdict: the JSR310 model is worth having; this package is a hard sell at 2 stars, 0 dependents, and a single maintainer. Approve only as a fenced, forked, single-bounded-context experiment with a defined exit ramp — otherwise take brick/date-time or stay on Carbon and solve the problem with DateTimeImmutable plus explicit timezone handling.