reference/datetime/datetime/createfromformat.xml
4d13f5e4b45f699eb855a5e84736aeda2ebd142a
...
...
@@ -1,6 +1,5 @@
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>
...
...
@@ -11,332 +10,43 @@
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></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></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
27
Returns a new DateTime object representing the date and time specified by the
29
-
<parameter>time</parameter> string, which was formatted in the given
28
+
<parameter>datetime</parameter> string, which was formatted in the given
30
29
<parameter>format</parameter>.
31
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>
32
42
</refsect1>
33
43

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

342
52
<refsect1 role="returnvalues">
...
...
@@ -346,124 +56,53 @@
346
56
</para>
347
57
</refsect1>
348
58

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

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

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

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

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

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

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

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