Author: Derick Rethans (derickr)
Date: 2022-08-25T17:20:54+01:00
Commit: https://github.com/php/doc-en/commit/c249f3bc56fcdb3ea3f64b1fa0c4fd96a7dcd5a4
Raw diff: https://github.com/php/doc-en/commit/c249f3bc56fcdb3ea3f64b1fa0c4fd96a7dcd5a4.diff
Incorporate useful information from notes (take #2)
Changed paths:
M reference/datetime/dateinterval.xml
M reference/datetime/dateinterval/construct.xml
M reference/datetime/dateinterval/createfromdatestring.xml
M reference/datetime/dateinterval/format.xml
M reference/datetime/dateperiod.xml
M reference/datetime/dateperiod/construct.xml
M reference/datetime/functions/date-create.xml
Diff:
diff --git a/reference/datetime/dateinterval.xml b/reference/datetime/dateinterval.xml
index 7149d052ca2..49129582887 100644
--- a/reference/datetime/dateinterval.xml
+++ b/reference/datetime/dateinterval.xml
@@ -123,6 +123,12 @@
<section xml:id="dateinterval.props">
&reftitle.properties;
+ <warning>
+ <para>
+ The available properties listed below depend on PHP version, and should
+ be considered as <emphasis>readonly</emphasis>.
+ </para>
+ </warning>
<variablelist>
<varlistentry xml:id="dateinterval.props.y">
<term><varname>y</varname></term>
@@ -198,7 +204,7 @@
If the DateInterval object was created by
<methodname>DateTimeImmutable::diff</methodname> or
<methodname>DateTime::diff</methodname>, then this is the
- total number of days between the start and end dates. Otherwise,
+ total number of full days between the start and end dates. Otherwise,
<varname>days</varname> will be &false;.
</para>
</listitem>
@@ -250,6 +256,13 @@
<methodname>DateInterval::createFromDateString</methodname> method.
</entry>
</row>
+ <row>
+ <entry>8.2.0</entry>
+ <entry>
+ Only the <literal>y</literal> to <literal>f</literal>,
+ <literal>invert</literal>, and <literal>days</literal> will be
visible.
+ </entry>
+ </row>
<row>
<entry>7.4.0</entry>
<entry>
diff --git a/reference/datetime/dateinterval/construct.xml
b/reference/datetime/dateinterval/construct.xml
index 25cb148b807..86dc0c5b329 100644
--- a/reference/datetime/dateinterval/construct.xml
+++ b/reference/datetime/dateinterval/construct.xml
@@ -158,6 +158,32 @@
<refsect1 role="examples">
&reftitle.examples;
+ <para>
+ <example>
+ <title>Constructing and using <classname>DateInterval</classname>
objects</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+// Create a specific date
+$someDate = \DateTime::createFromFormat("Y-m-d H:i", "2022-08-25 14:18");
+
+// Create interval
+$interval = new \DateInterval("P7D");
+
+// Add interval
+$someDate->add($interval);
+
+// Convert interval to string
+echo $interval->format("%d");
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen role="php">
+7
+ </screen>
+ </example>
+ </para>
+
<para>
<example>
<title><classname>DateInterval</classname> example</title>
diff --git a/reference/datetime/dateinterval/createfromdatestring.xml
b/reference/datetime/dateinterval/createfromdatestring.xml
index b59190f5fe2..832143c943d 100644
--- a/reference/datetime/dateinterval/createfromdatestring.xml
+++ b/reference/datetime/dateinterval/createfromdatestring.xml
@@ -13,8 +13,10 @@
<methodparam><type>string</type><parameter>datetime</parameter></methodparam>
</methodsynopsis>
<para>
- Uses the normal date parsers and sets up a DateInterval from the relative
- parts of the parsed string.
+ Uses the date/time parsers as used in the
+ <classname>DateTimeImmutable</classname> constructor to create a
+ <classname>DateInterval</classname> from the relative parts of the parsed
+ string.
</para>
</refsect1>
@@ -32,6 +34,10 @@
<classname>DateTime</classname>, and <function>strtotime</function>
will be used to construct the DateInterval.
</para>
+ <para>
+ To use an ISO-8601 format string like <literal>P7D</literal>, you must
+ use the contructor.
+ </para>
</listitem>
</varlistentry>
</variablelist>
@@ -103,6 +109,27 @@ $i = DateInterval::createFromDateString('3600 seconds');
</programlisting>
</example>
</para>
+ <para>
+ <example>
+ <title>Parsing combinations and negative intervals</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$i = DateInterval::createFromDateString('62 weeks + 1 day + 2 weeks + 2 hours + 70
minutes');
+echo $i->format('%d %h %i'), "\n";
+
+$i = DateInterval::createFromDateString('1 year - 10 days');
+echo $i->format('%y %d'), "\n";
+?>
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen role="shell">
+449 2 70
+1 -10
+ </screen>
+ </example>
+ </para>
<para>
<example>
<title>Parsing special relative date intervals</title>
diff --git a/reference/datetime/dateinterval/format.xml b/reference/datetime/dateinterval/format.xml
index eab044f9528..59b17812c0d 100644
--- a/reference/datetime/dateinterval/format.xml
+++ b/reference/datetime/dateinterval/format.xml
@@ -162,6 +162,11 @@
</row>
</thead>
<tbody>
+ <row>
+ <entry>7.2.12</entry>
+ <entry>The <literal>F</literal> and <literal>f</literal>
format
+ will now always be positive.</entry>
+ </row>
<row>
<entry>7.1.0</entry>
<entry>The <literal>F</literal> and <literal>f</literal>
format
diff --git a/reference/datetime/dateperiod.xml b/reference/datetime/dateperiod.xml
index 4df26e24ca0..8daf8dfeca9 100644
--- a/reference/datetime/dateperiod.xml
+++ b/reference/datetime/dateperiod.xml
@@ -46,6 +46,12 @@
<varname
linkend="dateperiod.constants.exclude-start-date">DatePeriod::EXCLUDE_START_DATE</varname>
<initializer>1</initializer>
</fieldsynopsis>
+ <fieldsynopsis>
+ <modifier>const</modifier>
+ <type>int</type>
+ <varname
linkend="dateperiod.constants.include-end-date">DatePeriod::INCLUDE_END_DATE</varname>
+ <initializer>2</initializer>
+ </fieldsynopsis>
<classsynopsisinfo role="comment">&Properties;</classsynopsisinfo>
<fieldsynopsis>
@@ -53,6 +59,11 @@
<type>int</type>
<varname linkend="dateperiod.props.recurrences">recurrences</varname>
</fieldsynopsis>
+ <fieldsynopsis>
+ <modifier>public</modifier>
+ <type>bool</type>
+ <varname
linkend="dateperiod.props.include_end_date">include_end_date</varname>
+ </fieldsynopsis>
<fieldsynopsis>
<modifier>public</modifier>
<type>bool</type>
@@ -102,6 +113,13 @@
</listitem>
</varlistentry>
+ <varlistentry xml:id="dateperiod.constants.include-end-date">
+ <term><constant>DatePeriod::INCLUDE_END_DATE</constant></term>
+ <listitem>
+ <para>Include end date, used in
<function>DatePeriod::__construct</function>.</para>
+ </listitem>
+ </varlistentry>
+
</variablelist>
</section>
<!-- }}} -->
@@ -119,6 +137,14 @@
</para>
</listitem>
</varlistentry>
+ <varlistentry xml:id="dateperiod.props.include_end_date">
+ <term><varname>include_end_date</varname></term>
+ <listitem>
+ <para>
+ Whether to include the end date in the set of recurring dates or not.
+ </para>
+ </listitem>
+ </varlistentry>
<varlistentry xml:id="dateperiod.props.include_start_date">
<term><varname>include_start_date</varname></term>
<listitem>
@@ -173,6 +199,13 @@
</row>
</thead>
<tbody>
+ <row>
+ <entry>8.2.0</entry>
+ <entry>
+ The <constant>DatePeriod::INCLUDE_END_DATE</constant> constant and
+ <property>include_end_date</property> property have been added.
+ </entry>
+ </row>
<row>
<entry>8.0.0</entry>
<entry>
diff --git a/reference/datetime/dateperiod/construct.xml
b/reference/datetime/dateperiod/construct.xml
index 96bbec935a6..d5f077d54e4 100644
--- a/reference/datetime/dateperiod/construct.xml
+++ b/reference/datetime/dateperiod/construct.xml
@@ -31,6 +31,18 @@
<para>
Creates a new DatePeriod object.
</para>
+ <para>
+ <classname>DatePeriod</classname> objects can be used as an iterator to
+ generate a number of <classname>DateTimeImmutable</classname> or
+ <classname>DateTime</classname> object from a
<parameter>start</parameter>
+ date, a <parameter>interval</parameter>, and an
<parameter>end</parameter>
+ date or the number of <parameter>recurrences</parameter>.
+ </para>
+ <para>
+ The class of returned objects is equivalent to the
+ <classname>DateTimeImmutable</classname> or
<classname>DateTime</classname>
+ ancester class of the <parameter>start</parameter> object.
+ </para>
</refsect1>
<refsect1 role="parameters">
@@ -41,7 +53,7 @@
<term><parameter>start</parameter></term>
<listitem>
<para>
- The start date of the period.
+ The start date of the period. Included by default in the result set.
</para>
</listitem>
</varlistentry>
@@ -57,7 +69,9 @@
<term><parameter>recurrences</parameter></term>
<listitem>
<para>
- The number of recurrences. Must be greater than <literal>0</literal>.
+ The number of recurrences. The number of returned results is
+ one higher than this, as the start date is included in the result set
+ by default. Must be greater than <literal>0</literal>.
</para>
</listitem>
</varlistentry>
@@ -65,7 +79,7 @@
<term><parameter>end</parameter></term>
<listitem>
<para>
- The end date of the period.
+ The end date of the period. Excluded by default in the result set.
</para>
</listitem>
</varlistentry>
@@ -83,10 +97,19 @@
<term><parameter>options</parameter></term>
<listitem>
<para>
- Can be set to <constant>DatePeriod::EXCLUDE_START_DATE</constant> to
+ A bit field which can be used to control certain behaviour with start-
+ and end- dates.
+ </para>
+ <para>
+ With <constant>DatePeriod::EXCLUDE_START_DATE</constant> you
exclude the start date from the set of recurring dates within the
period.
</para>
+ <para>
+ With <constant>DatePeriod::INCLUDE_END_DATE</constant> you
+ include the end date from the set of recurring dates within the
+ period.
+ </para>
</listitem>
</varlistentry>
</variablelist>
@@ -105,6 +128,12 @@
</row>
</thead>
<tbody>
+ <row>
+ <entry>8.2.0</entry>
+ <entry>
+ The <constant>DatePeriod::INCLUDE_END_DATE</constant> constant has been added.
+ </entry>
+ </row>
<row>
<entry>7.2.19, 7.3.6, 7.4.0</entry>
<entry>
@@ -185,6 +214,43 @@ foreach ($period as $date) {
2012-07-15
2012-07-22
2012-07-29
+]]>
+ </screen>
+ </example>
+ </para>
+ <para>
+ <example>
+ <title>DatePeriod example showing all last Thursdays in a year</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$begin = new DateTime('2021-12-31');
+$end = new DateTime('2022-12-31 23:59:59');
+
+$interval = DateInterval::createFromDateString('last thursday of next month');
+$period = new DatePeriod($begin, $interval, $end, DatePeriod::EXCLUDE_START_DATE);
+
+foreach ($period as $dt) {
+ echo $dt->format('l Y-m-d'), "\n";
+}
+?>
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+Thursday 2022-01-27
+Thursday 2022-02-24
+Thursday 2022-03-31
+Thursday 2022-04-28
+Thursday 2022-05-26
+Thursday 2022-06-30
+Thursday 2022-07-28
+Thursday 2022-08-25
+Thursday 2022-09-29
+Thursday 2022-10-27
+Thursday 2022-11-24
+Thursday 2022-12-29
]]>
</screen>
</example>
diff --git a/reference/datetime/functions/date-create.xml
b/reference/datetime/functions/date-create.xml
index cd439cda896..51a60889c6f 100644
--- a/reference/datetime/functions/date-create.xml
+++ b/reference/datetime/functions/date-create.xml
@@ -42,8 +42,9 @@
<refsect1 role="seealso">
&reftitle.seealso;
<simplelist>
- <member><methodname>DateTime::__construct</methodname></member>
<member><methodname>DateTimeImmutable::__construct</methodname></member>
+
<member><methodname>DateTimeImmutable::createFromFormat</methodname></member>
+ <member><methodname>DateTime::__construct</methodname></member>
</simplelist>
</refsect1>