reference/datetime/functions/date-parse.xml
50dcf55ce543220dd8375df2fdb4f7db702b9c9f
...
...
@@ -3,14 +3,32 @@
3
3
<refentry xml:id="function.date-parse" xmlns="http://docbook.org/ns/docbook">
4
4
<refnamediv>
5
5
<refname>date_parse</refname>
6
-
<refpurpose>Returns associative array with detailed info about given date</refpurpose>
6
+
<refpurpose>Returns associative array with detailed info about given date/time</refpurpose>
7
7
</refnamediv>
8
8
<refsect1 role="description">
9
9
&reftitle.description;
10
10
<methodsynopsis>
11
11
<type>array</type><methodname>date_parse</methodname>
12
-
<methodparam><type>string</type><parameter>date</parameter></methodparam>
12
+
<methodparam><type>string</type><parameter>datetime</parameter></methodparam>
13
13
</methodsynopsis>
14
+
<para>
15
+
<function>date_parse</function> parses the given
16
+
<parameter>datetime</parameter> string according to the same rules as
17
+
<function>strtotime</function> and
18
+
<function>DateTimeImmutable::__construct</function>. Instead of returning a
19
+
Unix timestamp (with <function>strtotime</function>) or a
20
+
<classname>DateTimeImmutable</classname> object (with
21
+
<function>DateTimeImmutable::__construct</function>), it returns an
22
+
associative array with the information that it could detect in the given
23
+
<parameter>datetime</parameter> string.
24
+
</para>
25
+
<para>
26
+
If no information about a certain group of elements can be found, these
27
+
array elements will be set to &false; or are missing. If needed for
28
+
constructing a timestamp or <classname>DateTimeImmutable</classname> object from
29
+
the same <parameter>datetime</parameter> string, more fields can be set to
30
+
a non-&false; value. See the examples for cases where that happens.
31
+
</para>
14
32
</refsect1>
15
33

16
34
<refsect1 role="parameters">
...
...
@@ -18,10 +36,11 @@
18
36
<para>
19
37
<variablelist>
20
38
<varlistentry>
21
-
<term><parameter>date</parameter></term>
39
+
<term><parameter>datetime</parameter></term>
22
40
<listitem>
23
41
<para>
24
-
Date in format accepted by <function>strtotime</function>.
42
+
Date/time in format accepted by
43
+
<function>DateTimeImmutable::__construct</function>.
25
44
</para>
26
45
</listitem>
27
46
</varlistentry>
...
...
@@ -32,53 +51,295 @@
32
51
<refsect1 role="returnvalues">
33
52
&reftitle.returnvalues;
34
53
<para>
35
-
Returns <type>array</type> with information about the parsed date
36
-
on success&return.falseforfailure;.
54
+
Returns <type>array</type> with information about the parsed date/time.
55
+
</para>
56
+
<para>
57
+
The returned array has keys for <literal>year</literal>,
58
+
<literal>month</literal>, <literal>day</literal>, <literal>hour</literal>,
59
+
<literal>minute</literal>, <literal>second</literal>,
60
+
<literal>fraction</literal>, and <literal>is_localtime</literal>.
37
61
</para>
62
+
<para>
63
+
If <literal>is_localtime</literal> is present then
64
+
<literal>zone_type</literal> indicates the type of timezone. For type
65
+
<literal>1</literal> (UTC offset) the <literal>zone</literal>,
66
+
<literal>is_dst</literal> fields are added; for type <literal>2</literal>
67
+
(abbreviation) the fields <literal>tz_abbr</literal>,
68
+
<literal>is_dst</literal> are added; and for type <literal>3</literal>
69
+
(timezone identifier) the <literal>tz_abbr</literal>,
70
+
<literal>tz_id</literal> are added.
71
+
</para>
72
+
<para>
73
+
If relative time elements are present in the
74
+
<parameter>datetime</parameter> string such as <literal>+3 days</literal>,
75
+
the then returned array includes a nested array with the key
76
+
<literal>relative</literal>. This array then contains the keys
77
+
<literal>year</literal>, <literal>month</literal>, <literal>day</literal>,
78
+
<literal>hour</literal>, <literal>minute</literal>,
79
+
<literal>second</literal>, and if necessary <literal>weekday</literal>, and
80
+
<literal>weekdays</literal>, depending on the string that was passed in.
81
+
</para>
82
+
<para>
83
+
The array includes <literal>warning_count</literal> and
84
+
<literal>warnings</literal> fields. The first one indicate how many
85
+
warnings there were.
86
+
The keys of elements <literal>warnings</literal> array indicate the
87
+
position in the given <parameter>datetime</parameter> where the warning
88
+
occurred, with the string value describing the warning itself.
89
+
</para>
90
+
<para>
91
+
The array also contains <literal>error_count</literal> and
92
+
<literal>errors</literal> fields. The first one indicate how many errors
93
+
were found.
94
+
The keys of elements <literal>errors</literal> array indicate the
95
+
position in the given <parameter>datetime</parameter> where the error
96
+
occurred, with the string value describing the error itself.
97
+
</para>
98
+
<warning>
99
+
<para>
100
+
The number of array elements in the <literal>warnings</literal> and
101
+
<literal>errors</literal> arrays might be less than
102
+
<literal>warning_count</literal> or <literal>error_count</literal> if they
103
+
occurred at the same position.
104
+
</para>
105
+
</warning>
38
106
</refsect1>
39
107

