nlopess Mon Aug 15 12:01:08 2005 EDT
Modified files:
/phpdoc/en/reference/datetime constants.xml
/phpdoc/en/reference/datetime/functions date.xml gmdate.xml
mktime.xml
Log:
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
http://cvs.php.net/diff.php/phpdoc/en/reference/datetime/constants.xml?r1=1.2&r2=1.3&ty=u
Index: phpdoc/en/reference/datetime/constants.xml
diff -u phpdoc/en/reference/datetime/constants.xml:1.2
phpdoc/en/reference/datetime/constants.xml:1.3
--- phpdoc/en/reference/datetime/constants.xml:1.2 Mon Aug 1 14:46:14 2005
+++ phpdoc/en/reference/datetime/constants.xml Mon Aug 15 12:01:05 2005
@@ -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>
http://cvs.php.net/diff.php/phpdoc/en/reference/datetime/functions/date.xml?r1=1.19&r2=1.20&ty=u
Index: phpdoc/en/reference/datetime/functions/date.xml
diff -u phpdoc/en/reference/datetime/functions/date.xml:1.19
phpdoc/en/reference/datetime/functions/date.xml:1.20
--- phpdoc/en/reference/datetime/functions/date.xml:1.19 Sat Jul 30
14:14:11 2005
+++ phpdoc/en/reference/datetime/functions/date.xml Mon Aug 15 12:01:08 2005
@@ -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>
http://cvs.php.net/diff.php/phpdoc/en/reference/datetime/functions/gmdate.xml?r1=1.9&r2=1.10&ty=u
Index: phpdoc/en/reference/datetime/functions/gmdate.xml
diff -u phpdoc/en/reference/datetime/functions/gmdate.xml:1.9
phpdoc/en/reference/datetime/functions/gmdate.xml:1.10
--- phpdoc/en/reference/datetime/functions/gmdate.xml:1.9 Sun Apr 24
19:50:58 2005
+++ phpdoc/en/reference/datetime/functions/gmdate.xml Mon Aug 15 12:01:08 2005
@@ -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 @@
</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>
http://cvs.php.net/diff.php/phpdoc/en/reference/datetime/functions/mktime.xml?r1=1.19&r2=1.20&ty=u
Index: phpdoc/en/reference/datetime/functions/mktime.xml
diff -u phpdoc/en/reference/datetime/functions/mktime.xml:1.19
phpdoc/en/reference/datetime/functions/mktime.xml:1.20
--- phpdoc/en/reference/datetime/functions/mktime.xml:1.19 Sat Aug 13
15:37:21 2005
+++ phpdoc/en/reference/datetime/functions/mktime.xml Mon Aug 15 12:01:08 2005
@@ -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>
