reference/datetime/dateperiod.xml
14767af0f05dffa6fdb9b49e1a1f4e9ca7022a60
...
...
@@ -1,6 +1,5 @@
1
1
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
-

4
3
<phpdoc:classref xml:id="class.dateperiod" xmlns:phpdoc="http://php.net/ns/phpdoc" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
5
4

6
5
<title>The DatePeriod class</title>
...
...
@@ -25,73 +24,81 @@
25
24
&reftitle.classsynopsis;
26
25

27
26
<!-- {{{ Synopsis -->
28
-
<classsynopsis>
29
-
<ooclass><classname>DatePeriod</classname></ooclass>
30
-

31
-
<!-- {{{ Class synopsis -->
32
-
<classsynopsisinfo>
33
-
<ooclass>
34
-
<classname>DatePeriod</classname>
35
-
</ooclass>
36
-
37
-
<oointerface>
38
-
<interfacename>Traversable</interfacename>
39
-
</oointerface>
40
-
</classsynopsisinfo>
41
-
<!-- }}} -->
27
+
<classsynopsis class="class">
28
+
<ooclass>
29
+
<classname>DatePeriod</classname>
30
+
</ooclass>
31
+

32
+
<oointerface>
33
+
<modifier>implements</modifier>
34
+
<interfacename>IteratorAggregate</interfacename>
35
+
</oointerface>
36
+

42
37
<classsynopsisinfo role="comment">&Constants;</classsynopsisinfo>
43
38
<fieldsynopsis>
39
+
<modifier>public</modifier>
44
40
<modifier>const</modifier>
45
-
<type>integer</type>
41
+
<type>int</type>
46
42
<varname linkend="dateperiod.constants.exclude-start-date">DatePeriod::EXCLUDE_START_DATE</varname>
47
-
<initializer>1</initializer>
43
+
</fieldsynopsis>
44
+
<fieldsynopsis>
45
+
<modifier>public</modifier>
46
+
<modifier>const</modifier>
47
+
<type>int</type>
48
+
<varname linkend="dateperiod.constants.include-end-date">DatePeriod::INCLUDE_END_DATE</varname>
48
49
</fieldsynopsis>
49
50

50
51
<classsynopsisinfo role="comment">&Properties;</classsynopsisinfo>
51
52
<fieldsynopsis>
52
53
<modifier>public</modifier>
53
-
<type>integer</type>
54
-
<varname linkend="dateperiod.props.recurrences">recurrences</varname>
54
+
<modifier>readonly</modifier>
55
+
<type class="union"><type>DateTimeInterface</type><type>null</type></type>
56
+
<varname linkend="dateperiod.props.start">start</varname>
57
+
</fieldsynopsis>
58
+
<fieldsynopsis>
59
+
<modifier>public</modifier>
60
+
<modifier>readonly</modifier>
61
+
<type class="union"><type>DateTimeInterface</type><type>null</type></type>
62
+
<varname linkend="dateperiod.props.current">current</varname>
55
63
</fieldsynopsis>
56
64
<fieldsynopsis>
57
65
<modifier>public</modifier>
58
-
<type>boolean</type>
59
-
<varname linkend="dateperiod.props.include_start_date">include_start_date</varname>
66
+
<modifier>readonly</modifier>
67
+
<type class="union"><type>DateTimeInterface</type><type>null</type></type>
68
+
<varname linkend="dateperiod.props.end">end</varname>
60
69
</fieldsynopsis>
61
70
<fieldsynopsis>
62
71
<modifier>public</modifier>
63
-
<type>DateTimeInterface</type>
64
-
<varname linkend="dateperiod.props.start">start</varname>
72
+
<modifier>readonly</modifier>
73
+
<type class="union"><type>DateInterval</type><type>null</type></type>
74
+
<varname linkend="dateperiod.props.interval">interval</varname>
65
75
</fieldsynopsis>
66
76
<fieldsynopsis>
67
77
<modifier>public</modifier>
68
-
<type>DateTimeInterface</type>
69
-
<varname linkend="dateperiod.props.current">current</varname>
78
+
<modifier>readonly</modifier>
79
+
<type>int</type>
80
+
<varname linkend="dateperiod.props.recurrences">recurrences</varname>
70
81
</fieldsynopsis>
71
82
<fieldsynopsis>
72
83
<modifier>public</modifier>
73
-
<type>DateTimeInterface</type>
74
-
<varname linkend="dateperiod.props.end">end</varname>
84
+
<modifier>readonly</modifier>
85
+
<type>bool</type>
86
+
<varname linkend="dateperiod.props.include-start-date">include_start_date</varname>
75
87
</fieldsynopsis>
76
88
<fieldsynopsis>
77
89
<modifier>public</modifier>
78
-
<type>DateInterval</type>
79
-
<varname linkend="dateperiod.props.interval">interval</varname>
90
+
<modifier>readonly</modifier>
91
+
<type>bool</type>
92
+
<varname linkend="dateperiod.props.include-end-date">include_end_date</varname>
80
93
</fieldsynopsis>
81
94

82
95
<classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
83
-
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.dateperiod')/db:refentry/db:refsect1[@role='description']/descendant::db:constructorsynopsis[not(@role='procedural')])">
84
-
<xi:fallback />
85
-
</xi:include>
86
-
<!--
87
-
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.dateperiod')/db:refentry/db:refsect1[@role='description']/descendant::db:destructorsynopsis[not(@role='procedural')])">
88
-
<xi:fallback />
96
+
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.dateperiod')/db:refentry/db:refsect1[@role='description']/descendant::db:constructorsynopsis[@role='DatePeriod'])">
97
+
<xi:fallback/>
89
98
</xi:include>
90
-
-->
91
-
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.dateperiod')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[not(@role='procedural')])">
92
-
<xi:fallback />
99
+
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.dateperiod')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[@role='DatePeriod'])">
100
+
<xi:fallback/>
93
101
</xi:include>
94
-

95
102
</classsynopsis>
96
103
<!-- }}} -->
97
104

