Fixed bug #79926: Unclear behavior with createFromFormat using absolute and relative values

reference/datetime/datetimeimmutable/createfromformat.xml

@@ -92,7 +92,11 @@
           <entry>A textual representation of a day</entry>
           <entry>
            <literal>Mon</literal> through <literal>Sun</literal> or
-           <literal>Sunday</literal> through <literal>Saturday</literal>
+           <literal>Sunday</literal> through <literal>Saturday</literal>. If
+           the day name given is different then the day name belonging to a
+           parsed (or default) date is different, then an overflow occurs to
+           the <emphasis>next</emphasis> date with the given day name. See the
+           examples below for an explanation.
           </entry>
          </row>
          <row>
@@ -550,9 +554,48 @@ Sat, 04 Jun 2022 17:01:37 +0000
    </orderedlist>
   </example>
 
+  <example>
+   <title>Overflowing day name behaviour</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$d = DateTime::createFromFormat(DateTimeInterface::RFC1123, 'Mon, 3 Aug 2020 25:00:00 +0000');
+echo $d->format(DateTime::RFC1123), "\n";
+?>
+]]>
+   </programlisting>
+   &example.outputs.similar;
+   <screen>
+<![CDATA[
+Mon, 10 Aug 2020 01:00:00 +0000
+]]>
+   </screen>
+   <para>
+    Although the result looks odd, it is correct, as the following overflows
+    happen:
+   </para>
+   <orderedlist>
+    <listitem>
+     <simpara>
+      <literal>3 Aug 2020 25:00:00</literal> overflows to <literal>(Tue) 4 Aug
+      2020 01:00</literal>.
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      <literal>Mon</literal> gets applied, which advances the date to
+      <literal>Mon, 10 Aug 2020 01:00:00</literal>. The explanation of
+      relative keywords such as <literal>Mon</literal> is explained in the
+      section on <link linkend="datetime.formats.relative">relative
+      formats</link>.
+     </simpara>
+    </listitem>
+   </orderedlist>
+  </example>
+
   <para>
    In order to detect overflows in dates, you can use the
-   <methodname>DateTimeInterface::getLastErrors</methodname> name, which will
+   <methodname>DateTimeImmutable::getLastErrors</methodname> name, which will
    include a warning if an overflow occured.
   </para>
   <example>

reference/datetime/formats.xml

@@ -965,7 +965,10 @@ class DateTime#1 (3) {
      </row>
      <row>
       <entry><literal>dayname</literal></entry>
-      <entry>Moves to the next day of this name.</entry>
+      <entry>
+       Moves to the next day of this name. (See <link
+       linkend="datetime.formats.relative.dayname-note">note</link>)
+      </entry>
       <entry>"Monday"</entry>
      </row>
      <row>
@@ -1001,7 +1004,7 @@ class DateTime#1 (3) {
    </para>
   </note>
   
-  <note>
+  <note xml:id="datetime.formats.relative.dayname-note">
    <para>
     Observe the following remarks when the current day-of-week is the
     same as the day-of-week used in the date/time string. The current