complete documentation about changes in version 5.1, like return values, negative timestamps.

add examples to the constant pages, and link it from the date() function git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@193515 c90b9560-bf6c-de11-be94-00142212c4b1
2025-03-16 00:48:54 +00:00 · 2005-08-15 16:01:08 +00:00 · 2005-08-15 16:01:08 +00:00 · 014d6b45da
commit 014d6b45da
parent f567c3de33
4 changed files with 62 additions and 53 deletions
--- a/reference/datetime/constants.xml
+++ b/reference/datetime/constants.xml
@ -1,5 +1,5 @@
 <?xml version='1.0' encoding='iso-8859-1'?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 <section id="datetime.constants">
 &reftitle.constants;
 <para>
@ -15,7 +15,7 @@
   </term>
   <listitem>
    <simpara>
-     Atom
+     Atom (example: 2005-08-15T15:52:01+0000)
    </simpara>
   </listitem>
  </varlistentry>
@ -26,7 +26,7 @@
   </term>
   <listitem>
    <simpara>
-     HTTP Cookies
+     HTTP Cookies (example: Mon, 15 Aug 2005 15:52:01 UTC)
    </simpara>
   </listitem>
  </varlistentry>
@ -37,7 +37,7 @@
   </term>
   <listitem>
    <simpara>
-     ISO-8601
+     ISO-8601 (example: 2005-08-15T15:52:01+0000)
    </simpara>
   </listitem>
  </varlistentry>
@ -48,7 +48,7 @@
   </term>
   <listitem>
    <simpara>
-     RFC 822
+     RFC 822 (example: Mon, 15 Aug 2005 15:52:01 UTC)
    </simpara>
   </listitem>
  </varlistentry>
@ -59,7 +59,7 @@
   </term>
   <listitem>
    <simpara>
-     RFC 850
+     RFC 850 (example: Monday, 15-Aug-05 15:52:01 UTC)
    </simpara>
   </listitem>
  </varlistentry>
@ -70,7 +70,7 @@
   </term>
   <listitem>
    <simpara>
-     RFC 1036
+     RFC 1036 (example: Monday, 15-Aug-05 15:52:01 UTC)
    </simpara>
   </listitem>
  </varlistentry>
@ -81,7 +81,7 @@
   </term>
   <listitem>
    <simpara>
-     RFC 1123
+     RFC 1123 (example: Mon, 15 Aug 2005 15:52:01 UTC)
    </simpara>
   </listitem>
  </varlistentry>
@ -92,7 +92,7 @@
   </term>
   <listitem>
    <simpara>
-     RFC 2822
+     RFC 2822 (Mon, 15 Aug 2005 15:52:01 +0000)
    </simpara>
   </listitem>
  </varlistentry>
@ -103,7 +103,7 @@
   </term>
   <listitem>
    <simpara>
-     RSS
+     RSS (Mon, 15 Aug 2005 15:52:01 UTC)
    </simpara>
   </listitem>
  </varlistentry>
@ -114,7 +114,7 @@
   </term>
   <listitem>
    <simpara>
-     World Wide Web Consortium (W3C)
+     World Wide Web Consortium (example: 2005-08-15T15:52:01+0000)
    </simpara>
   </listitem>
  </varlistentry>
--- a/reference/datetime/functions/date.xml
+++ b/reference/datetime/functions/date.xml
@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.19 $ -->
+<!-- $Revision: 1.20 $ -->
 <!-- splitted from ./en/functions/datetime.xml, last change in rev 1.2 -->
 <refentry id="function.date">
 <refnamediv>
@ -18,25 +18,33 @@
   given integer <parameter>timestamp</parameter> or the current local time
   if no timestamp is given.  In other words, <parameter>timestamp</parameter>
   is optional and defaults to the value of <function>time</function>.
-   <note>
-    <para>
-     The valid range of a timestamp is typically from Fri, 13 Dec
-     1901 20:45:54 GMT to Tue, 19 Jan 2038 03:14:07 GMT. (These are
-     the dates that correspond to the minimum and maximum values for
-     a 32-bit signed integer). On Windows this range is limited from
-     01-01-1970 to 19-01-2038.
-    </para>
-   </note>
-   <note>
-    <para>
-     To generate a timestamp from a string representation of the date, you
-     may be able to use <function>strtotime</function>. Additionally, some
-     databases have functions to convert their date formats into timestamps
-     (such as MySQL's <ulink url="&url.mysql.docs.date;">UNIX_TIMESTAMP</ulink>
-     function).
-    </para>
-   </note>
  </para>
