Override du CategoryController dans PrestaShop : guide complet

Pourquoi overrider le CategoryController ?

Le CategoryController est le contrôleur front-office responsable de l'affichage des pages catégories dans PrestaShop. Il gère le chargement des produits, la pagination, le tri, les filtres et l'injection des variables Smarty vers le template category.tpl.

Overrider ce contrôleur permet de :

• Modifier la logique de récupération des produits (filtres personnalisés, tri spécifique)
• Ajouter des variables Smarty supplémentaires au template
• Personnaliser la pagination ou le nombre de produits par page
• Injecter des données métier spécifiques (promotions, labels, stocks)
• Modifier le comportement SEO (canonical, meta dynamiques)

Créer l'override étape par étape

1. Créer le fichier d'override

Le fichier doit être placé dans le dossier override/controllers/front/ de votre installation PrestaShop :

/override/controllers/front/CategoryController.php

2. Structurer la classe correctement

La classe d'override doit étendre CategoryControllerCore (et non CategoryController) :

<?php
/**
 * Override du CategoryController
 * Personnalisation de l'affichage des pages catégories
 */
class CategoryController extends CategoryControllerCore
{
    /**
     * Initialisation du contrôleur
     */
    public function init()
    {
        parent::init();
        // Votre logique d'initialisation personnalisée
    }

    /**
     * Assignation des variables Smarty
     */
    public function initContent()
    {
        parent::initContent();

        // Exemple : ajouter une variable personnalisée au template
        $this->context->smarty->assign([
            'custom_category_data' => $this->getCustomData(),
        ]);
    }

    /**
     * Exemple de méthode personnalisée
     */
    protected function getCustomData()
    {
        // Récupérer des données spécifiques à la catégorie
        return [
            'category_id' => $this->category->id,
            'has_subcategories' => $this->category->getSubCategories($this->context->language->id) ? true : false,
        ];
    }
}

3. Vider le cache du class_index

C'est l'étape la plus fréquemment oubliée et la cause numéro un des overrides qui ne fonctionnent pas. PrestaShop maintient un index des classes pour optimiser l'autoloading. Après avoir créé ou modifié un override, vous devez impérativement supprimer le fichier cache :

rm var/cache/prod/class_index.php
rm var/cache/dev/class_index.php

Sur PrestaShop 1.6, le chemin est différent :

rm cache/class_index.php

Alternativement, vous pouvez vider le cache depuis le back-office : Paramètres avancés → Performances → Vider le cache.

Attention : Sur PrestaShop 8.x, le système de cache Symfony ajoute une couche supplémentaire. Pensez également à vider le cache Symfony :

```bash

php bin/console cache:clear --env=prod

```

Méthodes clés du CategoryController à connaître

Avant d'écrire votre override, il est essentiel de comprendre les méthodes principales :

MéthodeRôle `init()`Charge l'objet `Category`, vérifie les permissions d'accès `initContent()`Prépare et assigne les variables Smarty (produits, pagination, sous-catégories) `getTemplateVarPage()`Génère les métadonnées SEO de la page (PS 1.7+) `getListingLabel()`Retourne le label de la catégorie pour le fil d'Ariane (PS 1.7+) `getBreadcrumbLinks()`Construit le fil d'Ariane (PS 1.7+) `getCanonicalURL()`Génère l'URL canonique de la page catégorie

Exemple concret : modifier le tri par défaut

Voici un cas d'usage fréquent — forcer un tri spécifique sur certaines catégories :

<?php
class CategoryController extends CategoryControllerCore
{
    public function initContent()
    {
        // Forcer le tri par prix croissant pour la catégorie "Promotions" (id 42)
        if ((int)$this->category->id === 42) {
            $_GET['order'] = 'product.price.asc';
        }

        parent::initContent();
    }
}

Exemple avancé : injecter des données produit enrichies (PS 8.x)

Sur PrestaShop 8.x, le système de présentation des produits a évolué. Voici comment enrichir les données :

<?php

use PrestaShop\PrestaShop\Adapter\Presenter\Product\ProductListingPresenter;

class CategoryController extends CategoryControllerCore
{
    public function initContent()
    {
        parent::initContent();

        // Récupérer les produits déjà assignés
        $products = $this->context->smarty->getTemplateVars('listing');

        if (!empty($products['products'])) {
            foreach ($products['products'] as &$product) {
                // Ajouter le stock réel pour affichage front
                $product['real_stock'] = StockAvailable::getQuantityAvailableByProduct(
                    $product['id_product']
                );
            }

            $this->context->smarty->assign('listing', $products);
        }
    }
}

Bonnes pratiques et pièges à éviter

À faire

• **Toujours appeler `parent::method()`** dans vos méthodes overridées pour conserver le comportement natif
• **Tester en environnement de développement** avant de pousser en production
• **Documenter vos overrides** : ajoutez un commentaire en en-tête expliquant pourquoi l'override existe
• **Versionner vos overrides** dans Git pour garder un historique des modifications

À ne pas faire

• **Ne jamais modifier les fichiers core** directement (`classes/controller/FrontController.php`, etc.)
• **Ne pas empiler les overrides** : un seul fichier d'override par classe est autorisé. Si un module utilise déjà un override du `CategoryController`, il y aura un conflit
• **Ne pas oublier le cache** : c'est la cause la plus fréquente de "mon override ne fonctionne pas"

Gestion des conflits d'overrides

Si un module a déjà un override du CategoryController, vous avez deux options :

1. **Fusionner manuellement** les deux overrides dans un seul fichier
2. **Utiliser un hook** à la place de l'override quand c'est possible (approche recommandée sur PS 8.x)

Sur PrestaShop 8.x, les hooks sont souvent préférables aux overrides :

// Dans un module, utiliser le hook actionCategoryControllerInitAfter
public function hookActionCategoryControllerInitAfter($params)
{
    // Modifier le comportement sans override
    $controller = $params['controller'];
    // ...
}

Alternative moderne : les hooks sur PrestaShop 8.x

Depuis PrestaShop 1.7.7+, le système de hooks a été enrichi avec des hooks de contrôleur automatiques. Pour chaque contrôleur front, PrestaShop déclenche :

• `actionCategoryControllerInitBefore`
• `actionCategoryControllerInitAfter`
• `actionCategoryControllerInitContentBefore`
• `actionCategoryControllerInitContentAfter`

Ces hooks permettent d'intervenir sans créer d'override, évitant ainsi les conflits entre modules. C'est l'approche recommandée pour les nouvelles personnalisations sur PrestaShop 8.x.

Diagnostic : l'override ne fonctionne pas

Si votre override semble ignoré, vérifiez dans cet ordre :

1. **Le fichier `class_index.php`** a bien été supprimé (voir section cache ci-dessus)
2. **Le nom de la classe** est correct : `CategoryController extends CategoryControllerCore`
3. **Le chemin du fichier** est correct : `override/controllers/front/CategoryController.php`
4. **Le mode debug** est activé pour voir les erreurs éventuelles : dans `config/defines.inc.php`, passez `_PS_MODE_DEV_` à `true`
5. **Aucun autre override** ne crée de conflit (vérifiez les modules installés)
6. **La syntaxe PHP** est valide : testez avec `php -l override/controllers/front/CategoryController.php`