reference/datetime/datetime/createfromformat.xml
4d13f5e4b45f699eb855a5e84736aeda2ebd142a
...
...
@@ -10,14 +10,14 @@
10
10
<refsect1 role="description">
11
11
&reftitle.description;
12
12
<para>&style.oop;</para>
13
-
<methodsynopsis role="oop">
13
+
<methodsynopsis role="DateTime">
14
14
<modifier>public</modifier> <modifier>static</modifier> <type class="union"><type>DateTime</type><type>false</type></type><methodname>DateTime::createFromFormat</methodname>
15
15
<methodparam><type>string</type><parameter>format</parameter></methodparam>
16
16
<methodparam><type>string</type><parameter>datetime</parameter></methodparam>
17
17
<methodparam choice="opt"><type class="union"><type>DateTimeZone</type><type>null</type></type><parameter>timezone</parameter><initializer>&null;</initializer></methodparam>
18
18
</methodsynopsis>
19
19
<para>&style.procedural;</para>
20
-
<methodsynopsis role="procedural">
20
+
<methodsynopsis>
21
21
<type class="union"><type>DateTime</type><type>false</type></type><methodname>date_create_from_format</methodname>
22
22
<methodparam><type>string</type><parameter>format</parameter></methodparam>
23
23
<methodparam><type>string</type><parameter>datetime</parameter></methodparam>
...
...
@@ -28,325 +28,25 @@
28
28
<parameter>datetime</parameter> string, which was formatted in the given
29
29
<parameter>format</parameter>.
30
30
</para>
31
+
<para>
32
+
Like <methodname>DateTimeImmutable::createFromFormat</methodname>
33
+
and <function>date_create_immutable_from_format</function>, respectively, but
34
+
creates a <classname>DateTime</classname> object.
35
+
</para>
36
+
<para>
37
+
This method, including parameters, examples, and considerations are
38
+
documented on the <link
39
+
linkend="datetimeimmutable.createfromformat">DateTimeImmutable::createFromFormat</link>
40
+
page.
41
+
</para>
31
42
</refsect1>
32
43

