Merge pull request #11176 from cakephp/issue-11148

Better document unsafe inputs in the QueryBuilder.

src/Database/Query.php

@@ -315,7 +315,7 @@ class Query implements ExpressionInterface, IteratorAggregate
     }
 
     /**
-     * Adds new fields to be returned by a SELECT statement when this query is
+     * Adds new fields to be returned by a `SELECT` statement when this query is
      * executed. Fields can be passed as an array of strings, array of expression
      * objects, a single expression or a single string.
      *
@@ -372,7 +372,7 @@ class Query implements ExpressionInterface, IteratorAggregate
     }
 
     /**
-     * Adds a DISTINCT clause to the query to remove duplicates from the result set.
+     * Adds a `DISTINCT` clause to the query to remove duplicates from the result set.
      * This clause can only be used for select statements.
      *
      * If you wish to filter duplicates based of those rows sharing a particular field
@@ -422,7 +422,7 @@ class Query implements ExpressionInterface, IteratorAggregate
     }
 
     /**
-     * Adds a single or multiple SELECT modifiers to be used in the SELECT.
+     * Adds a single or multiple `SELECT` modifiers to be used in the `SELECT`.
      *
      * By default this function will append any passed argument to the list of modifiers
      * to be applied, unless the second argument is set to true.
@@ -510,11 +510,11 @@ class Query implements ExpressionInterface, IteratorAggregate
      * By default this function will append any passed argument to the list of tables
      * to be joined, unless the third argument is set to true.
      *
-     * When no join type is specified an INNER JOIN is used by default:
+     * When no join type is specified an `INNER JOIN` is used by default:
      * `$query->join(['authors'])` will produce `INNER JOIN authors ON 1 = 1`
      *
      * It is also possible to alias joins using the array key:
-     * `$query->join(['a' => 'authors'])`` will produce `INNER JOIN authors a ON 1 = 1`
+     * `$query->join(['a' => 'authors'])` will produce `INNER JOIN authors a ON 1 = 1`
      *
      * A join can be fully described and aliased using the array notation:
      *
@@ -645,7 +645,7 @@ class Query implements ExpressionInterface, IteratorAggregate
     }
 
     /**
-     * Adds a single LEFT JOIN clause to the query.
+     * Adds a single `LEFT JOIN` clause to the query.
      *
      * This is a shorthand method for building joins via `join()`.
      *
@@ -687,7 +687,7 @@ class Query implements ExpressionInterface, IteratorAggregate
     }
 
     /**
-     * Adds a single RIGHT JOIN clause to the query.
+     * Adds a single `RIGHT JOIN` clause to the query.
      *
      * This is a shorthand method for building joins via `join()`.
      *
@@ -707,7 +707,7 @@ class Query implements ExpressionInterface, IteratorAggregate
     }
 
     /**
-     * Adds a single INNER JOIN clause to the query.
+     * Adds a single `INNER JOIN` clause to the query.
      *
      * This is a shorthand method for building joins via `join()`.
      *
@@ -761,12 +761,12 @@ class Query implements ExpressionInterface, IteratorAggregate
      * string or an array of strings.
      *
      * When using arrays, each entry will be joined to the rest of the conditions using
-     * an AND operator. Consecutive calls to this function will also join the new
+     * an `AND` operator. Consecutive calls to this function will also join the new
      * conditions specified using the AND operator. Additionally, values can be
      * expressed using expression objects which can include other query objects.
      *
-     * Any conditions created with this methods can be used with any SELECT, UPDATE
-     * and DELETE type of queries.
+     * Any conditions created with this methods can be used with any `SELECT`, `UPDATE`
+     * and `DELETE` type of queries.
      *
      * ### Conditions using operators:
      *
@@ -807,7 +807,7 @@ class Query implements ExpressionInterface, IteratorAggregate
      *
      * Keep in mind that every time you call where() with the third param set to false
      * (default), it will join the passed conditions to the previous stored list using
-     * the AND operator. Also, using the same array key twice in consecutive calls to
+     * the `AND` operator. Also, using the same array key twice in consecutive calls to
      * this method will not override the previous value.
      *
      * ### Using expressions objects:
@@ -828,7 +828,7 @@ class Query implements ExpressionInterface, IteratorAggregate
      * You can use callable functions to construct complex expressions, functions
      * receive as first argument a new QueryExpression object and this query instance
      * as second argument. Functions must return an expression object, that will be
-     * added the list of conditions for the query using the AND operator.
+     * added the list of conditions for the query using the `AND` operator.
      *
      * ```
      * $query
@@ -855,8 +855,10 @@ class Query implements ExpressionInterface, IteratorAggregate
      * `WHERE articles.author_id = authors.id AND modified IS NULL`
      *
      * Please note that when using the array notation or the expression objects, all
-     * values will be correctly quoted and transformed to the correspondent database
+     * *values* will be correctly quoted and transformed to the correspondent database
      * data type automatically for you, thus securing your application from SQL injections.
+     * The keys however, are not treated as unsafe input, and should be sanitized/whitelisted.
+     *
      * If you use string conditions make sure that your values are correctly quoted.
      * The safest thing you can do is to never use string conditions.
      *
@@ -1045,6 +1047,10 @@ class Query implements ExpressionInterface, IteratorAggregate
      *
      * `ORDER BY (id %2 = 0), title ASC`
      *
+     * Order fields/directions are not sanitized by the query builder.
+     * You should use a whitelist of fields/directions when passing
+     * in user-supplied data to `order()`.
+     *
      * If you need to set complex expressions as order conditions, you
      * should use `orderAsc()` or `orderDesc()`.
      *
@@ -1076,6 +1082,9 @@ class Query implements ExpressionInterface, IteratorAggregate
      * This method allows you to set complex expressions
      * as order conditions unlike order()
      *
+     * Order fields are not suitable for use with user supplied data as they are
+     * not sanitized by the query builder.
+     *
      * @param string|\Cake\Database\Expression\QueryExpression $field The field to order on.
      * @param bool $overwrite Whether or not to reset the order clauses.
      * @return $this
@@ -1103,6 +1112,9 @@ class Query implements ExpressionInterface, IteratorAggregate
      * This method allows you to set complex expressions
      * as order conditions unlike order()
      *
+     * Order fields are not suitable for use with user supplied data as they are
+     * not sanitized by the query builder.
+     *
      * @param string|\Cake\Database\Expression\QueryExpression $field The field to order on.
      * @param bool $overwrite Whether or not to reset the order clauses.
      * @return $this
@@ -1142,6 +1154,9 @@ class Query implements ExpressionInterface, IteratorAggregate
      * $query->group('title');
      * ```
      *
+     * Group fields are not suitable for use with user supplied data as they are
+     * not sanitized by the query builder.
+     *
      * @param array|\Cake\Database\ExpressionInterface|string $fields fields to be added to the list
      * @param bool $overwrite whether to reset fields with passed list or not
      * @return $this
@@ -1163,11 +1178,14 @@ class Query implements ExpressionInterface, IteratorAggregate
     }
 
     /**
-     * Adds a condition or set of conditions to be used in the HAVING clause for this
+     * Adds a condition or set of conditions to be used in the `HAVING` clause for this
      * query. This method operates in exactly the same way as the method `where()`
      * does. Please refer to its documentation for an insight on how to using each
      * parameter.
      *
+     * Having fields are not suitable for use with user supplied data as they are
+     * not sanitized by the query builder.
+     *
      * @param string|array|\Cake\Database\ExpressionInterface|callable|null $conditions The having conditions.
      * @param array $types associative array of type names used to bind values to query
      * @param bool $overwrite whether to reset conditions with passed list or not
@@ -1190,6 +1208,9 @@ class Query implements ExpressionInterface, IteratorAggregate
      * the same way as the method `andWhere()` does. Please refer to its
      * documentation for an insight on how to using each parameter.
      *
+     * Having fields are not suitable for use with user supplied data as they are
+     * not sanitized by the query builder.
+     *
      * @param string|array|\Cake\Database\ExpressionInterface|callable $conditions The AND conditions for HAVING.
      * @param array $types associative array of type names used to bind values to query
      * @see \Cake\Database\Query::andWhere()
@@ -1208,6 +1229,9 @@ class Query implements ExpressionInterface, IteratorAggregate
      * the same way as the method `orWhere()` does. Please refer to its
      * documentation for an insight on how to using each parameter.
      *
+     * Having fields are not suitable for use with user supplied data as they are
+     * not sanitized by the query builder.
+     *
      * @param string|array|\Cake\Database\ExpressionInterface|callable $conditions The OR conditions for HAVING.
      * @param array $types associative array of type names used to bind values to query.
      * @see \Cake\Database\Query::orWhere()
@@ -1581,6 +1605,8 @@ class Query implements ExpressionInterface, IteratorAggregate
      *  ->epilog('RETURNING id');
      * ```
      *
+     * Epliog content is raw SQL and not suitable for use with user supplied data.
+     *
      * @param string|\Cake\Database\Expression\QueryExpression|null $expression The expression to be appended
      * @return $this
      */