Erreurs les plus fréquentes sur Laravel et comment les éviter sans y laisser votre week-end

Laravel est conçu pour aller vite. Très vite. Et c’est justement là que se glissent les erreurs les plus coûteuses : on accélère, on empile, et on s’aperçoit trop tard que le projet tient avec trois caches, deux suppositions et une prière.

Ce que vous voulez, en tant que cheffe de projet ou développeur côté delivery, ce n’est pas “juste” un code qui fonctionne. Vous voulez un code prévisible, déployable, maintenable et stable en production. Ici, on met le doigt sur les erreurs Laravel les plus fréquentes, avec des explications claires, des symptômes concrets, et les bons réflexes pour les éviter.

Modifier le .env et croire que tout va suivre automatiquement

C’est l’erreur la plus répandue, parce qu’elle est logique… mais fausse en production.

Ce qui se passe

Vous changez une valeur dans .env (clé API, driver, url, mailer). En local, parfois ça marche. En production, ça ne bouge pas. Ou pire : ça bouge une fois, puis ça “revient”.

Pourquoi

Laravel peut mettre en cache la configuration. Quand vous utilisez php artisan config:cache, le framework compile la config. Ensuite, le .env n’est plus relu comme vous le pensez. Et si vous appelez env() dans le code applicatif, vous ouvrez la porte aux incohérences.

À retenir

• env() doit rester dans les fichiers de config, pas dans vos controllers/services.

• Dans le code, vous utilisez config().

À éviter dans le code applicatif :

$apiKey = env('STRIPE_KEY'); // fragile dès que config:cache est activé

A faire: 

// config/services.php
return [
    'stripe' => [
        'key' => env('STRIPE_KEY'),
    ],
];

// dans le code
$apiKey = config('services.stripe.key');

Quand cela "ne prend pas":

php artisan config:clear
php artisan cache:clear
php artisan config:cache

Point important : en production, un problème de configuration est souvent un problème de cache, pas un problème de code.

Mal gérer les caches (config, routes, vues) et créer des bugs de production “impossibles à reproduire

En local, Laravel est permissif. En prod, il faut être disciplinée.

Symptômes typiques

• Routes qui disparaissent (404) après déploiement

• Templates Blade qui semblent “ne pas se mettre à jour”

• Comportements différents entre staging et prod

• Vous “corrigez”, mais le bug reste

L’erreur la plus fréquente : les routes en closure

Avec route:cache, Laravel ne supporte pas les closures.

À éviter :

Route::get('/health', function () {
    return 'OK';
});

A faire: 

Route::get('/health', [HealthController::class, 'index']);

Routine saine de déploiement (à adapter selon votre pipeline) :

php artisan config:cache
php artisan route:cache
php artisan view:cache

et si vous suspectez une incohérence: 

php artisan optimize:clear

À retenir : les caches sont un accélérateur. Mais un accélérateur mal géré, c’est une sortie de route.

Mass assignment : create($request->all()), ou l’art de donner trop de pouvoir à un formulaire

Cette ligne “fait gagner du temps” jusqu’au jour où elle vous en fait perdre beaucoup.

Erreur classique :

User::create($request->all());

Pourquoi c’est risqué

• Vous autorisez potentiellement l’écriture de champs sensibles (ex. is_admin, role, balance)

• Vous dépendez de la forme exacte du formulaire

• Vous créez des bugs silencieux quand un champ apparaît/disparaît

Bon réflexe

1. Définir ce qui est autorisé via $fillable

2. Valider et n’envoyer que les données attendues

// app/Models/User.php
protected $fillable = ['name', 'email', 'password'];

$data = $request->validate([
    'name' => ['required', 'string', 'max:255'],
    'email' => ['required', 'email'],
    'password' => ['required', 'min:12'],
]);

$data['password'] = bcrypt($data['password']);

User::create($data);

À retenir : un formulaire ne doit jamais décider de la structure métier. C’est l’application qui décide.

Le N+1 : le tueur silencieux de performance

Le N+1 est l’erreur la plus rentable à corriger… parce qu’elle apparaît tôt et coûte cher.

Exemple typique

