Merge branch '2.next' into 2.x

README.md

@@ -63,7 +63,6 @@ want to migrate, we could use the following to update files:
 
 ```
 # Replace imports
-find ./src -type f -name '*.php' -exec sed -i '' 's/use Carbon\\CarbonInterval/use Cake\\Chronos\\ChronosInterval/g' {} \;
 find ./src -type f -name '*.php' -exec sed -i '' 's/use Carbon\\CarbonImmutable/use Cake\\Chronos\\Chronos/g' {} \;
 find ./src -type f -name '*.php' -exec sed -i '' 's/use Carbon\\Carbon/use Cake\\Chronos\\Chronos/g' {} \;
 
@@ -104,7 +103,7 @@ In the case that you need a mutable instance you can get one:
 $time = new Chronos('2015-10-21 16:29:00');
 $mutable = $time->toMutable();
 
-$date = new Date('2015-10-21');
+$date = new ChronosDate('2015-10-21');
 $mutable = $date->toMutable();
 ```
 
@@ -130,9 +129,9 @@ set to the server default timezone. This makes them ideal when working with
 calendar dates as the time components will always match.
 
 ```php
-use Cake\Chronos\Date;
+use Cake\Chronos\ChronosDate;
 
-$today = new Date();
+$today = new ChronosDate();
 echo $today;
 // Outputs '2015-10-21'
 

compare-data.json

@@ -0,0 +1 @@
+{"2x":{"Cake\\Chronos\\Chronos":["__construct","toMutable","copy","setTestNow","getTestNow","hasTestNow","createInterval","__debugInfo","checkTypes","__wakeup","__set_state","createFromFormat","getLastErrors","format","getTimezone","getOffset","getTimestamp","diff","modify","add","sub","setTimezone","setTime","setDate","setISODate","setTimestamp","createFromMutable","createFromInterface","getWeekendDays","setWeekendDays","eq","equals","ne","notEquals","gt","greaterThan","gte","greaterThanOrEquals","lt","lessThan","lte","lessThanOrEquals","between","closest","farthest","min","max","isWeekday","isWeekend","isYesterday","isToday","isTomorrow","isNextWeek","isLastWeek","isNextMonth","isLastMonth","isNextYear","isLastYear","isFuture","isPast","isLeapYear","isSameDay","isSunday","isMonday","isTuesday","isWednesday","isThursday","isFriday","isSaturday","isThisWeek","isThisMonth","isThisYear","isBirthday","wasWithinLast","isWithinNext","isMutable","diffInYears","diffInMonths","diffInMonthsIgnoreTimezone","diffInWeeks","diffInDays","diffInDaysFiltered","diffInHoursFiltered","diffFiltered","diffInWeekdays","diffInWeekendDays","diffInHours","diffInMinutes","diffInSeconds","secondsSinceMidnight","secondsUntilEndOfDay","fromNow","diffForHumans","diffFormatter","instance","parse","now","today","tomorrow","yesterday","maxValue","minValue","create","createFromDate","createFromTime","createFromArray","createFromTimestamp","createFromTimestampUTC","resetToStringFormat","setToStringFormat","__toString","toDateString","toFormattedDateString","toTimeString","toDateTimeString","toDayDateTimeString","toAtomString","toCookieString","toIso8601String","toRfc822String","toRfc850String","toRfc1036String","toRfc1123String","toRfc2822String","toRfc3339String","toRssString","toW3cString","toUnixString","toQuarter","toWeek","__get","__isset","getWeekStartsAt","setWeekStartsAt","getWeekEndsAt","setWeekEndsAt","setDateTime","setTimeFromTimeString","timestamp","year","month","day","hour","minute","second","microsecond","addYears","addYear","subYears","subYear","addYearsWithOverflow","addYearWithOverflow","subYearsWithOverflow","subYearWithOverflow","addMonths","addMonth","subMonth","subMonths","addMonthsWithOverflow","addMonthWithOverflow","subMonthsWithOverflow","subMonthWithOverflow","addDays","addDay","subDay","subDays","addWeekdays","addWeekday","subWeekdays","subWeekday","addWeeks","addWeek","subWeek","subWeeks","addHours","addHour","subHour","subHours","addMinutes","addMinute","subMinute","subMinutes","addSeconds","addSecond","subSecond","subSeconds","startOfDay","endOfDay","startOfMonth","endOfMonth","startOfYear","endOfYear","startOfDecade","endOfDecade","startOfCentury","endOfCentury","startOfWeek","endOfWeek","next","previous","firstOfMonth","lastOfMonth","nthOfMonth","firstOfQuarter","lastOfQuarter","nthOfQuarter","firstOfYear","lastOfYear","nthOfYear","average","hasRelativeKeywords","timezone","tz"],"Cake\\Chronos\\ChronosDate":["__construct","toMutable","__debugInfo","create","add","sub","modify","setTimestamp","hour","minute","second","microsecond","__wakeup","__set_state","createFromFormat","getLastErrors","format","getTimezone","getOffset","getTimestamp","diff","setTimezone","setTime","setDate","setISODate","createFromMutable","createFromInterface","getWeekendDays","setWeekendDays","eq","equals","ne","notEquals","gt","greaterThan","gte","greaterThanOrEquals","lt","lessThan","lte","lessThanOrEquals","between","closest","farthest","min","max","isWeekday","isWeekend","isYesterday","isToday","isTomorrow","isNextWeek","isLastWeek","isNextMonth","isLastMonth","isNextYear","isLastYear","isFuture","isPast","isLeapYear","isSameDay","isSunday","isMonday","isTuesday","isWednesday","isThursday","isFriday","isSaturday","isThisWeek","isThisMonth","isThisYear","isBirthday","wasWithinLast","isWithinNext","isMutable","copy","diffInYears","diffInMonths","diffInMonthsIgnoreTimezone","diffInWeeks","diffInDays","diffInDaysFiltered","diffInHoursFiltered","diffFiltered","diffInWeekdays","diffInWeekendDays","diffInHours","diffInMinutes","diffInSeconds","secondsSinceMidnight","secondsUntilEndOfDay","fromNow","diffForHumans","diffFormatter","instance","parse","now","today","tomorrow","yesterday","maxValue","minValue","createFromDate","createFromTime","createFromArray","createFromTimestamp","createFromTimestampUTC","resetToStringFormat","setToStringFormat","__toString","toDateString","toFormattedDateString","toTimeString","toDateTimeString","toDayDateTimeString","toAtomString","toCookieString","toIso8601String","toRfc822String","toRfc850String","toRfc1036String","toRfc1123String","toRfc2822String","toRfc3339String","toRssString","toW3cString","toUnixString","toQuarter","toWeek","timezone","tz","hasRelativeKeywords","__get","__isset","getWeekStartsAt","setWeekStartsAt","getWeekEndsAt","setWeekEndsAt","setDateTime","setTimeFromTimeString","timestamp","year","month","day","addYears","addYear","subYears","subYear","addYearsWithOverflow","addYearWithOverflow","subYearsWithOverflow","subYearWithOverflow","addMonths","addMonth","subMonth","subMonths","addMonthsWithOverflow","addMonthWithOverflow","subMonthsWithOverflow","subMonthWithOverflow","addDays","addDay","subDay","subDays","addWeekdays","addWeekday","subWeekdays","subWeekday","addWeeks","addWeek","subWeek","subWeeks","addHours","addHour","subHour","subHours","addMinutes","addMinute","subMinute","subMinutes","addSeconds","addSecond","subSecond","subSeconds","startOfDay","endOfDay","startOfMonth","endOfMonth","startOfYear","endOfYear","startOfDecade","endOfDecade","startOfCentury","endOfCentury","startOfWeek","endOfWeek","next","previous","firstOfMonth","lastOfMonth","nthOfMonth","firstOfQuarter","lastOfQuarter","nthOfQuarter","firstOfYear","lastOfYear","nthOfYear","average","setTestNow","getTestNow","hasTestNow"]},"3x":{"Cake\\Chronos\\Chronos":["__construct","setTestNow","getTestNow","hasTestNow","hasRelativeKeywords","getWeekendDays","setWeekendDays","getWeekStartsAt","setWeekStartsAt","getWeekEndsAt","setWeekEndsAt","diffFormatter","instance","parse","now","today","tomorrow","yesterday","maxValue","minValue","create","createFromDate","createFromTime","createFromFormat","createFromArray","createFromTimestamp","createFromTimestampUTC","createInterval","setDateTime","setDate","setTime","modify","diff","format","getOffset","setTimestamp","getTimestamp","setTimezone","getTimezone","setTimeFromTimeString","timestamp","year","month","day","hour","minute","second","microsecond","addYears","subYears","addYearsWithOverflow","subYearsWithOverflow","addMonths","subMonths","addMonthsWithOverflow","subMonthsWithOverflow","addDays","subDays","addWeekdays","subWeekdays","addWeeks","subWeeks","addHours","subHours","addMinutes","subMinutes","addSeconds","subSeconds","startOfDay","endOfDay","startOfMonth","endOfMonth","startOfYear","endOfYear","startOfDecade","endOfDecade","startOfCentury","endOfCentury","startOfWeek","endOfWeek","next","previous","firstOfMonth","lastOfMonth","nthOfMonth","firstOfQuarter","lastOfQuarter","nthOfQuarter","firstOfYear","lastOfYear","nthOfYear","equals","notEquals","greaterThan","greaterThanOrEquals","lessThan","lessThanOrEquals","between","closest","farthest","min","max","average","isWeekday","isWeekend","isYesterday","isToday","isTomorrow","isNextWeek","isLastWeek","isNextMonth","isLastMonth","isNextYear","isLastYear","isFuture","isPast","isLeapYear","isSameDay","isSunday","isMonday","isTuesday","isWednesday","isThursday","isFriday","isSaturday","isThisWeek","isThisMonth","isThisYear","isBirthday","wasWithinLast","isWithinNext","diffFiltered","diffInYears","diffInMonths","diffInMonthsIgnoreTimezone","diffInWeeks","diffInDays","diffInDaysFiltered","diffInHoursFiltered","diffInWeekdays","diffInWeekendDays","diffInHours","diffInMinutes","diffInSeconds","secondsSinceMidnight","secondsUntilEndOfDay","fromNow","diffForHumans","__get","__isset","__debugInfo","resetToStringFormat","setToStringFormat","__toString","toDateString","toFormattedDateString","toTimeString","toDateTimeString","toDayDateTimeString","toAtomString","toCookieString","toIso8601String","toRfc822String","toRfc850String","toRfc1036String","toRfc1123String","toRfc2822String","toRfc3339String","toRssString","toW3cString","toUnixString","toQuarter","toWeek"],"Cake\\Chronos\\ChronosDate":["__construct","now","today","tomorrow","yesterday","parse","create","createFromFormat","createFromArray","diffFormatter","add","sub","modify","setDate","diff","format","year","month","day","addYears","subYears","addYearsWithOverflow","subYearsWithOverflow","addMonths","subMonths","addMonthsWithOverflow","subMonthsWithOverflow","addDays","subDays","addWeekdays","subWeekdays","addWeeks","subWeeks","startOfMonth","endOfMonth","startOfYear","endOfYear","startOfDecade","endOfDecade","startOfCentury","endOfCentury","startOfWeek","endOfWeek","next","previous","firstOfMonth","lastOfMonth","nthOfMonth","firstOfQuarter","lastOfQuarter","nthOfQuarter","firstOfYear","lastOfYear","nthOfYear","equals","notEquals","greaterThan","greaterThanOrEquals","lessThan","lessThanOrEquals","between","closest","farthest","isWeekday","isWeekend","isYesterday","isToday","isTomorrow","isNextWeek","isLastWeek","isNextMonth","isLastMonth","isNextYear","isLastYear","isFuture","isPast","isLeapYear","isSunday","isMonday","isTuesday","isWednesday","isThursday","isFriday","isSaturday","wasWithinLast","isWithinNext","diffFiltered","diffInYears","diffInMonths","diffInWeeks","diffInDays","diffInDaysFiltered","diffInWeekdays","diffInWeekendDays","diffForHumans","__get","__isset","__debugInfo","resetToStringFormat","setToStringFormat","__toString","toDateString","toFormattedDateString","toTimeString","toDateTimeString","toDayDateTimeString","toAtomString","toCookieString","toIso8601String","toRfc822String","toRfc850String","toRfc1036String","toRfc1123String","toRfc2822String","toRfc3339String","toRssString","toW3cString","toUnixString","toQuarter","toWeek"]}}

docs/en/2-4-upgrade-guide.rst

@@ -0,0 +1,78 @@
+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.

docs/en/contents.rst

@@ -3,5 +3,6 @@
     :caption: CakePHP Chronos
 
     /index
+    /2-4-upgrade-guide
 
-    API <https://api.cakephp.org/chronos>
+    API <https://api.cakephp.org/chronos>

docs/en/index.rst

@@ -26,11 +26,9 @@ Chronos provides 5 classes that cover mutable and immutable date/time variants
 and extensions to ``DateInterval``.
 
 * ``Cake\Chronos\Chronos`` is an immutable *date and time* object.
-* ``Cake\Chronos\Date`` is a immutable *date* object.
+* ``Cake\Chronos\ChronosDate`` is a immutable *date* object.
 * ``Cake\Chronos\MutableDateTime`` is a mutable *date and time* object.
 * ``Cake\Chronos\MutableDate`` is a mutable *date* object.
-* ``Cake\Chronos\ChronosInterval`` is an extension to the ``DateInterval``
-  object.
 
 Lastly, if you want to typehint against Chronos-provided date/time objects you
 should use ``Cake\Chronos\ChronosInterface``. All of the date and time objects
@@ -101,9 +99,9 @@ object that allows you to represent dates. The time for date objects is always
 fixed to ``00:00:00``, and the timezone is set to the server local timezone. All
 formatting/difference methods operate at the day resolution::
 
-    use Cake\Chronos\Date;
+    use Cake\Chronos\ChronosDate;
 
-    $today = Date::today();
+    $today = ChronosDate::today();
 
     // Changes to the time/timezone are ignored.
     $today->modify('+1 hours');
@@ -117,7 +115,7 @@ time zone to use for current time such as ``now()`` or ``today()``::
     use Cake\Chronos\Date:
 
     // Takes the current date from Asia/Tokyo time zone
-    $today = Date::today('Asia/Tokyo');
+    $today = ChronosDate::today('Asia/Tokyo');
 
 Modifier Methods
 ----------------
@@ -302,7 +300,7 @@ process you can include the following::
 
     Chronos::setTestNow(Chronos::now());
     MutableDateTime::setTestNow(MutableDateTime::now());
-    Date::setTestNow(Date::now());
+    ChronosDate::setTestNow(ChronosDate::now());
     MutableDate::setTestNow(MutableDate::now());
 
 This will fix the current time of all objects to be the point at which the test

docs/fr/index.rst

@@ -27,11 +27,9 @@ par PHP. Chronos fournit 5 classes qui gèrent les variantes mutables et
 immutables de date/time et les extensions de ``DateInterval``.
 
 * ``Cake\Chronos\Chronos`` est un objet de *date et heure* immutable.
-* ``Cake\Chronos\Date`` est un objet de *date* immutable.
+* ``Cake\Chronos\ChronosDate`` est un objet de *date* immutable.
 * ``Cake\Chronos\MutableDateTime`` est un objet de *date et heure* mutable.
 * ``Cake\Chronos\MutableDate`` est un objet de *date* mutable.
-* ``Cake\Chronos\ChronosInterval`` est une extension pour l'objet
-  ``DateInterval``.
 
 Enfin si vous voulez typer selon les objets date/time fournis par Chronos,
 vous devez utiliser ``Cake\Chronos\ChronosInterface``. Tous les objets date et
@@ -105,9 +103,9 @@ de représenter les dates. Les time et timezone pour ces objets sont toujours
 fixés à ``00:00:00 UTC`` et toutes les méthodes de formatage/différence
 fonctionnent au niveau du jour::
 
-    use Cake\Chronos\Date;
+    use Cake\Chronos\ChronosDate;
 
-    $today = Date::today();
+    $today = ChronosDate::today();
 
     // Les changements selon le time/timezone sont ignorés.
     $today->modify('+1 hours');
@@ -122,7 +120,7 @@ spécifier le fuseau à utiliser pour l'heure courante telle que ``now()`` ou
     use Cake\Chronos\Date:
 
     // Prend l'heure courante pour le fuseau horaire de Tokyo
-    $today = Date::today('Asia/Tokyo');
+    $today = ChronosDate::today('Asia/Tokyo');
 
 
 Méthodes de Modification
@@ -313,7 +311,7 @@ vous pouvez inclure ce qui suit::
 
     Chronos::setTestNow(Chronos::now());
     MutableDateTime::setTestNow(MutableDateTime::now());
-    Date::setTestNow(Date::now());
+    ChronosDate::setTestNow(ChronosDate::now());
     MutableDate::setTestNow(MutableDate::now());
 
 Ceci va fixer le time courant de tous les objets selon le moment où la suite de

docs/ja/index.rst

@@ -26,7 +26,7 @@ Chronos は ``DateInterval`` の拡張機能および、ミュータブル（変
 イミュータブル（変更不可）な 日付/時刻 の派生系をカバーする5つのクラスを提供します。
 
 * ``Cake\Chronos\Chronos`` はイミュータブルな *日付と時刻* オブジェクト。
-* ``Cake\Chronos\Date`` はイミュータブルな *日付* オブジェクト。
+* ``Cake\Chronos\ChronosDate`` はイミュータブルな *日付* オブジェクト。
 * ``Cake\Chronos\MutableDateTime`` はミュータブルな *日付と時刻* オブジェクト。
 * ``Cake\Chronos\MutableDate`` はミュータブルな *日付* オブジェクト。
 * ``Cake\Chronos\ChronosInterval`` は ``DateInterval`` の拡張機能。
@@ -100,9 +100,9 @@ Chronos は日時表現のための ``Date`` オブジェクトを提供しま
 これらのオブジェクトの時間とタイムゾーンは常に ``00:00:00 UTC`` に固定されており、
 全ての書式/差分のメソッドは一日単位で動作します。 ::
 
-    use Cake\Chronos\Date;
+    use Cake\Chronos\ChronosDate;
 
-    $today = Date::today();
+    $today = ChronosDate::today();
 
     // 時間/タイムゾーンの変更は無視されます
     $today->modify('+1 hours');
@@ -286,7 +286,7 @@ Chronos は、出力した日時オブジェクトを表示するための多く
 
     Chronos::setTestNow(Chronos::now());
     MutableDateTime::setTestNow(MutableDateTime::now());
-    Date::setTestNow(Date::now());
+    ChronosDate::setTestNow(ChronosDate::now());
     MutableDate::setTestNow(MutableDate::now());
 
 これでテストスイートが開始された時点で全てのオブジェクトの現在時刻を修正します。