- What is digital-craftsman/date-time-precision used for?
- It provides precise value objects for date and time subsets: Moment for an instant, plus Time, Date, Month, Year, Day and Weekday, along with typed collections, Symfony normalizers and Doctrine types. Each class is a thin wrapper around DateTime and DateTimeImmutable, so you do not have to force a DateTime to midnight or to the first of the month just to compare dates. It targets domains such as business hours, holidays, billing periods, recurring schedules and availability windows.
- How do I install digital-craftsman/date-time-precision in a Laravel app?
- Install it with composer require digital-craftsman/date-time-precision. The core value objects are plain PHP, so in Laravel you can use them without registering the Symfony bundle; the normalizers and Doctrine types only matter if you actually use those integration points. Your application must run PHP 8.4 or 8.5, which the package requires. Check Packagist for the current stable release before pinning a version in composer.json.
- Is this package Symfony-only or can I use it with Laravel?
- It ships as a Symfony bundle, but it is installable in Laravel without Symfony's HttpKernel or DependencyInjection, so you do not need the Symfony framework to use the value objects. In Laravel you typically use the classes directly and handle persistence with Eloquent casts or accessors, since the Symfony normalizers and bundle configuration are not part of the Laravel integration path. The Doctrine DBAL types are only relevant if your project already uses Doctrine.
- How does date-time-precision handle timezones and UTC?
- Moment is always UTC at construction: any DateTimeImmutable passed in with an offset is converted while preserving the exact instant, which keeps persistence and comparisons unambiguous. Timezone-specific work is explicit, for example through modifyInTimeZone or nextOccurrenceAtTimeInTimeZone, and display timezones belong in the presentation layer. This avoids DST off-by-one-hour bugs when switching between summer and winter time. Code that expected a Moment to remember its original local zone must now format explicitly.
- How do I store Moment, Date and Duration with Eloquent?
- The package does not ship Eloquent casts; store the values in suitable native columns such as date, time or datetime, or as strings, and convert them through custom casts, accessors or mutators. Doctrine types like Day and Days are provided for Doctrine DBAL users, while Eloquent stays on attribute casting. Duration is normalized as an integer number of microseconds, so it needs a bigint column with an integer cast, and API payloads should serialize microseconds rather than float seconds to avoid precision loss.
- What is the difference between Duration and CalendarPeriod?
- Duration models exact elapsed time with microsecond precision and is normalized as an integer of microseconds, which suits SLAs, billing and elapsed-time math. CalendarPeriod and CalendarUnit, covering days, weeks, months, quarters and years, model calendar movement instead. Keeping the two separate prevents the month-end overflow and DST drift bugs that come from conflating them, as fluent date libraries often do.
- Can this package model recurring schedules like weekly or monthly events?
- Yes, it includes recurrence value objects for daily, weekly-on-weekdays and monthly-on-days patterns, with methods such as occursOn, nextOccurrenceAfter, previousOccurrenceOnOrBefore, occurrencesBetween and the mustOccurOn guard. The scope is intentionally limited: there is no yearly recurrence, no interval support such as every two weeks, no BYSETPOS and no exception dates or holiday calendars. Validate those gaps against your product requirements before replacing a dedicated RRULE library.
- Which PHP and Laravel versions are supported?
- The package requires PHP 8.4 or 8.5, so that is the main constraint for a Laravel application. Laravel itself is not a declared dependency because the core is plain PHP, so the practical checks are your app's PHP version and, if you use the bundle integrations, the Symfony and Doctrine constraints listed in composer.json. Always confirm the current requirements on Packagist before upgrading.
- How does it compare with Carbon or RRULE libraries as an alternative?
- It is not a Carbon replacement: rather than a fluent manipulation API, it offers narrow value objects that make the meaning of a date, time, month or year explicit and keep moments in UTC. For recurrence it overlaps with RRULE libraries but deliberately omits yearly rules, intervals, BYSETPOS and exception dates. A common approach is to keep Carbon or native DateTime at the edges for parsing and formatting, and use these value objects inside the domain layer.
- Is it stable enough for production and how are breaking changes handled?
- It is tested thoroughly, including mutation testing, with more than 80 percent of the repository's lines of code being tests, and guards such as CollectionContainsDuplicates plus InvalidDate exceptions enforce domain invariants. However, it is still on 0.x releases and the API is evolving: recent versions changed datesUntil, monthsUntil and yearsUntil to return typed collections instead of arrays, and made Moment always UTC. Pin a version, read the changelog and re-verify serialization output shapes when upgrading.