reference/datetime/dateperiod/construct.xml
7d81260767f008218ffd338b365cfa3d10eb3d15
...
...
@@ -9,28 +9,46 @@
9
9

10
10
<refsect1 role="description">
11
11
&reftitle.description;
12
-
<constructorsynopsis role="oop">
12
+
<constructorsynopsis role="DatePeriod">
13
13
<modifier>public</modifier> <methodname>DatePeriod::__construct</methodname>
14
14
<methodparam><type>DateTimeInterface</type><parameter>start</parameter></methodparam>
15
15
<methodparam><type>DateInterval</type><parameter>interval</parameter></methodparam>
16
16
<methodparam><type>int</type><parameter>recurrences</parameter></methodparam>
17
17
<methodparam choice="opt"><type>int</type><parameter>options</parameter><initializer>0</initializer></methodparam>
18
18
</constructorsynopsis>
19
-
<constructorsynopsis role="oop">
19
+
<constructorsynopsis role="DatePeriod">
20
20
<modifier>public</modifier> <methodname>DatePeriod::__construct</methodname>
21
21
<methodparam><type>DateTimeInterface</type><parameter>start</parameter></methodparam>
22
22
<methodparam><type>DateInterval</type><parameter>interval</parameter></methodparam>
23
23
<methodparam><type>DateTimeInterface</type><parameter>end</parameter></methodparam>
24
24
<methodparam choice="opt"><type>int</type><parameter>options</parameter><initializer>0</initializer></methodparam>
25
25
</constructorsynopsis>
26
-
<constructorsynopsis role="oop">
27
-
<modifier>public</modifier> <methodname>DatePeriod::__construct</methodname>
28
-
<methodparam><type>string</type><parameter>isostr</parameter></methodparam>
29
-
<methodparam choice="opt"><type>int</type><parameter>options</parameter><initializer>0</initializer></methodparam>
30
-
</constructorsynopsis>
26
+
<warning>
27
+
<constructorsynopsis role="DatePeriod">
28
+
<modifier>public</modifier> <methodname>DatePeriod::__construct</methodname>
29
+
<methodparam><type>string</type><parameter>isostr</parameter></methodparam>
30
+
<methodparam choice="opt"><type>int</type><parameter>options</parameter><initializer>0</initializer></methodparam>
31
+
</constructorsynopsis>
32
+
<simpara>
33
+
This variant of the constructor has been deprecated, use
34
+
<methodname>DatePeriod::createFromISO8601String</methodname> instead.
35
+
</simpara>
36
+
</warning>
31
37
<para>
32
38
Creates a new DatePeriod object.
33
39
</para>
40
+
<para>
41
+
<classname>DatePeriod</classname> objects can be used as an iterator to
42
+
generate a number of <classname>DateTimeImmutable</classname> or
43
+
<classname>DateTime</classname> object from a <parameter>start</parameter>
44
+
date, a <parameter>interval</parameter>, and an <parameter>end</parameter>
45
+
date or the number of <parameter>recurrences</parameter>.
46
+
</para>
47
+
<para>
48
+
The class of returned objects is equivalent to the
49
+
<classname>DateTimeImmutable</classname> or <classname>DateTime</classname>
50
+
ancestor class of the <parameter>start</parameter> object.
51
+
</para>
34
52
</refsect1>
35
53

