Module PrestaShop sans affichage : corriger un AdminController défaillant

Le symptôme classique : un module installé mais invisible

Vous avez développé votre premier module PrestaShop avec une interface d'administration, l'installation se passe sans erreur, le menu apparaît dans le back-office… mais quand vous cliquez dessus, c'est le néant. Page blanche, aucun champ, aucun listing. Le module semble fantôme.

Ce problème touche énormément de développeurs PrestaShop, et la cause est presque toujours la même : une incohérence dans le nommage du contrôleur admin ou un constructeur mal positionné.

Comprendre la convention de nommage des AdminController

PrestaShop impose une convention de nommage stricte pour les contrôleurs d'administration. Le moindre écart provoque un échec silencieux — pas d'erreur, juste une page vide.

La règle d'or

Trois éléments doivent être parfaitement synchronisés :

1. **Le nom du fichier** : `AdminGestionRecetteController.php`
2. **Le nom de la classe** : `AdminGestionRecetteController`
3. **La déclaration dans le module** : référence à `AdminGestionRecette` (sans le suffixe `Controller`)

// fichier : modules/monmodule/controllers/admin/AdminGestionRecetteController.php

class AdminGestionRecetteController extends ModuleAdminController
{
    // ...
}

Les erreurs fréquentes

ErreurExempleConséquence Fichier mal nommé`AdminGestionrecetteController.php` (minuscule)Contrôleur introuvable Classe qui ne correspond pas au fichierFichier `AdminRecetteController.php` avec classe `AdminGestionRecetteController`Page blanche Oubli du préfixe `Admin``GestionRecetteController.php`Non reconnu comme contrôleur admin Suffixe `Controller` manquant dans le nom de fichier`AdminGestionRecette.php`Autoload échoue

Positionner correctement le constructeur

Une erreur subtile mais redoutable : placer l'appel à parent::__construct() avant la définition de $this->fields_list. PrestaShop initialise le helper list dans le constructeur parent. Si vos champs ne sont pas encore définis à ce moment-là, le listing sera vide.

La mauvaise approche

class AdminGestionRecetteController extends ModuleAdminController
{
    public function __construct()
    {
        parent::__construct(); // Trop tôt !

        $this->table = 'recette';
        $this->identifier = 'id_recette';
        $this->className = 'Recette';
        $this->lang = false;
        $this->bootstrap = true;

        $this->fields_list = [
            'id_recette' => ['title' => 'ID', 'align' => 'center', 'class' => 'fixed-width-xs'],
            'name'       => ['title' => 'Nom', 'filter_key' => 'a!name'],
            'active'     => ['title' => 'Actif', 'active' => 'status', 'type' => 'bool', 'align' => 'center'],
        ];
    }
}

La bonne approche

class AdminGestionRecetteController extends ModuleAdminController
{
    public function __construct()
    {
        $this->table = 'recette';
        $this->identifier = 'id_recette';
        $this->className = 'Recette';
        $this->lang = false;
        $this->bootstrap = true;

        // Définir fields_list AVANT l'appel parent
        $this->fields_list = [
            'id_recette' => ['title' => 'ID', 'align' => 'center', 'class' => 'fixed-width-xs'],
            'name'       => ['title' => 'Nom', 'filter_key' => 'a!name'],
            'active'     => ['title' => 'Actif', 'active' => 'status', 'type' => 'bool', 'align' => 'center'],
        ];

        parent::__construct(); // Maintenant que tout est prêt
    }
}

Cette règle s'applique aussi à $this->fields_form, $this->bulk_actions et toute propriété que le constructeur parent exploite lors de l'initialisation.

Purger le cache : l'étape qu'on oublie toujours

PrestaShop maintient un index des classes pour accélérer l'autoloading. Quand vous ajoutez ou renommez un contrôleur, cet index est obsolète et votre nouveau fichier est tout simplement ignoré.

Sur PrestaShop 1.7 et 8.x

La méthode la plus fiable est de supprimer manuellement le fichier d'index :

# Supprimer le cache d'index des classes
rm -f var/cache/dev/class_index.php
rm -f var/cache/prod/class_index.php

Vous pouvez aussi vider le cache depuis le back-office via Paramètres avancés > Performances > Vider le cache, mais en cas de problème de contrôleur, la suppression manuelle du class_index.php est plus sûre car elle force une reconstruction complète.

Astuce PrestaShop 8.x : Si vous travaillez en mode debug (_PS_MODE_DEV_ à true dans config/defines.inc.php), le cache est reconstruit automatiquement à chaque requête. Activez-le systématiquement en développement.

Déclarer correctement le contrôleur dans le module

Le fichier principal du module doit enregistrer l'onglet d'administration. Voici la structure complète :

// monmodule.php

class MonModule extends Module
{
    public function __construct()
    {
        $this->name = 'monmodule';
        $this->tab = 'administration';
        $this->version = '1.0.0';
        $this->author = 'Alexandre Carette';
        $this->need_instance = 0;
        $this->bootstrap = true;

        parent::__construct();

        $this->displayName = $this->l('Mon Module');
        $this->description = $this->l('Gestion des recettes depuis le back-office.');
    }

    public function install()
    {
        return parent::install() && $this->installTab();
    }

    public function uninstall()
    {
        return parent::uninstall() && $this->uninstallTab();
    }

    private function installTab()
    {
        $tab = new Tab();
        $tab->active = 1;
        // "AdminGestionRecette" — sans le suffixe Controller
        $tab->class_name = 'AdminGestionRecette';
        $tab->name = [];

        foreach (Language::getLanguages(true) as $lang) {
            $tab->name[$lang['id_lang']] = 'Gestion Recettes';
        }

        $tab->id_parent = (int) Tab::getIdFromClassName('AdminParentModulesSf');
        $tab->module = $this->name;

        return $tab->add();
    }

    private function uninstallTab()
    {
        $id = (int) Tab::getIdFromClassName('AdminGestionRecette');
        if ($id) {
            $tab = new Tab($id);
            return $tab->delete();
        }
        return true;
    }
}

Utiliser le générateur de modules PrestaShop

Pour éviter ces erreurs de structure dès le départ, PrestaShop met à disposition un générateur de squelette de module via le validateur officiel. Cet outil produit une arborescence conforme avec les bons nommages, les bons répertoires et un composer.json prêt à l'emploi.

C'est un gain de temps considérable, surtout pour les premiers modules : plutôt que de deviner la convention, on part d'une base fonctionnelle et on se concentre sur la logique métier.

Checklist de diagnostic rapide

Si votre contrôleur admin affiche une page blanche, vérifiez dans cet ordre :

1. **Nommage** : fichier, classe et déclaration Tab sont-ils synchronisés ?
2. **Constructeur** : `parent::__construct()` est-il appelé **après** les définitions de propriétés ?
3. **Cache** : avez-vous supprimé `var/cache/*/class_index.php` ?
4. **Arborescence** : le fichier est-il dans `modules/monmodule/controllers/admin/` ?
5. **Mode debug** : `_PS_MODE_DEV_` est-il activé pour voir les erreurs PHP ?
6. **ObjectModel** : si vous utilisez `$this->className`, la classe Model correspondante existe-t-elle et est-elle accessible ?
7. **Permissions** : le profil employé a-t-il les droits sur ce contrôleur (onglet Permissions) ?