Clarify how properties are populated when using PDO::FETCH_CLASS (#4360)

 Private and read-only properties are populated and mention PDO::FETCH_PROPS_LATE consistently.

Co-authored-by: Gina Peter Banyard <[email protected]>
Co-authored-by: Kamil Tekiela <[email protected]>

Author: 3 people

reference/pdo/constants.xml

@@ -242,13 +242,20 @@
    <listitem>
     <simpara>
      Specifies that the fetch method shall return a new instance of the
-     requested class, mapping the columns to named properties in the class.
+     requested class.
     </simpara>
     <note>
      <simpara>
-      The magic
-      <link linkend="language.oop5.overloading.members"><methodname>__set</methodname></link>
-      method is called if the property doesn't exist in the requested class
+      The object is initialized by mapping the columns from the result set to
+      properties in the class. This process occurs before the constructor is
+      called, allowing the population of properties regardless of their
+      visibility or whether they are marked as <literal>readonly</literal>. If
+      a property does not exist in the class, the magic
+      <link linkend="object.set">__set()</link>
+      method will be invoked if it exists; otherwise, a dynamic public property
+      will be created. However, when <constant>PDO::FETCH_PROPS_LATE</constant>
+      is also given, the constructor is called <emphasis>before</emphasis> the
+      properties are populated.
      </simpara>
     </note>
    </listitem>

reference/pdo/pdostatement/fetch.xml

@@ -53,13 +53,18 @@
         </para></listitem>
         <listitem><para>
          <literal>PDO::FETCH_CLASS</literal>: returns a new instance of the
-         requested class, mapping the columns of the result set to named
-         properties in the class, and calling the constructor afterwards, unless
-         <literal>PDO::FETCH_PROPS_LATE</literal> is also given.
-         If <parameter>mode</parameter>
-         includes PDO::FETCH_CLASSTYPE (e.g. <literal>PDO::FETCH_CLASS |
-         PDO::FETCH_CLASSTYPE</literal>) then the name of the class is
-         determined from a value of the first column.
+         requested class. The object is initialized by mapping the columns of
+         the result set to properties in the class. This occurs before the
+         constructor is called, allowing properties to be populated regardless
+         of their visibility or whether they are marked as <literal>readonly</literal>.
+         If a property does not exist in the class, the magic <link linkend="object.set">__set()</link>
+         method will be invoked if it exists; otherwise, a dynamic public
+         property will be created. However, when <constant>PDO::FETCH_PROPS_LATE</constant>
+         is also given, the constructor is called <emphasis>before</emphasis>
+         the properties are populated. If <parameter>mode</parameter> includes
+         <constant>PDO::FETCH_CLASSTYPE</constant> (e.g.
+         <literal>PDO::FETCH_CLASS | PDO::FETCH_CLASSTYPE</literal>), the name
+         of the class is determined from the value of the first column.
         </para></listitem>
         <listitem><para>
          <literal>PDO::FETCH_INTO</literal>: updates an existing instance
@@ -266,11 +271,11 @@ Reading backwards:
 
    <example><title>Construction order</title>
     <simpara>
-     When objects are fetched via <literal>PDO::FETCH_CLASS</literal> the object
+     When objects are fetched via <constant>PDO::FETCH_CLASS</constant>, the object
      properties are assigned first, and then the constructor of the class is
-     invoked. If <literal>PDO::FETCH_PROPS_LATE</literal> is also given, this
-     order is reversed, i.e. first the constructor is called, and afterwards the
-     properties are assigned.
+     invoked. However, when <constant>PDO::FETCH_PROPS_LATE</constant> is also given,
+     this order is reversed, i.e. first the constructor is called, and
+     afterwards the properties are assigned.
     </simpara>
     <programlisting role="php">
 <![CDATA[