+  <tip>
+   <para>
+    Since PHP 5.1.0 there are a couple of usefull <link
+    linkend="datetime.constants">constants</link> of standard date/time
+    formats that can be used to specify the <parameter>format</parameter>
+    parameter.
+   </para>
+  </tip>
+  <note>
+   <para>
+    The valid range of a timestamp is typically from Fri, 13 Dec
+    1901 20:45:54 GMT to Tue, 19 Jan 2038 03:14:07 GMT. (These are
+    the dates that correspond to the minimum and maximum values for
+    a 32-bit signed integer). However, before PHP 5.1 this range was limited
+    from 01-01-1970 to 19-01-2038 on some systems (e.g. Windows).
+   </para>
+  </note>
+  <note>
+   <para>
+    To generate a timestamp from a string representation of the date, you
+    may be able to use <function>strtotime</function>. Additionally, some
+    databases have functions to convert their date formats into timestamps
+    (such as MySQL's <ulink url="&url.mysql.docs.date;">UNIX_TIMESTAMP</ulink>
+    function).
+   </para>
+  </note>
  <para>
   <table>
    <title>The following characters are recognized in the
@ -277,14 +285,25 @@
    <programlisting role="php">
 <![CDATA[
 <?php
-// Prints something like: Wednesday
+// set the default timezone to use. Available since PHP 5.1
+date_default_timezone_set('UTC');
+
+
+// Prints something like: Monday
 echo date("l");

-// Prints something like: Wednesday 15th of January 2003 05:51:38 AM
-echo date("l dS of F Y h:i:s A");
+// Prints something like: Monday 15th of August 2005 03:12:46 PM
+echo date('l dS \of F Y h:i:s A');

 // Prints: July 1, 2000 is on a Saturday
 echo "July 1, 2000 is on a " . date("l", mktime(0, 0, 0, 7, 1, 2000));
+
+/* use the constants in the format parameter */
+// prints something like: Mon, 15 Aug 2005 15:12:46 UTC
+echo date(DATE_RFC822);
+
+// prints something like: 2000-07-01T00:00:00+0000
+echo date(DATE_ATOM, mktime(0, 0, 0, 7, 1, 2000));
 ?>
 ]]>
    </programlisting>
--- a/reference/datetime/functions/gmdate.xml
+++ b/reference/datetime/functions/gmdate.xml
@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.9 $ -->
+<!-- $Revision: 1.10 $ -->
 <!-- splitted from ./en/functions/datetime.xml, last change in rev 1.2 -->
 <refentry id="function.gmdate">
 <refnamediv>
@ -32,22 +32,8 @@ echo gmdate("M d Y H:i:s", mktime(0, 0, 0, 1, 1, 1998));
  </para>
  <note>
   <para>
-    In the Microsoft Windows series of Operating Systems the system
-    libraries implementing this function are broken, so
-    <function>gmdate</function> does not support negative values
-    for the <parameter>timestamp</parameter>.
-    For details see bug reports:
-    <ulink url="&url.php.bugs;22620">#22620</ulink>,
-    <ulink url="&url.php.bugs;22457">#22457</ulink>,
-    and <ulink url="&url.php.bugs;14391">#14391</ulink>.
-   </para>
-   <para>
-    This problem does not occur in Unix/Linux Operating Systems, as the
-    system libraries behave as expected.
-   </para>
-   <para>
-    PHP cannot fix broken system libraries. Contact
-    your OS vendor for a fix to this and similar problems.
+    Prior to PHP 5.1.0, negative timestamps (dates before 1970) didn't work on
+    some systems (Windows, for example).
   </para>
  </note>
  <para>
--- a/reference/datetime/functions/mktime.xml
+++ b/reference/datetime/functions/mktime.xml
@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.19 $ -->
+<!-- $Revision: 1.20 $ -->
 <!-- splitted from ./en/functions/datetime.xml, last change in rev 1.2 -->
 <refentry id="function.mktime">
 <refnamediv>
@ -123,7 +123,7 @@
   <function>mktime</function> returns the Unix timestamp of the arguments
   given.
   If the arguments are invalid (eg. if the year, month and day are all 0), the
-   function returns <literal>-1</literal>.
+   function returns &false; (before PHP 5.1 it returned <literal>-1</literal>).
  </para>
 </refsect1>

@ -145,7 +145,11 @@
      </row>
      <row>
       <entry>5.1.0</entry>
-       <entry>the <parameter>is_dst</parameter> parameter became deprecated</entry>
+       <entry>
+        The <parameter>is_dst</parameter> parameter became deprecated.
+        Made the function return &false; on error, instead of
+        <literal>-1</literal>.
+       </entry>
      </row>
     </tbody>
    </tgroup>