reference/datetime/functions/date-parse.xml
50dcf55ce543220dd8375df2fdb4f7db702b9c9f
...
...
@@ -11,6 +11,24 @@
11
11
<type>array</type><methodname>date_parse</methodname>
12
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">
...
...
@@ -33,16 +51,65 @@
33
51
<refsect1 role="returnvalues">
34
52
&reftitle.returnvalues;
35
53
<para>
36
-
Returns <type>array</type> with information about the parsed date/time
37
-
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>.
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.
38
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>
39
106
</refsect1>
40
107

41
108
<refsect1 role="errors">
42
109
&reftitle.errors;
43
110
<para>
44
111
In case the date/time format has an error, the element 'errors' will
45
-
contains the error messages.
112
+
contain the error messages.
46
113
</para>
47
114
</refsect1>
48
115
...
...
@@ -74,36 +141,205 @@
74
141
&reftitle.examples;
75
142
<para>
76
143
<example>
77
-
<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>
146
+
<programlisting role="php">
147
+
<![CDATA[
148
+
<?php
149
+
var_dump(date_parse("2006-12-12 10:00:00.5"));
150
+
?>
151
+
]]>
152
+
</programlisting>
153
+
&example.outputs;
154
+
<screen>
155
+
<![CDATA[
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
+
}
184
+
]]>
185
+
</screen>
186
+
</example>
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>
78
300
<programlisting role="php">
79
301
<![CDATA[
80
302
<?php
81
-
print_r(date_parse("2006-12-12 10:00:00.5"));
303
+
var_dump(date_parse("June 2nd, 2022"));
82
304
?>
83
305
]]>
84
306
</programlisting>
85
307
&example.outputs;
86
308
<screen>
87
309
<![CDATA[
88
-
Array
89
-
(
90
-
[year] => 2006
91
-
[month] => 12
92
-
[day] => 12
93
-
[hour] => 10
94
-
[minute] => 0
95
-
[second] => 0
96
-
[fraction] => 0.5
97
-
[warning_count] => 0
98
-
[warnings] => Array()
99
-
[error_count] => 0
100
-
[errors] => Array()
101
-
[is_localtime] =>
102
-
)
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
+
}
103
338
]]>
104
339
</screen>
105
340
</example>
106
341
</para>
342
+

107
343
<para>
108
344
<link linkend="datetime.formats.relative">Relative formats</link> do not
109
345
influence the values parsed from absolute formats, but are parsed into the
...
...
@@ -113,44 +349,126 @@ Array
113
349
<programlisting role="php">
114
350
<![CDATA[
115
351
<?php
116
-
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"));
117
353
?>
118
354
]]>
119
355
</programlisting>
120
356
&example.outputs;
121
357
<screen>
122
358
<![CDATA[
123
-
Array
124
-
(
125
-
[year] => 2006
126
-
[month] => 12
127
-
[day] => 12
128
-
[hour] => 10
129
-
[minute] => 0
130
-
[second] => 0
131
-
[fraction] => 0.5
132
-
[warning_count] => 0
133
-
[warnings] => Array
134
-
(
135
-
)
136
-

137
-
[error_count] => 0
138
-
[errors] => Array
139
-
(
140
-
)
141
-

142
-
[is_localtime] =>
143
-
[relative] => Array
144
-
(
145
-
[year] => 0
146
-
[month] => 0
147
-
[day] => 7
148
-
[hour] => 1
149
-
[minute] => 0
150
-
[second] => 0
151
-
)
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>
152
406

153
-
)]]>
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
+
]]>
154
472
</screen>
155
473
</example>
156
474
</para>
...
...
@@ -160,7 +478,9 @@ Array
160
478
&reftitle.seealso;
161
479
<para>
162
480
<simplelist>
163
-
<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>
164
484
<member><function>getdate</function></member>
165
485
</simplelist>
166
486
</para>
167
487



Tools (French Manual)