Dates Timezone Conversion Trait Laravel Package

Product Decisions This Supports

• Per-user timezone handling without a data model rewrite. v3.1.0 interprets incoming date strings in the authenticated user's timezone and stores them in the application timezone, so a "9am meeting" entered by a user in Berlin and one in Denver land in the database as the correct instants. This unblocks features like scheduling, deadlines, reminders, and reporting cutoffs for a multi-region user base without adding timezone columns to every table or a conversion layer in every controller.
• Modernisation and upgrade sequencing. The package claims support for Laravel 5.1 through 13 on PHP 5.5.9 upward. That makes it viable as a stabilising dependency during a framework upgrade: fix timezone correctness now, defer the Laravel/PHP upgrade, and keep the same package across both.
• Build vs. buy. The core behaviour (cast, user-timezone input, app-timezone storage, Carbon immutability on read) is small but fiddly and easy to get subtly wrong in-house. Buying/ adopting costs one Composer line; building costs a custom cast plus ongoing edge-case maintenance.
• Bug-fix roadmap items that are cheap to close. Two items in this release are quality-of-life fixes that will otherwise generate support tickets: nullable date columns now pass through unchanged (no more null-to-epoch surprises), and returned Carbon values are cloned so reading a model attribute can no longer mutate the underlying model value and cause phantom dirty state or off-by-one saves.
• Legacy surface coverage. Recognising both legacy date fields and current date/datetime casts means existing models keep working after adoption — no need to audit and rewrite every $dates/$casts declaration before shipping.
• Use cases it directly enables: user-facing scheduling and calendars, SLA/response-time tracking, "today" boundary logic in dashboards, audit timestamps displayed in local time, and any feature where two users must agree on when something happened.

When to Consider This Package

Adopt it when most of the following hold:

• You have (or are about to have) users in more than one timezone, and dates are currently entered or displayed without conversion.
• You store timestamps in the database but want the input and display boundaries handled consistently rather than ad hoc in controllers and views.
• You are on an older Laravel (5.x–8.x) or constrained PHP version and cannot rely on newer framework datetime casting or immutable Carbon defaults.
• You have a mixed bag of legacy $dates properties and modern $casts entries that you cannot migrate in one go.
• You want a narrow, single-responsibility dependency rather than a full audit/scheduling package.

Look elsewhere or stay in-framework when:

• You are on a current Laravel with Carbon 3 immutable dates and are happy with datetime casts plus a thin display helper — the marginal value shrinks.
• You need timezone conversion at the presentation layer only (formatting a UTC timestamp in the viewer's zone). A Blade/JSON transformer is simpler than a cast.
• You need recurring events, DST-aware scheduling rules, or business-calendar logic — that is a scheduling engine, not a cast.
• You require strict, verifiable platform support: "Laravel 5.1 through 13 with PHP 5.5.9" is a very wide claim. Verify against the package's CI matrix before committing, and check whether future-major support is real or a permissive constraint. Supporting PHP 5.5.9 also implies the codebase cannot use modern language features — a long-term maintenance signal worth weighing.
• You depend on the package's mutating-read behaviour somewhere. The Carbon-clone change alters semantics for any code that currently relies on receiving a mutable reference; audit before upgrading.

How to Pitch It (Stakeholders)

For executives: We have a correctness bug class — dates entered by users in different regions are stored inconsistently, which produces wrong reminders, wrong deadlines, and reporting numbers that don't reconcile. This release lets us fix that with a one-line dependency instead of a schema migration and a rewrite of every date-handling endpoint. It is backward compatible, ships null-safety and a fix for a subtle data-corruption bug where reading a date could silently alter the record, and it works across our entire Laravel/PHP version range — so it is not coupled to any upgrade project we have planned. Cost is near zero; the risk of not doing it is a continuing stream of timezone support tickets and untrustworthy timestamps.

For engineering: v3.1.0 gives us user-timezone input parsing, app-timezone storage, null passthrough, and coverage for both legacy $dates and date/datetime casts. Two behavioural notes before you merge: returned Carbon instances are now clones, so any code relying on mutating a returned date object will no longer affect the model (this is the correct behaviour, but it is a change); and the declared support window (Laravel 5.1–13, PHP 5.5.9) is broad enough that we should confirm which combinations are actually exercised in CI and pin our own integration test to our combination. Adoption is a single Composer require plus swapping the cast on the models that need it — no migrations, no data backfill.