$posts = Post::latest()->take(50)->get();

foreach ($posts as $post) {
    echo $post->author->name; // requête à chaque tour
}

Ce que vous croyez : “je boucle sur des posts”.
Ce que la base vit réellement : 1 requête + 50 requêtes. Et demain : 1 + 500.

Solution : eager loading

$posts = Post::with('author')->latest()->take(50)->get();

foreach ($posts as $post) {
    echo $post->author->name;
}

Pourquoi c’est crucial côté projet

• Les lenteurs arrivent d’abord sur les pages “listings” (dashboards, admin, pages catégories)

• Ce sont précisément les pages les plus utilisées par les équipes internes

• Et ce sont souvent elles qui donnent l’impression que “Laravel est lent”, alors que c’est juste une requête mal pensée

À retenir : si vous voyez une relation Eloquent appelée dans une boucle, pensez N+1.

5) Validation “minimaliste” : la base devient un bazar, puis le bazar devient un bug

Valider “vite fait” est tentant. Mais ce qui n’est pas validé aujourd’hui se paye demain.

Les dégâts concrets

• Données incohérentes (emails invalides, quantités négatives, ids inexistants)

• Règles métier dispersées partout

• Correction “à la main” en base (le fameux moment où personne n’a envie d’être volontaire)

Solution propre : Form Request

php artisan make:request StoreOrderRequest

// app/Http/Requests/StoreOrderRequest.php
public function rules(): array
{
    return [
        'product_id' => ['required', 'integer', 'exists:products,id'],
        'quantity' => ['required', 'integer', 'min:1', 'max:999'],
        'email' => ['required', 'email'],
    ];
}

public function store(StoreOrderRequest $request)
{
    $data = $request->validated();
    return Order::create($data);
}

À retenir : la validation n’est pas une formalité, c’est un investissement pour la stabilité.

6) Erreur 419 (CSRF) : “Page Expired”, ou le bug qui adore vous faire douter

Le 419 est un grand classique, et il excelle dans un domaine : vous faire chercher au mauvais endroit.

Cause la plus fréquente

Formulaire sans token CSRF.

Autres causes fréquentes

• Requête AJAX sans token

• Cookies de session mal gérés (domaines, sous-domaines)

• Problèmes de HTTPS / reverse proxy : l’app croit être en HTTP, les cookies ne se comportent pas comme prévu

À retenir : une 419 en prod, c’est souvent un problème de contexte (cookies, domaine, proxy) plus qu’un problème de formulaire.

Migrations et clés étrangères : la base de données n’oublie rien

Laravel facilite les migrations. Ce qui est formidable… jusqu’à ce que les relations et la cohérence deviennent non négociables.

Erreur fréquente

Types incompatibles entre clé primaire et clé étrangère. Par exemple :

• users.id en big integer

• posts.user_id en integer

Solution claire

Schema::create('posts', function (Blueprint $table) {
    $table->id();
    $table->foreignId('user_id')->constrained()->cascadeOnDelete();
    $table->string('title');
    $table->timestamps();
});

À retenir : les contraintes ne sont pas là pour vous embêter, elles sont là pour éviter des données impossibles à gérer.

Oublier les transactions : créer des données “à moitié” et perdre la confiance

Vous créez une commande, vous décrémentez un stock, vous générez une facture. Et au milieu, une exception. Sans transaction, vous créez des états incohérents.

Exemple concret

• Stock décrémenté

• Commande non créée

• Facture inexistante

Ce n’est pas “un bug”. C’est une incohérence métier. Et c’est ce qui casse la confiance.

Solution : transaction

DB::transaction(function () use ($data) {
    $order = Order::create($data);

    Stock::where('product_id', $data['product_id'])
        ->decrement('quantity', $data['quantity']);

    Invoice::create(['order_id' => $order->id]);
});

À retenir : dès qu’une opération doit être atomique, utilisez une transaction.

Tout faire en synchrone : jusqu’au jour où ça time-out

Au début, envoyer un mail “dans le controller” semble acceptable. Puis votre application grandit, et chaque requête devient un mini-process.

Symptômes

• Pages lentes

• Timeouts

