Debian Codegraph @

vendor/doctrine/collections/docs/en/index.rst

raw
1 Getting Started
2 ===============
3
4 Introduction
5 ------------
6
7 Doctrine Collections is a library that contains classes for working with
8 arrays of data. Here is an example using the simple
9 ``Doctrine\Common\Collections\ArrayCollection`` class:
10
11 .. code-block:: php
12 <?php
13
14 use Doctrine\Common\Collections\ArrayCollection;
15
16 $collection = new ArrayCollection([1, 2, 3]);
17
18 $filteredCollection = $collection->filter(static fn ($element): bool => $element > 1); // [2, 3]
19
20 Collection Methods
21 ------------------
22
23 Doctrine Collections provides an interface named ``Doctrine\Common\Collections\Collection``
24 that resembles the nature of a regular PHP array. That is,
25 it is essentially an **ordered map** that can also be used
26 like a list.
27
28 A Collection has an internal iterator just like a PHP array. In addition,
29 a Collection can be iterated with external iterators, which is preferable.
30 To use an external iterator simply use the foreach language construct to
31 iterate over the collection, which calls ``getIterator()`` internally, or
32 explicitly retrieve an iterator though ``getIterator()`` which can then be
33 used to iterate over the collection. You can not rely on the internal iterator
34 of the collection being at a certain position unless you explicitly positioned it before.
35
36 Methods that do not alter the collection or have template types
37 appearing in invariant or contravariant positions are not directly
38 defined in ``Doctrine\Common\Collections\Collection``, but are inherited
39 from the ``Doctrine\Common\Collections\ReadableCollection`` interface.
40
41 The methods available on the interface are:
42
43 add
44 ^^^
45
46 Adds an element at the end of the collection.
47
48 .. code-block:: php
49 $collection->add('test');
50
51 clear
52 ^^^^^
53
54 Clears the collection, removing all elements.
55
56 .. code-block:: php
57 $collection->clear();
58
59 contains
60 ^^^^^^^^
61
62 Checks whether an element is contained in the collection. This is an O(n) operation, where n is the size of the collection.
63
64 .. code-block:: php
65 $collection = new Collection(['test']);
66
67 $contains = $collection->contains('test'); // true
68
69 containsKey
70 ^^^^^^^^^^^
71
72 Checks whether the collection contains an element with the specified key/index.
73
74 .. code-block:: php
75 $collection = new Collection(['test' => true]);
76
77 $contains = $collection->containsKey('test'); // true
78
79 current
80 ^^^^^^^
81
82 Gets the element of the collection at the current iterator position.
83
84 .. code-block:: php
85 $collection = new Collection(['first', 'second', 'third']);
86
87 $current = $collection->current(); // first
88
89 get
90 ^^^
91
92 Gets the element at the specified key/index.
93
94 .. code-block:: php
95 $collection = new Collection([
96 'key' => 'value',
97 ]);
98
99 $value = $collection->get('key'); // value
100
101 getKeys
102 ^^^^^^^
103
104 Gets all keys/indices of the collection.
105
106 .. code-block:: php
107 $collection = new Collection(['a', 'b', 'c']);
108
109 $keys = $collection->getKeys(); // [0, 1, 2]
110
111 getValues
112 ^^^^^^^^^
113
114 Gets all values of the collection.
115
116 .. code-block:: php
117 $collection = new Collection([
118 'key1' => 'value1',
119 'key2' => 'value2',
120 'key3' => 'value3',
121 ]);
122
123 $values = $collection->getValues(); // ['value1', 'value2', 'value3']
124
125 isEmpty
126 ^^^^^^^
127
128 Checks whether the collection is empty (contains no elements).
129
130 .. code-block:: php
131 $collection = new Collection(['a', 'b', 'c']);
132
133 $isEmpty = $collection->isEmpty(); // false
134
135 first
136 ^^^^^
137
138 Sets the internal iterator to the first element in the collection and returns this element.
139
140 .. code-block:: php
141 $collection = new Collection(['first', 'second', 'third']);
142
143 $first = $collection->first(); // first
144
145 exists
146 ^^^^^^
147
148 Tests for the existence of an element that satisfies the given predicate.
149
150 .. code-block:: php
151 $collection = new Collection(['first', 'second', 'third']);
152
153 $exists = $collection->exists(static fn ($key, $value): bool => $value === 'first'); // true
154
155 findFirst
156 ^^^^^^^^^
157
158 Returns the first element of this collection that satisfies the given predicate.
159
160 .. code-block:: php
161 $collection = new Collection([1, 2, 3, 2, 1]);
162
163 $one = $collection->findFirst(static fn (int $key, int $value): bool => $value > 2 && $key > 1); // 3
164
165 filter
166 ^^^^^^
167
168 Returns all the elements of this collection for which your callback function returns `true`.
169 The order and keys of the elements are preserved.
170
171 .. code-block:: php
172 $collection = new ArrayCollection([1, 2, 3]);
173
174 $filteredCollection = $collection->filter(static fn ($element): bool => $element > 1); // [2, 3]
175
176 forAll
177 ^^^^^^
178
179 Tests whether the given predicate holds for all elements of this collection.
180
181 .. code-block:: php
182 $collection = new ArrayCollection([1, 2, 3]);
183
184 $forAll = $collection->forAll(static fn ($key, $value): bool => $value > 1); // false
185
186 indexOf
187 ^^^^^^^
188
189 Gets the index/key of a given element. The comparison of two elements is strict, that means not only the value but also the type must match. For objects this means reference equality.
190
191 .. code-block:: php
192 $collection = new ArrayCollection([1, 2, 3]);
193
194 $indexOf = $collection->indexOf(3); // 2
195
196 key
197 ^^^
198
199 Gets the key/index of the element at the current iterator position.
200
201 .. code-block:: php
202 $collection = new ArrayCollection([1, 2, 3]);
203
204 $collection->next();
205
206 $key = $collection->key(); // 1
207
208 last
209 ^^^^
210
211 Sets the internal iterator to the last element in the collection and returns this element.
212
213 .. code-block:: php
214 $collection = new ArrayCollection([1, 2, 3]);
215
216 $last = $collection->last(); // 3
217
218 map
219 ^^^
220
221 Applies the given function to each element in the collection and returns a new collection with the elements returned by the function.
222
223 .. code-block:: php
224 $collection = new ArrayCollection([1, 2, 3]);
225
226 $mappedCollection = $collection->map(static fn (int $value): int => $value + 1); // [2, 3, 4]
227
228 reduce
229 ^^^^^^
230
231 Applies iteratively the given function to each element in the collection, so as to reduce the collection to a single value.
232
233 .. code-block:: php
234 $collection = new ArrayCollection([1, 2, 3]);
235
236 $reduce = $collection->reduce(static fn (int $accumulator, int $value): int => $accumulator + $value, 0); // 6
237
238 next
239 ^^^^
240
241 Moves the internal iterator position to the next element and returns this element.
242
243 .. code-block:: php
244 $collection = new ArrayCollection([1, 2, 3]);
245
246 $next = $collection->next(); // 2
247
248 partition
249 ^^^^^^^^^
250
251 Partitions this collection in two collections according to a predicate. Keys are preserved in the resulting collections.
252
253 .. code-block:: php
254 $collection = new ArrayCollection([1, 2, 3]);
255
256 $mappedCollection = $collection->partition(static fn ($key, $value): bool => $value > 1); // [[2, 3], [1]]
257
258 remove
259 ^^^^^^
260
261 Removes the element at the specified index from the collection.
262
263 .. code-block:: php
264 $collection = new ArrayCollection([1, 2, 3]);
265
266 $collection->remove(0); // [2, 3]
267
268 removeElement
269 ^^^^^^^^^^^^^
270
271 Removes the specified element from the collection, if it is found.
272
273 .. code-block:: php
274 $collection = new ArrayCollection([1, 2, 3]);
275
276 $collection->removeElement(3); // [1, 2]
277
278 set
279 ^^^
280
281 Sets an element in the collection at the specified key/index.
282
283 .. code-block:: php
284 $collection = new ArrayCollection();
285
286 $collection->set('name', 'jwage');
287
288 slice
289 ^^^^^
290
291 Extracts a slice of $length elements starting at position $offset from the Collection. If $length is null it returns all elements from $offset to the end of the Collection. Keys have to be preserved by this method. Calling this method will only return the selected slice and NOT change the elements contained in the collection slice is called on.
292
293 .. code-block:: php
294 $collection = new ArrayCollection([0, 1, 2, 3, 4, 5]);
295
296 $slice = $collection->slice(1, 2); // [1, 2]
297
298 toArray
299 ^^^^^^^
300
301 Gets a native PHP array representation of the collection.
302
303 .. code-block:: php
304 $collection = new ArrayCollection([0, 1, 2, 3, 4, 5]);
305
306 $array = $collection->toArray(); // [0, 1, 2, 3, 4, 5]
307
308 Selectable Methods
309 ------------------
310
311 Some Doctrine Collections, like ``Doctrine\Common\Collections\ArrayCollection``,
312 implement an interface named ``Doctrine\Common\Collections\Selectable``
313 that offers the usage of a powerful expressions API, where conditions
314 can be applied to a collection to get a result with matching elements
315 only.
316
317 matching
318 ^^^^^^^^
319
320 Selects all elements from a selectable that match the expression and
321 returns a new collection containing these elements and preserved keys.
322
323 .. code-block:: php
324 use Doctrine\Common\Collections\Criteria;
325 use Doctrine\Common\Collections\Expr\Comparison;
326
327 $collection = new ArrayCollection([
328 'wage' => [
329 'name' => 'jwage',
330 ],
331 'roman' => [
332 'name' => 'romanb',
333 ],
334 ]);
335
336 $expr = new Comparison('name', '=', 'jwage');
337
338 $criteria = new Criteria();
339
340 $criteria->where($expr);
341
342 $matchingCollection = $collection->matching($criteria); // [ 'wage' => [ 'name' => 'jwage' ]]
343
344 You can read more about expressions :ref:`here <expressions>`.
345
346 .. note::
347
348 Currently, expressions use strict comparison for the ``EQ`` (equal) and ``NEQ`` (not equal)
349 checks. That makes them behave more naturally as long as only scalar values are involved.
350 For example, ``'04'`` and ``4`` are *not* equal.
351
352 However, this can lead to surprising results when working with objects, especially objects
353 representing values. ``DateTime`` and ``DateTimeImmutable`` are two widespread examples for
354 objects that would typically rather be compared by their value than by identity.
355
356 Comparative operators like ``GT`` or ``LTE`` as well as ``IN`` and ``NIN`` do
357 not exhibit this behavior.
358
359 Also, multi-dimensional sorting based on non-scalar values will only consider the
360 next sort criteria for *identical* matches, which may not give the expected results
361 when objects come into play. Keep this in mind, for example, when sorting by fields that
362 contain ``DateTime`` or ``DateTimeImmutable`` objects.
363
364 .. note::
365
366 For collections that contain objects, the field name given to ``Comparison`` will
367 lead to various access methods being tried in sequence. This behavior is deprecated
368 as of v2.4.0. Set the ``$accessRawFieldValues`` parameter in the ``Criteria`` constructor
369 to ``true`` to opt-in to the new behaviour of using direct (reflection-based) field access only.
370 This will be the only option in the next major version.
371
372 Unless you opt in, refer to the ``ClosureExpressionVisitor::getObjectFieldValue()`` method
373 for the exact order of accessors tried. Roughly speaking, for a field named ``field``,
374 the following things will be tried in order:
375
376 1. ``getField()``, ``isField()`` and ``field()`` as getter methods
377 2. When the object implements a ``__call`` magic method, invoke it
378 by calling ``getField()``
379 3. When the object implements ``ArrayAccess``, use that to access the
380 ``field`` offset
381 4. When the object contains a ``::$field`` public property that is not
382 ``null``, access it directly
383 5. Convert snake-case field names to camel case and retry the ``get``, ``is``
384 and prefixless accessor methods
385 6. Direct access to ``::$field``, which must be a public property, as a
386 last resort.