reference/datetime/datetime/createfromformat.xml
4d13f5e4b45f699eb855a5e84736aeda2ebd142a
...
...
@@ -1,340 +1,52 @@
1
1
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
-

4
3
<refentry xml:id="datetime.createfromformat" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
5
4
<refnamediv>
6
5
<refname>DateTime::createFromFormat</refname>
7
6
<refname>date_create_from_format</refname>
8
-
<refpurpose>Returns new DateTime object formatted according to the specified format</refpurpose>
7
+
<refpurpose>Parses a time string according to a specified format</refpurpose>
9
8
</refnamediv>
10
9

11
10
<refsect1 role="description">
12
11
&reftitle.description;
13
12
<para>&style.oop;</para>
14
-
<methodsynopsis role="oop">
15
-
<modifier>public</modifier> <modifier>static</modifier> <type>DateTime</type><methodname>DateTime::createFromFormat</methodname>
13
+
<methodsynopsis role="DateTime">
14
+
<modifier>public</modifier> <modifier>static</modifier> <type class="union"><type>DateTime</type><type>false</type></type><methodname>DateTime::createFromFormat</methodname>
16
15
<methodparam><type>string</type><parameter>format</parameter></methodparam>
17
-
<methodparam><type>string</type><parameter>time</parameter></methodparam>
18
-
<methodparam choice="opt"><type>DateTimeZone</type><parameter>timezone</parameter><initializer>date_default_timezone_get()</initializer></methodparam>
16
+
<methodparam><type>string</type><parameter>datetime</parameter></methodparam>
17
+
<methodparam choice="opt"><type class="union"><type>DateTimeZone</type><type>null</type></type><parameter>timezone</parameter><initializer>&null;</initializer></methodparam>
19
18
</methodsynopsis>
20
19
<para>&style.procedural;</para>
21
-
<methodsynopsis role="procedural">
22
-
<type>DateTime</type><methodname>date_create_from_format</methodname>
20
+
<methodsynopsis>
21
+
<type class="union"><type>DateTime</type><type>false</type></type><methodname>date_create_from_format</methodname>
23
22
<methodparam><type>string</type><parameter>format</parameter></methodparam>
24
-
<methodparam><type>string</type><parameter>time</parameter></methodparam>
25
-
<methodparam choice="opt"><type>DateTimeZone</type><parameter>timezone</parameter><initializer>date_default_timezone_get()</initializer></methodparam>
23
+
<methodparam><type>string</type><parameter>datetime</parameter></methodparam>
24
+
<methodparam choice="opt"><type class="union"><type>DateTimeZone</type><type>null</type></type><parameter>timezone</parameter><initializer>&null;</initializer></methodparam>
26
25
</methodsynopsis>
27
26
<para>
28
-
Returns new DateTime object formatted according to the specified format.
27
+
Returns a new DateTime object representing the date and time specified by the
28
+
<parameter>datetime</parameter> string, which was formatted in the given
29
+
<parameter>format</parameter>.
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.
29
41
</para>
30
42
</refsect1>
31
43

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

340
52
<refsect1 role="returnvalues">
...
...
@@ -344,124 +56,53 @@
344
56
</para>
345
57
</refsect1>
346
58

347
-
<refsect1 role="changelog">
348
-
&reftitle.changelog;
59
+
<refsect1 role="errors">
60
+
&reftitle.errors;
349
61
<para>
350
-
<informaltable>
351
-
<tgroup cols="2">
352
-
<thead>
353
-
<row>
354
-
<entry>&Version;</entry>
355
-
<entry>&Description;</entry>
356
-
</row>
357
-
</thead>
358
-
<tbody>
359
-
<row>
360
-
<entry>5.3.9</entry>
361
-
<entry>
362
-
The + <parameter>format</parameter> specifier has been added.
363
-
</entry>
364
-
</row>
365
-
</tbody>
366
-
</tgroup>
367
-
</informaltable>
62
+
This method throws <exceptionname>ValueError</exceptionname> when the
63
+
<parameter>datetime</parameter> contains NULL-bytes.
368
64
</para>
369
65
</refsect1>
370
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
+

371
91
<refsect1 role="examples">
372
92
&reftitle.examples;
373
-
<example>
374
-
<title><function>DateTime::createFromFormat</function> example</title>
375
-
<para>&style.oop;</para>
376
-
<programlisting role="php">
377
-
<![CDATA[
378
-
<?php
379
-
$date = DateTime::createFromFormat('j-M-Y', '15-Feb-2009');
380
-
echo $date->format('Y-m-d');
381
-
?>
382
-
]]>
383
-
</programlisting>
384
-
<para>&style.procedural;</para>
385
-
<programlisting role="php">
386
-
<![CDATA[
387
-
<?php
388
-
$date = date_create_from_format('j-M-Y', '15-Feb-2009');
389
-
echo date_format($date, 'Y-m-d');
390
-
?>
391
-
]]>
392
-
</programlisting>
393
-
&examples.outputs;
394
-
<screen>
395
-
<![CDATA[
396
-
2009-02-15
397
-
]]>
398
-
</screen>
399
-
</example>
400
-
<example>
401
-
<title>Intricacies of <function>DateTime::createFromFormat</function></title>
402
-
<programlisting role="php">
403
-
<![CDATA[
404
-
<?php
405
-
echo 'Current time: ' . date('Y-m-d H:i:s') . "\n";
406
-

407
-
$format = 'Y-m-d';
408
-
$date = DateTime::createFromFormat($format, '2009-02-15');
409
-
echo "Format: $format; " . $date->format('Y-m-d H:i:s') . "\n";
410
-

411
-
$format = 'Y-m-d H:i:s';
412
-
$date = DateTime::createFromFormat($format, '2009-02-15 15:16:17');
413
-
echo "Format: $format; " . $date->format('Y-m-d H:i:s') . "\n";
414
-

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

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

454
99
<refsect1 role="seealso">
455
100
&reftitle.seealso;
456
101
<simplelist>
457
-
<member><function>DateTime::__construct</function></member>
458
-
<member><function>DateTime::getLastErrors</function></member>
459
-
<member><function>checkdate</function></member>
460
-
<member><function>strptime</function></member>
102
+
<member><function>DateTimeImmutable::createFromFormat</function></member>
461
103
</simplelist>
462
104
</refsect1>
463
105
</refentry>
464
-

465
106
<!-- Keep this comment at the end of the file
466
107
Local variables:
467
108
mode: sgml
468
109