From 9ef5f81456d06f2b4fcb9b579d8e4e0f043bf592 Mon Sep 17 00:00:00 2001 From: Corey Taylor Date: Mon, 25 Sep 2023 04:10:05 -0500 Subject: [PATCH 1/2] Remove ChronosInterface references and clean up ChronosDate and ChronosTime refs --- docs/en/index.rst | 74 ++++++++++++++++++----------------------- docs/fr/index.rst | 8 ++--- docs/ja/index.rst | 8 ++--- docs/pt/index.rst | 8 ++--- src/FormattingTrait.php | 9 ++--- 5 files changed, 43 insertions(+), 64 deletions(-) diff --git a/docs/en/index.rst b/docs/en/index.rst index 43cf032..014b4c9 100644 --- a/docs/en/index.rst +++ b/docs/en/index.rst @@ -1,14 +1,22 @@ Chronos ####### -Chronos provides a zero-dependency collection of extensions to the ``DateTime`` -object. In addition to convenience methods, Chronos provides: +Chronos provides a zero-dependency set of ``DateTimeImmutable`` extension, Date-only and Time-only classes: -* ``Date`` objects for representing calendar dates. -* Immutable date and datetime objects. +* ``Cake\Chronos\Chronos`` extends ``DateTimeImmutable`` and provides many helpers. +* ``Cake\Chronos\ChronosDate`` represents calendar dates unaffected by time or time zones. +* ``Cake\Chronos\ChronosTime`` represents clock times independent of date or time zones. +* Only safe, immutable objects. * A pluggable translation system. Only English translations are included in the library. However, ``cakephp/i18n`` can be used for full language support. +The ``Chronos`` class extends ``DateTimeImmutable`` and implements ``DateTimeInterface`` +which allows users to use type declarations that support either. + + ``ChronoDate`` and ``ChronosTime`` do not extend ``DateTimeImmutable`` and do not + share an interface. However, they can be converted to a ``DateTimeImmutable`` instance + using ``toDateTimeImmutable()``. + Installation ------------ @@ -18,22 +26,6 @@ following:: php composer.phar require "cakephp/chronos:^3.0" -Overview --------- - -Chronos provides a number of extensions to the DateTime objects provided by PHP. -Chronos provides extensions to PHP's immutable datetime and dateinterval -objects. - -* ``Cake\Chronos\Chronos`` is an immutable *date and time* object. -* ``Cake\Chronos\ChronosDate`` is a immutable *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``. Both the date and time objects -implement this interface. - Creating Instances ------------------ @@ -63,23 +55,26 @@ factory methods that work with different argument sets:: Working with Immutable Objects ------------------------------ -If you've used PHP's ``DateTime`` objects, you're comfortable with *mutable* -objects. However, Chronos offers provides *immutable* objects. Immutable objects create -copies of an object each time a change is made. Because modifier methods +Chronos provides only *immutable* objects. + +If you've used PHP ``DateTimeImmutable`` and ``DateTime`` classes, then you understand +the difference between *mutable* and *immutable* objects. + +Immutable objects create copies of an object each time a change is made. Because modifier methods around datetimes are not always easy to identify, data can be modified accidentally or without the developer knowing. Immutable objects prevent accidental changes to data, and make code free of order-based dependency issues. Immutability does mean that you will need to remember to replace variables when using modifiers:: // This code doesn't work with immutable objects - $time->addDay(1); - doSomething($time); - return $time; + $chronos->addDay(1); + doSomething($chronos); + return $chronos; // This works like you'd expect - $time = $time->addDay(1); - $time = doSomething($time); - return $time; + $chronos = $chronos->addDay(1); + $chronos = doSomething($chronos); + return $chronos; By capturing the return value of each modification your code will work as expected. @@ -87,12 +82,12 @@ expected. Date Objects ------------ -PHP only provides a single DateTime object that combines both dates and time. -Representing calendar dates can be a bit awkward with `DateTime` as it includes +PHP provides only date-time classes that combines both dates and time parts. +Representing calendar dates can be a bit awkward with ``DateTimeImmutable`` as it includes time and timezones, which aren't part of a 'date'. Chronos provides -``ChronosDate`` that allows you to represent dates. The time and timezone for -these objects is always fixed to ``00:00:00 UTC`` and all formatting/difference -methods operate at the day resolution:: +``ChronosDate`` that allows you to represent dates. The time these objects +these objects is always fixed to ``00:00:00`` and not affeced by the server time zone +or modify helpers:: use Cake\Chronos\ChronosDate; @@ -104,7 +99,7 @@ methods operate at the day resolution:: // Outputs '2015-12-20' echo $today; -Although ``Date`` uses a fixed time zone internally, you can specify which +Although ``ChronosDate`` uses a fixed time zone internally, you can specify which time zone to use for current time such as ``now()`` or ``today()``:: use Cake\Chronos\ChronosDate: @@ -112,11 +107,6 @@ time zone to use for current time such as ``now()`` or ``today()``:: // Takes the current date from Asia/Tokyo time zone $today = ChronosDate::today('Asia/Tokyo'); -The API of ``ChronosDate`` is mostly the same as ``Chronos`` with exceptions for -modifying with expressions or mutating time attributes. While the interfaces are -generally consistent, there isn't a common interface between ``ChronosDate`` and -``Chronos`` as combining date and datetime objects is not type-safe. - Modifier Methods ---------------- @@ -154,8 +144,8 @@ It is also possible to make big jumps to defined points in time:: Or jump to specific days of the week:: - $time->next(ChronosInterface::TUESDAY); - $time->previous(ChronosInterface::MONDAY); + $time->next(Chronos::TUESDAY); + $time->previous(Chronos::MONDAY); When modifying dates/times across :abbr:`DST (Daylight Savings Time)` transitions your operations may gain/lose an additional hours resulting in hour values that diff --git a/docs/fr/index.rst b/docs/fr/index.rst index a841960..9feae52 100644 --- a/docs/fr/index.rst +++ b/docs/fr/index.rst @@ -33,10 +33,6 @@ immutables de date/time et les extensions de ``DateInterval``. * ``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 -time implémentent cette interface. - Créer des Instances ------------------- @@ -163,8 +159,8 @@ temps:: Ou de sauter à un jour spécifique de la semaine:: - $time->next(ChronosInterface::TUESDAY); - $time->previous(ChronosInterface::MONDAY); + $time->next(Chronos::TUESDAY); + $time->previous(Chronos::MONDAY); Quand vous modifiez des dates/heures au-delà d'un passage à l'heure d'été ou à l'heure d'hiver, vous opérations peuvent gagner/perdre une heure de plus, de diff --git a/docs/ja/index.rst b/docs/ja/index.rst index 9798a5c..186c368 100644 --- a/docs/ja/index.rst +++ b/docs/ja/index.rst @@ -31,10 +31,6 @@ Chronos は ``DateInterval`` の拡張機能および、ミュータブル（変 * ``Cake\Chronos\MutableDate`` はミュータブルな *日付* オブジェクト。 * ``Cake\Chronos\ChronosInterval`` は ``DateInterval`` の拡張機能。 -最後に、もしあなたが Chronos が提供する 日付/時刻 のオブジェクトに対して型宣言を行ないたい場合、 -``Cake\Chronos\ChronosInterface`` を使用することができます。 -全ての日付と時間のオブジェクトはこのインターフェイスを実装しています。 - インスタンスの作成 ------------------ @@ -146,8 +142,8 @@ Chronos オブジェクトは細やかに値を変更できるメソッドを提 また、1週間中の特定の日にも飛べます。 :: - $time->next(ChronosInterface::TUESDAY); - $time->previous(ChronosInterface::MONDAY); + $time->next(Chronos::TUESDAY); + $time->previous(Chronos::MONDAY); :abbr:`DST (夏時間)` の遷移の前後で日付/時間を変更すると、 あなたの操作で時間が増減するかもしれませんが、その結果、意図しない時間の値になります。 diff --git a/docs/pt/index.rst b/docs/pt/index.rst index faa07f9..5a06edc 100644 --- a/docs/pt/index.rst +++ b/docs/pt/index.rst @@ -32,10 +32,6 @@ cobrem variantes de data/hora mutáveis e imutáveis e uma extensão do objeto * ``Cake\Chronos\MutableDate`` é um objeto *date* mutável. * ``Cake\Chronos\ChronosInterval`` é uma extensão do objeto ``DateInterval``. -Por último, se você quiser usar o *typehint* em objetos do Chronos, será preciso -usar a interface ``Cake\Chronos\ChronosInterface``. Todos os objetos de data e -hora implementam essa interface. - Criando instâncias ------------------ @@ -146,8 +142,8 @@ Também é possível realizar grandes saltos para períodos definidos no tempo:: Ou ainda para dias específicos da semana:: - $time->next(ChronosInterface::TUESDAY); - $time->previous(ChronosInterface::MONDAY); + $time->next(Chronos::TUESDAY); + $time->previous(Chronos::MONDAY); Métodos de comparação --------------------- diff --git a/src/FormattingTrait.php b/src/FormattingTrait.php index 70bd8d6..33a1f31 100644 --- a/src/FormattingTrait.php +++ b/src/FormattingTrait.php @@ -26,7 +26,7 @@ trait FormattingTrait { /** - * Reset the format used to the default when type juggling a ChronosInterface instance to a string + * Resets the __toString() format to ``DEFAULT_TO_STRING_FORMAT``. * * @return void */ @@ -36,9 +36,9 @@ public static function resetToStringFormat(): void } /** - * Set the default format used when type juggling a ChronosInterface instance to a string + * Sets the __toString() format. * - * @param string $format The format to use in future __toString() calls. + * @param string $format See ``format()`` for accepted specifiers. * @return void */ public static function setToStringFormat(string $format): void @@ -47,7 +47,8 @@ public static function setToStringFormat(string $format): void } /** - * Format the instance as a string using the set format + * Returns a formatted string specified by ``setToStringFormat()`` + * or the default ``DEFAULT_TO_STRING_FORMAT`` format. * * @return string */ From 4bea8c7917f959320137d263147aad7d656ed600 Mon Sep 17 00:00:00 2001 From: Mark Story Date: Thu, 28 Sep 2023 17:49:52 -0700 Subject: [PATCH 2/2] Apply suggestions from code review --- docs/en/index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/en/index.rst b/docs/en/index.rst index 014b4c9..7a201cd 100644 --- a/docs/en/index.rst +++ b/docs/en/index.rst @@ -1,7 +1,7 @@ Chronos ####### -Chronos provides a zero-dependency set of ``DateTimeImmutable`` extension, Date-only and Time-only classes: +Chronos provides a zero-dependency ``DateTimeImmutable`` extension, Date-only and Time-only classes: * ``Cake\Chronos\Chronos`` extends ``DateTimeImmutable`` and provides many helpers. * ``Cake\Chronos\ChronosDate`` represents calendar dates unaffected by time or time zones. @@ -13,7 +13,7 @@ Chronos provides a zero-dependency set of ``DateTimeImmutable`` extension, Date- The ``Chronos`` class extends ``DateTimeImmutable`` and implements ``DateTimeInterface`` which allows users to use type declarations that support either. - ``ChronoDate`` and ``ChronosTime`` do not extend ``DateTimeImmutable`` and do not + ``ChronosDate`` and ``ChronosTime`` do not extend ``DateTimeImmutable`` and do not share an interface. However, they can be converted to a ``DateTimeImmutable`` instance using ``toDateTimeImmutable()``.