33
44
<refsect1 role="parameters">
34
45
&reftitle.parameters;
35
-
<variablelist>
36
-
<varlistentry>
37
-
<term><parameter>format</parameter></term>
38
-
<listitem>
39
-
<para>
40
-
The format that the passed in <type>string</type> should be in. See the
41
-
formatting options below. In most cases, the same letters as for the
42
-
<function>date</function> can be used.
43
-
</para>
44
-
<para>
45
-
<table>
46
-
<title>The following characters are recognized in the
47
-
<parameter>format</parameter> parameter string</title>
48
-
<tgroup cols="3">
49
-
<thead>
50
-
<row>
51
-
<entry><parameter>format</parameter> character</entry>
52
-
<entry>Description</entry>
53
-
<entry>Example parsable values</entry>
54
-
</row>
55
-
</thead>
56
-
<tbody>
57
-
<row>
58
-
<entry align="center"><emphasis>Day</emphasis></entry>
59
-
<entry>---</entry>
60
-
<entry>---</entry>
61
-
</row>
62
-
<row>
63
-
<entry><literal>d</literal> and <literal>j</literal></entry>
64
-
<entry>Day of the month, 2 digits with or without leading zeros</entry>
65
-
<entry>
66
-
<literal>01</literal> to <literal>31</literal> or
67
-
<literal>1</literal> to <literal>31</literal>
68
-
</entry>
69
-
</row>
70
-
<row>
71
-
<entry><literal>D</literal> and <literal>l</literal></entry>
72
-
<entry>A textual representation of a day</entry>
73
-
<entry>
74
-
<literal>Mon</literal> through <literal>Sun</literal> or
75
-
<literal>Sunday</literal> through <literal>Saturday</literal>
76
-
</entry>
77
-
</row>
78
-
<row>
79
-
<entry><literal>S</literal></entry>
80
-
<entry>English ordinal suffix for the day of the month, 2
81
-
characters. It's ignored while processing.</entry>
82
-
<entry>
83
-
<literal>st</literal>, <literal>nd</literal>, <literal>rd</literal> or
84
-
<literal>th</literal>.
85
-
</entry>
86
-
</row>
87
-
<row>
88
-
<entry><literal>z</literal></entry>
89
-
<entry>
90
-
The day of the year (starting from 0);
91
-
must be preceded by <literal>Y</literal> or <literal>y</literal>.
92
-
</entry>
93
-
<entry><literal>0</literal> through <literal>365</literal></entry>
94
-
</row>
95
-
<row>
96
-
<entry align="center"><emphasis>Month</emphasis></entry>
97
-
<entry>---</entry>
98
-
<entry>---</entry>
99
-
</row>
100
-
<row>
101
-
<entry><literal>F</literal> and <literal>M</literal></entry>
102
-
<entry>A textual representation of a month, such as January or Sept</entry>
103
-
<entry>
104
-
<literal>January</literal> through <literal>December</literal> or
105
-
<literal>Jan</literal> through <literal>Dec</literal>
106
-
</entry>
107
-
</row>
108
-
<row>
109
-
<entry><literal>m</literal> and <literal>n</literal></entry>
110
-
<entry>Numeric representation of a month, with or without leading zeros</entry>
111
-
<entry>
112
-
<literal>01</literal> through <literal>12</literal> or
113
-
<literal>1</literal> through <literal>12</literal>
114
-
</entry>
115
-
</row>
116
-
<row>
117
-
<entry align="center"><emphasis>Year</emphasis></entry>
118
-
<entry>---</entry>
119
-
<entry>---</entry>
120
-
</row>
121
-
<row>
122
-
<entry><literal>Y</literal></entry>
123
-
<entry>A full numeric representation of a year, 4 digits</entry>
124
-
<entry>Examples: <literal>1999</literal> or <literal>2003</literal></entry>
125
-
</row>
126
-
<row>
127
-
<entry><literal>y</literal></entry>
128
-
<entry>
129
-
A two digit representation of a year (which is assumed to be in the
130
-
range 1970-2069, inclusive)
131
-
</entry>
132
-
<entry>
133
-
Examples:
134
-
<literal>99</literal> or <literal>03</literal>
135
-
(which will be interpreted as <literal>1999</literal> and
136
-
<literal>2003</literal>, respectively)
137
-
</entry>
138
-
</row>
139
-
<row>
140
-
<entry align="center"><emphasis>Time</emphasis></entry>
141
-
<entry>---</entry>
142
-
<entry>---</entry>
143
-
</row>
144
-
<row>
145
-
<entry><literal>a</literal> and <literal>A</literal></entry>
146
-
<entry>Ante meridiem and Post meridiem</entry>
147
-
<entry><literal>am</literal> or <literal>pm</literal></entry>
148
-
</row>
149
-
<row>
150
-
<entry><literal>g</literal> and <literal>h</literal></entry>
151
-
<entry>12-hour format of an hour with or without leading zero</entry>
152
-
<entry>
153
-
<literal>1</literal> through <literal>12</literal> or
154
-
<literal>01</literal> through <literal>12</literal>
155
-
</entry>
156
-
</row>
157
-
<row>
158
-
<entry><literal>G</literal> and <literal>H</literal></entry>
159
-
<entry>24-hour format of an hour with or without leading zeros</entry>
160
-
<entry>
161
-
<literal>0</literal> through <literal>23</literal> or
162
-
<literal>00</literal> through <literal>23</literal>
163
-
</entry>
164
-
</row>
165
-
<row>
166
-
<entry><literal>i</literal></entry>
167
-
<entry>Minutes with leading zeros</entry>
168
-
<entry><literal>00</literal> to <literal>59</literal></entry>
169
-
</row>
170
-
<row>
171
-
<entry><literal>s</literal></entry>
172
-
<entry>Seconds, with leading zeros</entry>
173
-
<entry><literal>00</literal> through <literal>59</literal></entry>
174
-
</row>
175
-
<row>
176
-
<entry><literal>v</literal></entry>
177
-
<entry>Milliseconds (up to three digits)</entry>
178
-
<entry>Example: <literal>12</literal>, <literal>345</literal></entry>
179
-
</row>
180
-
<row>
181
-
<entry><literal>u</literal></entry>
182
-
<entry>Microseconds (up to six digits)</entry>
183
-
<entry>Example: <literal>45</literal>, <literal>654321</literal></entry>
184
-
</row>
185
-
<row>
186
-
<entry align="center"><emphasis>Timezone</emphasis></entry>
187
-
<entry>---</entry>
188
-
<entry>---</entry>
189
-
</row>
190
-
<row>
191
-
<entry>
192
-
<literal>e</literal>, <literal>O</literal>,
193
-
<literal>P</literal> and <literal>T</literal>
194
-
</entry>
195
-
<entry>Timezone identifier, or difference to UTC in hours, or
196
-
difference to UTC with colon between hours and minutes, or timezone
197
-
abbreviation</entry>
198
-
<entry>Examples: <literal>UTC</literal>, <literal>GMT</literal>,
199
-
<literal>Atlantic/Azores</literal> or
200
-
<literal>+0200</literal> or <literal>+02:00</literal> or
201
-
<literal>EST</literal>, <literal>MDT</literal>
202
-
</entry>
203
-
</row>
204
-
<row>
205
-
<entry align="center"><emphasis>Full Date/Time</emphasis></entry>
206
-
<entry>---</entry>
207
-
<entry>---</entry>
208
-
</row>
209
-
<row>
210
-
<entry><literal>U</literal></entry>
211
-
<entry>Seconds since the Unix Epoch (January 1 1970 00:00:00 GMT)</entry>
212
-
<entry>Example: <literal>1292177455</literal></entry>
213
-
</row>
214
-
<row>
215
-
<entry align="center"><emphasis>Whitespace and Separators</emphasis></entry>
216
-
<entry>---</entry>
217
-
<entry>---</entry>
218
-
</row>
219
-
<row>
220
-
<entry><literal> </literal> (space)</entry>
221
-
<entry>One space or one tab</entry>
222
-
<entry>Example: <literal> </literal></entry>
223
-
</row>
224
-
<row>
225
-
<entry><literal>#</literal></entry>
226
-
<entry>
227
-
One of the following separation symbol: <literal>;</literal>,
228
-
<literal>:</literal>, <literal>/</literal>, <literal>.</literal>,
229
-
<literal>,</literal>, <literal>-</literal>, <literal>(</literal> or
230
-
<literal>)</literal>
231
-
</entry>
232
-
<entry>Example: <literal>/</literal></entry>
233
-
</row>
234
-
<row>
235
-
<entry>
236
-
<literal>;</literal>,
237
-
<literal>:</literal>, <literal>/</literal>, <literal>.</literal>,
238
-
<literal>,</literal>, <literal>-</literal>, <literal>(</literal> or
239
-
<literal>)</literal>
240
-
</entry>
241
-
<entry>The specified character.</entry>
242
-
<entry>Example: <literal>-</literal></entry>
243
-
</row>
244
-
<row>
245
-
<entry><literal>?</literal></entry>
246
-
<entry>A random byte</entry>
247
-
<entry>Example: <literal>^</literal> (Be aware that for UTF-8
248
-
characters you might need more than one <literal>?</literal>.
249
-
In this case, using <literal>*</literal> is probably what you want
250
-
instead)</entry>
251
-
</row>
252
-
<row>
253
-
<entry><literal>*</literal></entry>
254
-
<entry>Random bytes until the next separator or digit</entry>
255
-
<entry>Example: <literal>*</literal> in <literal>Y-*-d</literal> with
256
-
the string <literal>2009-aWord-08</literal> will match
257
-
<literal>aWord</literal></entry>
258
-
</row>
259
-
<row>
260
-
<entry><literal>!</literal></entry>
261
-
<entry>Resets all fields (year, month, day, hour, minute, second,
262
-
fraction and timezone information) to zero-like values (
263
-
<literal>0</literal> for hour, minute, second and fraction,
264
-
<literal>1</literal> for month and day, <literal>1970</literal>
265
-
for year and <literal>UTC</literal> for timezone information)</entry>
266
-
<entry>Without <literal>!,</literal> all fields will be set to the
267
-
current date and time.</entry>
268
-
</row>
269
-
<row>
270
-
<entry><literal>|</literal></entry>
271
-
<entry>Resets all fields (year, month, day, hour, minute, second,
272
-
fraction and timezone information) to zero-like values if they have
273
-
not been parsed yet</entry>
274
-
<entry><literal>Y-m-d|</literal> will set the year, month and day
275
-
to the information found in the string to parse, and sets the hour,
276
-
minute and second to 0.</entry>
277
-
</row>
278
-
<row>
279
-
<entry><literal>+</literal></entry>
280
-
<entry>If this format specifier is present, trailing data in the
281
-
string will not cause an error, but a warning instead</entry>
282
-
<entry>Use <methodname>DateTime::getLastErrors</methodname> to find out
283
-
whether trailing data was present.</entry>
284
-
</row>
285
-
</tbody>
286
-
</tgroup>
287
-
</table>
288
-
</para>
289
-
<para>
290
-
Unrecognized characters in the format string will cause the
291
-
parsing to fail and an error message is appended to the returned
292
-
structure. You can query error messages with
293
-
<methodname>DateTime::getLastErrors</methodname>.
294
-
</para>
295
-
<para>
296
-
To include literal characters in <parameter>format</parameter>, you have
297
-
to escape them with a backslash (<literal>\</literal>).
298
-
</para>
299
-
<para>
300
-
If <parameter>format</parameter> does not contain the character
301
-
<literal>!</literal> then portions of the generated time which are not
302
-
specified in <parameter>format</parameter> will be set to the current
303
-
system time.
304
-
</para>
305
-
<para>
306
-
If <parameter>format</parameter> contains the
307
-
character <literal>!</literal>, then portions of the generated
308
-
time not provided in <parameter>format</parameter>, as well as
309
-
values to the left-hand side of the <literal>!</literal>, will
310
-
be set to corresponding values from the Unix epoch.
311
-
</para>
312
-
<para>
313
-
The Unix epoch is 1970-01-01 00:00:00 UTC.
314
-
</para>
315
-
</listitem>
316
-
</varlistentry>
317
-
<varlistentry>
318
-
<term><parameter>datetime</parameter></term>
319
-
<listitem>
320
-
<para>
321
-
String representing the time.
322
-
</para>
323
-
</listitem>
324
-
</varlistentry>
325
-
<varlistentry>
326
-
<term><parameter>timezone</parameter></term>
327
-
<listitem>
328
-
<para>
329
-
A <classname>DateTimeZone</classname> object representing the
330
-
desired time zone.
331
-
</para>
332
-
<para>
333
-
If <parameter>timezone</parameter> is omitted or &null; and
334
-
<parameter>datetime</parameter> contains no timezone,
335
-
the current timezone will be used.
336
-
</para>
337
-
<note>
338
-
<para>
339
-
The <parameter>timezone</parameter> parameter
340
-
and the current timezone are ignored when the
341
-
<parameter>datetime</parameter> parameter either
342
-
contains a UNIX timestamp (e.g. <literal>946684800</literal>)
343
-
or specifies a timezone
344
-
(e.g. <literal>2010-01-28T15:00:00+02:00</literal>).
345
-
</para>
346
-
</note>
347
-
</listitem>
348
-
</varlistentry>
349
-
</variablelist>
46
+
<para>
47
+
See <link
48
+
linkend="datetimeimmutable.createfromformat">DateTimeImmutable::createFromFormat</link>.
49
+
</para>
350
50
</refsect1>
351
51

