Aller au contenu principal

Règles Laravel DMV

Statut​

Document de règles projet — v1.0 — relu le 2026-05-10.

Objectif​

Règles spécifiques au développement du backend Laravel API DMV, applicables aux développeurs et aux agents IA intervenant sur api/.

Règles strictes​

  • Ne jamais retourner autre chose que du JSON — l'API est JSON-only.
  • Ne jamais exposer de trace de pile, secret ou donnée personnelle dans une réponse d'erreur.
  • Ne jamais utiliser dd(), dump() ou var_dump() dans le code en production.
  • Ne jamais contourner Sanctum ou les policies pour accéder à des données restreintes.
  • Ne jamais modifier les migrations Supabase depuis Laravel — utiliser les migrations de test uniquement.
  • Ne jamais stocker de secrets dans AppSetting — c'est une table de paramètres applicatifs, pas un coffre.
  • Ne jamais ajouter de logique métier dans un contrôleur — tout passe par les services.
  • Ne jamais ignorer les tests — les tests existants doivent rester verts après chaque modification.

Structure à respecter​

  • Controllers : valider → déléguer au service → répondre.
  • Services : porter la logique métier, orchestrer les modèles, DTOs et intégrations.
  • Models : représenter les données, scopes, relations, casts.
  • DTOs : objets de transfert immuables entre service et contrôleur.
  • Policies : règles d'autorisation isolées et testables.
  • Requests : validation des entrées HTTP.

Principes directeurs​

  • Un module = un dossier app/Modules/{Module}/ avec sa structure complète.
  • Les erreurs métier sont des exceptions typées mappées dans bootstrap/app.php.
  • Les jobs planifiés sont déclarés dans bootstrap/app.php via withSchedule().
  • Les middlewares de module sont enregistrés dans bootstrap/app.php via alias().
  • declare(strict_types=1) en tête de chaque fichier PHP.

Recommandations​

  • Préférer les Form Requests aux validations inline dans les contrôleurs.
  • Utiliser les scopes Eloquent pour les filtres réutilisables.
  • Tester les services avec des tests unitaires, les contrôleurs avec des tests d'intégration.
  • Documenter les endpoints non évidents avec des commentaires PHPDoc dans le contrôleur.
  • Éviter les N+1 queries — utiliser with() pour les relations nécessaires.

Anti-patterns à éviter​

  • Logique métier dans un contrôleur.
  • Requêtes SQL brutes hors des cas justifiés.
  • Couplage direct entre modules (passer par un service ou une interface).
  • Retourner des modèles Eloquent bruts en réponse API (utiliser des DTOs ou Resources).
  • Exposer des colonnes sensibles sans les ajouter à $hidden.