Datetime Laravel Package

Technical Evaluation

Architecture fit

• tempest/datetime is the datetime component of the Tempest framework, extracted as a read-only sub-split. It is not a Laravel package: no service provider, no facade, no config, no Eloquent casts, no validation rules, no Blade directives. Everything Laravel-shaped must be written by us.
• The component's value proposition is locale- and timezone-aware date/time value objects built on ext-intl (ICU), i.e. immutable, calendar-aware types with a Tempest\… namespace. This overlaps almost entirely with Carbon + ext-intl, which Laravel already ships and wires into Eloquent, now(), the scheduler, date validation, and Blade.
• Net fit: low as a framework-wide choice, plausible as a bounded-context utility. Any adoption is an island, not a substitution.

Integration feasibility

• Requires a standalone-compatibility check: does the split package pull tempest/support or other framework primitives (container, attributes, discovery) that assume a Tempest kernel? If yes, we inherit transitive framework surface area from a non-Laravel framework. This is the first spike.
• Practical integration surface we would own: an Eloquent cast (CastsAttributes) for each persisted type, Castable/JsonSerializable adapters at API boundaries, a bridge to/from CarbonImmutable for anything Laravel hands us (scheduler, now(), queue payloads, signed URLs, cache TTLs), and a formatter for Blade/API output.
• Effort is not in the library; it is in the seam. Budget 2–3x the library-evaluation effort for adapter + parity tests.

Technical risk

• Pre-1.0 API churn. Tempest is young; class names, method signatures, and parsing semantics should be assumed unstable until 1.0. Pin exactly and treat upgrades as planned work.
• Sub-split signal distortion. 0 stars / 0 dependents / score 0 are artifacts of the split, not quality signals — consumers depend on the framework distribution or the monorepo, and issues/PRs are routed to tempestphp/tempest-framework. Do not read the score as "unmaintained," but do read it as "you cannot judge health from this repo page; you must read the parent."
• ICU drift. Correctness depends on ext-intl and the system ICU/timezone database. Container images, CI, and prod must be pinned to matching ICU builds or DST/zone/formatting edge cases diverge between environments. Carbon has the same class of risk but a larger body of tribal knowledge around it.
• Key-person and bus-factor risk. Effectively one primary author across the framework. Acceptable for a utility library consumed behind an internal interface; not acceptable as a load-bearing dependency in a revenue-critical scheduling domain without a fallback plan.
• Ecosystem gravity. Every answer, Stack Overflow result, hiring signal, and code-review reflex in a Laravel team is Carbon-shaped. Choosing otherwise has a permanent, low-grade tax.
• License: MIT — no legal friction.

Key questions

1. Does the split package install and operate standalone without tempest/framework or its container/discovery layer?
2. Minimum PHP version, and is ext-intl a hard requirement or polyfilled?
3. Are tags versioned in lockstep with the framework, and does the split publish stable semver or dev-master only?
4. What is the actual differentiator versus CarbonImmutable + IntlDateFormatter — non-Gregorian calendar support? Strongly-typed Duration/Interval distinction? Attribute-driven serialization?
5. What does the reverse migration cost look like if Tempest 1.0 direction diverges (framework-first, Laravel-irrelevant)?
6. Who are the maintainers of the parent repo, and what is the release cadence and deprecation policy?

Integration Approach

Stack fit

• Keep Laravel's Carbon as the default and boundary type. Introduce tempest/datetime only where its semantics earn their keep — e.g. a booking/availability domain needing locale-correct calendar arithmetic, or reporting surfaces with heavy non-Gregorian/locale formatting.
• Encapsulate behind a domain-owned interface (e.g. App\Domain\Time\Clock, …\Calendar), with Tempest types as an internal implementation detail. No Tempest type in a controller signature, model property, or API resource.
• Persist as UTC in standard SQL datetime/timestamp columns. Convert at the edges. Do not let a third-party datetime type define the storage contract.

Migration path

• Greenfield domains first; no retrofit of existing models.
• If retrofit is ever considered, do it per-domain with a strangler pattern and a strict rule: Tempest types never cross a domain boundary.

Compatibility

• Pin the package to an exact version (not ^) until upstream reaches 1.0, and record the corresponding framework commit SHA in the ADR.
• Pin ICU/timezone data in Docker images; add a CI check asserting the same output for a fixture set of DST/zone/locale edge cases across CI and staging.
• Add a composer audit note: verify transitive dependencies before first install; a framework split pulling container code is a stop signal.

Sequencing

1. Spike (1 week): install standalone, confirm no framework primitives required, exercise DST/locale/parse edge cases against Carbon outputs.
2. Parity harness: property-based and fixture tests comparing Tempest and Carbon results for our actual date operations. This is the artifact that de-risks everything.
3. Single bounded context: implement behind the internal interface, with Eloquent cast + JSON adapter.
4. Review gate: measure adapter LOC, upgrade pain, and reviewer friction before any second consumer.
5. Stop by default. Absent a concrete capability gap, remain on Carbon. Do not expand for consistency alone.

Operational Impact

Maintenance

• We own 100% of the glue: casts, adapters, converters, formatting. That code is ours forever and is the main ongoing cost.
• Upstream fixes flow only through monorepo releases into the split; we cannot patch the split directly (read-only). Local forks are a last resort and create a permanent merge burden.
• Vendor maintenance is low-effort but low-visibility: no security mailing list for this package specifically; subscribe to the parent repo instead.

Support

• No meaningful community for this package in a Laravel context. Internal expertise is a single person's head unless we deliberately spread it.
• Escalation path is GitHub issues on the parent monorepo — no SLA, no commercial support.
• Key-person risk is real but bounded if adoption stays behind an interface: a revert is a code change in one adapter, not a migration project.

Scaling

• Runtime cost is negligible either way; the library is a thin wrapper over ext-intl. Immutability may reduce a class of aliasing bugs. This is not a performance decision.
• Scaling concern is organizational: onboarding cost per engineer, and the drag of a second datetime idiom in a codebase that already has one.

Failure modes

• Silent formatting divergence between environments from mismatched ICU versions — surfaces as locale/DST bugs in production only.
• Boundary leakage: a Tempest type ends up in an API resource or model, and the adapter tax becomes a rewrite.
• Upstream breaking change in a minor version pre-1.0, blocking a PHP upgrade until we patch or pin.
• Abandonment: upstream direction shifts away from framework-agnostic utilities; we are left on a dead pinned version behind our own interface.
• Parsing ambiguity: a parse succeeds with different semantics than Carbon would have produced, silently changing stored values — mitigated by the parity harness.

Ramp-up

• Assume 1–2 days per engineer to reach competence, plus a permanent review tax because reviewers' reflexes are Carbon-shaped. Codify conventions in an ADR and a short internal guide.
• Recommend: adopt only with a named owner, a written ADR justifying the capability gap, and the parity harness merged before the first production use. Otherwise, stay on Carbon and revisit when Tempest reaches 1.0 with a stable, framework-independent API.