From e440c79af15cf829549736b2a292b5f8f6887142 Mon Sep 17 00:00:00 2001
From: Christoph Michael Becker <cmb@php.net>
Date: Wed, 29 Jun 2016 11:03:39 +0000
Subject: [PATCH] Fix #53394: Insufficient docs regarding
 PDOStatement::fetch(Object) and constructors

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@339520 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/pdo/pdostatement/fetch.xml       | 60 +++++++++++++++++++++-
 reference/pdo/pdostatement/fetchobject.xml |  4 ++
 2 files changed, 63 insertions(+), 1 deletion(-)

diff --git a/reference/pdo/pdostatement/fetch.xml b/reference/pdo/pdostatement/fetch.xml
index 4624f99b14..85a6829a47 100644
--- a/reference/pdo/pdostatement/fetch.xml
+++ b/reference/pdo/pdostatement/fetch.xml
@@ -54,7 +54,9 @@
         <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. If <parameter>fetch_style</parameter>
+         properties in the class, and calling the constructor afterwards, unless
+         <literal>PDO::FETCH_PROPS_LATE</literal> is also given.
+         If <parameter>fetch_style</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.
@@ -85,6 +87,12 @@
          property names that correspond to the column names returned in your
          result set
         </para></listitem>
+        <listitem><para>
+         <literal>PDO::FETCH_PROPS_LATE</literal>: when used with
+         <literal>PDO::FETCH_CLASS</literal>, the constructor of the class is
+         called before the properties are assigned from the respective column
+         values.
+        </para></listitem>
        </itemizedlist>
       </para>
      </listitem>
@@ -262,6 +270,56 @@ Reading backwards:
     </screen>
    </example>
 
+   <example><title>Construction order</title>
+    <simpara>
+     When objects are fetched via <literal>PDO::FETCH_CLASS</literal> 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.
+    </simpara>
+    <programlisting role="php">
+<![CDATA[
+<?php
+class Person
+{
+    private $name;
+
+    public function __construct()
+    {
+        $this->tell();
+    }
+
+    public function tell()
+    {
+        if (isset($this->name)) {
+            echo "I am {$this->name}.\n";
+        } else {
+            echo "I don't have a name yet.\n";
+        }
+    }
+}
+
+$sth = $dbh->query("SELECT * FROM people");
+$sth->setFetchMode(PDO::FETCH_CLASS, 'Person');
+$person = $sth->fetch();
+$person->tell();
+$sth->setFetchMode(PDO::FETCH_CLASS|PDO::FETCH_PROPS_LATE, 'Person');
+$person = $sth->fetch();
+$person->tell();
+?>
+]]>
+    </programlisting>
+    &example.outputs.similar;
+    <screen>
+<![CDATA[
+I am Alice.
+I am Alice.
+I don't have a name yet.
+I am Bob.
+]]>
+    </screen>
+   </example>
   </para>
  </refsect1>
 
diff --git a/reference/pdo/pdostatement/fetchobject.xml b/reference/pdo/pdostatement/fetchobject.xml
index 754b223bfe..1f29f40125 100644
--- a/reference/pdo/pdostatement/fetchobject.xml
+++ b/reference/pdo/pdostatement/fetchobject.xml
@@ -19,6 +19,10 @@
    <constant>PDO::FETCH_CLASS</constant> or
    <constant>PDO::FETCH_OBJ</constant> style.
   </para>
+  <para>
+   When an object is fetched, its properties are assigned from respective
+   column values, and afterwards its constructor is invoked.
+  </para>
 
  </refsect1>
  <refsect1 role="parameters">