2.4 Upgrade Guide
#################

Chronos 2.4 introduces a number of deprecations that will help you prepare your
application for the upcoming Chronos 3.x release. This guide covers the
deprecations introduced in 2.4 and gives a preview of what to expect in 3.0.

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.

Carbon aliases removed
----------------------

When Chronos was started Carbon had no active maintainers. We included
compatiblity aliases in Chronos to help users migrate from the unmaintained
Carbon library to Chronos. Presently, Carbon has active maintainers and we no
longer feel the need to provide shims.

No longer extending DateTime
----------------------------

Historically Chronos has extended PHP's ``DateTime`` classes. This has proven to
be problematic especially for date classes. While Chronos will not extend
PHP's ``DateTime`` classes or implements the ``DateTimeInterface``, if a method does
not emit a deprecation in 2.4.0 it will continue to work in 3.0.

To adapt to this change before upgrading to 3.0 replace references to PHP's
``DateTime`` and ``DateTimeInterface`` and use ``Chronos`` or ``ChronosDate``
instead.