Modèles

Les modèles de données

Swell propose une collection de modèles prêts à l'emploi, conçus pour couvrir les besoins courants d'un projet e-commerce moderne.

Ces modèles servent de base solide, mais restent entièrement personnalisables afin de s'adapter à la structure et aux spécificités de votre application.

Vous pouvez ainsi les modifier ou en créer de nouveaux selon les exigences de votre domaine métier, tout en profitant d'une intégration fluide avec l'écosystème Swell.

Adapter un modèle

Les modèles Swell sont situés dans le dossier app/Models, à l'exception des fonctionnalités optionnelles dont les modèles sont placés dans app/Modules/{ModuleName}/Models.

Ils sont associés à leurs fichiers de migration respectifs dans database/migrations ou app/Modules/{ModuleName}/database/migrations, permettant de définir la structure des tables correspondantes.

Modèles Core

Ces modèles constituent le cœur de l'application e-commerce et sont situés dans app/Models/.

Brand

Représente une marque de produits.

Relations :

• hasMany(Product) - Une marque possède plusieurs produits

Category

Représente une catégorie de produits avec support hiérarchique (catégories/sous-catégories).

Relations :

• belongsTo(Category) - Parent category (pour hiérarchie)
• hasMany(Category) - Sous-catégories enfants
• hasMany(Product) - Produits de cette catégorie

Product

Modèle principal représentant un produit avec support des variantes, images, et intégration Algolia.

Relations :

• belongsTo(Category) - Catégorie du produit
• belongsTo(Brand) - Marque du produit
• belongsTo(Collection) - Collection associée (optionnel)
• hasMany(ProductImage) - Images du produit
• hasOne(ProductImage) - Image featured (via featuredImage())
• hasMany(ProductOption) - Options/variantes (taille, couleur, etc.)
• hasMany(Review) - Avis clients (module Review)
• hasMany(OrderItem) - Éléments de commandes
• belongsToMany(Wishlist) - Listes de souhaits (module Wishlist)

Méthodes utiles :

• getPrice() - Retourne discount_price si défini, sinon price
• isOutOfStock() - Vérifie si le stock est épuisé
• incrementSales($quantity) - Incrémente le compteur de ventes
• scopePopular($limit) - Scope pour récupérer les produits populaires

Traits :

• Searchable (Laravel Scout) - Synchronisation automatique avec Algolia
• shouldBeSearchable() - Seuls les produits avec status = true sont indexés

Collection

Regroupe plusieurs produits sous une collection thématique (ex: "Nouveautés", "Soldes d'été").

Relations :

• hasMany(Product) - Produits de cette collection

ProductImage

Images associées à un produit avec support d'image principale (featured).

Relations :

• belongsTo(Product) - Produit associé

ProductOption

Options/variantes disponibles pour un produit (ex: "Taille", "Couleur").

Relations :

• belongsTo(Product) - Produit associé
• hasMany(ProductOptionValue) - Valeurs possibles pour cette option

Exemple d'utilisation :

// Option: Taille
// Values: S, M, L, XL

// Option: Couleur
// Values: Rouge, Bleu, Noir

ProductOptionValue

Valeurs possibles pour une option de produit.

Relations :

• belongsTo(ProductOption) - Option associée

Cart

Panier d'achat (session pour invités, persistant pour utilisateurs authentifiés).

Relations :

• belongsTo(User) - Utilisateur (si authentifié)
• hasMany(CartItem) - Éléments du panier

CartItem

Élément individuel dans un panier avec support des options de produit.

Relations :

• belongsTo(Cart) - Panier associé
• belongsTo(Product) - Produit ajouté

Casts :

• options → array - Options sélectionnées pour ce produit (ex: {"Taille": "M", "Couleur": "Bleu"})

Order

Commande finalisée avec génération automatique du numéro de commande.

Relations :

• belongsTo(User) - Client de la commande
• hasMany(OrderItem) - Produits commandés

Casts :

• billing_address → collection
• shipping_address → collection

Génération automatique : Le order_number est généré au format : {PREFIX}-{YEAR}-{RANDOM} (ex: ORD-2025-A3F8K9L2)

• Prefix configurable via SWELL_ORDER_PREFIX (défaut: ORD)

Méthodes utiles :

• total() - Calcule le total de la commande depuis les items

OrderItem

Produit individuel dans une commande (snapshot pour historique).

Relations :

• belongsTo(Order) - Commande associée
• belongsTo(Product) - Référence au produit

Modèles des Modules

Ces modèles font partie des fonctionnalités optionnelles et sont situés dans app/Modules/{ModuleName}/Models/.