40
108
<refsect1 role="errors">
41
109
&reftitle.errors;
42
110
<para>
43
-
In case the date format has an error, the element 'errors' will
44
-
contains the error messages.
111
+
In case the date/time format has an error, the element 'errors' will
112
+
contain the error messages.
45
113
</para>
46
114
</refsect1>
47
115
116
+
<refsect1 role="changelog">
117
+
&reftitle.changelog;
118
+
<informaltable>
119
+
<tgroup cols="2">
120
+
<thead>
121
+
<row>
122
+
<entry>&Version;</entry>
123
+
<entry>&Description;</entry>
124
+
</row>
125
+
</thead>
126
+
<tbody>
127
+
<row>
128
+
<entry>7.2.0</entry>
129
+
<entry>
130
+
The <literal>zone</literal> element of the returned array represents
131
+
seconds instead of minutes now, and its sign is inverted. For instance
132
+
<literal>-120</literal> is now <literal>7200</literal>.
133
+
</entry>
134
+
</row>
135
+
</tbody>
136
+
</tgroup>
137
+
</informaltable>
138
+
</refsect1>
139
+

48
140
<refsect1 role="examples">
49
141
&reftitle.examples;
50
142
<para>
51
143
<example>
52
-
<title>A <function>date_parse</function> example</title>
144
+
<title>A <function>date_parse</function> example with a comprehensive
145
+
<parameter>datetime</parameter> string</title>
53
146
<programlisting role="php">
54
147
<![CDATA[
55
148
<?php
56
-
print_r(date_parse("2006-12-12 10:00:00.5"));
149
+
var_dump(date_parse("2006-12-12 10:00:00.5"));
57
150
?>
58
151
]]>
59
152
</programlisting>
60
153
&example.outputs;
61
154
<screen>
62
155
<![CDATA[
63
-
Array
64
-
(
65
-
[year] => 2006
66
-
[month] => 12
67
-
[day] => 12
68
-
[hour] => 10
69
-
[minute] => 0
70
-
[second] => 0
71
-
[fraction] => 0.5
72
-
[warning_count] => 0
73
-
[warnings] => Array()
74
-
[error_count] => 0
75
-
[errors] => Array()
76
-
[is_localtime] =>
77
-
)
156
+
array(12) {
157
+
["year"]=>
158
+
int(2006)
159
+
["month"]=>
160
+
int(12)
161
+
["day"]=>
162
+
int(12)
163
+
["hour"]=>
164
+
int(10)
165
+
["minute"]=>
166
+
int(0)
167
+
["second"]=>
168
+
int(0)
169
+
["fraction"]=>
170
+
float(0.5)
171
+
["warning_count"]=>
172
+
int(0)
173
+
["warnings"]=>
174
+
array(0) {
175
+
}
176
+
["error_count"]=>
177
+
int(0)
178
+
["errors"]=>
179
+
array(0) {
180
+
}
181
+
["is_localtime"]=>
182
+
bool(false)
183
+
}
78
184
]]>
79
185
</screen>
80
186
</example>
81
187
</para>
188
+