• Utilisateurs qui re-cliquent (et créent des doublons)

• Dépendances externes qui rendent l’app instable

Solution : queues + jobs

Tout faire en synchrone : jusqu’au jour où ça time-out

Au début, envoyer un mail “dans le controller” semble acceptable. Puis votre application grandit, et chaque requête devient un mini-process.

Symptômes

• Pages lentes

• Timeouts

• Utilisateurs qui re-cliquent (et créent des doublons)

• Dépendances externes qui rendent l’app instable

Solution : queues + jobs

php artisan make:job SendInvoiceEmail

class SendInvoiceEmail implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public function __construct(public int $invoiceId) {}

    public function handle(): void
    {
        $invoice = Invoice::findOrFail($this->invoiceId);

        Mail::to($invoice->customer_email)
            ->send(new InvoiceMail($invoice));
    }
}

Et coté worker: 

php artisan queue:work --tries=3

Point important : ne sérialisez pas un modèle complet si un id suffit. Plus léger, plus fiable, plus reproductible.

Charger trop de données en mémoire : le bug qui apparaît quand vous avez enfin du trafic

L’application “marche” jusqu’au jour où la table grossit. Et le jour où elle grossit, il est trop tard pour découvrir que vous faisiez all() partout.

À éviter :

$users = User::all();

À privilégier :

• paginate() pour l’interface

• chunk() ou cursor() pour les traitements

User::where('active', true)->chunk(500, function ($users) {
    foreach ($users as $user) {
        // traitement
    }
});

foreach (User::where('active', true)->cursor() as $user) {
    // traitement
}

À retenir : pensez “données futures”, pas “données actuelles”.

Sécurité : APP_DEBUG=true en prod, ou l’auto-sabotage

C’est brut, mais utile : APP_DEBUG=true en production est une erreur majeure.

Pourquoi

• Exposition d’informations sensibles (chemins, requêtes, structure interne)

• Aide involontaire aux attaques

• Risque de fuite de secrets dans les logs

Et côté Blade :

{{ $value }}      // échappé
{!! $value !!}    // non échappé : dangereux si contenu utilisateur

À retenir : le non échappé doit rester exceptionnel et justifié.

Controllers “fourre-tout” : l’erreur qui ne casse pas l’app, mais casse l’équipe

Une app peut être stable et pourtant pénible à maintenir. Le coupable n’est pas toujours technique : c’est souvent organisationnel.

Symptômes

• Controller qui fait validation + logique métier + requêtes + API + formatage

• Duplication de logique

• Tests difficiles

• Peur de toucher à un fichier “central”

Solution : extraire la logique métier

class PriceCalculator
{
    public function total(int $unitPrice, int $qty): int
    {
        return $unitPrice * $qty;
    }
}

public function store(StoreOrderRequest $request, PriceCalculator $calc)
{
    $data = $request->validated();

    $total = $calc->total($data['unit_price'], $data['quantity']);

    return Order::create([...$data, 'total' => $total]);
}

À retenir : plus votre projet grandit, plus la lisibilité est une feature.

Déploiement : permissions, storage, workers… les pannes “bêtes” qui font très mal

Une app Laravel peut être parfaite… et tomber pour une raison simple :

• permissions sur storage et bootstrap/cache

• oubli de storage:link

• worker de queue non relancé après déploiement (il garde l’ancien code en mémoire)

• caches jamais reconstruits correctement

Commande indispensable si vous servez des fichiers depuis storage :

php artisan storage:link

À retenir : un déploiement, ce n’est pas “envoyer du code”. C’est mettre en production un système cohérent.

Et pour finir...

Les erreurs Laravel les plus fréquentes sont rarement “complexes”. Elles sont banales, donc elles se répètent. La bonne nouvelle, c’est qu’elles se corrigent souvent sans refonte : quelques bonnes pratiques suffisent à faire passer un projet de “ça marche” à c’est solide.

Si vous visez moins de bugs, plus de vitesse, et des déploiements sans sueurs froides : maîtrisez configuration + caches, surveillez Eloquent, imposez validation + transactions, et professionnalisez queues + déploiement. Laravel fera le reste.