Collection
La classe Collection fournit une interface fluide et immuable pour manipuler des tableaux et objets. Elle implémente les interfaces IteratorAggregate, Countable et ArrayAccess.
Création
use Elementum\Helpers\Collection; // Depuis un tableau $collection = new Collection([1, 2, 3]); // Depuis un objet $collection = new Collection($monObjet); // Méthode usine (shortcut) $collection = Collection::from([1, 2, 3]);
Méthodes de base
add(mixed $value, string|int|null $key = null): Collection
Ajoute un élément et retourne une nouvelle collection.
$collection = $collection->add('valeur'); $collection = $collection->add('valeur', 'maCle');
remove(string|int ...$keys): Collection
Supprime par clé(s) et retourne une nouvelle collection.
$collection = $collection->remove('cle1', 'cle2');
removeValue(mixed $value, bool $strict = true): Collection
Supprime par valeur (premières occurrences).
$collection = $collection->removeValue('valeur');
set(mixed $key, mixed $value): void
Définit une valeur (modifie la collection courante).
$collection->set('cle', 'valeur');
clear(): Collection
Vide la collection.
$collection = $collection->clear();
Inspection
count(): int
Retourne le nombre d'éléments.
$count = $collection->count();
isEmpty(): bool
Vrai si la collection est vide.
if ($collection->isEmpty()) { // ... }
has(string|int ...$keys): bool
Vrai si toutes les clés existent.
if ($collection->has('id', 'title')) { // ... }
all(): array
Retourne tous les éléments sous forme de tableau.
$items = $collection->all();
first(): mixed
Retourne le premier élément ou null.
$first = $collection->first();
keys(): Collection
Retourne une collection des clés.
$keys = $collection->keys();
values(): Collection
Retourne une collection des valeurs (réindexée).
$values = $collection->values();
Opérations fonctionnelles
map(callable $callback): Collection
Applique une fonction à chaque élément.
$doubled = $collection->map(fn($n) => $n * 2);
filter(callable|array $callback): Collection
Filtre les éléments selon un callback.
$filtered = $collection->filter(fn($n) => $n > 10);
reduce(mixed $initial, callable $callback): mixed
Réduit la collection à une seule valeur.
$sum = $collection->reduce(0, fn($carry, $n) => $carry + $n);
pluck(string|int $key): Collection
Extrait une propriété/clé de chaque élément.
$titles = $collection->pluck('title');
slice(int $offset, ?int $length = null, bool $preserveKeys = false): Collection
Extrait une portion.
$sliced = $collection->slice(0, 10);
sort(?callable $comparator = null): Collection
Tri les éléments.
// Tri par valeur $sorted = $collection->sort(); // Tri personnalisé $sorted = $collection->sort(fn($a, $b) => $b <=> $a);
Conversions
toArray(bool $deep = false): array
Convertit en tableau.
$array = $collection->toArray(); $arrayDeep = $collection->toArray(deep: true);
toStdObject(bool $deep = false): stdClass
Convertit en stdClass.
$obj = $collection->toStdObject();
toObject(string $class): object
Convertit en objet d'une classe spécifique.
$myObj = $collection->toObject(MyClass::class);
Itération
La collection est itérable avec foreach :
foreach ($collection as $key => $value) { echo "$key: $value"; }
Accès par index
La collection implémente ArrayAccess :
// Lecture $value = $collection['maCle']; // Écriture (lève une exception, utiliser set() ou add()) $collection['maCle'] = 'valeur'; // ❌ Exception
Exemple complet
use Elementum\Helpers\Collection; $posts = new Collection($wpQuery->posts); // Filtrer, mapper et extraire $titles = $posts ->filter(fn($post) => $post->post_status === 'publish') ->map(fn($post) => $post->post_title) ->slice(0, 5); // Conversion $array = $titles->toArray();
Notes importantes
-
Immuabilité : La plupart des méthodes (
add,remove,map,filter, etc.) retournent une nouvelle collection. La collection originale n'est pas modifiée. -
Utilisation de
set(): Pour modifier la collection courante, utilisezset(). Pour chaîner les opérations, utilisez les méthodes qui retournent une nouvelle collection. -
Template generics : La classe utilise les generics PHP (
@template TKey,@template TValue) pour un typage statique amélioré.