Skip to content

Commit 020c691

Browse files
derickrtiffany-taylor
derickr
authored and
tiffany-taylor
committed
Incorporate useful information from notes (take php#2)
1 parent 2fcceda commit 020c691

File tree

7 files changed

+179
-8
lines changed

7 files changed

+179
-8
lines changed

‎reference/datetime/dateinterval.xml

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -123,6 +123,12 @@
123123

124124
<section xml:id="dateinterval.props">
125125
&reftitle.properties;
126+
<warning>
127+
<para>
128+
The available properties listed below depend on PHP version, and should
129+
be considered as <emphasis>readonly</emphasis>.
130+
</para>
131+
</warning>
126132
<variablelist>
127133
<varlistentry xml:id="dateinterval.props.y">
128134
<term><varname>y</varname></term>
@@ -198,7 +204,7 @@
198204
If the DateInterval object was created by
199205
<methodname>DateTimeImmutable::diff</methodname> or
200206
<methodname>DateTime::diff</methodname>, then this is the
201-
total number of days between the start and end dates. Otherwise,
207+
total number of full days between the start and end dates. Otherwise,
202208
<varname>days</varname> will be &false;.
203209
</para>
204210
</listitem>
@@ -250,6 +256,13 @@
250256
<methodname>DateInterval::createFromDateString</methodname> method.
251257
</entry>
252258
</row>
259+
<row>
260+
<entry>8.2.0</entry>
261+
<entry>
262+
Only the <literal>y</literal> to <literal>f</literal>,
263+
<literal>invert</literal>, and <literal>days</literal> will be visible.
264+
</entry>
265+
</row>
253266
<row>
254267
<entry>7.4.0</entry>
255268
<entry>

‎reference/datetime/dateinterval/construct.xml

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -158,6 +158,32 @@
158158

159159
<refsect1 role="examples">
160160
&reftitle.examples;
161+
<para>
162+
<example>
163+
<title>Constructing and using <classname>DateInterval</classname> objects</title>
164+
<programlisting role="php">
165+
<![CDATA[
166+
<?php
167+
// Create a specific date
168+
$someDate = \DateTime::createFromFormat("Y-m-d H:i", "2022-08-25 14:18");
169+
170+
// Create interval
171+
$interval = new \DateInterval("P7D");
172+
173+
// Add interval
174+
$someDate->add($interval);
175+
176+
// Convert interval to string
177+
echo $interval->format("%d");
178+
]]>
179+
</programlisting>
180+
&example.outputs;
181+
<screen role="php">
182+
7
183+
</screen>
184+
</example>
185+
</para>
186+
161187
<para>
162188
<example>
163189
<title><classname>DateInterval</classname> example</title>

‎reference/datetime/dateinterval/createfromdatestring.xml

Lines changed: 29 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,10 @@
1313
<methodparam><type>string</type><parameter>datetime</parameter></methodparam>
1414
</methodsynopsis>
1515
<para>
16-
Uses the normal date parsers and sets up a DateInterval from the relative
17-
parts of the parsed string.
16+
Uses the date/time parsers as used in the
17+
<classname>DateTimeImmutable</classname> constructor to create a
18+
<classname>DateInterval</classname> from the relative parts of the parsed
19+
string.
1820
</para>
1921
</refsect1>
2022

@@ -32,6 +34,10 @@
3234
<classname>DateTime</classname>, and <function>strtotime</function>
3335
will be used to construct the DateInterval.
3436
</para>
37+
<para>
38+
To use an ISO-8601 format string like <literal>P7D</literal>, you must
39+
use the contructor.
40+
</para>
3541
</listitem>
3642
</varlistentry>
3743
</variablelist>
@@ -103,6 +109,27 @@ $i = DateInterval::createFromDateString('3600 seconds');
103109
</programlisting>
104110
</example>
105111
</para>
112+
<para>
113+
<example>
114+
<title>Parsing combinations and negative intervals</title>
115+
<programlisting role="php">
116+
<![CDATA[
117+
<?php
118+
$i = DateInterval::createFromDateString('62 weeks + 1 day + 2 weeks + 2 hours + 70 minutes');
119+
echo $i->format('%d %h %i'), "\n";
120+
121+
$i = DateInterval::createFromDateString('1 year - 10 days');
122+
echo $i->format('%y %d'), "\n";
123+
?>
124+
]]>
125+
</programlisting>
126+
&example.outputs;
127+
<screen role="shell">
128+
449 2 70
129+
1 -10
130+
</screen>
131+
</example>
132+
</para>
106133
<para>
107134
<example>
108135
<title>Parsing special relative date intervals</title>

‎reference/datetime/dateinterval/format.xml

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -162,6 +162,11 @@
162162
</row>
163163
</thead>
164164
<tbody>
165+
<row>
166+
<entry>7.2.12</entry>
167+
<entry>The <literal>F</literal> and <literal>f</literal> format
168+
will now always be positive.</entry>
169+
</row>
165170
<row>
166171
<entry>7.1.0</entry>
167172
<entry>The <literal>F</literal> and <literal>f</literal> format

‎reference/datetime/dateperiod.xml

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,13 +46,24 @@
4646
<varname linkend="dateperiod.constants.exclude-start-date">DatePeriod::EXCLUDE_START_DATE</varname>
4747
<initializer>1</initializer>
4848
</fieldsynopsis>
49+
<fieldsynopsis>
50+
<modifier>const</modifier>
51+
<type>int</type>
52+
<varname linkend="dateperiod.constants.include-end-date">DatePeriod::INCLUDE_END_DATE</varname>
53+
<initializer>2</initializer>
54+
</fieldsynopsis>
4955

5056
<classsynopsisinfo role="comment">&Properties;</classsynopsisinfo>
5157
<fieldsynopsis>
5258
<modifier>public</modifier>
5359
<type>int</type>
5460
<varname linkend="dateperiod.props.recurrences">recurrences</varname>
5561
</fieldsynopsis>
62+
<fieldsynopsis>
63+
<modifier>public</modifier>
64+
<type>bool</type>
65+
<varname linkend="dateperiod.props.include_end_date">include_end_date</varname>
66+
</fieldsynopsis>
5667
<fieldsynopsis>
5768
<modifier>public</modifier>
5869
<type>bool</type>
@@ -102,6 +113,13 @@
102113
</listitem>
103114
</varlistentry>
104115

116+
<varlistentry xml:id="dateperiod.constants.include-end-date">
117+
<term><constant>DatePeriod::INCLUDE_END_DATE</constant></term>
118+
<listitem>
119+
<para>Include end date, used in <function>DatePeriod::__construct</function>.</para>
120+
</listitem>
121+
</varlistentry>
122+
105123
</variablelist>
106124
</section>
107125
<!-- }}} -->
@@ -119,6 +137,14 @@
119137
</para>
120138
</listitem>
121139
</varlistentry>
140+
<varlistentry xml:id="dateperiod.props.include_end_date">
141+
<term><varname>include_end_date</varname></term>
142+
<listitem>
143+
<para>
144+
Whether to include the end date in the set of recurring dates or not.
145+
</para>
146+
</listitem>
147+
</varlistentry>
122148
<varlistentry xml:id="dateperiod.props.include_start_date">
123149
<term><varname>include_start_date</varname></term>
124150
<listitem>
@@ -173,6 +199,13 @@
173199
</row>
174200
</thead>
175201
<tbody>
202+
<row>
203+
<entry>8.2.0</entry>
204+
<entry>
205+
The <constant>DatePeriod::INCLUDE_END_DATE</constant> constant and
206+
<property>include_end_date</property> property have been added.
207+
</entry>
208+
</row>
176209
<row>
177210
<entry>8.0.0</entry>
178211
<entry>

