Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 0 additions & 34 deletions docs/en/appendices/6-0-migration-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
27 changes: 20 additions & 7 deletions docs/en/orm/query-builder.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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:

Expand Down Expand Up @@ -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

Expand All @@ -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
Expand Down
Loading