Laravel Dateinterval Cast Laravel Package

Technical Evaluation

Decision summary: Do not adopt this as a production Composer dependency. Treat atymic/laravel-dateinterval-cast as a reference implementation and vendor the cast class (~40–80 lines) into the application with internal tests and ownership. Value is in the pattern, not the package.

Architecture fit

• The package does one narrow thing: registers an Eloquent custom cast that hydrates a database column into a CarbonInterval/DateInterval object and serializes it back on write. It sits entirely in the persistence layer and introduces no service provider sprawl, no config surface, and no runtime hooks.
• Carbon is already a hard transitive dependency of every Laravel app, so the conceptual fit is clean — engineers won't need a new mental model, only a cast declaration on a model.
• Fit is conditional on storage format. The cast is only as good as the column contract behind it (ISO 8601 duration string vs. integer seconds vs. HH:MM:SS). Most integration failures here are data-modeling failures, not code failures.
• It does not solve scheduling semantics: a CarbonInterval of "P1M" is not a fixed number of seconds. If the business logic needs month-aware or DST-aware arithmetic, the cast is a transport mechanism only and the domain layer must own the math.

Integration feasibility

• Mechanically trivial: add to $casts, confirm the column type, write two or three feature tests. A mid-level engineer can validate it in under a day.
• The real gate is Composer resolution, not code. With a last release of 2020-09-09, the published illuminate/* and nesbot/carbon constraints almost certainly cap at Laravel 7/8 and Carbon 2. On Laravel 10/11/12 with Carbon 3, composer require will either fail outright or silently resolve the whole app back to an older Carbon. That is a fleet-wide blast radius from a 12-star package.
• Even where it installs, the internal CastsAttributes contract has drifted (get/set signatures, cast parameters, the casts() method replacing the $casts property in Laravel 11). None of these are guaranteed to break, but none are covered by the package's test matrix either.

Technical risk

• Abandonment (high, accepted): no upstream since Sept 2020, 12 stars, ~zero issue throughput. Effectively unmaintained. Mitigated by the tiny surface area — you can read the whole thing in one sitting.
• Dependency conflict (high, avoidable): the dominant failure mode, and the reason to vendor rather than require.
• Silent data corruption (medium): round-tripping intervals through a lossy format (e.g., storing P1M as 2,592,000 seconds) will pass tests and then drift. Enforce format at the schema and validation layer, not in the cast.
• Hydration exceptions on bad rows (medium): an unparseable value throws during model hydration, so one bad row becomes a 500 on read. Needs defensive accessors or a write-time guard.
• Low opportunity score (0.38): this is a convenience, not a differentiator. Do not let it consume roadmap attention beyond the initial spike.

Key questions

1. What format is the source of truth — ISO 8601 (P1Y2M3D), integer seconds, or a Postgres INTERVAL? Who owns that decision?
2. Do we need calendar-aware intervals (months, years, DST) or only fixed-duration seconds? This changes the correct answer entirely.
3. Are we on Carbon 2 or Carbon 3 today, and does the package's constraint permit it?
4. Is there existing production data in these columns, and does it round-trip cleanly?
5. What is the API contract — ISO 8601 string, human-readable (forHumans()), or seconds?
6. Who owns the vendored copy after the spike?

Integration Approach

Stack fit

• Laravel + Eloquent + Carbon stack, no additional infrastructure. Works regardless of database engine as long as the column type is explicit (varchar(64) for ISO 8601 is the safest default; integer seconds if calendar semantics are genuinely unnecessary).
• Prefer ISO 8601 strings: human-readable in the database, unambiguous, portable across MySQL/Postgres/SQLite, and inspectable during incidents without a decoder.

Migration path

1. Spike (0.5 day): clone, read the source, run it against our Laravel version in a scratch branch. Record exactly where Composer or the cast contract diverges.
2. Vendor (0.5 day): copy the cast class into app/Casts/, add an MIT attribution header, and pin our own signature to the current CastsAttributes interface.
3. Harden (0.5–1 day): unit tests covering null, zero, malformed input, round-trip fidelity, and month/year intervals. Decide the failure mode for unparseable values (exception vs. null + log).
4. Pilot (0.5 day): apply to one low-traffic model and one read path.
5. Rollout: document the storage contract in the model/README and expand.

Compatibility

• Explicitly verify against our pinned PHP, Laravel major, and Carbon major. If the vendored copy is ours, compatibility is a solved problem by construction — that is the core argument for vendoring.
• Add a CI job that exercises the cast on the framework version we will run at next upgrade, so Laravel/Carbon upgrades surface breakage in our own test suite rather than in production.

Sequencing

Run this after the schema/format decision and before any feature that consumes intervals. Do not let the cast become the de facto specification of what an interval means — write that down first.

Operational Impact

Maintenance

• Cost is near-zero but non-zero: ~50 lines we own, plus tests. Budget a few hours per Laravel major upgrade to re-verify the cast interface.
• Owning it also removes the "is this package dead?" question from every future dependency audit — worth more than the code itself.

Support

• Community-only, no SLA, 12 stars, no maintainer response guarantee. Internal documentation and a named owner are mandatory if adopted at all.
• On-call engineers will encounter this only via hydration exceptions; the runbook should say "check the stored string format" first.

Scaling

• Negligible. Casts are per-attribute, in-memory transformations — no query cost, no N+1 implications, no serialization overhead worth measuring.
• The one scaling-adjacent concern is API payload size and consistency: CarbonInterval JSON-serializes poorly by default, so expose an explicit toIso8601String() accessor rather than letting the cast object leak into responses.

Failure modes

• Composer constraint conflict blocking a framework upgrade (highest severity, avoided by vendoring).
• Malformed stored value → exception on hydration → 500 on any read of that row. Mitigate with write-time validation, a DB CHECK, and a null-safe accessor.
• Lossy round-trip: months and years collapsed to seconds, or sub-second precision silently dropped.
• Null vs. zero ambiguity: null (unknown) and PT0S (zero) must not be conflated.
• DST/timezone confusion if anyone treats an interval as a date offset — a documentation problem, but a recurring one.

Ramp-up

• 1–2 hours for a mid-level Laravel engineer to be productive; the cast idiom is standard. The onboarding cost is in the storage contract documentation, not the code.
• Total organizational investment for the vendored path: roughly 1.5–2.5 engineer-days including tests, pilot, and docs. The dependency path looks cheaper on day one and costs more at the next Laravel upgrade.