reference/datetime/dateinterval/createfromdatestring.xml
34f483426930c25870b4c5455157e7a759e0053c
...
...
@@ -1,6 +1,5 @@
1
1
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
-

4
3
<refentry xml:id="dateinterval.createfromdatestring" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
5
4
<refnamediv>
6
5
<refname>DateInterval::createFromDateString</refname>
...
...
@@ -9,13 +8,21 @@
9
8

10
9
<refsect1 role="description">
11
10
&reftitle.description;
12
-
<methodsynopsis role="oop">
11
+
<para>&style.oop;</para>
12
+
<methodsynopsis role="DateInterval">
13
13
<modifier>public</modifier> <modifier>static</modifier> <type>DateInterval</type><methodname>DateInterval::createFromDateString</methodname>
14
-
<methodparam><type>string</type><parameter>time</parameter></methodparam>
14
+
<methodparam><type>string</type><parameter>datetime</parameter></methodparam>
15
+
</methodsynopsis>
16
+
<para>&style.procedural;</para>
17
+
<methodsynopsis>
18
+
<type class="union"><type>DateInterval</type><type>false</type></type><methodname>date_interval_create_from_date_string</methodname>
19
+
<methodparam><type>string</type><parameter>datetime</parameter></methodparam>
15
20
</methodsynopsis>
16
21
<para>
17
-
Uses the normal date parsers and sets up a DateInterval from the relative
18
-
parts of the parsed string.
22
+
Uses the date/time parsers as used in the
23
+
<classname>DateTimeImmutable</classname> constructor to create a
24
+
<classname>DateInterval</classname> from the relative parts of the parsed
25
+
string.
19
26
</para>
20
27
</refsect1>
21
28

...
...
@@ -24,14 +31,18 @@
24
31
<para>
25
32
<variablelist>
26
33
<varlistentry>
27
-
<term><parameter>time</parameter></term>
34
+
<term><parameter>datetime</parameter></term>
28
35
<listitem>
29
36
<para>
30
-
A date with relative parts. Specifically, the
31
-
<link linkend="datetime.formats.relative">relative formats</link>
32
-
supported by the parser used for <function>strtotime</function> and
33
-
<classname>DateTime</classname> will be used to construct the
34
-
DateInterval.
37
+
A date with relative parts. Specifically, the <link
38
+
linkend="datetime.formats.relative">relative formats</link> supported
39
+
by the parser used for <classname>DateTimeImmutable</classname>,
40
+
<classname>DateTime</classname>, and <function>strtotime</function>
41
+
will be used to construct the DateInterval.
42
+
</para>
43
+
<para>
44
+
To use an ISO-8601 format string like <literal>P7D</literal>, you must
45
+
use the <methodname>DateInterval::__construct</methodname>.
35
46
</para>
36
47
</listitem>
37
48
</varlistentry>
...
...
@@ -39,6 +50,57 @@
39
50
</para>
40
51
</refsect1>
41
52

53
+
<refsect1 role="returnvalues">
54
+
&reftitle.returnvalues;
55
+
<para>
56
+
Returns <classname>DateInterval</classname> on success.
57
+
&return.falseforfailure.style.procedural;
58
+
</para>
59
+
</refsect1>
60
+

61
+
<refsect1 role="errors">
62
+
&reftitle.errors;
63
+
<para>
64
+
Object Oriented API only: If an invalid Date/Time string is passed,
65
+
<exceptionname>DateMalformedStringException</exceptionname> is thrown.
66
+
</para>
67
+
</refsect1>
68
+

69
+
<refsect1 role="changelog">
70
+
&reftitle.changelog;
71
+
<informaltable>
72
+
<tgroup cols="2">
73
+
<thead>
74
+
<row>
75
+
<entry>&Version;</entry>
76
+
<entry>&Description;</entry>
77
+
</row>
78
+
</thead>
79
+
<tbody>
80
+
<row>
81
+
<entry>8.3.0</entry>
82
+
<entry>
83
+
<methodname>DateInterval::createFromDateString</methodname> now throws
84
+
<exceptionname>DateMalformedStringException</exceptionname> if an
85
+
invalid string is passed. Previously, it returned <literal>false</literal>,
86
+
and a warning was emitted.
87
+
<function>date_interval_create_from_date_string</function> has not been
88
+
changed.
89
+
</entry>
90
+
</row>
91
+
<row>
92
+
<entry>8.2.0</entry>
93
+
<entry>
94
+
Only the <literal>from_string</literal> and
95
+
<literal>date_string</literal> properties will be visible when a
96
+
<classname>DateInterval</classname> is created with this method.
97
+
</entry>
98
+
</row>
99
+
</tbody>
100
+
</tgroup>
101
+
</informaltable>
102
+
</refsect1>
103
+

