From fb5ef0293e210f26025c4f012f784ae92a1ca805 Mon Sep 17 00:00:00 2001
From: Ingo Schommer <ingo@silverstripe.com>
Date: Tue, 2 Apr 2013 12:20:36 +0200
Subject: [PATCH] Clearer docs on where SQL strings are expected to be escaped
 already

Also quoted some phpdoc examples, to avoid them failing by default on
stricter DB drivers like Postgres
---
 model/DataQuery.php | 16 +++++++++-------
 model/Database.php  | 16 ++++++++++++++++
 2 files changed, 25 insertions(+), 7 deletions(-)

diff --git a/model/DataQuery.php b/model/DataQuery.php
index 361515820..cda34707c 100644
--- a/model/DataQuery.php
+++ b/model/DataQuery.php
@@ -139,6 +139,8 @@ class DataQuery {
 
 	/**
 	 * Ensure that the query is ready to execute.
+	 *
+	 * @return SQLQuery
 	 */
 	public function getFinalisedQuery($queriedColumns = null) {
 		if(!$queriedColumns) $queriedColumns = $this->queriedColumns;
@@ -419,7 +421,7 @@ class DataQuery {
 	}
 	
 	/**
-	 * Set the HAVING clause of this query
+	 * Set the HAVING clause of this query.
 	 * 
 	 * @param String $having Escaped SQL statement
 	 */
@@ -458,10 +460,10 @@ class DataQuery {
 	 *
 	 * <code>
 	 *  // the entire predicate as a single string
-	 *  $query->where("Column = 'Value'");
+	 *  $query->where("\"Column\" = 'Value'");
 	 *
 	 *  // multiple predicates as an array
-	 *  $query->where(array("Column = 'Value'", "Column != 'Value'"));
+	 *  $query->where(array("\"Column\" = 'Value'", "\"Column\" != 'Value'"));
 	 * </code>
 	 *
 	 * @param string|array $where Predicate(s) to set, as escaped SQL statements.
@@ -476,7 +478,7 @@ class DataQuery {
 	/**
 	 * Set a WHERE with OR.
 	 * 
-	 * @example $dataQuery->whereAny(array("Monkey = 'Chimp'", "Color = 'Brown'"));
+	 * @example $dataQuery->whereAny(array("\"Monkey\" = 'Chimp'", "\"Color\" = 'Brown'"));
 	 * @see where()
 	 *
 	 * @param array $filter Escaped SQL statement.
@@ -778,10 +780,10 @@ class DataQuery_SubGroup extends DataQuery {
 	 *
 	 * <code>
 	 *  // the entire predicate as a single string
-	 *  $query->where("Column = 'Value'");
+	 *  $query->where("\"Column\" = 'Value'");
 	 *
 	 *  // multiple predicates as an array
-	 *  $query->where(array("Column = 'Value'", "Column != 'Value'"));
+	 *  $query->where(array("\"Column\" = 'Value'", "\"Column\" != 'Value'"));
 	 * </code>
 	 *
 	 * @param string|array $where Predicate(s) to set, as escaped SQL statements.
@@ -796,7 +798,7 @@ class DataQuery_SubGroup extends DataQuery {
 	/**
 	 * Set a WHERE with OR.
 	 * 
-	 * @example $dataQuery->whereAny(array("Monkey = 'Chimp'", "Color = 'Brown'"));
+	 * @example $dataQuery->whereAny(array("\"Monkey\" = 'Chimp'", "\"Color\" = 'Brown'"));
 	 * @see where()
 	 *
 	 * @param array $filter Escaped SQL statement.
diff --git a/model/Database.php b/model/Database.php
index 7770f03d2..ea73d5503 100644
--- a/model/Database.php
+++ b/model/Database.php
@@ -750,6 +750,8 @@ abstract class SS_Database {
 
 	/**
 	 * Returns the SELECT clauses ready for inserting into a query.
+	 * Caution: Expects correctly quoted and escaped SQL fragments.
+	 * 
 	 * @param array $select Select columns
 	 * @param boolean $distinct Distinct select?
 	 * @return string
@@ -770,6 +772,8 @@ abstract class SS_Database {
 
 	/**
 	 * Return the FROM clause ready for inserting into a query.
+	 * Caution: Expects correctly quoted and escaped SQL fragments.
+	 * 
 	 * @return string
 	 */
 	public function sqlFromToString($from) {
@@ -778,6 +782,8 @@ abstract class SS_Database {
 
 	/**
 	 * Returns the WHERE clauses ready for inserting into a query.
+	 * Caution: Expects correctly quoted and escaped SQL fragments.
+	 * 
 	 * @return string
 	 */
 	public function sqlWhereToString($where, $connective) {
@@ -786,6 +792,8 @@ abstract class SS_Database {
 
 	/**
 	 * Returns the ORDER BY clauses ready for inserting into a query.
+	 * Caution: Expects correctly quoted and escaped SQL fragments.
+	 * 
 	 * @return string
 	 */
 	public function sqlOrderByToString($orderby) {
@@ -800,6 +808,8 @@ abstract class SS_Database {
 
 	/**
 	 * Returns the GROUP BY clauses ready for inserting into a query.
+	 * Caution: Expects correctly quoted and escaped SQL fragments.
+	 * 
 	 * @return string
 	 */
 	public function sqlGroupByToString($groupby) {
@@ -808,6 +818,8 @@ abstract class SS_Database {
 
 	/**
 	 * Returns the HAVING clauses ready for inserting into a query.
+	 * Caution: Expects correctly quoted and escaped SQL fragments.
+	 * 
 	 * @return string
 	 */
 	public function sqlHavingToString($having) {
@@ -816,6 +828,8 @@ abstract class SS_Database {
 
 	/**
 	 * Return the LIMIT clause ready for inserting into a query.
+	 * Caution: Expects correctly quoted and escaped SQL fragments.
+	 * 
 	 * @return string
 	 */
 	public function sqlLimitToString($limit) {
@@ -847,6 +861,8 @@ abstract class SS_Database {
 
 	/**
 	 * Convert a SQLQuery object into a SQL statement
+	 * Caution: Expects correctly quoted and escaped SQL fragments.
+	 * 
 	 * @param $query SQLQuery
 	 */
 	public function sqlQueryToString(SQLQuery $query) {