reference/datetime/functions/date-parse-from-format.xml
4d13f5e4b45f699eb855a5e84736aeda2ebd142a
4d13f5e4b45f699eb855a5e84736aeda2ebd142a
...
...
@@ -27,7 +27,10 @@
27
27
<term><parameter>format</parameter></term>
28
28
<listitem>
29
29
<para>
30
-
Format accepted by <function>DateTime::createFromFormat</function>.
30
+
Documentation on how the <parameter>format</parameter> is used, please
31
+
refer to the documentation of
32
+
<function>DateTimeImmutable::createFromFormat</function>. The same
33
+
rules apply.
31
34
</para>
32
35
</listitem>
33
36
</varlistentry>
...
...
@@ -49,6 +52,56 @@
49
52
<para>
50
53
Returns associative array with detailed info about given date/time.
51
54
</para>
55
+
<para>
56
+
The returned array has keys for <literal>year</literal>,
57
+
<literal>month</literal>, <literal>day</literal>, <literal>hour</literal>,
58
+
<literal>minute</literal>, <literal>second</literal>,
59
+
<literal>fraction</literal>, and <literal>is_localtime</literal>.
60
+
</para>
61
+
<para>
62
+
If <literal>is_localtime</literal> is present then
63
+
<literal>zone_type</literal> indicates the type of timezone. For type
64
+
<literal>1</literal> (UTC offset) the <literal>zone</literal>,
65
+
<literal>is_dst</literal> fields are added; for type <literal>2</literal>
66
+
(abbreviation) the fields <literal>tz_abbr</literal>,
67
+
<literal>is_dst</literal> are added; and for type <literal>3</literal>
68
+
(timezone identifier) the <literal>tz_abbr</literal>,
69
+
<literal>tz_id</literal> are added.
70
+
</para>
71
+
<para>
72
+
The array includes <literal>warning_count</literal> and
73
+
<literal>warnings</literal> fields. The first one indicate how many
74
+
warnings there were.
75
+
The keys of elements <literal>warnings</literal> array indicate the
76
+
position in the given <parameter>datetime</parameter> where the warning
77
+
occurred, with the string value describing the warning itself. An example
78
+
below shows such a warning.
79
+
</para>
80
+
<para>
81
+
The array also contains <literal>error_count</literal> and
82
+
<literal>errors</literal> fields. The first one indicate how many errors
83
+
were found.
84
+
The keys of elements <literal>errors</literal> array indicate the
85
+
position in the given <parameter>datetime</parameter> where the error
86
+
occurred, with the string value describing the error itself. An example
87
+
below shows such an error.
88
+
</para>
89
+
<warning>
90
+
<para>
91
+
The number of array elements in the <literal>warnings</literal> and
92
+
<literal>errors</literal> arrays might be less than
93
+
<literal>warning_count</literal> or <literal>error_count</literal> if they
94
+
occurred at the same position.
95
+
</para>
96
+
</warning>
97
+
</refsect1>
98
+
99
+
<refsect1 role="errors">
100
+
&reftitle.errors;
101
+
<para>
102
+
This functions throws <exceptionname>ValueError</exceptionname> when the
103
+
<parameter>datetime</parameter> contains NULL-bytes.
104
+
</para>
52
105
</refsect1>
53
106
54
107
<refsect1 role="changelog">
...
...
@@ -63,6 +116,14 @@
63
116
</thead>
64
117
<tbody>
65
118
<row>
119
+
<entry>8.0.21, 8.1.8, 8.2.0</entry>
120
+
<entry>
121
+
Now throws <exceptionname>ValueError</exceptionname> when NULL-bytes
122
+
are passed into <parameter>datetime</parameter>, which previously was silently
123
+
ignored.
124
+
</entry>
125
+
</row>
126
+
<row>
66
127
<entry>7.2.0</entry>
67
128
<entry>
68
129
The <literal>zone</literal> element of the returned array represents
...
...
@@ -119,12 +180,66 @@ Array
119
180
</screen>
120
181
</example>
121
182
</para>
183
+
184
+
<para>
185
+
<example>
186
+
<title><function>date_parse_from_format</function> with warnings example</title>
187
+
<programlisting role="php">
188
+
<![CDATA[
189
+
<?php
190
+
$date = "26 August 2022 22:30 pm";
191
+
$parsed = date_parse_from_format("j F Y G:i a", $date);
192
+
193
+
echo "Warnings count: ", $parsed['warning_count'], "\n";
194
+
foreach ($parsed['warnings'] as $position => $message) {
195
+
echo "\tOn position {$position}: {$message}\n";
196
+
}
197
+
?>
198
+
]]>
199
+
</programlisting>
200
+
&example.outputs;
201
+
<screen>
202
+
<![CDATA[
203
+
Warnings count: 1
204
+
On position 23: The parsed time was invalid
205
+
]]>
206
+
</screen>
207
+
</example>
208
+
</para>
209
+
210
+
<para>
211
+
<example>
212
+
<title><function>date_parse_from_format</function> with errors example</title>
213
+
<programlisting role="php">
214
+
<![CDATA[
215
+
<?php
216
+
$date = "26 August 2022 CEST";
217
+
$parsed = date_parse_from_format("j F Y H:i", $date);
218
+
219
+
echo "Errors count: ", $parsed['error_count'], "\n";
220
+
foreach ($parsed['errors'] as $position => $message) {
221
+
echo "\tOn position {$position}: {$message}\n";
222
+
}
223
+
?>
224
+
]]>
225
+
</programlisting>
226
+
&example.outputs;
227
+
<screen>
228
+
<![CDATA[
229
+
Errors count: 3
230
+
On position 15: A two digit hour could not be found
231
+
On position 19: Data missing
232
+
]]>
233
+
</screen>
234
+
</example>
235
+
</para>
122
236
</refsect1>
237
+
123
238
<refsect1 role="seealso">
124
239
&reftitle.seealso;
125
240
<para>
126
241
<simplelist>
127
-
<member><function>DateTime::createFromFormat</function></member>
242
+
<member><function>DateTimeImmutable::createFromFormat</function></member>
128
243
<member><function>checkdate</function></member>
129
244
</simplelist>
130
245
</para>
131
246