‎reference/datetime/dateperiod/construct.xml

Lines changed: 70 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,18 @@
3131
<para>
3232
Creates a new DatePeriod object.
3333
</para>
34+
<para>
35+
<classname>DatePeriod</classname> objects can be used as an iterator to
36+
generate a number of <classname>DateTimeImmutable</classname> or
37+
<classname>DateTime</classname> object from a <parameter>start</parameter>
38+
date, a <parameter>interval</parameter>, and an <parameter>end</parameter>
39+
date or the number of <parameter>recurrences</parameter>.
40+
</para>
41+
<para>
42+
The class of returned objects is equivalent to the
43+
<classname>DateTimeImmutable</classname> or <classname>DateTime</classname>
44+
ancester class of the <parameter>start</parameter> object.
45+
</para>
3446
</refsect1>
3547

3648
<refsect1 role="parameters">
@@ -41,7 +53,7 @@
4153
<term><parameter>start</parameter></term>
4254
<listitem>
4355
<para>
44-
The start date of the period.
56+
The start date of the period. Included by default in the result set.
4557
</para>
4658
</listitem>
4759
</varlistentry>
@@ -57,15 +69,17 @@
5769
<term><parameter>recurrences</parameter></term>
5870
<listitem>
5971
<para>
60-
The number of recurrences. Must be greater than <literal>0</literal>.
72+
The number of recurrences. The number of returned results is
73+
one higher than this, as the start date is included in the result set
74+
by default. Must be greater than <literal>0</literal>.
6175
</para>
6276
</listitem>
6377
</varlistentry>
6478
<varlistentry>
6579
<term><parameter>end</parameter></term>
6680
<listitem>
6781
<para>
68-
The end date of the period.
82+
The end date of the period. Excluded by default in the result set.
6983
</para>
7084
</listitem>
7185
</varlistentry>
@@ -83,10 +97,19 @@
8397
<term><parameter>options</parameter></term>
8498
<listitem>
8599
<para>
86-
Can be set to <constant>DatePeriod::EXCLUDE_START_DATE</constant> to
100+
A bit field which can be used to control certain behaviour with start-
101+
and end- dates.
102+
</para>
103+
<para>
104+
With <constant>DatePeriod::EXCLUDE_START_DATE</constant> you
87105
exclude the start date from the set of recurring dates within the
88106
period.
89107
</para>
108+
<para>
109+
With <constant>DatePeriod::INCLUDE_END_DATE</constant> you
110+
include the end date from the set of recurring dates within the
111+
period.
112+
</para>
90113
</listitem>
91114
</varlistentry>
92115
</variablelist>
@@ -105,6 +128,12 @@
105128
</row>
106129
</thead>
107130
<tbody>
131+
<row>
132+
<entry>8.2.0</entry>
133+
<entry>
134+
The <constant>DatePeriod::INCLUDE_END_DATE</constant> constant has been added.
135+
</entry>
136+
</row>
108137
<row>
109138
<entry>7.2.19, 7.3.6, 7.4.0</entry>
110139
<entry>
@@ -185,6 +214,43 @@ foreach ($period as $date) {
185214
2012-07-15
186215
2012-07-22
187216
2012-07-29
217+
]]>
218+
</screen>
219+
</example>
220+
</para>
221+
<para>
222+
<example>
223+
<title>DatePeriod example showing all last Thursdays in a year</title>
224+
<programlisting role="php">
225+
<![CDATA[
226+
<?php
227+
$begin = new DateTime('2021-12-31');
228+
$end = new DateTime('2022-12-31 23:59:59');
229+
230+
$interval = DateInterval::createFromDateString('last thursday of next month');
231+
$period = new DatePeriod($begin, $interval, $end, DatePeriod::EXCLUDE_START_DATE);
232+
233+
foreach ($period as $dt) {
234+
echo $dt->format('l Y-m-d'), "\n";
235+
}
236+
?>
237+
]]>
238+
</programlisting>
239+
&example.outputs;
240+
<screen>
241+
<![CDATA[
242+
Thursday 2022-01-27
243+
Thursday 2022-02-24
244+
Thursday 2022-03-31
245+
Thursday 2022-04-28
246+
Thursday 2022-05-26
247+
Thursday 2022-06-30
248+
Thursday 2022-07-28
249+
Thursday 2022-08-25
250+
Thursday 2022-09-29
251+
Thursday 2022-10-27
252+
Thursday 2022-11-24
253+
Thursday 2022-12-29
188254
]]>
189255
</screen>
190256
</example>

‎reference/datetime/functions/date-create.xml

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,8 +42,9 @@
4242
<refsect1 role="seealso">
4343
&reftitle.seealso;
4444
<simplelist>
45-
<member><methodname>DateTime::__construct</methodname></member>
4645
<member><methodname>DateTimeImmutable::__construct</methodname></member>
46+
<member><methodname>DateTimeImmutable::createFromFormat</methodname></member>
47+
<member><methodname>DateTime::__construct</methodname></member>
4748
</simplelist>
4849
</refsect1>
4950

0 commit comments

Comments
 (0)