reference/datetime/dateinterval/createfromdatestring.xml
bd1ae73f4a88404c9a3015940c66a85aaeec5889
...
...
@@ -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">
13
-
<modifier>public</modifier> <modifier>static</modifier> <type>DateInterval</type><methodname>DateInterval::createFromDateString</methodname>
14
-
<methodparam><type>string</type><parameter>time</parameter></methodparam>
11
+
<para>&style.oop;</para>
12
+
<methodsynopsis role="DateInterval">
13
+
<modifier>public</modifier> <modifier>static</modifier> <type class="union"><type>DateInterval</type><type>false</type></type><methodname>DateInterval::createFromDateString</methodname>
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 constructor.
35
46
</para>
36
47
</listitem>
37
48
</varlistentry>
...
...
@@ -39,6 +50,37 @@
39
50
</para>
40
51
</refsect1>
41
52

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

60
+
<refsect1 role="changelog">
61
+
&reftitle.changelog;
62
+
<informaltable>
63
+
<tgroup cols="2">
64
+
<thead>
65
+
<row>
66
+
<entry>&Version;</entry>
67
+
<entry>&Description;</entry>
68
+
</row>
69
+
</thead>
70
+
<tbody>
71
+
<row>
72
+
<entry>8.2.0</entry>
73
+
<entry>
74
+
Only the <literal>from_string</literal> and
75
+
<literal>date_string</literal> properties will be visible when a
76
+
<classname>DateInterval</classname> is created with this method.
77
+
</entry>
78
+
</row>
79
+
</tbody>
80
+
</tgroup>
81
+
</informaltable>
82
+
</refsect1>
83
+

42
84
<refsect1 role="examples">
43
85
&reftitle.examples;
44
86
<para>
...
...
@@ -73,17 +115,135 @@ $i = DateInterval::createFromDateString('3600 seconds');
73
115
</programlisting>
74
116
</example>
75
117
</para>
76
-
</refsect1>
118
+
<para>
119
+
<example>
120
+
<title>Parsing combinations and negative intervals</title>
121
+
<programlisting role="php">
122
+
<![CDATA[
123
+
<?php
124
+
$i = DateInterval::createFromDateString('62 weeks + 1 day + 2 weeks + 2 hours + 70 minutes');
125
+
echo $i->format('%d %h %i'), "\n";
77
126

78
-
<refsect1 role="returnvalues">
79
-
&reftitle.returnvalues;
127
+
$i = DateInterval::createFromDateString('1 year - 10 days');
128
+
echo $i->format('%y %d'), "\n";
129
+
?>
130
+
]]>
131
+
</programlisting>
132
+
&example.outputs;
133
+
<screen role="shell">
134
+
449 2 70
135
+
1 -10
136
+
</screen>
137
+
</example>
138
+
</para>
80
139
<para>
81
-
Returns a new <classname>DateInterval</classname> instance.
140
+
<example>
141
+
<title>Parsing special relative date intervals</title>
142
+
<programlisting role="php">
143
+
<![CDATA[
144
+
<?php
145
+
$i = DateInterval::createFromDateString('last day of next month');
146
+
var_dump($i);
147
+

148
+
$i = DateInterval::createFromDateString('last weekday');
149
+
var_dump($i);
150
+
]]>
151
+
</programlisting>
152
+
&example.outputs.82;
153
+
<screen role="php">
154
+
<![CDATA[
155
+
object(DateInterval)#1 (2) {
156
+
["from_string"]=>
157
+
bool(true)
158
+
["date_string"]=>
159
+
string(22) "last day of next month"
160
+
}
161
+
object(DateInterval)#2 (2) {
162
+
["from_string"]=>
163
+
bool(true)
164
+
["date_string"]=>
165
+
string(12) "last weekday"
166
+
}
167
+
]]>
168
+
</screen>
169
+
&example.outputs.8.similar;
170
+
<screen role="php">
171
+
<![CDATA[
172
+
object(DateInterval)#1 (16) {
173
+
["y"]=>
174
+
int(0)
175
+
["m"]=>
176
+
int(1)
177
+
["d"]=>
178
+
int(0)
179
+
["h"]=>
180
+
int(0)
181
+
["i"]=>
182
+
int(0)
183
+
["s"]=>
184
+
int(0)
185
+
["f"]=>
186
+
float(0)
187
+
["weekday"]=>
188
+
int(0)
189
+
["weekday_behavior"]=>
190
+
int(0)
191
+
["first_last_day_of"]=>
192
+
int(2)
193
+
["invert"]=>
194
+
int(0)
195
+
["days"]=>
196
+
bool(false)
197
+
["special_type"]=>
198
+
int(0)
199
+
["special_amount"]=>
200
+
int(0)
201
+
["have_weekday_relative"]=>
202
+
int(0)
203
+
["have_special_relative"]=>
204
+
int(0)
205
+
}
206
+
object(DateInterval)#2 (16) {
207
+
["y"]=>
208
+
int(0)
209
+
["m"]=>
210
+
int(0)
211
+
["d"]=>
212
+
int(0)
213
+
["h"]=>
214
+
int(0)
215
+
["i"]=>
216
+
int(0)
217
+
["s"]=>
218
+
int(0)
219
+
["f"]=>
220
+
float(0)
221
+
["weekday"]=>
222
+
int(0)
223
+
["weekday_behavior"]=>
224
+
int(0)
225
+
["first_last_day_of"]=>
226
+
int(0)
227
+
["invert"]=>
228
+
int(0)
229
+
["days"]=>
230
+
bool(false)
231
+
["special_type"]=>
232
+
int(1)
233
+
["special_amount"]=>
234
+
int(-1)
235
+
["have_weekday_relative"]=>
236
+
int(0)
237
+
["have_special_relative"]=>
238
+
int(1)
239
+
}
240
+
]]>
241
+
</screen>
242
+
</example>
82
243
</para>
83
244
</refsect1>
84
245

85
246
</refentry>
86
-

87
247
<!-- Keep this comment at the end of the file
88
248
Local variables:
89
249
mode: sgml
90
250