BannerMessage (Module Banner)

Messages d'information affichés sur le site.

Emplacement : app/Modules/Banner/Models/BannerMessage.php

Casts :

• is_active → boolean

Review (Module Review)

Avis et évaluations produits laissés par les clients.

Emplacement : app/Modules/Review/Models/Review.php

Relations :

• belongsTo(User) - Auteur de l'avis
• belongsTo(Product) - Produit évalué

Casts :

• rating → integer (généralement 1-5 étoiles)

Wishlist (Module Wishlist)

Liste de souhaits utilisateur.

Emplacement : app/Modules/Wishlist/Models/Wishlist.php

Relations :

• belongsTo(User) - Propriétaire de la wishlist
• belongsToMany(Product) - Produits dans la wishlist (via table pivot wishlist_items)

LoyaltyAccount (Module Loyalty)

Compte de points de fidélité utilisateur.

Emplacement : app/Modules/Loyalty/Models/LoyaltyAccount.php

Relations :

• belongsTo(User) - Utilisateur propriétaire
• hasMany(LoyaltyTransaction) - Historique des transactions

Accesseurs calculés :

• available_points - Points disponibles (non expirés)
• expiring_points - Points expirant dans les 30 prochains jours

Casts :

• points → integer
• lifetime_points → integer

LoyaltyTransaction (Module Loyalty)

Transaction de points de fidélité (gain, dépense, expiration, etc.).

Emplacement : app/Modules/Loyalty/Models/LoyaltyTransaction.php

Relations :

• belongsTo(LoyaltyAccount) - Compte de fidélité
• belongsTo(Order) - Commande associée (si applicable)

Types de transaction (Enum) :

• EARNED - Points gagnés
• SPENT - Points dépensés
• EXPIRED - Points expirés
• REFUNDED - Points remboursés
• ADMIN_ADJUSTMENT - Ajustement administrateur

Casts :

• type → TransactionType (enum)
• points → integer
• balance_after → integer
• expires_at → datetime

Méthodes utiles :

• isExpired() - Vérifie si les points ont expiré
• isExpiringSoon() - Vérifie si les points expirent dans les 30 jours

Relations entre modèles

Diagramme simplifié

User
├── hasMany(Order)
├── hasMany(Review)
├── hasOne(Cart)
├── hasOne(Wishlist)
└── hasOne(LoyaltyAccount)

Product
├── belongsTo(Brand)
├── belongsTo(Category)
├── belongsTo(Collection)
├── hasMany(ProductImage)
├── hasMany(ProductOption)
├── hasMany(Review)
└── belongsToMany(Wishlist)

Order
├── belongsTo(User)
├── hasMany(OrderItem)
└── hasMany(LoyaltyTransaction)

LoyaltyAccount
├── belongsTo(User)
└── hasMany(LoyaltyTransaction)

Bonnes pratiques

1. Utiliser les relations Eloquent

✅ Préférez :

$product->brand->name
$user->loyaltyAccount->points

❌ Évitez :

Brand::find($product->brand_id)->name
LoyaltyAccount::where('user_id', $user->id)->first()->points

2. Eager loading pour éviter N+1

// ✅ Bon - 2 requêtes
$products = Product::with(['brand', 'category', 'images'])->get();

// ❌ Mauvais - 1 + N requêtes
$products = Product::all();
foreach ($products as $product) {
    echo $product->brand->name; // Requête pour chaque produit
}

3. Utiliser les scopes

// Défini dans le modèle Product
public function scopePopular($query, int $limit = 10)
{
    return $query->orderBy('sales_count', 'desc')->limit($limit);
}

// Utilisation
$popularProducts = Product::popular(5)->get();

4. Casts pour les types de données

Les modèles Swell utilisent déjà les casts appropriés :

protected $casts = [
    'status' => 'boolean',
    'price' => 'float',
    'options' => 'array', // JSON → Array automatique
    'type' => TransactionType::class, // String → Enum
];

Personnalisation

Pour personnaliser un modèle :

1. Ajouter des champs : Créez une migration
2. Ajouter des relations : Définissez-les dans le modèle
3. Ajouter des méthodes : Ajoutez vos méthodes métier
4. Ajouter des scopes : Pour des requêtes réutilisables
5. Ajouter des accesseurs : Pour des attributs calculés

Exemple :

// Migration
Schema::table('products', function (Blueprint $table) {
    $table->string('barcode')->nullable();
});

// Modèle Product
protected $fillable = [..., 'barcode'];

public function isSoldOut(): bool
{
    return $this->stock === 0;
}