reference/datetime/functions/date-parse-from-format.xml
4d13f5e4b45f699eb855a5e84736aeda2ebd142a
...
...
@@ -12,10 +12,10 @@
12
12
<methodsynopsis>
13
13
<type>array</type><methodname>date_parse_from_format</methodname>
14
14
<methodparam><type>string</type><parameter>format</parameter></methodparam>
15
-
<methodparam><type>string</type><parameter>date</parameter></methodparam>
15
+
<methodparam><type>string</type><parameter>datetime</parameter></methodparam>
16
16
</methodsynopsis>
17
17
<para>
18
-
Returns associative array with detailed info about given date.
18
+
Returns associative array with detailed info about given date/time.
19
19
</para>
20
20
</refsect1>
21
21

...
...
@@ -27,15 +27,18 @@
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>
34
37
<varlistentry>
35
-
<term><parameter>date</parameter></term>
38
+
<term><parameter>datetime</parameter></term>
36
39
<listitem>
37
40
<para>
38
-
String representing the date.
41
+
String representing the date/time.
39
42
</para>
40
43
</listitem>
41
44
</varlistentry>
...
...
@@ -47,10 +50,92 @@
47
50
&reftitle.returnvalues;
48
51
<!-- See also &return.success; -->
49
52
<para>
50
-
Returns associative array with detailed info about given date.
53
+
Returns associative array with detailed info about given date/time.
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.
51
104
</para>
52
105
</refsect1>
53
106

107
+
<refsect1 role="changelog">
108
+
&reftitle.changelog;
109
+
<informaltable>
110
+
<tgroup cols="2">
111
+
<thead>
112
+
<row>
113
+
<entry>&Version;</entry>
114
+
<entry>&Description;</entry>
115
+
</row>
116
+
</thead>
117
+
<tbody>
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>
127
+
<entry>7.2.0</entry>
128
+
<entry>
129
+
The <literal>zone</literal> element of the returned array represents
130
+
seconds instead of minutes now, and its sign is inverted. For instance
131
+
<literal>-120</literal> is now <literal>7200</literal>.
132
+
</entry>
133
+
</row>
134
+
</tbody>
135
+
</tgroup>
136
+
</informaltable>
137
+
</refsect1>
138
+

54
139
<refsect1 role="examples">
55
140
&reftitle.examples;
56
141
<para>
...
...
@@ -88,19 +173,73 @@ Array
88
173

89
174
[is_localtime] => 1
90
175
[zone_type] => 1
91
-
[zone] => -60
176
+
[zone] => 3600
92
177
[is_dst] =>
93
178
)
94
179
]]>
95
180
</screen>
96
181
</example>
97
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>
98
236
</refsect1>
237
+

99
238
<refsect1 role="seealso">
100
239
&reftitle.seealso;
101
240
<para>
102
241
<simplelist>
103
-
<member><function>DateTime::createFromFormat</function></member>
242
+
<member><function>DateTimeImmutable::createFromFormat</function></member>
104
243
<member><function>checkdate</function></member>
105
244
</simplelist>
106
245
</para>
107
246