2.4 Upgrade Guide¶

No more mutable objects¶

Chronos was an early adopter of PHP’s immutable datetime objects. With PHP moving away from mutable datetime objects both Cake\Chronos\MutableDate and Cake\Chronos\MutaleDateTime are deprecated and will be removed in 3.0.0.

To upgrade, replace usage of MutableDate with ChronosDate and MutableDateTime with Chronos. When modifying datetimes be sure to always re-assign the variable with the datetime:

// Mutate in place
$datetime->modify('+1 days');

// Immutable objects must re-assign
$datetime = $datetime->modify('+1 days');

ChronosInterface deprecated¶

Having a consistent interface between date and datetime objects has proven to be problematic. It created an illusion of compatibility between mutable and immutable objects and date and datetime objects. Because the ChronosInterface didn’t and can’t really deliver on the goals of interfaces it is deprecated, and will be removed in 3.0. To update your code replace references to ChronosInterface with either a reference to Cake\Chronos\Chronos for datetime instances or Cake\Chronos\ChronosDate for date instances.

Fewer mutation methods¶

For historical reasons the chronos classes included many redundant methods. For example addYear() and addYears(). In 2.4.0, all of the singular methods e.g. addYear() are deprecated. Instead use the plural versions of the methods e.g. addYears().

Simpler Date class¶

When date abstractions were introduced they shared an interfaces with DateTime classes. This resulted in many no-op methods on dates. For example calling setTime() on a date would have no effect. In 2.4, all time related methods (including timezones) are deprecated on date instances. If your application needs to use the time component of a date, you should use Chronos instead.

Upcoming removals in 3.0¶

The following changes will arrive in 3.0, and don’t have a simple deprecation path. Unfortunately these changes will result in hard breaks in 3.0.