...
...
@@ -108,6 +115,13 @@
108
115
</listitem>
109
116
</varlistentry>
110
117

118
+
<varlistentry xml:id="dateperiod.constants.include-end-date">
119
+
<term><constant>DatePeriod::INCLUDE_END_DATE</constant></term>
120
+
<listitem>
121
+
<para>Include end date, used in <function>DatePeriod::__construct</function>.</para>
122
+
</listitem>
123
+
</varlistentry>
124
+

111
125
</variablelist>
112
126
</section>
113
127
<!-- }}} -->
...
...
@@ -119,13 +133,77 @@
119
133
<term><varname>recurrences</varname></term>
120
134
<listitem>
121
135
<para>
122
-
The number of recurrences, if the <classname>DatePeriod</classname> instance
123
-
had been created by explicitly passing <literal>$recurrences</literal>.
136
+
The minimum amount of instances as retured by the iterator.
137
+
</para>
138
+
<para>
139
+
If the number of recurrences has been explicitly passed through the
140
+
<varname>recurrences</varname> parameter in the constructor of the
141
+
<classname>DatePeriod</classname> instance, then this property contains
142
+
this value, <emphasis>plus</emphasis> one if the start date has not been disabled
143
+
through <constant>DatePeriod::EXCLUDE_START_DATE</constant>,
144
+
<emphasis>plus</emphasis> one if the end date has been enabled through
145
+
<constant>DatePeriod::INCLUDE_END_DATE</constant>.
146
+
</para>
147
+
<para>
148
+
If the number of recurrences has not been explicitly passed, then this
149
+
property contains the minimum number of returned instances. This would
150
+
be <literal>0</literal>, <emphasis>plus</emphasis> one if the start date
151
+
has not been disabled through
152
+
<constant>DatePeriod::EXCLUDE_START_DATE</constant>,
153
+
<emphasis>plus</emphasis> one if the end date has been enabled through
154
+
<constant>DatePeriod::INCLUDE_END_DATE</constant>.
155
+
</para>
156
+
<para>
157
+
<example>
158
+
<programlisting role="php">
159
+
<![CDATA[<?php
160
+
$start = new DateTime('2018-12-31 00:00:00');
161
+
$end = new DateTime('2021-12-31 00:00:00');
162
+
$interval = new DateInterval('P1M');
163
+
$recurrences = 5;
164
+

165
+
// recurrences explicitly set through the constructor
166
+
$period = new DatePeriod($start, $interval, $recurrences, DatePeriod::EXCLUDE_START_DATE);
167
+
echo $period->recurrences, "\n";
168
+

169
+
$period = new DatePeriod($start, $interval, $recurrences);
170
+
echo $period->recurrences, "\n";
171
+

172
+
$period = new DatePeriod($start, $interval, $recurrences, DatePeriod::INCLUDE_END_DATE);
173
+
echo $period->recurrences, "\n";
174
+

175
+
// recurrences not set in the constructor
176
+
$period = new DatePeriod($start, $interval, $end);
177
+
echo $period->recurrences, "\n";
178
+

179
+
$period = new DatePeriod($start, $interval, $end, DatePeriod::EXCLUDE_START_DATE);
180
+
echo $period->recurrences, "\n";
181
+
?>]]>
182
+
</programlisting>
183
+
&example.outputs;
184
+
<screen role="php">
185
+
5
186
+
6
187
+
7
188
+
1
189
+
0
190
+
</screen>
191
+
</example>
192
+
</para>
193
+
<para>
124
194
See also <methodname>DatePeriod::getRecurrences</methodname>.
125
195
</para>
126
196
</listitem>
127
197
</varlistentry>
128
-
<varlistentry xml:id="dateperiod.props.include_start_date">
198
+
<varlistentry xml:id="dateperiod.props.include-end-date">
199
+
<term><varname>include_end_date</varname></term>
200
+
<listitem>
201
+
<para>
202
+
Whether to include the end date in the set of recurring dates or not.
203
+
</para>
204
+
</listitem>
205
+
</varlistentry>
206
+
<varlistentry xml:id="dateperiod.props.include-start-date">
129
207
<term><varname>include_start_date</varname></term>
130
208
<listitem>
131
209
<para>
...
...
@@ -168,31 +246,35 @@
168
246
</variablelist>
169
247
</section>
170
248

