Fixed bug #81319: Unfortunate example on time() man page

reference/datetime/functions/date.xml

@@ -3,9 +3,9 @@
 <refentry xml:id="function.date" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>date</refname>
-  <refpurpose>Format a local time/date</refpurpose>
+  <refpurpose>Format a Unix timestamp</refpurpose>
  </refnamediv>
-  
+
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
@@ -15,10 +15,16 @@
   </methodsynopsis>
   <para>
    Returns a string formatted according to the given format string using the
-   given integer <parameter>timestamp</parameter> or the current time
-   if no timestamp is given.  In other words, <parameter>timestamp</parameter>
+   given integer <parameter>Unix timestamp</parameter> or the current time
+   if no timestamp is given. In other words, <parameter>timestamp</parameter>
    is optional and defaults to the value of <function>time</function>.
   </para>
+  <para>
+   Unix timestamps do not handle timezones. Use the
+   <classname>DateTimeImmutable</classname> class, and its
+   <methodname>DateTimeInterface::format</methodname> formatting method to
+   format date/time information with a timezone attached.
+  </para>
  </refsect1>
 
  <refsect1 role="parameters">
@@ -28,30 +34,30 @@
     <term><parameter>format</parameter></term>
     <listitem>
      <para>
-      Format accepted by <function>DateTimeInterface::format</function>.
+      Format accepted by <methodname>DateTimeInterface::format</methodname>.
      </para>
     </listitem>
    </varlistentry>
-    
+
    &date.timestamp.description;
-   
+
   </variablelist>
  </refsect1>
 
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   Returns a formatted date string. If a non-numeric value is used for 
-   <parameter>timestamp</parameter>, &false; is returned and an 
+   Returns a formatted date string. If a non-numeric value is used for
+   <parameter>timestamp</parameter>, &false; is returned and an
    <constant>E_WARNING</constant> level error is emitted.
   </para>
  </refsect1>
 
  <refsect1 role="errors">
   &reftitle.errors;
-   
+
    &date.timezone.errors.description;
- 
+
  </refsect1>
 
  <refsect1 role="changelog">
@@ -211,6 +217,8 @@ $today = date("Y-m-d H:i:s");                   // 2001-03-10 17:16:18 (the MySQ
   &reftitle.seealso;
   <para>
    <simplelist>
+    <member><methodname>DateTimeImmutable::__construct</methodname></member>
+    <member><methodname>DateTimeInterface::format</methodname></member>
     <member><function>gmdate</function></member>
     <member><function>idate</function></member>
     <member><function>getdate</function></member>
@@ -218,7 +226,6 @@ $today = date("Y-m-d H:i:s");                   // 2001-03-10 17:16:18 (the MySQ
     <member><function>mktime</function></member>
     <member><methodname>IntlDateFormatter::format</methodname></member>
     <member><function>time</function></member>
-    <member><function>DateTimeImmutable::__construct</function></member>
     <member><link linkend="datetime.constants.types">Predefined DateTime Constants</link></member>
    </simplelist>
   </para>

reference/datetime/functions/time.xml

@@ -16,6 +16,15 @@
    Returns the current time measured in the number of seconds since
    the Unix Epoch (January 1 1970 00:00:00 GMT).
   </para>
+  <note>
+   <para>
+    Unix timestamps do not contain any information with regards to any local
+    timezone. It is recommended to use the
+    <classname>DateTimeImmutable</classname> class for handling date and time
+    information in order to avoid the pitfalls that come with just Unix
+    timestamps.
+   </para>
+  </note>
  </refsect1>
 
  <refsect1 role="parameters">
@@ -38,11 +47,7 @@
     <programlisting role="php">
 <![CDATA[
 <?php
-$nextWeek = time() + (7 * 24 * 60 * 60);
-                   // 7 days; 24 hours; 60 mins; 60 secs
 echo 'Now:       '. date('Y-m-d') ."\n";
-echo 'Next Week: '. date('Y-m-d', $nextWeek) ."\n";
-// or using strtotime():
 echo 'Next Week: '. date('Y-m-d', strtotime('+1 week')) ."\n";
 ?>
 ]]>
@@ -50,9 +55,8 @@ echo 'Next Week: '. date('Y-m-d', strtotime('+1 week')) ."\n";
     &example.outputs.similar;
     <screen>
 <![CDATA[
-Now:       2005-03-30
-Next Week: 2005-04-06
-Next Week: 2005-04-06
+Now:       2022-06-04
+Next Week: 2022-06-11
 ]]>
     </screen>
    </example>