Skip to content
Permalink
Browse files

Better document unsafe inputs in the QueryBuilder.

Better document which methods are not safe for untrusted data.

Refs #11148
  • Loading branch information...
markstory committed Sep 13, 2017
1 parent 6829ddd commit b2b45af37f807068f6c23f152fe6e5bf64656915
Showing with 41 additions and 15 deletions.
  1. +41 −15 src/Database/Query.php
@@ -315,7 +315,7 @@ public function traverse(callable $visitor, array $parts = [])
}
/**
* 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 @@ public function select($fields = [], $overwrite = false)
}
/**
* 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 @@ public function distinct($on = [], $overwrite = false)
}
/**
* 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 @@ public function from($tables = [], $overwrite = false)
* 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 @@ public function removeJoin($name)
}
/**
* 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 @@ public function leftJoin($table, $conditions = [], $types = [])
}
/**
* 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 @@ public function rightJoin($table, $conditions = [], $types = [])
}
/**
* 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 @@ protected function _makeJoin($table, $conditions, $type)
* 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 @@ protected function _makeJoin($table, $conditions, $type)
*
* 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 @@ protected function _makeJoin($table, $conditions, $type)
* 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 @@ protected function _makeJoin($table, $conditions, $type)
* `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 @@ public function orWhere($conditions, $types = [])
*
* `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 @@ public function order($fields, $overwrite = false)
* 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 @@ public function orderAsc($field, $overwrite = false)
* 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 @@ public function orderDesc($field, $overwrite = false)
* $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 @@ public function group($fields, $overwrite = false)
}
/**
* 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 @@ public function having($conditions = null, $types = [], $overwrite = false)
* 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 @@ public function andHaving($conditions, $types = [])
* 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 @@ public function delete($table = null)
* ->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
*/

0 comments on commit b2b45af

Please sign in to comment.
You can’t perform that action at this time.