36
54
<refsect1 role="parameters">
...
...
@@ -41,7 +59,7 @@
41
59
<term><parameter>start</parameter></term>
42
60
<listitem>
43
61
<para>
44
-
The start date of the period.
62
+
The start date of the period. Included by default in the result set.
45
63
</para>
46
64
</listitem>
47
65
</varlistentry>
...
...
@@ -57,7 +75,9 @@
57
75
<term><parameter>recurrences</parameter></term>
58
76
<listitem>
59
77
<para>
60
-
The number of recurrences. Must be greater than <literal>0</literal>.
78
+
The number of recurrences. The number of returned results is
79
+
one higher than this, as the start date is included in the result set
80
+
by default. Must be greater than <literal>0</literal>.
61
81
</para>
62
82
</listitem>
63
83
</varlistentry>
...
...
@@ -65,7 +85,7 @@
65
85
<term><parameter>end</parameter></term>
66
86
<listitem>
67
87
<para>
68
-
The end date of the period.
88
+
The end date of the period. Excluded by default from the result set.
69
89
</para>
70
90
</listitem>
71
91
</varlistentry>
...
...
@@ -73,26 +93,61 @@
73
93
<term><parameter>isostr</parameter></term>
74
94
<listitem>
75
95
<para>
76
-
An <link
77
-
xlink:href="&url.iso-8601.repeating_intervals;">ISO 8601 repeating interval specification</link>.
78
-
Zero occurrences (<literal>R0/</literal>) are not supported.
96
+
A subset of the <link
97
+
xlink:href="&url.iso-8601.repeating_intervals;">ISO 8601 repeating
98
+
interval specification</link>.
99
+
</para>
100
+
<para>
101
+
Examples of some ISO 8601 interval specification features that PHP does
102
+
not support are:
79
103
</para>
104
+
<orderedlist>
105
+
<listitem>
106
+
<simpara>
107
+
zero occurrences (<literal>R0/</literal>)
108
+
</simpara>
109
+
</listitem>
110
+
<listitem>
111
+
<simpara>
112
+
time offsets other than UTC (<literal>Z</literal>), such as <literal>+02:00</literal>.
113
+
</simpara>
114
+
</listitem>
115
+
</orderedlist>
80
116
</listitem>
81
117
</varlistentry>
82
118
<varlistentry>
83
119
<term><parameter>options</parameter></term>
84
120
<listitem>
85
121
<para>
86
-
Can be set to <constant>DatePeriod::EXCLUDE_START_DATE</constant> to
122
+
A bit field which can be used to control certain behaviour with start-
123
+
and end- dates.
124
+
</para>
125
+
<para>
126
+
With <constant>DatePeriod::EXCLUDE_START_DATE</constant> you
87
127
exclude the start date from the set of recurring dates within the
88
128
period.
89
129
</para>
130
+
<para>
131
+
With <constant>DatePeriod::INCLUDE_END_DATE</constant> you
132
+
include the end date in the set of recurring dates within the
133
+
period.
134
+
</para>
90
135
</listitem>
91
136
</varlistentry>
92
137
</variablelist>
93
138
</para>
94
139
</refsect1>
95
140

141
+
<refsect1 role="errors">
142
+
&reftitle.errors;
143
+
<para>
144
+
Throws an <classname>DateMalformedPeriodStringException</classname> when
145
+
the <parameter>isostr</parameter> cannot be parsed as a valid ISO 8601
146
+
period. Prior to PHP 8.3, this was
147
+
<exceptionname>Exception</exceptionname>.
148
+
</para>
149
+
</refsect1>
150
+

96
151
<refsect1 role="changelog">
97
152
&reftitle.changelog;
98
153
<para>
...
...
@@ -106,6 +161,20 @@
106
161
</thead>
107
162
<tbody>
108
163
<row>
164
+
<entry>8.3.0</entry>
165
+
<entry>
166
+
Now throws
167
+
<exceptionname>DateMalformedPeriodStringException</exceptionname>
168
+
instead of <exceptionname>Exception</exceptionname>.
169
+
</entry>
170
+
</row>
171
+
<row>
172
+
<entry>8.2.0</entry>
173
+
<entry>
174
+
The <constant>DatePeriod::INCLUDE_END_DATE</constant> constant has been added.
175
+
</entry>
176
+
</row>
177
+
<row>
109
178
<entry>7.2.19, 7.3.6, 7.4.0</entry>
110
179
<entry>
111
180
<parameter>recurrences</parameter> must be greater than <literal>0</literal> now.
...
...
@@ -189,6 +258,43 @@ foreach ($period as $date) {
189
258
</screen>
190
259
</example>
191
260
</para>
261
+
<para>
262
+
<example>
263
+
<title>DatePeriod example showing all last Thursdays in a year</title>
264
+
<programlisting role="php">
265
+
<![CDATA[
266
+
<?php
267
+
$begin = new DateTime('2021-12-31');
268
+
$end = new DateTime('2022-12-31 23:59:59');
269
+

270
+
$interval = DateInterval::createFromDateString('last thursday of next month');
271
+
$period = new DatePeriod($begin, $interval, $end, DatePeriod::EXCLUDE_START_DATE);
272
+

273
+
foreach ($period as $dt) {
274
+
echo $dt->format('l Y-m-d'), "\n";
275
+
}
276
+
?>
277
+
]]>
278
+
</programlisting>
279
+
&example.outputs;
280
+
<screen>
281
+
<![CDATA[
282
+
Thursday 2022-01-27
283
+
Thursday 2022-02-24
284
+
Thursday 2022-03-31
285
+
Thursday 2022-04-28
286
+
Thursday 2022-05-26
287
+
Thursday 2022-06-30
288
+
Thursday 2022-07-28
289
+
Thursday 2022-08-25
290
+
Thursday 2022-09-29
291
+
Thursday 2022-10-27
292
+
Thursday 2022-11-24
293
+
Thursday 2022-12-29
294
+
]]>
295
+
</screen>
296
+
</example>
297
+
</para>
192
298
</refsect1>
193
299

194
300
<refsect1 role="notes">
195
301