💥 Breaking changes

• Instant::toISOString() and ZonedDateTime::toISOString() now always include seconds, to be RFC 3339 compliant (#131 by @dualfroz)

💥 Breaking changes

• Minimum PHP version is now 8.2
• The following classes are now final:
  • YearMonthRange
  • ZonedDateTime
  • Parser\DateTimeParseException

✨ Compatibility improvements

• The following parser and parse methods now accept hours only in timezone offsets, such as +01 equivalent to +01:00 (#123 by @antonkomarev):
  • IsoParsers:timeZoneOffset()
  • TimeZoneOffset::parse()
  • ZonedDateTime::parse()

💥 Breaking changes

• Duration::toISOString() and __toString() now output negative durations as -P... (#122 by @BastienClement)
  Example: -PT2H21M instead of PT-2H-21M.
  This aligns with ISO 8601-2:2019 and improves compatibility with the JavaScript Temporal API.

🐛 Bug fixes

• ZoneDateTime incorrectly handled DST Transitions with relative time addition (#115)

✨ New features

• LocalDate::getQuarter() and getQuarterValue() return the quarter of the year (#114 by @pscheit)

💥 Breaking changes

• DayOfWeek:
  • deprecated method of() has been removed, use DayOfWeek::from() instead
  • the following deprecated methods have been removed, use enum values instead:
    • DayOfWeek::monday() → DayOfWeek::MONDAY
    • DayOfWeek::tuesday() → DayOfWeek::TUESDAY
    • DayOfWeek::wednesday() → DayOfWeek::WEDNESDAY
    • DayOfWeek::thursday() → DayOfWeek::THURSDAY
    • DayOfWeek::friday() → DayOfWeek::FRIDAY
    • DayOfWeek::saturday() → DayOfWeek::SATURDAY
    • DayOfWeek::sunday() → DayOfWeek::SUNDAY
  • deprecated method getValue() has been removed, use $dayOfWeek->value instead
  • deprecated method is() has been removed, compare values with $dayOfWeek or $dayOfWeek->value instead
  • deprecated method isEqualTo() has been removed, use strict equality === between DayOfWeek instances instead.
• DefaultClock:
  • deprecated method travel() has been removed, use travelTo() instead
• LocalDate:
  • deprecated method getDay() has been removed, use getDayOfMonth() instead
  • getMonth() now returns a Month enum; use getMonthValue() if you want the month number
• LocalDateTime:
  • deprecated method getDay() has been removed, use getDayOfMonth() instead
  • getMonth() now returns a Month enum; use getMonthValue() if you want the month number
• Month:
  • deprecated method of() has been removed, use Month::from() instead
  • deprecated method getAll() has been removed, use Month::cases() instead
  • deprecated method getValue() has been removed, use $month->value instead
  • deprecated method is() has been removed, compare values with $month or $month->value instead
  • deprecated method isEqualTo() has been removed, use strict equality === between Month instances instead
• MonthDay:
  • deprecated method getDay() has been removed, use getDayOfMonth() instead
  • getMonth() now returns a Month enum; use getMonthValue() if you want the month number
• YearMonth:
  • getMonth() now returns a Month enum; use getMonthValue() if you want the month number
• ZonedDateTime:
  • deprecated method getDay() has been removed, use getDayOfMonth() instead
  • getMonth() now returns a Month enum; use getMonthValue() if you want the month number

🔧 Improvements

• Methods returning int are now type-annotated with int ranges

✨ New methods

• LocalDate::previousDayOfWeek()
• LocalDate::previousOrSameDayOfWeek()
• LocalDate::nextDayOfWeek()
• LocalDate::nextOrSameDayOfWeek()

✨ New features

• DefaultClock::travelBy() travels in time by a duration (#92)

🗑️ Deprecations

• DefaultClock::travel() is now deprecated in favour of travelTo() (#92)

Thanks to @francislavoie!

✨ New features

• Stopwatch::stop() now returns the lap duration (#98)

Thanks to @rodnaph!

✨ New features

• MonthDay::of() and MonthDay::withMonth() now accept a Month enum as parameter (#106)
• LocalDate::of() and LocalDate::withMonth() now accept a Month enum as parameter (#106)
• LocalDateTime::of() and LocalDateTime::withMonth() now accept a Month enum as parameter (#106)
• ZonedDateTime::withMonth() now accepts a Month enum as parameter (#106)

✨ Undeprecations

• Passing an int to Year::atMonth() is un-deprecated, and now valid again (#103)
• Passing an int to YearMonth::of() and YearMonth::withMonth() is un-deprecated, and now valid again (#103)
• Passing an int to YearWeek::atDay() is un-deprecated, and now valid again (#103)

Thanks to @gnutix!

✨ New features

• Year::atMonth() now accepts a Month enum as parameter (#95)
• YearMonth::of() and YearMonth::withMonth() now accept a Month enum as parameter (#96)

🔧 Improvements

• Narrower Psalm types for compareTo(), __toString(), toISOString(), jsonSerialize() methods (#97)

💩 Deprecations

• Passing an int to Year::atMonth() is now deprecated, pass a Month enum instead (#95)
• Passing an int to YearMonth::of() and YearMonth::withMonth() is now deprecated, pass a Month enum instead (#96)

Thanks to @gnutix!

💥 Breaking changes

• Minimum PHP version is now 8.1
• DayOfWeek:
  • DayOfWeek is now an enum: constants MONDAY, TUESDAY, etc. are now DayOfWeek instances, not integers
  • the __toString() method is removed, use toString() instead (enums disallow magic methods)
  • the all() method does not accept null anymore, and defaults to DayOfWeek::MONDAY
• Month:
  • Monthis now an enum: constants JANUARY, FEBRUARY, etc. are now Month instances, not integers
  • the __toString() method is removed, use toString() instead (enums disallow magic methods)

💩 Deprecations

• DayOfWeek:
  • the of() method is deprecated, use DayOfWeek::from() instead
  • the following methods are deprecated, use enum values instead:
    • DayOfWeek::monday() → DayOfWeek::MONDAY
    • DayOfWeek::tuesday() → DayOfWeek::TUESDAY
    • DayOfWeek::wednesday() → DayOfWeek::WEDNESDAY
    • DayOfWeek::thursday() → DayOfWeek::THURSDAY
    • DayOfWeek::friday() → DayOfWeek::FRIDAY
    • DayOfWeek::saturday() → DayOfWeek::SATURDAY
    • DayOfWeek::sunday() → DayOfWeek::SUNDAY
  • the getValue() method is deprecated, use $dayOfWeek->value instead
  • the is() method is deprecated, compare values with $dayOfWeek->value instead
  • the isEqualTo() method is deprecated, use strict equality === between DayOfWeek instances instead.
• LocalDate:
  • getDay() is deprecated, use getDayOfMonth() instead
  • getMonth() is deprecated, use getMonthValue() instead (getMonth() will be repurposed to return a Month instance in a future release)
• LocalDateTime:
  • getDay() is deprecated, use getDayOfMonth() instead
  • getMonth() is deprecated, use getMonthValue() instead (getMonth() will be repurposed to return a Month instance in a future release)
• Month:
  • the of() method is deprecated, use Month::from() instead
  • the getAll() method is deprecated, use Month::cases() instead
  • the getValue() method is deprecated, use $month->value instead
  • the is() method is deprecated, compare values with $month->value instead
  • the isEqualTo() method is deprecated, use strict equality === between Month instances instead
• MonthDay:
  • getDay() is deprecated, use getDayOfMonth() instead
  • getMonth() is deprecated, use getMonthValue() instead (getMonth() will be repurposed to return a Month instance in a future release)
• YearMonth:
  • getMonth() is deprecated, use getMonthValue() instead (getMonth() will be repurposed to return a Month instance in a future release)
• YearWeek:
  • the atDay() method now accepts a DayOfWeek instance, passing an integer is deprecated
• ZonedDateTime:
  • getDay() is deprecated, use getDayOfMonth() instead
  • getMonth() is deprecated, use getMonthValue() instead (getMonth() will be repurposed to return a Month instance in a future release)

🐛 Bug fixes

• Year::toISOString() / __toString() did not respect ISO 8601; years with less than 4 digits are now left-padded with zeros (#90)

Thanks to @andreaswolf!

🐛 Bug fixes

• YearMonth::__toString() would return an invalid string for years < 1000 (#87)

✨ New methods

• Year::parse() and Year::from() (#86)
• YearWeek::parse() and YearWeek::from() (#86)
• the following classes now have a toISOString() method: (#87)
  • Duration
  • Instant
  • Interval
  • LocalDate
  • LocalDateRange
  • LocalDateTime
  • LocalTime
  • MonthDay
  • Period
  • Year
  • YearMonth
  • YearMonthRange
  • YearWeek
  • ZonedDateTime

The toISOString() methods return the same result as __toString(), but are better suited for the nullsafe operator:

$date?->toISOString();

⚡️ Performance optimizations

• Most __toString() methods got a small performance boost (#85)

Thanks to @gnutix!

✨ New methods

• Instant::getIntervalTo() (#81)
• ZonedDateTime::getIntervalTo() (#81)

Thanks to @solodkiy!

⚡️ Performance optimizations

• These methods got a small performance boost: Local(Date|Time|DateTime) minOf()/maxOf() (#76)
• Static objects returned by factory methods are now cached (#77)
• The special case LocalDate::plusDays(1) is now much faster (#79)

Thanks to @gnutix and @BastienClement!

✨ New methods

• ZonedDateTime::getDurationTo() (#71) (@solodkiy)

💥 Breaking changes

• Deprecated Interval constructor is now private; please use Interval::of() instead

• The following deprecated methods have been removed, please use the new names:

  Class Name	Old Method Name	New Method Name
  LocalDate	fromDateTime()	fromNativeDateTime()
  LocalDate	toDateTime()	toNativeDateTime()
  LocalDate	toDateTimeImmutable()	toNativeDateTimeImmutable()
  LocalDateRange	toDatePeriod()	toNativeDatePeriod()
  LocalDateTime	fromDateTime()	fromNativeDateTime()
  LocalDateTime	toDateTime()	toNativeDateTime()
  LocalDateTime	toDateTimeImmutable()	toNativeDateTimeImmutable()
  LocalTime	fromDateTime()	fromNativeDateTime()
  LocalTime	toDateTime()	toNativeDateTime()
  LocalTime	toDateTimeImmutable()	toNativeDateTimeImmutable()
  Period	fromDateInterval()	fromNativeDateInterval()
  Period	toDateInterval()	toNativeDateInterval()
  TimeZone	fromDateTimeZone()	fromNativeDateTimeZone()
  TimeZone	toDateTimeZone()	toNativeDateTimeZone()
  ZonedDateTime	fromDateTime()	fromNativeDateTime()
  ZonedDateTime	toDateTime()	toNativeDateTime()
  ZonedDateTime	toDateTimeImmutable()	toNativeDateTimeImmutable()

🔧 Improvements

• TimeZoneOffset::parse() return type has been narrowed to TimeZoneOffset
• Support for seconds in TimeZoneOffset has been added back (#60) (@jiripudil)

🐛 Bug fixes

• Old date/times could fail to be parsed by ZonedDateTime due to sub-minute timezone offsets (#44)

✨ New methods

• Duration::isGreaterThanOrEqualTo() (#50)
• Duration::isLessThanOrEqualTo() (#50)
• Interval::of() (#64)
• Interval::contains() (#64)
• Interval::intersectsWith() (#64)
• Interval::getIntersectionWith() (#64)
• Interval::isEqualTo() (#64)

💩 Deprecations

• Interval constructor is deprecated in favour of Interval::of() (#64)

✨ New methods

• LocalDateRange::toPeriod() (#51)
• Year::toLocalDateRange() (#46)
• YearMonth::toLocalDateRange() (#46)
• YearMonthRange::toLocalDateRange() (#46)
• YearWeek::toLocalDateRange() (#46)

💩 Deprecations

The following methods have been deprecated in favour of new names (#47):

• Period::fromDateInterval() → fromNativeDateInterval()
• Period::toDateInterval() → toNativeDateInterval()
• TimeZone::fromDateTimeZone() → fromNativeDateTimeZone()
• TimeZone::toDateTimeZone() → toNativeDateTimeZone()
• LocalTime::fromDateTime() → fromNativeDateTime()
• LocalTime::toDateTime() → toNativeDateTime()
• LocalTime::toDateTimeImmutable() → toNativeDateTimeImmutable()
• LocalDateRange::toDatePeriod() → toNativeDatePeriod()
• LocalDate::fromDateTime() → fromNativeDateTime()
• LocalDate::toDateTime() → toNativeDateTime()
• LocalDate::toDateTimeImmutable() → toNativeDateTimeImmutable()
• ZonedDateTime::fromDateTime() → fromNativeDateTime()
• ZonedDateTime::toDateTime() → toNativeDateTime()
• ZonedDateTime::toDateTimeImmutable() → toNativeDateTimeImmutable()
• LocalDateTime::fromDateTime() → fromNativeDateTime()
• LocalDateTime::toDateTime() → toNativeDateTime()
• LocalDateTime::toDateTimeImmutable() → toNativeDateTimeImmutable()

💥 Breaking changes

• Minimum PHP version is now 7.4
• TimeZoneOffset does not allow seconds anymore (#35):
  • TimeZoneOffset::of()'s $seconds parameter is removed
  • TimeZoneOffset::ofTotalSeconds() now throws if the number of seconds is not a multiple of 60
  • IsoParsers::timeZoneOffset() does not allow seconds in timezone offset anymore; this affects not only TimeZoneOffset:parse() but also ZonedDateTime::parse()

🔧 Fix

• Fixed return type of TimeZoneRegion::parse() (#38) Thanks to @adrianguenter

✨ New methods

• Period::fromDateInterval() converts a native DateInterval object to Period

✨ New methods

• DayOfWeek::isWeekday()
• DayOfWeek::isWeekend()
• LocalDate::plusWeekdays()
• LocalDate::minusWeekDays()

✨ New methods

• LocalDateRange::withStart()
• LocalDateRange::withEnd()

💥 Breaking changes

• The following methods now have return types:
  • Brick\DateTime\DayOfWeek::monday() through sunday()
  • Brick\DateTime\DayOfWeek::__toString()
  • Brick\DateTime\Month::__toString()

✨ New method

• LocalDateRange::toDatePeriod() (#31) Thanks to @morrislaptop

🔧 Fix

• Added missing ext-json requirement in composer.json

🐛 Bug fix

LocalDateTime::plusDuration() and LocalDateTime::minusDuration() could return the wrong day. (#25)

Thanks @JodyLognoul!

✨ New methods

• LocalDateRange::intersectsWith()
• LocalDateRange::getIntersectionWith()

Thanks @solodkiy!

💥 Breaking changes

• most of the project classes are now final (#8)
• the following deprecated methods have been removed:
  • LocalDateRange::getStartDate() - use getStart() instead (#13)
  • LocalDateRange::getEndDate() - use getEnd() instead (#13)
  • Duration::ofMilliseconds() - use ofMillis() instead

✨ New methods

• LocalDateRange::getStart() - deprecates getStartDate()
• LocalDateRange::getEnd() - deprecates getEndDate()

💩 Deprecations

• LocalDateRange::getStartDate() is now deprecated and will be removed in 0.2.0.
• LocalDateRange::getEndDate() is now deprecated and will be removed in 0.2.0.

This makes LocalDateRange consistent with YearMonthRange.

🛠 Improvement

The following classes now implement JsonSerializable (#19):

• DayOfWeek
• Duration
• Instant
• Interval
• LocalDate
• LocalDateRange
• LocalDateTime
• LocalTime
• Month
• MonthDay
• Period
• Year
• YearMonth
• YearMonthRange
• YearWeek
• ZonedDateTime

Thanks to @kagmole!

✨ New methods

• Duration::toDays()
• Duration::toDaysPart()
• Duration::toHours()
• Duration::toHoursPart()
• Duration::toMinutes()
• Duration::toMinutesPart()
• Duration::toSeconds()
• Duration::toSecondsPart()
• Duration::toMillis()
• Duration::toMillisPart()
• Duration::toNanos()
• Duration::toNanosPart()
• Duration::ofNanos()

See #15 for more information.

💩 Deprecations

• Duration::ofMilliseconds() is now ofMillis(); ofMilliseconds() is now deprecated and will be removed in 0.2.0.

New methods

• LocalDateTime::isFuture()
• LocalDateTime::isPast()

These methods return whether a local date-time is in the future or in the past, in a given time-zone.

New methods

• Instant::withEpochSecond() returns a copy of the Instant with the epoch second altered
• Instant::withNano() returns a copy of the Instant with the nano-of-second altered

New class: YearMonthRange.

LocalDateRange::getIterator() is now type-hinted as LocalDate[] to allow static code analysis in IDEs.

New method: LocalDate::daysUntil()

This allows to get the number of days between two dates.

New methods to convert objects to native DateTimeImmutable objects:

• LocalDate::toDateTimeImmutable()
• LocalTime::toDateTimeImmutable()
• LocalDateTime::toDateTimeImmutable()
• ZonedDateTime::toDateTimeImmutable()

New methods to convert to native DateTime objects:

• LocalDate::toDateTime()
• LocalTime::toDateTime()
• LocalDateTime::toDateTime()

This makes these methods in line with their fromDateTime() counterparts.

Note: even though these classes represent partial date-time concepts, PHP merges all these concepts into a single DateTime class, so it is relevant to be able to easily export them as native PHP date-times, with sensible defaults.

New method:

ZonedDateTime::toDateTime() : converts the ZonedDateTime to a native DateTime object.

New factory method:

• Duration::ofMilliseconds()

New methods available to create objects from native DateTime or DateTimeImmutable objects:

• LocalDate::fromDateTime()
• LocalTime::fromDateTime()
• LocalDateTime::fromDateTime()
• ZonedDateTime::fromDateTime()

This release adds support for YearWeek.

Bug fix:

• Duration::multipliedBy() could return an invalid Duration with negative nanos

New methods:

• Instant::toDecimal() returns a decimal timestamp such as 123456789.123456
• FixedClock::move() allows to move the clock by a number of seconds and/or nanos

New clock implementation:

• ScaleClock makes the time move at a given pace

New feature:

• Methods such as now() now use the clock returned by DefaultClock. By default, this clock is still SystemClock, but it can now be overridden in tests. DefaultClock offers the freeze(), travel() and scale() methods inspired by timecop.

ZonedDateTime::isPast() and isFuture() now accept an optional Clock parameter.

First beta release.