From 0cc39af382513b48a29634556cb25dda42b7e02e Mon Sep 17 00:00:00 2001
From: Sam Minnee <sam@silverstripe.com>
Date: Fri, 9 Nov 2018 11:08:36 +1300
Subject: [PATCH] DOC: Added documentation for strict type changes

---
 .../00_Model/08_SQL_Select.md                    | 12 ++++++++++++
 docs/en/04_Changelogs/4.4.0.md                   | 14 ++++++++++++++
 src/ORM/Connect/Query.php                        | 16 ++++++++++++++--
 src/ORM/Connect/TransactionManager.php           | 12 ++++++++++--
 4 files changed, 50 insertions(+), 4 deletions(-)
 create mode 100644 docs/en/04_Changelogs/4.4.0.md

diff --git a/docs/en/02_Developer_Guides/00_Model/08_SQL_Select.md b/docs/en/02_Developer_Guides/00_Model/08_SQL_Select.md
index dc85ec060..ee4c31c81 100644
--- a/docs/en/02_Developer_Guides/00_Model/08_SQL_Select.md
+++ b/docs/en/02_Developer_Guides/00_Model/08_SQL_Select.md
@@ -291,6 +291,18 @@ $players = Player::get();
 $map = $players->map('Name', 'NameWithBirthyear');
 ```
 
+### Data types
+
+As of SilverStripe 4.4, the following PHP types will be used to return datbase content:
+
+ * booleans will be an integer 1 or 0, to ensure consistency with MySQL that doesn't have native booleans.
+ * integer types returned as integers
+ * floating point / decimal types returned as floats
+ * strings returned as strings
+ * dates / datetimes returned as strings
+
+Up until SilverStripe 4.3, bugs meant that strings were used for every column type.
+
 ## Related Lessons
 * [Building custom SQL](https://www.silverstripe.org/learn/lessons/v4/beyond-the-orm-building-custom-sql-1)
 
diff --git a/docs/en/04_Changelogs/4.4.0.md b/docs/en/04_Changelogs/4.4.0.md
new file mode 100644
index 000000000..f37ba13a6
--- /dev/null
+++ b/docs/en/04_Changelogs/4.4.0.md
@@ -0,0 +1,14 @@
+# 4.4.0
+
+## Overview {#overview}
+
+ - [Correct PHP types are now returned from database queries](/developer_guides/model/sql_select#data-types)
+ 
+## Upgrading {#upgrading}
+
+tbc
+
+## Changes to internal APIs
+
+ - `PDOQuery::__construct()` now has a 2nd argument. If you have subclassed PDOQuery and overridden __construct() 
+   you may see an E_STRICT error
diff --git a/src/ORM/Connect/Query.php b/src/ORM/Connect/Query.php
index 4a1b28b88..1f994dd7f 100644
--- a/src/ORM/Connect/Query.php
+++ b/src/ORM/Connect/Query.php
@@ -6,12 +6,24 @@ use SilverStripe\Core\Convert;
 use Iterator;
 
 /**
- * Abstract query-result class.
+ * Abstract query-result class. A query result provides an iterator that returns a map for each record of a query
+ * result.
+ *
+ * The map should be keyed by the column names, and the values should use the following types:
+ *
+ *  - boolean returned as integer 1 or 0 (to ensure consistency with MySQL that doesn't have native booleans)
+ *  - integer types returned as integers
+ *  - floating point / decimal types returned as floats
+ *  - strings returned as strings
+ *  - dates / datetimes returned as strings
+ *
+ * Note that until SilverStripe 4.3, bugs meant that strings were used for every column type.
+ *
  * Once again, this should be subclassed by an actual database implementation.  It will only
  * ever be constructed by a subclass of SS_Database.  The result of a database query - an iteratable object
  * that's returned by DB::SS_Query
  *
- * Primarily, the SS_Query class takes care of the iterator plumbing, letting the subclasses focusing
+ * Primarily, the Query class takes care of the iterator plumbing, letting the subclasses focusing
  * on providing the specific data-access methods that are required: {@link nextRecord()}, {@link numRecords()}
  * and {@link seek()}
  */
diff --git a/src/ORM/Connect/TransactionManager.php b/src/ORM/Connect/TransactionManager.php
index bec59835f..7dbb6be1f 100644
--- a/src/ORM/Connect/TransactionManager.php
+++ b/src/ORM/Connect/TransactionManager.php
@@ -3,7 +3,13 @@
 namespace SilverStripe\ORM\Connect;
 
 /**
- * Represents an object that is capable of controlling transactions
+ * Represents an object that is capable of controlling transactions.
+ *
+ * The TransactionManager might be the database connection itself, calling queries to orchestrate
+ * transactions, or a connector such as the PDOConnector.
+ *
+ * Generally speaking you should rely on your Database object to manage the creation of a TansactionManager
+ * for you; unless you are building new database connectors this should be treated as an internal API.
  */
 interface TransactionManager
 {
@@ -51,7 +57,9 @@ interface TransactionManager
     public function transactionDepth();
 
     /**
-     * Return true if savepoints are supported by this transaction manager
+     * Return true if savepoints are supported by this transaction manager.
+     * Savepoints aren't supported by all database connectors (notably PDO doesn't support them)
+     * and should be used with caution.
      *
      * @return boolean
      */