352
52
<refsect1 role="returnvalues">
...
...
@@ -356,120 +56,50 @@
356
56
</para>
357
57
</refsect1>
358
58

359
-
<refsect1 role="changelog">
360
-
&reftitle.changelog;
59
+
<refsect1 role="errors">
60
+
&reftitle.errors;
361
61
<para>
362
-
<informaltable>
363
-
<tgroup cols="2">
364
-
<thead>
365
-
<row>
366
-
<entry>&Version;</entry>
367
-
<entry>&Description;</entry>
368
-
</row>
369
-
</thead>
370
-
<tbody>
371
-
<row>
372
-
<entry>7.3.0</entry>
373
-
<entry>
374
-
The <literal>v</literal> <parameter>format</parameter> specifier has been added.
375
-
</entry>
376
-
</row>
377
-
</tbody>
378
-
</tgroup>
379
-
</informaltable>
62
+
This method throws <exceptionname>ValueError</exceptionname> when the
63
+
<parameter>datetime</parameter> contains NULL-bytes.
380
64
</para>
381
65
</refsect1>
382
66

67
+
<refsect1 role="changelog">
68
+
&reftitle.changelog;
69
+
<informaltable>
70
+
<tgroup cols="2">
71
+
<thead>
72
+
<row>
73
+
<entry>&Version;</entry>
74
+
<entry>&Description;</entry>
75
+
</row>
76
+
</thead>
77
+
<tbody>
78
+
<row>
79
+
<entry>8.0.21, 8.1.8, 8.2.0</entry>
80
+
<entry>
81
+
Now throws <exceptionname>ValueError</exceptionname> when NULL-bytes
82
+
are passed into <parameter>datetime</parameter>, which previously was silently
83
+
ignored.
84
+
</entry>
85
+
</row>
86
+
</tbody>
87
+
</tgroup>
88
+
</informaltable>
89
+
</refsect1>
90
+

