Weave Code
Date Time Laravel Package
brick/date-time
A powerful set of immutable PHP date-time classes built on native PHP and following ISO 8601, inspired by Java's JSR 310. Adds missing concepts such as LocalDate, LocalTime, YearMonth, and MonthDay. Requires PHP 8.2+.
Brick\DateTime is an immutable date-time library for PHP that extends the native date-time classes with concepts PHP lacks, such as LocalDate, LocalTime, YearMonth, and MonthDay. Inspired by Java's JSR 310 API and following ISO 8601, it offers a rich, consistent API for modeling dates and times safely.
- Immutable value objects—safe to pass around without side effects
- Rich types including LocalDate, LocalTime, YearMonth, MonthDay, and DayOfWeek
- ISO 8601-compliant representations
- Requires PHP 8.2+, installable via Composer
- Well tested and stable enough for production use
Frequently asked questions about Date Time
- How do I install brick/date-time in Laravel?
- Install via Composer with composer require brick/date-time. The package requires PHP 8.2 or later. No Laravel service provider or configuration is needed; it works as a standalone library alongside Laravel.
- Is brick/date-time compatible with Laravel 10 or 11?
- Yes, brick/date-time is framework-agnostic and can be used in any Laravel version that runs on PHP 8.2 or later. It does not replace Laravel's Carbon but complements it for domain-specific date logic. You can use both in the same application without conflicts.
- What PHP version does brick/date-time require?
- The library requires PHP 8.2 or later. There is no polyfill available for older PHP versions. If your Laravel app targets PHP 8.1, you must upgrade PHP before adopting this package.
- How does brick/date-time compare to Carbon?
- Carbon is mutable and deeply integrated with Laravel, while brick/date-time is fully immutable and focuses on ISO 8601 types like LocalDate, YearMonth, and MonthDay. Brick is not a drop-in replacement for Carbon but can coexist. It excels when you need type safety, immutability, and precise date-component modeling.
- Can I use brick/date-time with Eloquent models?
- Direct Eloquent integration is not built in, but a separate package (brick/date-time-doctrine) provides Doctrine types. For Eloquent, you would need custom casts or manual conversion between brick objects and database values. Typed fields like YearMonth may require schema changes.
- How do I test time-dependent code with brick/date-time?
- Use the Clock interface with implementations like FixedClock to simulate specific times in tests. This enables deterministic testing of date-sensitive workflows such as promotions or subscriptions. You can inject a clock or set a default clock for now() methods.
- Is brick/date-time stable for production use?
- The library is well tested and stable enough for production, but it uses 0.x versioning, meaning breaking changes may occur on minor releases. Lock your project to a specific minor version like 0.10.* and review changelogs before upgrading. This mitigates upgrade risks.
- What are the main benefits of brick/date-time over native DateTime?
- It provides immutable objects, preventing accidental mutation when sharing instances. It adds missing ISO 8601 concepts such as LocalDate, YearMonth, and MonthDay, and offers a rich API inspired by Java's JSR 310. The Clock abstraction also makes time-based testing much easier.
- Does brick/date-time support time zones and daylight saving time?
- Yes, it follows ISO 8601 and includes time-zone-aware classes like ZonedDateTime. It handles daylight saving transitions, but as with any date library, you should test edge cases around DST changes. The immutable design helps avoid side effects in complex time-zone logic.
- What are alternatives to brick/date-time for Laravel?
- Alternatives include Carbon (Laravel's default), native DateTime, and libraries like Chronos. Brick/date-time stands out for immutability, ISO 8601 component types, and a Clock abstraction for testing. Evaluate based on your need for typed date components and deterministic time handling.
Weaver
How can I help you explore Laravel packages today?