Date Time Laravel Package

Product Decisions This Supports

• Modeling real business date concepts instead of only timestamps. LocalDate, LocalTime, YearMonth, MonthDay, YearWeek, LocalDateRange, Interval, Duration, and Period let teams represent domain rules directly—billing cycles, renewal dates, availability windows, reporting periods, trial expirations, blackout dates, leave ranges, and promotion windows—without overloading DateTime/Carbon or inventing fragile helper methods.
• Timezone-safe scheduling and event flows. Instant, ZonedDateTime, TimeZoneRegion, and TimeZoneOffset separate “a moment in time” from “a local calendar date.” This supports decisions around cross-region bookings, reminders, cutoffs, daylight-saving boundaries, and audit timestamps where correctness matters more than convenient formatting.
• Calendar arithmetic and range logic as a build-vs-buy decision. Range intersection helpers (LocalDateRange::intersectsWith(), getIntersectionWith()), date-range conversions, plusWeekdays()/minusWeekDays(), and period/duration objects reduce the need to hand-roll date math. This is a targeted “buy” of domain logic rather than a platform-level replacement.
• Deterministic testing for time-dependent features. DefaultClock::freeze(), travelTo(), travelBy(), and scale() support QA and engineering in testing expirations, renewals, reminders, and scheduled jobs without sleeping or mocking low-level system time. This can improve confidence in roadmap items that depend on time.
• Roadmap prioritization for date-heavy modules. Best candidate features are subscriptions/billing, booking and scheduling, promotions, payroll/leave, financial reporting periods, and compliance deadlines. Low-complexity CRUD screens with created/updated timestamps are not a strong fit.
• Architecture decision: keep Laravel-facing concerns separate from domain rules. Use Laravel’s existing Carbon/Illuminate date handling for Eloquent timestamps, request validation, and UI formatting; use brick/date-time where immutable domain value objects and explicit calendar concepts reduce defects.
• Vendor/risk decision. MIT licensing and Composer installation make adoption cheap. However, the package is 0.x, explicitly under development, and the provided dependency signal is weak. That argues for a bounded pilot with a pinned release cycle, not an unbounded enterprise-wide mandate.

When to Consider This Package

• Consider it when the product has non-trivial date/time rules: recurring billing, subscription renewals, booking availability, cross-timezone scheduling, date ranges with overlap/intersection logic, fiscal periods, partial dates such as month/day without year, or weekday-aware calculations.
• Consider it when immutability is valuable. All core classes are immutable, reducing accidental mutation bugs when values are passed through services, jobs, and domain objects.
• Consider it when the team wants a JSR-310/Java-inspired API and can accept a learning curve. The API is richer than Carbon but is not Laravel-specific and does not provide facades, service providers, or framework conventions.
• Consider it when the application is on PHP 8.2+ and can lock to a 0.x release cycle. The changelog shows a pattern of breaking changes between minor cycles, so version pinning and upgrade review are required.
• Consider it when Doctrine is used or planned, via the separate brick/date-time-doctrine package. Laravel teams using Eloquent should expect custom casts/integration work rather than a drop-in Laravel package.
• Look elsewhere when the need is simple timestamp storage, date formatting, or “created at/updated at” behavior. Laravel’s built-in Carbon support is the lower-friction default.
• Look elsewhere when the organization requires a mature 1.0 dependency, broad ecosystem adoption, or strict long-term semantic-versioning guarantees. This package is stable enough for production per its README, but its 0.x posture and low dependents signal are real adoption risks.
• Look elsewhere when PHP 8.2+ is a blocker, or when the team cannot absorb a Java-style date/time API and prefers Carbon-compatible idioms.
• Look elsewhere when a Laravel-native package with configuration, service provider, facades, and framework test helpers is mandatory. This is a framework-agnostic PHP library; integration effort is modest but nonzero.

How to Pitch It (Stakeholders)

Executive summary: brick/date-time is a small, MIT-licensed PHP library for correct, immutable date/time modeling. It is not a Laravel platform replacement and does not require replacing Carbon everywhere. It is most valuable in date-heavy product areas—billing cycles, scheduling, availability, renewals, reporting periods, and timezone-sensitive workflows—where ad hoc date math creates defects and slows delivery. The business case is reduced date-related bugs and clearer domain models, not a broad platform migration. Because the package is 0.x and has limited visible adoption, recommend a scoped pilot with a pinned version and clear success criteria.

Engineering summary: adopt it as a domain library alongside Laravel’s existing date handling. Use immutable value objects (LocalDate, LocalTime, YearMonth, LocalDateRange, Instant, ZonedDateTime, Duration, Period) for business rules, and use Carbon for framework-facing formatting and Eloquent timestamps. The built-in Clock abstraction improves deterministic tests for time-dependent features. Integration is standard Composer plus custom casts/adapters where needed; Doctrine users can use the companion mapping package. Main risks are the 0.x release cadence, PHP 8.2+ requirement, and lack of Laravel-native conveniences. Mitigate by pinning a release cycle, wrapping usage behind domain services or casts, and starting with one high-value module rather than a wholesale rewrite.