Comment créer une classe Builder personnalisée avec des scopes Laravel

Lorsque vous travaillez avec Laravel, il est couramment utile d'ajouter des méthodes scope à vos requêtes afin d'améliorer la lisibilité et la réutilisabilité de votre code. Plutôt que d'inclure ces scopes directement dans chaque modèle, il est préférable de créer une classe dédiée qui étend la classe Builder et d'y définir vos méthodes scope publiques. Vous pouvez ensuite override la méthode newEloquentBuilder dans votre modèle pour lui faire utiliser cette nouvelle classe. Voici la démarche à suivre, étape par étape.

Étape 1 : Concevoir une nouvelle classe qui hérite de Builder

La classe doit hériter de Illuminate\Database\Eloquent\Builder ou Illuminate\Database\Query\Builder selon votre contexte. Pour ajouter des méthodes scope, il suffit d'y définir des méthodes publiques.

Exemple de classe personnalisée

Supposons que vous utilisez un modèle Product et que vous souhaitez y ajouter des scopes tels que available et category. Voici comment créer cette classe étendue :

<?php
namespace App\Builders;

use Illuminate\Database\Eloquent\Builder;

class ProductBuilder extends Builder
{
    public function available(): self
    {
        return $this->where('stock', '>', 0);
    }

    public function category(string $categoryName): self
    {
        return $this->whereHas('category', function ($query) use ($categoryName) {
            $query->where('name', $categoryName);
        });
    }
}

Étape 2 : Override la méthode newEloquentBuilder dans votre modèle

Pour que Laravel utilise cette nouvelle classe pour le modèle concerné, il faut override la méthode newEloquentBuilder dans votre modèle. Cela garantit que toutes vos requêtes sur ce modèle emploieront votre builder personnalisé.

Exemple dans le modèle Product

<?php
namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Builder;
use App\Builders\ProductBuilder;

class Product extends Model
{
    public function newEloquentBuilder(Builder $query): ProductBuilder
    {
        return new ProductBuilder($query);
    }
}

Étape 3 : Utiliser vos scopes dans les requêtes

Une fois cette configuration en place, vous pouvez utiliser vos méthodes scope comme s'il s'agissait de méthodes magiques ou statiques sur le modèle. Par exemple :

$products = Product::available()->category('Electronics')->get();

En étendant la classe Builder, vous organisez clairement vos requêtes customisées tout en conservant une syntaxe fluide, expressive et professionnelle.

Résumé des étapes clés

• Créer une classe qui hérite de Illuminate\Database\Eloquent\Builder et y définir vos méthodes scope publiques.

• Remplacer la méthode newEloquentBuilder dans votre modèle pour utiliser cette nouvelle classe.

• Employer vos scopes comme méthodes sur votre modèle pour un code plus lisible et maintenable.

Bonnes pratiques et recommandations

• Nommez vos méthodes scope de façon claire et descriptive pour améliorer la compréhension.

• Organisez vos classes dans un namespace dédié, par exemple App\Builders, afin de favoriser une architecture soignée.

• Combinez cette approche avec d'autres techniques Laravel comme les macros ou traits pour encore plus de flexibilité.

Adopter cette méthode vous permet d'améliorer la maintenabilité de votre code tout en profitant d'une syntaxe élégante et efficace pour vos requêtes complexes.