diff --git a/docs/en/appendices/6-0-migration-guide.md b/docs/en/appendices/6-0-migration-guide.md index bf13575b12..7343e6e4f4 100644 --- a/docs/en/appendices/6-0-migration-guide.md +++ b/docs/en/appendices/6-0-migration-guide.md @@ -157,40 +157,6 @@ Some properties have also been renamed to better reflect their purpose. These ar [Building Conditions with Expressions](../orm/query-builder#building-conditions-with-expressions) for updated examples. -- Operators in condition-array keys, such as `['views >' => 1000]` or - `['id IN' => $ids]`, are no longer supported and raise an - `InvalidArgumentException`. Use the predicate functions in - `Cake\Database\Expression` instead. Plain equality conditions, nested boolean - arrays, and the fluent `QueryExpression` API remain supported. - - ```php - use function Cake\Database\Expression\{equals, greaterThan, in, notEquals}; - - // Before (CakePHP 5.x) - $query->where([ - 'views >' => 1000, - 'id IN' => $ids, - 'parent_id IS' => $parentId, - 'deleted IS NOT' => null, - ]); - - // After (CakePHP 6.x) - $query->where([ - 'views' => greaterThan(1000), - 'id' => in($ids), - 'parent_id' => equals($parentId), - 'deleted' => notEquals(null), - ]); - ``` - - `equals()` and `notEquals()` generate `IS NULL` and `IS NOT NULL` when their - value is `null`. Use `isNull()` and `isNotNull()` for explicit null checks. - Predicates infer binding types from the query; pass `type:` to override them. - The [upgrade tool](6-0-upgrade-guide#upgrade-tool-use) includes this conversion - in its `cakephp60` rules. See - [Predicate Functions](../orm/query-builder#predicate-functions) for the full - function reference and examples. - - Binary columns now use `binary` for fixed-length data and `varbinary` for variable-length data. In migration `addColumn()` calls, remove `'fixed' => true` from fixed-length `binary` columns, and change variable-length diff --git a/docs/en/orm/query-builder.md b/docs/en/orm/query-builder.md index 6a5fb571da..98a82836fd 100644 --- a/docs/en/orm/query-builder.md +++ b/docs/en/orm/query-builder.md @@ -14,7 +14,7 @@ queries using unions and subqueries with ease. Underneath the covers, the query builder uses PDO prepared statements which protect against SQL injection attacks. -For comparisons in condition arrays, import the predicate functions from +For comparisons in condition arrays, you can import the predicate functions from `Cake\Database\Expression` with `use function`. The array key supplies the field, and the predicate supplies the operator and values. See [Predicate Functions](#predicate-functions) for the available functions. @@ -1093,10 +1093,21 @@ WHERE published = true AND title LIKE '%cake%' ``` -The values are bound as parameters. Condition keys must contain only the field -or a trusted SQL expression. CakePHP 6 no longer accepts operators in array keys -such as `'view_count >'` or `'title LIKE'`; these raise an -`InvalidArgumentException`. +The values are bound as parameters. Operators in condition-array keys, such as +`'view_count >'` or `'title LIKE'`, remain supported. You can mix both styles: + +```php +use function Cake\Database\Expression\greaterThan; + +$query = $articles->find()->where([ + 'view_count' => greaterThan(1000), + 'title LIKE' => '%cake%', +]); +``` + +When the value is a predicate, the key must contain only the field or a trusted +SQL expression. Combining an operator in the key with a predicate, such as +`['view_count >' => greaterThan(1000)]`, raises an `InvalidArgumentException`. The following predicate functions are available: @@ -1740,7 +1751,8 @@ $query = $categories->find() The above will generate `parent_id = :c1` or `parent_id IS NULL` depending on whether `$parentId` is `null`. Use `isNull()` for an unconditional null check. A plain condition such as `['parent_id' => null]` raises an -`InvalidArgumentException`; a null-aware predicate is required. +`InvalidArgumentException`. Use a null-aware predicate or an explicit `IS` +operator, such as `['parent_id IS' => $parentId]`. ### Automatic IS NOT NULL Creation @@ -1755,7 +1767,8 @@ $query = $categories->find() The above will generate `parent_id != :c1` or `parent_id IS NOT NULL` depending on whether `$parentId` is `null`. Use `isNotNull()` for an -unconditional non-null check. Ordering and pattern predicates such as +unconditional non-null check. You can also use an explicit `IS NOT` operator, +such as `['parent_id IS NOT' => $parentId]`. Ordering and pattern predicates such as `greaterThan()` and `like()` reject `null` values. ### Raw Expressions