171
-
<section role="changelog" xml:id="dateperiod.changelog">
249
+
<section role="changelog">
172
250
&reftitle.changelog;
173
-
<para>
174
-
<informaltable>
175
-
<tgroup cols="2">
176
-
<thead>
177
-
<row>
178
-
<entry>&Version;</entry>
179
-
<entry>&Description;</entry>
180
-
</row>
181
-
</thead>
182
-
<tbody>
183
-
<row>
184
-
<entry>5.3.27, 5.4.17</entry>
185
-
<entry>
186
-
The public properties <varname>recurrences</varname>,
187
-
<varname>include_start_date</varname>, <varname>start</varname>,
188
-
<varname>current</varname>, <varname>end</varname> and
189
-
<varname>interval</varname> have been exposed.
190
-
</entry>
191
-
</row>
192
-
</tbody>
193
-
</tgroup>
194
-
</informaltable>
195
-
</para>
251
+
<informaltable>
252
+
<tgroup cols="2">
253
+
<thead>
254
+
<row>
255
+
<entry>&Version;</entry>
256
+
<entry>&Description;</entry>
257
+
</row>
258
+
</thead>
259
+
<tbody>
260
+
<row>
261
+
<entry>8.2.0</entry>
262
+
<entry>
263
+
The <constant>DatePeriod::INCLUDE_END_DATE</constant> constant and
264
+
<property>include_end_date</property> property have been added.
265
+
</entry>
266
+
</row>
267
+
<row>
268
+
<entry>8.0.0</entry>
269
+
<entry>
270
+
<classname>DatePeriod</classname> implements
271
+
<interfacename>IteratorAggregate</interfacename> now.
272
+
Previously, <interfacename>Traversable</interfacename> was implemented instead.
273
+
</entry>
274
+
</row>
275
+
</tbody>
276
+
</tgroup>
277
+
</informaltable>
196
278
</section>
197
279

198
280
</partintro>
...
...
@@ -200,7 +282,6 @@
200
282
&reference.datetime.entities.dateperiod;
201
283

202
284
</phpdoc:classref>
203
-

204
285
<!-- Keep this comment at the end of the file
205
286
Local variables:
206
287
mode: sgml
207
288