- How do I install digital-craftsman/datetime-parts in a Laravel app?
- Install it with Composer using the package name, then register the package Clock implementation in Laravel's service container. The core value objects are mostly plain PHP, so they work without Symfony, but the bundled normalizers and Doctrine types are optional Symfony-oriented extras. For Eloquent, add custom casts for Moment, Date, Time and the new collection and range types. Check the changelog and README for the exact install and registration steps for your version.
- Is this package compatible with Laravel or only Symfony?
- The value objects are pure PHP and can be used in Laravel without Symfony. However, the package remains Symfony and Doctrine oriented: it ships Symfony normalizers and Doctrine types, not Laravel casts or service providers. Laravel adoption requires deliberate bridging for the Clock service, serialization, and Eloquent casts.
- What is the difference between Moment, Date, Time, Month and Year?
- Moment represents an exact instant in time and is always stored internally in UTC. Date, Time, Month and Year represent partial values that are not tied to a single instant, such as business hours, Christmas, or a billing month. This avoids the misleading extra information that DateTime carries when you only need part of a date.
- How do I store Moment and Date values with Eloquent?
- Moment expects microsecond-capable columns such as DATETIME(6) or TIMESTAMP(6), and Date, Time, Month and Year need appropriate column types. Create custom Eloquent casts that map the value objects to and from the database. If you use Doctrine instead, the package includes Doctrine types for many of the objects. New collection and range types may still require custom serialization strategies.
- How does v0.15.0 change timezone handling?
- Moment is now always UTC, and non-UTC inputs are converted on construction. Timezone handling becomes an explicit presentation concern, and Moment::toTimeZone is deprecated. Code that expected a non-UTC offset to be preserved must be updated. modifyInTimeZone on Date, Month and Year is also deprecated in favor of calendar-period-based add and subtract methods.
- What breaking changes should I expect when upgrading to 0.15?
- Moment converts to UTC on construction, Date rejects impossible dates such as 31 April, and datesUntil, monthsUntil and yearsUntil now return collections instead of arrays. Several methods are deprecated, including Moment::toTimeZone and Time::distanceInMinutesTo. Imports, fixtures and legacy rows must be audited before upgrading. Pin to 0.15.* while you remediate.
- Can I use this package for recurring events and availability calendars?
- Yes, v0.15.0 adds Duration, CalendarPeriod, CalendarUnit, Recurrence, Week, DateRange, MomentRange and TimeRange. These are suited to bookings, appointments, subscriptions, SLAs, availability calendars and recurring billing. They integrate with the first-class collection types for filtering, sorting and comparison.
- How do the collection classes like Dates and Moments work?
- Collections such as Dates, Moments, Times, Weeks, Months, Years, Durations, CalendarUnits, CalendarPeriods, DateRanges, MomentRanges, TimeRanges and Recurrences are real objects, not arrays. They implement Countable and IteratorAggregate and support filtering, mapping, sorting, min/max and equality checks. They also reject duplicates via CollectionContainsDuplicates. Because they are not plain arrays, API resources, queue payloads and third-party code need explicit mapping.
- Is this package safe to use in production before 1.0?
- It is pre-1.0 and minor releases can contain breaking changes, so pin to 0.15.* and monitor the changelog. The package is thoroughly tested, with more than 80% of the repository in tests including mutation testing. Audit legacy data for invalid dates and UTC assumptions during migration. Add integration tests around your Eloquent casts and queue serialization.
- What are alternatives to Carbon for date-only or time-only values in Laravel?
- Carbon and DateTime always represent an instant and carry misleading context when you only need a Time, Date, Month or Year. This package provides dedicated immutable value objects plus collections and ranges, which can be cleaner for domain-driven design. You can also build custom casts or use other value-object libraries. The tradeoff is less Laravel-native integration than Carbon.