383
91
<refsect1 role="examples">
384
92
&reftitle.examples;
385
-
<example>
386
-
<title><function>DateTime::createFromFormat</function> example</title>
387
-
<para>&style.oop;</para>
388
-
<programlisting role="php">
389
-
<![CDATA[
390
-
<?php
391
-
$date = DateTime::createFromFormat('j-M-Y', '15-Feb-2009');
392
-
echo $date->format('Y-m-d');
393
-
?>
394
-
]]>
395
-
</programlisting>
396
-
<para>&style.procedural;</para>
397
-
<programlisting role="php">
398
-
<![CDATA[
399
-
<?php
400
-
$date = date_create_from_format('j-M-Y', '15-Feb-2009');
401
-
echo date_format($date, 'Y-m-d');
402
-
?>
403
-
]]>
404
-
</programlisting>
405
-
&examples.outputs;
406
-
<screen>
407
-
<![CDATA[
408
-
2009-02-15
409
-
]]>
410
-
</screen>
411
-
</example>
412
-
<example>
413
-
<title>Intricacies of <function>DateTime::createFromFormat</function></title>
414
-
<programlisting role="php">
415
-
<![CDATA[
416
-
<?php
417
-
echo 'Current time: ' . date('Y-m-d H:i:s') . "\n";
418
-

419
-
$format = 'Y-m-d';
420
-
$date = DateTime::createFromFormat($format, '2009-02-15');
421
-
echo "Format: $format; " . $date->format('Y-m-d H:i:s') . "\n";
422
-

423
-
$format = 'Y-m-d H:i:s';
424
-
$date = DateTime::createFromFormat($format, '2009-02-15 15:16:17');
425
-
echo "Format: $format; " . $date->format('Y-m-d H:i:s') . "\n";
426
-

427
-
$format = 'Y-m-!d H:i:s';
428
-
$date = DateTime::createFromFormat($format, '2009-02-15 15:16:17');
429
-
echo "Format: $format; " . $date->format('Y-m-d H:i:s') . "\n";
430
-

431
-
$format = '!d';
432
-
$date = DateTime::createFromFormat($format, '15');
433
-
echo "Format: $format; " . $date->format('Y-m-d H:i:s') . "\n";
434
-
?>
435
-
]]>
436
-
</programlisting>
437
-
&example.outputs.similar;
438
-
<screen>
439
-
<![CDATA[
440
-
Current time: 2010-04-23 10:29:35
441
-
Format: Y-m-d; 2009-02-15 10:29:35
442
-
Format: Y-m-d H:i:s; 2009-02-15 15:16:17
443
-
Format: Y-m-!d H:i:s; 1970-01-15 15:16:17
444
-
Format: !d; 1970-01-15 00:00:00
445
-
]]>
446
-
</screen>
447
-
</example>
448
-
<example>
449
-
<title>Format string with literal characters</title>
450
-
<programlisting role="php">
451
-
<![CDATA[
452
-
<?php
453
-
echo DateTime::createFromFormat('H\h i\m s\s','23h 15m 03s')->format('H:i:s');
454
-
?>
455
-
]]>
456
-
</programlisting>
457
-
&example.outputs.similar;
458
-
<screen>
459
-
<![CDATA[
460
-
23:15:03
461
-
]]>
462
-
</screen>
463
-
</example>
93
+
<para>
94
+
For an extensive set of examples, see <link
95
+
linkend="datetimeimmutable.createfromformat">DateTimeImmutable::createFromFormat</link>.
96
+
</para>
464
97
</refsect1>
465
98

466
99
<refsect1 role="seealso">
467
100
&reftitle.seealso;
468
101
<simplelist>
469
-
<member><function>DateTime::__construct</function></member>
470
-
<member><function>DateTime::getLastErrors</function></member>
471
-
<member><function>checkdate</function></member>
472
-
<member><function>strptime</function></member>
102
+
<member><function>DateTimeImmutable::createFromFormat</function></member>
473
103
</simplelist>
474
104
</refsect1>
475
105
</refentry>
476
106