Debian Codegraph @

vendor/doctrine/collections/UPGRADE.md

raw
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.