189
+
<para>
190
+
The timezone elements only show up if they are included in the given
191
+
<parameter>datetime</parameter> string. In that case there will
192
+
always be a <literal>zone_type</literal> element and a few more depending
193
+
on its value.
194
+
<example>
195
+
<title><function>date_parse</function> with timezone abbreviation information</title>
196
+
<programlisting role="php">
197
+
<![CDATA[
198
+
<?php
199
+
var_dump(date_parse("June 2nd, 2022, 10:28:17 BST"));
200
+
?>
201
+
]]>
202
+
</programlisting>
203
+
&example.outputs;
204
+
<screen>
205
+
<![CDATA[
206
+
array(16) {
207
+
["year"]=>
208
+
int(2022)
209
+
["month"]=>
210
+
int(6)
211
+
["day"]=>
212
+
int(2)
213
+
["hour"]=>
214
+
int(10)
215
+
["minute"]=>
216
+
int(28)
217
+
["second"]=>
218
+
int(17)
219
+
["fraction"]=>
220
+
float(0)
221
+
["warning_count"]=>
222
+
int(0)
223
+
["warnings"]=>
224
+
array(0) {
225
+
}
226
+
["error_count"]=>
227
+
int(0)
228
+
["errors"]=>
229
+
array(0) {
230
+
}
231
+
["is_localtime"]=>
232
+
bool(true)
233
+
["zone_type"]=>
234
+
int(2)
235
+
["zone"]=>
236
+
int(0)
237
+
["is_dst"]=>
238
+
bool(true)
239
+
["tz_abbr"]=>
240
+
string(3) "BST"
241
+
}
242
+
]]>
243
+
</screen>
244
+
</example>
245
+
<example>
246
+
<title><function>date_parse</function> with timezone identifier information</title>
247
+
<programlisting role="php">
248
+
<![CDATA[
249
+
<?php
250
+
var_dump(date_parse("June 2nd, 2022, 10:28:17 Europe/London"));
251
+
?>
252
+
]]>
253
+
</programlisting>
254
+
&example.outputs;
255
+
<screen>
256
+
<![CDATA[
257
+
array(14) {
258
+
["year"]=>
259
+
int(2022)
260
+
["month"]=>
261
+
int(6)
262
+
["day"]=>
263
+
int(2)
264
+
["hour"]=>
265
+
int(10)
266
+
["minute"]=>
267
+
int(28)
268
+
["second"]=>
269
+
int(17)
270
+
["fraction"]=>
271
+
float(0)
272
+
["warning_count"]=>
273
+
int(0)
274
+
["warnings"]=>
275
+
array(0) {
276
+
}
277
+
["error_count"]=>
278
+
int(0)
279
+
["errors"]=>
280
+
array(0) {
281
+
}
282
+
["is_localtime"]=>
283
+
bool(true)
284
+
["zone_type"]=>
285
+
int(3)
286
+
["tz_id"]=>
287
+
string(13) "Europe/London"
288
+
}
289
+
]]>
290
+
</screen>
291
+
</example>
292
+
</para>
293
+

294
+
<para>
295
+
If a more minimal <parameter>datetime</parameter> string is parsed, less
296
+
information is available. In this example, all the time parts are returned
297
+
as &false;.
298
+
<example>
299
+
<title><function>date_parse</function> with a minimal string</title>
300
+
<programlisting role="php">
301
+
<![CDATA[
302
+
<?php
303
+
var_dump(date_parse("June 2nd, 2022"));
304
+
?>
305
+
]]>
306
+
</programlisting>
307
+
&example.outputs;
308
+
<screen>
309
+
<![CDATA[
310
+
array(12) {
311
+
["year"]=>
312
+
int(2022)
313
+
["month"]=>
314
+
int(6)
315
+
["day"]=>
316
+
int(2)
317
+
["hour"]=>
318
+
bool(false)
319
+
["minute"]=>
320
+
bool(false)
321
+
["second"]=>
322
+
bool(false)
323
+
["fraction"]=>
324
+
bool(false)
325
+
["warning_count"]=>
326
+
int(0)
327
+
["warnings"]=>
328
+
array(0) {
329
+
}
330
+
["error_count"]=>
331
+
int(0)
332
+
["errors"]=>
333
+
array(0) {
334
+
}
335
+
["is_localtime"]=>
336
+
bool(false)
337
+
}
338
+
]]>
339
+
</screen>
340
+
</example>
341
+
</para>
342
+

