Fatal error Class FrontController not found dans un module PrestaShop

Comprendre l'erreur « Class FrontController not found »

Lorsque vous développez un module PrestaShop et que vous tentez d'accéder à un contrôleur front personnalisé, vous pouvez rencontrer cette erreur fatale :

Fatal error: Class 'FrontController' not found in /modules/monmodule/controllers/front/mapage.php

Cette erreur est déroutante car FrontController est bien une classe native de PrestaShop. Le problème ne vient pas de l'absence de la classe dans le cœur du CMS, mais d'une convention de nommage non respectée dans votre module. PrestaShop utilise un système d'autoloading très strict qui repose sur la correspondance exacte entre le nom du module, le nom du fichier contrôleur et le nom de la classe PHP.

La convention de nommage obligatoire

PrestaShop impose une convention précise pour les contrôleurs front de modules. Le non-respect de cette convention empêche l'autoloader de résoudre correctement la chaîne d'héritage, ce qui provoque l'erreur.

La règle fondamentale

Le nom de la classe doit suivre exactement ce format :

{nomdumodule}{nomducontroleur}ModuleFrontController

Où :

• `{nomdumodule}` correspond au nom technique du module (le nom du dossier dans `/modules/`), **en minuscules et sans underscores**
• `{nomducontroleur}` correspond au nom du fichier PHP du contrôleur (sans l'extension), **avec la première lettre en majuscule**
• `ModuleFrontController` est le suffixe imposé par PrestaShop

Exemple concret

Pour un module nommé monmodule avec un contrôleur affichage :

Structure de fichiers :

modules/
└── monmodule/
    ├── monmodule.php
    └── controllers/
        └── front/
            └── affichage.php

Classe du contrôleur (affichage.php) :

<?php

class monmoduleAffichageModuleFrontController extends ModuleFrontController
{
    public function initContent()
    {
        parent::initContent();
        // Votre logique ici
        $this->setTemplate('module:monmodule/views/templates/front/affichage.tpl');
    }
}

Le piège classique : les underscores dans le nom du module

C'est la cause la plus fréquente de cette erreur. Si votre module s'appelle mon_module (avec un underscore), PrestaShop ne parvient pas à résoudre correctement le nom de la classe du contrôleur.

Pourquoi les underscores posent problème

L'autoloader de PrestaShop (classe Dispatcher) construit le nom de la classe attendue en concaténant directement le nom du module et le nom du contrôleur. Lorsqu'un underscore est présent, le mécanisme de résolution interprète potentiellement les segments comme des espaces de noms ou des séparateurs de classe, ce qui casse la chaîne d'héritage.

Solution : renommer le module sans underscores

Si vous êtes en phase de développement, la solution la plus propre est de renommer votre module en supprimant les underscores :

# Avant (problématique)
modules/chronos_accueil/
  → class chronos_accueilAccueilModuleFrontController  ❌

# Après (correct)
modules/chronosaccueil/
  → class chronosaccueilAccueilModuleFrontController  ✅

Attention : renommer un module déjà installé nécessite plusieurs étapes :

1. Désinstaller le module via le back-office
2. Renommer le dossier du module
3. Renommer le fichier PHP principal
4. Mettre à jour le nom de la classe principale
5. Mettre à jour tous les contrôleurs
6. Réinstaller le module

Checklist de diagnostic complet

Si l'erreur persiste malgré un nommage correct, vérifiez ces points dans l'ordre :

1. Vérifier la correspondance nom de dossier / nom de classe

// Le dossier s'appelle "monmodule"
// Le fichier contrôleur s'appelle "details.php"
// La classe DOIT s'appeler :
class monmoduleDetailsModuleFrontController extends ModuleFrontController

2. Vérifier l'héritage

Votre classe doit étendre ModuleFrontController, pas FrontController :

// ❌ Incorrect
class monmoduleDetailsModuleFrontController extends FrontController

// ✅ Correct
class monmoduleDetailsModuleFrontController extends ModuleFrontController

3. Vider le cache PrestaShop

Après toute modification de contrôleur, videz systématiquement le cache :

# Suppression manuelle du cache
rm -rf var/cache/prod/*
rm -rf var/cache/dev/*

Ou via le back-office : Paramètres avancés → Performances → Vider le cache.

4. Vérifier les droits de fichiers

chmod 644 modules/monmodule/controllers/front/details.php
chown www-data:www-data modules/monmodule/controllers/front/details.php

5. Vérifier la route du contrôleur

L'URL d'accès à un contrôleur front de module suit ce format :

https://votresite.com/index.php?fc=module&module=monmodule&controller=details

Avec les URL simplifiées activées :

https://votresite.com/module/monmodule/details

Spécificités PrestaShop 8.x

Sur PrestaShop 8.x, le mécanisme reste identique pour les contrôleurs front de modules. Cependant, quelques points méritent attention :

• Le **namespace Symfony** n'est pas utilisé pour les contrôleurs front de modules (contrairement aux contrôleurs admin qui migrent progressivement vers Symfony)
• Le cache se trouve dans `var/cache/` (et non plus `cache/` comme sur les versions 1.6)
• En mode debug (`_PS_MODE_DEV_ = true` dans `config/defines.inc.php`), l'erreur affichera une stack trace complète qui vous aidera à identifier le point exact de rupture

Activer le mode debug pour un diagnostic précis

// config/defines.inc.php
define('_PS_MODE_DEV_', true);

Cela vous donnera la trace complète de l'autoloading et vous permettra de voir exactement quel nom de classe PrestaShop cherche à instancier.

Modèle de contrôleur front complet et fonctionnel

Voici un template de contrôleur front prêt à l'emploi pour PrestaShop 1.7 et 8.x :

<?php
/**
 * Contrôleur front du module monmodule
 * Fichier : modules/monmodule/controllers/front/details.php
 */

class monmoduleDetailsModuleFrontController extends ModuleFrontController
{
    /** @var bool Active le rendu dans la colonne de gauche */
    public $display_column_left = false;

    /** @var bool Active le rendu dans la colonne de droite */
    public $display_column_right = false;

    /**
     * Initialisation du contenu de la page
     */
    public function initContent()
    {
        parent::initContent();

        // Assignation de variables Smarty
        $this->context->smarty->assign([
            'mon_variable' => 'valeur',
            'module_dir' => _MODULE_DIR_ . $this->module->name . '/',
        ]);

        // Définition du template
        $this->setTemplate('module:monmodule/views/templates/front/details.tpl');
    }

    /**
     * Gestion des métadonnées SEO
     */
    public function getTemplateVarPage()
    {
        $page = parent::getTemplateVarPage();
        $page['meta']['title'] = $this->trans('Mon titre de page', [], 'Modules.Monmodule.Front');
        $page['meta']['description'] = $this->trans('Ma description', [], 'Modules.Monmodule.Front');
        return $page;
    }
}

Résumé des conventions de nommage

ÉlémentConventionExemple Dossier moduleminuscules, sans underscores`monmodule` Fichier contrôleurminuscules`details.php` Classe contrôleur`{module}{Controller}ModuleFrontController``monmoduleDetailsModuleFrontController` Classe parente`ModuleFrontController`— Chemin du template`module:{module}/views/templates/front/{fichier}.tpl``module:monmodule/views/templates/front/details.tpl`