42
104
<refsect1 role="examples">
43
105
&reftitle.examples;
44
106
<para>
...
...
@@ -73,17 +135,135 @@ $i = DateInterval::createFromDateString('3600 seconds');
73
135
</programlisting>
74
136
</example>
75
137
</para>
76
-
</refsect1>
138
+
<para>
139
+
<example>
140
+
<title>Parsing combinations and negative intervals</title>
141
+
<programlisting role="php">
142
+
<![CDATA[
143
+
<?php
144
+
$i = DateInterval::createFromDateString('62 weeks + 1 day + 2 weeks + 2 hours + 70 minutes');
145
+
echo $i->format('%d %h %i'), "\n";
77
146

78
-
<refsect1 role="returnvalues">
79
-
&reftitle.returnvalues;
147
+
$i = DateInterval::createFromDateString('1 year - 10 days');
148
+
echo $i->format('%y %d'), "\n";
149
+
?>
150
+
]]>
151
+
</programlisting>
152
+
&example.outputs;
153
+
<screen role="shell">
154
+
449 2 70
155
+
1 -10
156
+
</screen>
157
+
</example>
158
+
</para>
80
159
<para>
81
-
Returns a new <classname>DateInterval</classname> instance.
160
+
<example>
161
+
<title>Parsing special relative date intervals</title>
162
+
<programlisting role="php">
163
+
<![CDATA[
164
+
<?php
165
+
$i = DateInterval::createFromDateString('last day of next month');
166
+
var_dump($i);
167
+

168
+
$i = DateInterval::createFromDateString('last weekday');
169
+
var_dump($i);
170
+
]]>
171
+
</programlisting>
172
+
&example.outputs.82;
173
+
<screen role="php">
174
+
<![CDATA[
175
+
object(DateInterval)#1 (2) {
176
+
["from_string"]=>
177
+
bool(true)
178
+
["date_string"]=>
179
+
string(22) "last day of next month"
180
+
}
181
+
object(DateInterval)#2 (2) {
182
+
["from_string"]=>
183
+
bool(true)
184
+
["date_string"]=>
185
+
string(12) "last weekday"
186
+
}
187
+
]]>
188
+
</screen>
189
+
&example.outputs.8.similar;
190
+
<screen role="php">
191
+
<![CDATA[
192
+
object(DateInterval)#1 (16) {
193
+
["y"]=>
194
+
int(0)
195
+
["m"]=>
196
+
int(1)
197
+
["d"]=>
198
+
int(0)
199
+
["h"]=>
200
+
int(0)
201
+
["i"]=>
202
+
int(0)
203
+
["s"]=>
204
+
int(0)
205
+
["f"]=>
206
+
float(0)
207
+
["weekday"]=>
208
+
int(0)
209
+
["weekday_behavior"]=>
210
+
int(0)
211
+
["first_last_day_of"]=>
212
+
int(2)
213
+
["invert"]=>
214
+
int(0)
215
+
["days"]=>
216
+
bool(false)
217
+
["special_type"]=>
218
+
int(0)
219
+
["special_amount"]=>
220
+
int(0)
221
+
["have_weekday_relative"]=>
222
+
int(0)
223
+
["have_special_relative"]=>
224
+
int(0)
225
+
}
226
+
object(DateInterval)#2 (16) {
227
+
["y"]=>
228
+
int(0)
229
+
["m"]=>
230
+
int(0)
231
+
["d"]=>
232
+
int(0)
233
+
["h"]=>
234
+
int(0)
235
+
["i"]=>
236
+
int(0)
237
+
["s"]=>
238
+
int(0)
239
+
["f"]=>
240
+
float(0)
241
+
["weekday"]=>
242
+
int(0)
243
+
["weekday_behavior"]=>
244
+
int(0)
245
+
["first_last_day_of"]=>
246
+
int(0)
247
+
["invert"]=>
248
+
int(0)
249
+
["days"]=>
250
+
bool(false)
251
+
["special_type"]=>
252
+
int(1)
253
+
["special_amount"]=>
254
+
int(-1)
255
+
["have_weekday_relative"]=>
256
+
int(0)
257
+
["have_special_relative"]=>
258
+
int(1)
259
+
}
260
+
]]>
261
+
</screen>
262
+
</example>
82
263
</para>
83
264
</refsect1>
84
265

85
266
</refentry>
86
-

87
267
<!-- Keep this comment at the end of the file
88
268
Local variables:
89
269
mode: sgml
90
270



Translation status