| 1 |
Note about upgrading: Doctrine uses static and runtime mechanisms to raise |
| 2 |
awareness about deprecated code. |
| 3 |
|
| 4 |
- Use of `@deprecated` docblock that is detected by IDEs (like PHPStorm) or |
| 5 |
Static Analysis tools (like Psalm, phpstan) |
| 6 |
- Use of our low-overhead runtime deprecation API, details: |
| 7 |
https://github.com/doctrine/deprecations/ |
| 8 |
|
| 9 |
# Upgrade to 2.6 |
| 10 |
|
| 11 |
When extending `Doctrine\Common\Collections\AbstractLazyCollection`, the |
| 12 |
backing collection initialized in `doInitialize()` must implement |
| 13 |
`Doctrine\Common\Collections\Selectable`. Initializing with a collection that |
| 14 |
does not implement `Selectable` is deprecated and will throw an exception in 3.0. |
| 15 |
|
| 16 |
Also, implementing `ReadableCollection` without implementing `Selectable` |
| 17 |
deprecated and will be an error in 3.0. |
| 18 |
|
| 19 |
# Upgrade to 2.5 |
| 20 |
|
| 21 |
Extending the following classes is deprecated and will no longer be possible in 3.0: |
| 22 |
|
| 23 |
- `Doctrine\Common\Collections\Criteria` |
| 24 |
- `Doctrine\Common\Collections\Expr\ClosureExpressionVisitor` |
| 25 |
- `Doctrine\Common\Collections\Expr\Comparison` |
| 26 |
- `Doctrine\Common\Collections\Expr\CompositeExpression` |
| 27 |
- `Doctrine\Common\Collections\Expr\Value` |
| 28 |
- `Doctrine\Common\Collections\ExpressionBuilder` |
| 29 |
|
| 30 |
# Upgrade to 2.4 |
| 31 |
|
| 32 |
## Deprecated accessing fields through other means than raw field access when using the criteria filtering API (the `Doctrine\Common\Collections\Selectable` interface) |
| 33 |
|
| 34 |
Starting with the next major version, the only way to access data when using the criteria filtering |
| 35 |
API is through direct (reflection-based) access at properties directly, also bypassing property hooks. |
| 36 |
This is to ensure consistency with how the ORM/ODM works. See https://github.com/doctrine/collections/pull/472 for |
| 37 |
the full motivation. |
| 38 |
|
| 39 |
To opt-in to the new behaviour, pass `true` for the `$accessRawFieldValues` parameter when creating a `Criteria` |
| 40 |
object through either `Doctrine\Common\Collections\Criteria::create()` or when calling the `Doctrine\Common\Collections\Criteria` constructor. |
| 41 |
|
| 42 |
Be aware that switching to reflection-based field access may prevent ORM or ODM proxy objects |
| 43 |
becoming initialized, since their triggers (like calling public methods) are bypassed. This might lead |
| 44 |
to `null` values being read from such objects, which may cause wrong filtering or sorting results. |
| 45 |
To avoid this issue, use native lazy objects added in PHP 8.4. |
| 46 |
See https://github.com/doctrine/collections/issues/487 for more details on when this may happen. |
| 47 |
|
| 48 |
# Upgrade to 2.2 |
| 49 |
|
| 50 |
## Deprecated string representation of sort order |
| 51 |
|
| 52 |
Criteria orderings direction is now represented by the |
| 53 |
`Doctrine\Common\Collection\Order` enum. |
| 54 |
|
| 55 |
As a consequence: |
| 56 |
|
| 57 |
- `Criteria::ASC` and `Criteria::DESC` are deprecated in favor of |
| 58 |
`Order::Ascending` and `Order::Descending`, respectively. |
| 59 |
- `Criteria::getOrderings()` is deprecated in favor of `Criteria::orderings()`, |
| 60 |
which returns `array<string, Order>`. |
| 61 |
- `Criteria::orderBy()` accepts `array<string, string|Order>`, but passing |
| 62 |
anything other than `array<string, Order>` is deprecated. |
| 63 |
|
| 64 |
# Upgrade to 2.0 |
| 65 |
|
| 66 |
## BC breaking changes |
| 67 |
|
| 68 |
Native parameter types were added. Native return types will be added in 3.0.x |
| 69 |
As a consequence, some signatures were changed and will have to be adjusted in sub-classes. |
| 70 |
|
| 71 |
Note that in order to keep compatibility with both 1.x and 2.x versions, |
| 72 |
extending code would have to omit the added parameter types. |
| 73 |
This would only work in PHP 7.2+ which is the first version featuring |
| 74 |
[parameter widening](https://wiki.php.net/rfc/parameter-no-type-variance). |
| 75 |
It is also recommended to add return types according to the tables below |
| 76 |
|
| 77 |
You can find a list of major changes to public API below. |
| 78 |
|
| 79 |
### Doctrine\Common\Collections\Collection |
| 80 |
|
| 81 |
| 1.0.x | 3.0.x | |
| 82 |
|---------------------------------:|:-------------------------------------------------| |
| 83 |
| `add($element)` | `add(mixed $element): void` | |
| 84 |
| `clear()` | `clear(): void` | |
| 85 |
| `contains($element)` | `contains(mixed $element): bool` | |
| 86 |
| `isEmpty()` | `isEmpty(): bool` | |
| 87 |
| `removeElement($element)` | `removeElement(mixed $element): bool` | |
| 88 |
| `containsKey($key)` | `containsKey(string\|int $key): bool` | |
| 89 |
| `get()` | `get(string\|int $key): mixed` | |
| 90 |
| `getKeys()` | `getKeys(): array` | |
| 91 |
| `getValues()` | `getValues(): array` | |
| 92 |
| `set($key, $value)` | `set(string\|int $key, $value): void` | |
| 93 |
| `toArray()` | `toArray(): array` | |
| 94 |
| `first()` | `first(): mixed` | |
| 95 |
| `last()` | `last(): mixed` | |
| 96 |
| `key()` | `key(): int\|string\|null` | |
| 97 |
| `current()` | `current(): mixed` | |
| 98 |
| `next()` | `next(): mixed` | |
| 99 |
| `exists(Closure $p)` | `exists(Closure $p): bool` | |
| 100 |
| `filter(Closure $p)` | `filter(Closure $p): self` | |
| 101 |
| `forAll(Closure $p)` | `forAll(Closure $p): bool` | |
| 102 |
| `map(Closure $func)` | `map(Closure $func): self` | |
| 103 |
| `partition(Closure $p)` | `partition(Closure $p): array` | |
| 104 |
| `indexOf($element)` | `indexOf(mixed $element): int\|string\|false` | |
| 105 |
| `slice($offset, $length = null)` | `slice(int $offset, ?int $length = null): array` | |
| 106 |
| `count()` | `count(): int` | |
| 107 |
| `getIterator()` | `getIterator(): \Traversable` | |
| 108 |
| `offsetSet($offset, $value)` | `offsetSet(mixed $offset, mixed $value): void` | |
| 109 |
| `offsetUnset($offset)` | `offsetUnset(mixed $offset): void` | |
| 110 |
| `offsetExists($offset)` | `offsetExists(mixed $offset): bool` | |
| 111 |
|
| 112 |
### Doctrine\Common\Collections\AbstractLazyCollection |
| 113 |
|
| 114 |
| 1.0.x | 3.0.x | |
| 115 |
|------------------:|:------------------------| |
| 116 |
| `isInitialized()` | `isInitialized(): bool` | |
| 117 |
| `initialize()` | `initialize(): void` | |
| 118 |
| `doInitialize()` | `doInitialize(): void` | |
| 119 |
|
| 120 |
### Doctrine\Common\Collections\ArrayCollection |
| 121 |
|
| 122 |
| 1.0.x | 3.0.x | |
| 123 |
|------------------------------:|:--------------------------------------| |
| 124 |
| `createFrom(array $elements)` | `createFrom(array $elements): static` | |
| 125 |
| `__toString()` | `__toString(): string` | |
| 126 |
|
| 127 |
### Doctrine\Common\Collections\Criteria |
| 128 |
|
| 129 |
| 1.0.x | 3.0.x | |
| 130 |
|------------------------------------------:|:--------------------------------------------| |
| 131 |
| `where(Expression $expression): self` | `where(Expression $expression): static` | |
| 132 |
| `andWhere(Expression $expression): self` | `andWhere(Expression $expression): static` | |
| 133 |
| `orWhere(Expression $expression): self` | `orWhere(Expression $expression): static` | |
| 134 |
| `orderBy(array $orderings): self` | `orderBy(array $orderings): static` | |
| 135 |
| `setFirstResult(?int $firstResult): self` | `setFirstResult(?int $firstResult): static` | |
| 136 |
| `setMaxResult(?int $maxResults): self` | `setMaxResults(?int $maxResults): static` | |
| 137 |
|
| 138 |
### Doctrine\Common\Collections\Selectable |
| 139 |
|
| 140 |
| 1.0.x | 3.0.x | |
| 141 |
|-------------------------------:|:-------------------------------------------| |
| 142 |
| `matching(Criteria $criteria)` | `matching(Criteria $criteria): Collection` | |
| 143 |
|
| 144 |
# Upgrade to 1.7 |
| 145 |
|
| 146 |
## Deprecated null first result |
| 147 |
|
| 148 |
Passing null as `$firstResult` to |
| 149 |
`Doctrine\Common\Collections\Criteria::__construct()` and to |
| 150 |
`Doctrine\Common\Collections\Criteria::setFirstResult()` is deprecated. |
| 151 |
Use `0` instead. |