reference/datetime/functions/date.xml
7f385d3239d0df073e2208fb0c3c243ef13553bb
...
...
@@ -3,7 +3,7 @@
3
3
<refentry xml:id="function.date" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
4
4
<refnamediv>
5
5
<refname>date</refname>
6
-
<refpurpose>Format a local time/date</refpurpose>
6
+
<refpurpose>Format a Unix timestamp</refpurpose>
7
7
</refnamediv>
8
8

9
9
<refsect1 role="description">
...
...
@@ -11,14 +11,22 @@
11
11
<methodsynopsis>
12
12
<type>string</type><methodname>date</methodname>
13
13
<methodparam><type>string</type><parameter>format</parameter></methodparam>
14
-
<methodparam choice="opt"><type>int</type><parameter>timestamp</parameter><initializer>time()</initializer></methodparam>
14
+
<methodparam choice="opt"><type class="union"><type>int</type><type>null</type></type><parameter>timestamp</parameter><initializer>&null;</initializer></methodparam>
15
15
</methodsynopsis>
16
16
<para>
17
17
Returns a string formatted according to the given format string using the
18
-
given integer <parameter>timestamp</parameter> or the current time
19
-
if no timestamp is given. In other words, <parameter>timestamp</parameter>
18
+
given integer <parameter>timestamp</parameter> (Unix timestamp) or the current time
19
+
if no timestamp is given. In other words, <parameter>timestamp</parameter>
20
20
is optional and defaults to the value of <function>time</function>.
21
21
</para>
22
+
<warning>
23
+
<para>
24
+
Unix timestamps do not handle timezones. Use the
25
+
<classname>DateTimeImmutable</classname> class, and its
26
+
<methodname>DateTimeInterface::format</methodname> formatting method to
27
+
format date/time information with a timezone attached.
28
+
</para>
29
+
</warning>
22
30
</refsect1>
23
31

24
32
<refsect1 role="parameters">
...
...
@@ -28,8 +36,17 @@
28
36
<term><parameter>format</parameter></term>
29
37
<listitem>
30
38
<para>
31
-
Format accepted by <function>DateTimeInterface::format</function>.
39
+
Format accepted by <methodname>DateTimeInterface::format</methodname>.
32
40
</para>
41
+
<note>
42
+
<simpara>
43
+
<function>date</function> will always generate
44
+
<literal>000000</literal> as microseconds since it takes an <type>int</type>
45
+
parameter, whereas <methodname>DateTime::format</methodname> does
46
+
support microseconds if <classname>DateTime</classname> was
47
+
created with microseconds.
48
+
</simpara>
49
+
</note>
33
50
</listitem>
34
51
</varlistentry>
35
52

...
...
@@ -41,9 +58,7 @@
41
58
<refsect1 role="returnvalues">
42
59
&reftitle.returnvalues;
43
60
<para>
44
-
Returns a formatted date string. If a non-numeric value is used for
45
-
<parameter>timestamp</parameter>, &false; is returned and an
46
-
<constant>E_WARNING</constant> level error is emitted.
61
+
Returns a formatted date string.
47
62
</para>
48
63
</refsect1>
49
64

...
...
@@ -54,6 +69,30 @@
54
69

55
70
</refsect1>
56
71

72
+
<refsect1 role="changelog">
73
+
&reftitle.changelog;
74
+
<para>
75
+
<informaltable>
76
+
<tgroup cols="2">
77
+
<thead>
78
+
<row>
79
+
<entry>&Version;</entry>
80
+
<entry>&Description;</entry>
81
+
</row>
82
+
</thead>
83
+
<tbody>
84
+
<row>
85
+
<entry>8.0.0</entry>
86
+
<entry>
87
+
<parameter>timestamp</parameter> is nullable now.
88
+
</entry>
89
+
</row>
90
+
</tbody>
91
+
</tgroup>
92
+
</informaltable>
93
+
</para>
94
+
</refsect1>
95
+

57
96
<refsect1 role="examples">
58
97
&reftitle.examples;
59
98
<para>
...
...
@@ -62,7 +101,7 @@
62
101
<programlisting role="php">
63
102
<![CDATA[
64
103
<?php
65
-
// set the default timezone to use. Available since PHP 5.1
104
+
// set the default timezone to use.
66
105
date_default_timezone_set('UTC');
67
106

68
107

...
...
@@ -158,9 +197,9 @@ $today = date("Y-m-d H:i:s"); // 2001-03-10 17:16:18 (the MySQ
158
197
</example>
159
198
</para>
160
199
<para>
161
-
To format dates in other languages, you should use the
162
-
<function>setlocale</function> and <function>strftime</function>
163
-
functions instead of <function>date</function>.
200
+
To format dates in other languages,
201
+
<methodname>IntlDateFormatter::format</methodname>
202
+
can be used instead of <function>date</function>.
164
203
</para>
165
204
</refsect1>
166
205

...
...
@@ -178,7 +217,7 @@ $today = date("Y-m-d H:i:s"); // 2001-03-10 17:16:18 (the MySQ
178
217
<tip>
179
218
<para>
180
219
Timestamp of the start of the request is available in
181
-
<varname>$_SERVER['REQUEST_TIME']</varname> since PHP 5.1.
220
+
<varname>$_SERVER['REQUEST_TIME']</varname>.
182
221
</para>
183
222
</tip>
184
223
</refsect1>
...
...
@@ -187,20 +226,20 @@ $today = date("Y-m-d H:i:s"); // 2001-03-10 17:16:18 (the MySQ
187
226
&reftitle.seealso;
188
227
<para>
189
228
<simplelist>
229
+
<member><methodname>DateTimeImmutable::__construct</methodname></member>
230
+
<member><methodname>DateTimeInterface::format</methodname></member>
190
231
<member><function>gmdate</function></member>
191
232
<member><function>idate</function></member>
192
233
<member><function>getdate</function></member>
193
234
<member><function>getlastmod</function></member>
194
235
<member><function>mktime</function></member>
195
-
<member><function>strftime</function></member>
236
+
<member><methodname>IntlDateFormatter::format</methodname></member>
196
237
<member><function>time</function></member>
197
-
<member><function>DateTimeImmutable::__construct</function></member>
198
-
<member><link linkend="datetime.constants.types">Predefined DateTime Constants</link></member>
238
+
<member><link linkend="datetimeinterface.constants.types">Predefined DateTime Constants</link></member>
199
239
</simplelist>
200
240
</para>
201
241
</refsect1>
202
242
</refentry>
203
-

204
243
<!-- Keep this comment at the end of the file
205
244
Local variables:
206
245
mode: sgml
207
246