82
343
<para>
83
344
<link linkend="datetime.formats.relative">Relative formats</link> do not
84
345
influence the values parsed from absolute formats, but are parsed into the
...
...
@@ -88,44 +349,126 @@ Array
88
349
<programlisting role="php">
89
350
<![CDATA[
90
351
<?php
91
-
print_r(date_parse("2006-12-12 10:00:00.5 +1 week +1 hour"));
352
+
var_dump(date_parse("2006-12-12 10:00:00.5 +1 week +1 hour"));
92
353
?>
93
354
]]>
94
355
</programlisting>
95
356
&example.outputs;
96
357
<screen>
97
358
<![CDATA[
98
-
Array
99
-
(
100
-
[year] => 2006
101
-
[month] => 12
102
-
[day] => 12
103
-
[hour] => 10
104
-
[minute] => 0
105
-
[second] => 0
106
-
[fraction] => 0.5
107
-
[warning_count] => 0
108
-
[warnings] => Array
109
-
(
110
-
)
111
-

112
-
[error_count] => 0
113
-
[errors] => Array
114
-
(
115
-
)
116
-

117
-
[is_localtime] =>
118
-
[relative] => Array
119
-
(
120
-
[year] => 0
121
-
[month] => 0
122
-
[day] => 7
123
-
[hour] => 1
124
-
[minute] => 0
125
-
[second] => 0
126
-
)
359
+
array(13) {
360
+
["year"]=>
361
+
int(2006)
362
+
["month"]=>
363
+
int(12)
364
+
["day"]=>
365
+
int(12)
366
+
["hour"]=>
367
+
int(10)
368
+
["minute"]=>
369
+
int(0)
370
+
["second"]=>
371
+
int(0)
372
+
["fraction"]=>
373
+
float(0.5)
374
+
["warning_count"]=>
375
+
int(0)
376
+
["warnings"]=>
377
+
array(0) {
378
+
}
379
+
["error_count"]=>
380
+
int(0)
381
+
["errors"]=>
382
+
array(0) {
383
+
}
384
+
["is_localtime"]=>
385
+
bool(false)
386
+
["relative"]=>
387
+
array(6) {
388
+
["year"]=>
389
+
int(0)
390
+
["month"]=>
391
+
int(0)
392
+
["day"]=>
393
+
int(7)
394
+
["hour"]=>
395
+
int(1)
396
+
["minute"]=>
397
+
int(0)
398
+
["second"]=>
399
+
int(0)
400
+
}
401
+
}
402
+
]]>
403
+
</screen>
404
+
</example>
405
+
</para>
127
406

128
-
)]]>
407
+
<para>
408
+
Some stanzas, such as <literal>Thursday</literal> will set the time portion
409
+
of the string to <literal>0</literal>. If <literal>Thursday</literal> is
410
+
passed to <function>DateTimeImmutable::__construct</function> it would also
411
+
have resulted in the hour, minute, second, and fraction being set to
412
+
<literal>0</literal>. In the example below, the year element is however
413
+
left as &false;.
414
+
<example>
415
+
<title><function>date_parse</function> with side-effects</title>
416
+
<programlisting role="php">
417
+
<![CDATA[
418
+
<?php
419
+
var_dump(date_parse("Thursday, June 2nd"));
420
+
?>
421
+
]]>
422
+
</programlisting>
423
+
&example.outputs;
424
+
<screen>
425
+
<![CDATA[
426
+
array(13) {
427
+
["year"]=>
428
+
bool(false)
429
+
["month"]=>
430
+
int(6)
431
+
["day"]=>
432
+
int(2)
433
+
["hour"]=>
434
+
int(0)
435
+
["minute"]=>
436
+
int(0)
437
+
["second"]=>
438
+
int(0)
439
+
["fraction"]=>
440
+
float(0)
441
+
["warning_count"]=>
442
+
int(0)
443
+
["warnings"]=>
444
+
array(0) {
445
+
}
446
+
["error_count"]=>
447
+
int(0)
448
+
["errors"]=>
449
+
array(0) {
450
+
}
451
+
["is_localtime"]=>
452
+
bool(false)
453
+
["relative"]=>
454
+
array(7) {
455
+
["year"]=>
456
+
int(0)
457
+
["month"]=>
458
+
int(0)
459
+
["day"]=>
460
+
int(0)
461
+
["hour"]=>
462
+
int(0)
463
+
["minute"]=>
464
+
int(0)
465
+
["second"]=>
466
+
int(0)
467
+
["weekday"]=>
468
+
int(4)
469
+
}
470
+
}
471
+
]]>
129
472
</screen>
130
473
</example>
131
474
</para>
...
...
@@ -135,14 +478,15 @@ Array
135
478
&reftitle.seealso;
136
479
<para>
137
480
<simplelist>
138
-
<member><function>checkdate</function></member>
481
+
<member><function>date_parse_from_format</function> for
482
+
parsing a <parameter>datetime</parameter> with a specific given format</member>
483
+
<member><function>checkdate</function> for Gregorian date validation</member>
139
484
<member><function>getdate</function></member>
140
485
</simplelist>
141
486
</para>
142
487
</refsect1>
143
488

144
489
</refentry>
145
-

146
490
<!-- Keep this comment at the end of the file
147
491
Local variables:
148
492
mode: sgml
149
493