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

4
-
<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">
3
+
<reference xml:id="class.dateperiod" role="class" 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>
7
6
<titleabbrev>DatePeriod</titleabbrev>
...
...
@@ -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

...
...
@@ -102,12 +109,25 @@
102
109
&reftitle.constants;
103
110
<variablelist>
104
111
<varlistentry xml:id="dateperiod.constants.exclude-start-date">
105
-
<term><constant>DatePeriod::EXCLUDE_START_DATE</constant></term>
112
+
<term>
113
+
<constant>DatePeriod::EXCLUDE_START_DATE</constant>
114
+
<type>int</type>
115
+
</term>
106
116
<listitem>
107
117
<para>Exclude start date, used in <function>DatePeriod::__construct</function>.</para>
108
118
</listitem>
109
119
</varlistentry>
110
120

121
+
<varlistentry xml:id="dateperiod.constants.include-end-date">
122
+
<term>
123
+
<constant>DatePeriod::INCLUDE_END_DATE</constant>
124
+
<type>int</type>
125
+
</term>
126
+
<listitem>
127
+
<para>Include end date, used in <function>DatePeriod::__construct</function>.</para>
128
+
</listitem>
129
+
</varlistentry>
130
+

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

171
+
// recurrences explicitly set through the constructor
172
+
$period = new DatePeriod($start, $interval, $recurrences, DatePeriod::EXCLUDE_START_DATE);
173
+
echo $period->recurrences, "\n";
174
+

175
+
$period = new DatePeriod($start, $interval, $recurrences);
176
+
echo $period->recurrences, "\n";
177
+

178
+
$period = new DatePeriod($start, $interval, $recurrences, DatePeriod::INCLUDE_END_DATE);
179
+
echo $period->recurrences, "\n";
180
+

181
+
// recurrences not set in the constructor
182
+
$period = new DatePeriod($start, $interval, $end);
183
+
echo $period->recurrences, "\n";
184
+

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

171
-
<section role="changelog" xml:id="dateperiod.changelog">
255
+
<section role="changelog">
172
256
&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>
257
+
<informaltable>
258
+
<tgroup cols="2">
259
+
<thead>
260
+
<row>
261
+
<entry>&Version;</entry>
262
+
<entry>&Description;</entry>
263
+
</row>
264
+
</thead>
265
+
<tbody>
266
+
<row>
267
+
<entry>8.4.0</entry>
268
+
<entry>
269
+
The class constants are now typed.
270
+
</entry>
271
+
</row>
272
+
<row>
273
+
<entry>8.2.0</entry>
274
+
<entry>
275
+
The <constant>DatePeriod::INCLUDE_END_DATE</constant> constant and
276
+
<property>include_end_date</property> property have been added.
277
+
</entry>
278
+
</row>
279
+
<row>
280
+
<entry>8.0.0</entry>
281
+
<entry>
282
+
<classname>DatePeriod</classname> implements
283
+
<interfacename>IteratorAggregate</interfacename> now.
284
+
Previously, <interfacename>Traversable</interfacename> was implemented instead.
285
+
</entry>
286
+
</row>
287
+
</tbody>
288
+
</tgroup>
289
+
</informaltable>
196
290
</section>
197
291

198
292
</partintro>
199
293

200
294
&reference.datetime.entities.dateperiod;
201
295

202
-
</phpdoc:classref>
203
-

296
+
</reference>
204
297
<!-- Keep this comment at the end of the file
205
298
Local variables:
206
299
mode: sgml
207
300



Translation status