docs: update user guide

Author: kenjis

user_guide_src/source/changelogs/v4.6.0.rst

@@ -71,6 +71,12 @@ Time with Microseconds
 Fixed bugs that some methods in ``Time`` to lose microseconds have been fixed.
 See :ref:`Upgrading Guide <upgrade-460-time-keeps-microseconds>` for details.
 
+Time::setTimestamp()
+--------------------
+
+``Time::setTimestamp()`` behavior has been fixed.
+See :ref:`Upgrading Guide <upgrade-460-time-set-timestamp>` for details.
+
 .. _v460-interface-changes:
 
 Interface Changes

user_guide_src/source/installation/upgrade_460.rst

@@ -85,6 +85,25 @@ Also, methods that returns an ``int`` still lose the microseconds.
 .. literalinclude:: upgrade_460/005.php
    :lines: 2-
 
+.. _upgrade-460-time-set-timestamp:
+
+Time::setTimestamp() Behavior Fix
+=================================
+
+In previous versions, if you call ``Time::setTimestamp()`` on a Time instance with
+a timezone other than the default timezone might return a Time instance with the
+wrong date/time.
+
+This bug has been fixed, and it now behaves in the same way as ``DateTimeImmutable``:
+
+.. literalinclude:: upgrade_460/008.php
+   :lines: 2-
+
+Note that if you use the default timezone, the behavior is not changed:
+
+.. literalinclude:: upgrade_460/009.php
+   :lines: 2-
+
 .. _upgrade-460-registrars-with-dirty-hack:
 
 Registrars with Dirty Hack

user_guide_src/source/installation/upgrade_460/008.php

@@ -0,0 +1,18 @@
+<?php
+
+use CodeIgniter\I18n\Time;
+
+// The Application Timezone is "UTC".
+
+// Set $time1 timezone to "America/Chicago".
+$time1 = Time::parse('2024-08-20', 'America/Chicago');
+
+// The timestamp is "2024-08-20 00:00" in "UTC".
+$stamp = strtotime('2024-08-20'); // 1724112000
+
+// But $time2 timezone is "America/Chicago".
+$time2 = $time1->setTimestamp($stamp);
+
+echo $time2->format('Y-m-d H:i:s P');
+// Before: 2024-08-20 00:00:00 -05:00
+//  After: 2024-08-19 19:00:00 -05:00

user_guide_src/source/installation/upgrade_460/009.php

@@ -0,0 +1,18 @@
+<?php
+
+use CodeIgniter\I18n\Time;
+
+// The Application Timezone is "America/Chicago".
+
+// $time1 timezone is "America/Chicago".
+$time1 = Time::parse('2024-08-20');
+
+// The timestamp is "2024-08-20 00:00" in "America/Chicago".
+$stamp = strtotime('2024-08-20'); // 1724130000
+
+// $time2 timezone is also "America/Chicago".
+$time2 = $time1->setTimestamp($stamp);
+
+echo $time2->format('Y-m-d H:i:s P');
+// Before: 2024-08-20 00:00:00 -05:00
+//  After: 2024-08-20 00:00:00 -05:00

user_guide_src/source/libraries/time.rst

@@ -314,6 +314,9 @@ Returns a new instance with the date set to the new timestamp:
 
 .. literalinclude:: time/030.php
 
+.. note:: Prior to v4.6.0, due to a bug, this method might return incorrect
+    date/time. See :ref:`Upgrading Guide <upgrade-460-time-set-timestamp>` for details.
+
 Modifying the Value
 ===================
 

user_guide_src/source/libraries/time/030.php

@@ -2,7 +2,9 @@
 
 use CodeIgniter\I18n\Time;
 
-$time  = Time::parse('May 10, 2017', 'America/Chicago');
+// The Application Timezone is "America/Chicago".
+
+$time  = Time::parse('May 10, 2017');
 $time2 = $time->setTimestamp(strtotime('April 1, 2017'));
 
 echo $time->toDateTimeString();  // 2017-05-10 00:00:00