cocoon-projet / collection
0.0.3
2025-02-26 16:40 UTC
Requires
- php: ^8.0
Requires (Dev)
This package is auto-updated.
Last update: 2025-03-23 18:04:49 UTC
README
Cocoon Collection
Une bibliothèque PHP moderne pour manipuler des collections de données avec une interface fluide.
🚀 Installation
composer require cocoon-projet/collection
📋 Prérequis
- PHP 8.0 ou supérieur
- Composer
🎯 Caractéristiques
- Interface fluide pour la manipulation de tableaux
- Support complet du typage PHP 8
- Méthodes de filtrage style SQL (where, whereIn, etc.)
- Fonctions d'agrégation (sum, avg, etc.)
- Manipulation de collections (map, filter, etc.)
- Compatible avec les interfaces PHP standards (Countable, ArrayAccess, IteratorAggregate)
📖 Documentation
Création d'une collection
use Cocoon\Collection\Collection; // Collection vide $collection = new Collection(); // Collection avec des données initiales $collection = new Collection(['un', 'deux', 'trois']); // Collection d'objets ou tableaux associatifs $collection = new Collection([ ['id' => 1, 'nom' => 'Alice'], ['id' => 2, 'nom' => 'Bob'] ]);
Méthodes de Base
Accès aux éléments
// Obtenir tous les éléments $tous = $collection->all(); // Obtenir le premier élément $premier = $collection->first(); // Obtenir le dernier élément $dernier = $collection->last(); // Obtenir un élément spécifique $element = $collection->get('cle', 'valeur_par_defaut');
Manipulation
// Ajouter un élément $collection->set('cle', 'valeur'); // Vérifier l'existence d'un élément $existe = $collection->exists('valeur'); // Supprimer le premier élément $premier = $collection->shift(); // Obtenir une portion de la collection $portion = $collection->slice(0, 2); // Prendre N éléments $elements = $collection->take(3); // 3 premiers éléments $elements = $collection->take(-2); // 2 derniers éléments
Filtrage et Recherche
// Filtrage simple $filtree = $collection->where('age', '>', 25); // Filtrage avec IN $filtree = $collection->whereIn('id', [1, 2, 3]); // Filtrage avec BETWEEN $filtree = $collection->whereBetween('age', [25, 35]); // Filtrage avec NOT IN $filtree = $collection->whereNotIn('id', [4, 5, 6]); // Filtrage avec NOT BETWEEN $filtree = $collection->whereNotBetween('age', [40, 50]);
Tri et Groupement
// Tri simple $triee = $collection->sort('asc'); // ou 'desc' // Tri par clé $triee = $collection->orderBy('age', 'desc'); // Groupement $groupee = $collection->groupBy('categorie');
Transformation
// Mapper les éléments $mappee = $collection->map(fn($item) => strtoupper($item)); // Filtrer les éléments $filtree = $collection->filter(fn($item) => $item > 10); // Extraire une colonne $noms = $collection->pluck('nom'); // Extraire une colonne avec index personnalisé $noms = $collection->pluck('nom', 'id'); // Diviser en morceaux $morceaux = $collection->chunk(2);
Agrégation
// Compter les éléments $total = $collection->count(); // Calculer une somme $somme = $collection->sum(); $somme = $collection->sum('prix'); // Calculer la somme d'un tableau de valeurs $sommeNotes = $collection->sumKey([10, 15, 20]); // Retourne 45 // Calculer une moyenne $moyenne = $collection->avg(); $moyenne = $collection->avg('age'); // Calculer la moyenne d'un tableau de valeurs $moyenneNotes = $collection->avgKey([10, 15, 20]); // Retourne 15 // Joindre les éléments $chaine = $collection->implode(', '); $chaine = $collection->implode(', ', 'nom');
Vérifications
// Vérifier si vide $estVide = $collection->isEmpty(); // Vérifier si non vide $nonVide = $collection->isNotEmpty(); // Vérifier l'existence d'une valeur $existe = $collection->exists('valeur'); $existe = $collection->exists(fn($item) => $item->age > 25);
Sélection de Clés
// Sélectionner certaines clés $selection = $collection->only('id', 'nom'); // Exclure certaines clés $exclusion = $collection->except('password', 'token'); // Obtenir toutes les clés $cles = $collection->keys();
🔄 Conversion
// Convertir en tableau $tableau = $collection->toArray(); // Convertir en chaîne $chaine = $collection->implode(', ');
🤝 Contribution
Les contributions sont les bienvenues ! N'hésitez pas à :
- Fork le projet
- Créer une branche pour votre fonctionnalité
- Commiter vos changements
- Pousser vers la branche
- Ouvrir une Pull Request
📝 Licence
Ce projet est sous licence MIT. Voir le fichier LICENSE pour plus de détails.
🔍 Exemples Complets
Exemple 1 : Gestion d'une liste de produits
$produits = new Collection([ ['id' => 1, 'nom' => 'Laptop', 'prix' => 1200, 'stock' => 5], ['id' => 2, 'nom' => 'Smartphone', 'prix' => 800, 'stock' => 10], ['id' => 3, 'nom' => 'Tablette', 'prix' => 400, 'stock' => 3] ]); // Produits en stock avec prix > 500€ $produitsDisponibles = $produits ->where('stock', '>', 0) ->where('prix', '>', 500) ->orderBy('prix', 'desc'); // Calculer la valeur totale du stock $valeurStock = $produits ->map(fn($item) => $item['prix'] * $item['stock']) ->sum(); // Liste des noms de produits $noms = $produits->pluck('nom')->implode(', ');
Exemple 2 : Traitement de données utilisateurs
$utilisateurs = new Collection([ ['id' => 1, 'nom' => 'Alice', 'age' => 25, 'role' => 'admin'], ['id' => 2, 'nom' => 'Bob', 'age' => 30, 'role' => 'user'], ['id' => 3, 'nom' => 'Charlie', 'age' => 35, 'role' => 'user'] ]); // Grouper par rôle $parRole = $utilisateurs->groupBy('role'); // Moyenne d'âge $moyenneAge = $utilisateurs->avg('age'); // Utilisateurs de 25 à 32 ans $trancheAge = $utilisateurs->whereBetween('age', [25, 32]); // Extraire emails et noms $contacts = $utilisateurs->pluck('email', 'nom');
Nouvelles Fonctionnalités de Filtrage
// Filtrer les éléments NULL $sansStock = $collection->whereNull('stock'); // Filtrer les éléments non NULL $enStock = $collection->whereNotNull('stock'); // Filtrer avec LIKE (style SQL) $recherche = $collection->whereLike('nom', '%Dell%'); // Contient 'Dell' $recherche = $collection->whereLike('nom', 'Dell%'); // Commence par 'Dell' $recherche = $collection->whereLike('nom', '%Dell'); // Termine par 'Dell'
Jointures
// Jointure interne (INNER JOIN) $resultat = $produits->join($ventes, 'id', 'produit_id', 'inner'); // Jointure gauche (LEFT JOIN) $resultat = $produits->join($ventes, 'id', 'produit_id', 'left'); // Jointure droite (RIGHT JOIN) $resultat = $produits->join($ventes, 'id', 'produit_id', 'right');
Statistiques et Agrégation
// Compter les occurrences par valeur $parCategorie = $collection->countBy('categorie'); // Statistiques complètes $stats = $collection->stats('prix'); // Retourne : [ // 'min' => valeur minimale, // 'max' => valeur maximale, // 'avg' => moyenne, // 'sum' => somme, // 'count' => nombre d'éléments // ]
Groupement Avancé
// Groupement multi-niveaux $groupes = $collection->groupByMultiple('categorie', 'marque', 'annee'); // Groupement par intervalles $parPrix = $collection->groupByRange('prix', 500); // Groupes de 500€
Exemple Complet
$produits = new Collection([ ['id' => 1, 'nom' => 'Laptop Dell', 'prix' => 1200, 'categorie' => 'Informatique'], ['id' => 2, 'nom' => 'iPhone 13', 'prix' => 999, 'categorie' => 'Téléphonie'], // ... ]); // Analyse complexe $analyse = $produits ->whereNotNull('stock') // Uniquement les produits en stock ->whereBetween('prix', [300, 1000]) // Prix entre 300€ et 1000€ ->groupBy('categorie') // Grouper par catégorie ->map(function ($groupe) { // Analyser chaque groupe return [ 'count' => $groupe->count(), // Nombre de produits 'stats' => $groupe->stats('prix'), // Statistiques des prix 'total_stock' => $groupe->sum('stock') // Stock total ]; });
Bonnes Pratiques
-
Performance
- Utilisez
whereNotNull()
avant d'autres filtres pour réduire le jeu de données - Préférez
groupByMultiple()
à desgroupBy()
imbriqués - Utilisez
stats()
plutôt que plusieurs appels individuels aux méthodes d'agrégation
- Utilisez
-
Jointures
- Spécifiez le type de jointure approprié pour éviter les résultats inattendus
- Utilisez 'left' pour préserver les données de la collection principale
- Vérifiez les clés de jointure avant d'effectuer l'opération
-
Filtrage
whereLike()
est sensible à la casse par défaut- Les motifs de recherche suivent la syntaxe SQL (
%
pour zéro ou plusieurs caractères) - Combinez plusieurs conditions de filtrage pour des recherches précises