Créer un thème PrestaShop : overrides, assets et bonnes pratiques

Introduction

Créer un thème PrestaShop sur-mesure est un passage obligé pour tout développeur e-commerce sérieux. Que vous partiez d'un thème existant ou d'une base vierge, la maîtrise du système d'overrides et de la gestion des assets (CSS/JS) est fondamentale.

Dans cet article, je vous guide à travers les mécanismes internes de PrestaShop pour créer un thème propre, performant, et maintenable — en évitant les pièges classiques qui font perdre des heures.

Comprendre le chargement des assets dans PrestaShop

Le rôle central de `FrontController::setMedia()`

Tout commence dans la méthode setMedia() du contrôleur front. C'est elle qui détermine quels fichiers CSS et JavaScript sont chargés sur chaque page de votre boutique.

Voici le mécanisme de base (PrestaShop 1.6) :

public function setMedia()
{
    if ($this->useMobileTheme()) {
        $this->setMobileMedia();
        return true;
    }

    $this->addCSS(_THEME_CSS_DIR_ . 'global.css', 'all');
    $this->addjquery();
    $this->addjqueryPlugin('easing');
    $this->addJS(_PS_JS_DIR_ . 'tools.js');
    $this->addJS(_THEME_JS_DIR_ . 'global.js');
}

Point clé : l'ordre d'appel des méthodes addCSS() et addJS() détermine l'ordre de chargement des fichiers dans le HTML — sauf si le CCC est activé, auquel cas les fichiers sont concaténés et l'ordre peut varier.

Le système d'autoload des assets

PrestaShop intègre un mécanisme d'autoload très pratique : tout fichier .js placé dans themes/votre-theme/js/autoload/ et tout fichier .css dans themes/votre-theme/css/autoload/ sont automatiquement inclus sur toutes les pages.

// Chargement automatique des JS
if (@filemtime($this->getThemeDir() . 'js/autoload/')) {
    foreach (scandir($this->getThemeDir() . 'js/autoload/', 0) as $file) {
        if (preg_match('/^[^.].*\.js$/', $file)) {
            $this->addJS($this->getThemeDir() . 'js/autoload/' . $file);
        }
    }
}

Astuce : les fichiers sont chargés par ordre alphabétique (scandir avec le flag 0). Si vous avez besoin d'un ordre précis, préfixez vos fichiers : 01-utils.js, 02-main.js, etc.

PrestaShop 1.7 / 8.x : le système d'assets a été modernisé. Les thèmes utilisent désormais Webpack via theme.yml et les assets sont déclarés dans assets/css/ et assets/js/. La méthode setMedia() existe toujours dans les contrôleurs, mais les bonnes pratiques privilégient la déclaration dans le fichier de configuration du thème.

Le système d'overrides : personnaliser sans toucher au core

L'override est le mécanisme qui permet de modifier le comportement natif de PrestaShop sans éditer les fichiers du cœur. C'est indispensable pour un thème maintenable et compatible avec les mises à jour.

Hiérarchie des fichiers

La règle d'or : respecter exactement la même arborescence que le dossier classes/ du core.

Par exemple, pour overrider la classe Media :

# Fichier original
classes/Media.php

# Votre override
override/classes/Media.php

Syntaxe d'un override

Votre classe doit étendre la classe Core correspondante :

<?php

// override/classes/Media.php
class Media extends MediaCore
{
    public static function cccJS($js_files)
    {
        // Votre logique personnalisée ici
    }
}

Les 5 pièges classiques des overrides

#### 1. Le commentaire mal placé avant la déclaration de classe

Un piège redoutable et difficile à diagnostiquer. Le commentaire doit être placé avant la ligne de déclaration, jamais sur la même ligne de façon ambiguë :

// ❌ MAUVAIS — peut provoquer une erreur de parsing
class Media extends MediaCore // Ma classe override
{
}

// ✅ CORRECT
// Ma classe override
class Media extends MediaCore
{
}

En PHP, un commentaire // sur la même ligne qu'une déclaration de classe est syntaxiquement valide, mais certaines versions de PrestaShop parsent ce fichier de manière non standard pour le système de cache. Gardez vos déclarations de classe propres.

#### 2. Le cache class_index.php non vidé

C'est la cause n°1 des overrides qui "ne fonctionnent pas". PrestaShop maintient un index de toutes les classes dans app/cache/ (ou cache/ selon les versions). Cet index n'est pas régénéré automatiquement quand vous ajoutez un override.

Solution : supprimez le fichier class_index.php dans le dossier cache :

# PrestaShop 1.6
rm -f cache/class_index.php

# PrestaShop 1.7 / 8.x
rm -f var/cache/dev/class_index.php
rm -f var/cache/prod/class_index.php

PrestaShop le régénèrera automatiquement au prochain chargement de page.

#### 3. La casse de class vs Class

PHP est insensible à la casse pour les mots-clés, mais PrestaShop l'est dans son système de résolution d'overrides. Utilisez toujours class en minuscules :

// ❌ Peut poser problème
Class Media extends MediaCore {}

// ✅ Toujours en minuscules
class Media extends MediaCore {}

#### 4. Les overrides désactivés en back-office

PrestaShop permet de désactiver globalement les overrides dans les paramètres avancés. Si votre override ne fonctionne pas malgré tout :

• **PrestaShop 1.6 :** Paramètres avancés > Performances > Désactiver les surcharges
• **PrestaShop 1.7 / 8.x :** Paramètres avancés > Performances > Désactiver toutes les surcharges

Vérifiez que cette option est bien sur Non.

#### 5. Les permissions fichiers (chmod)

Sur un serveur Linux, des permissions incorrectes empêchent PHP de lire vos fichiers d'override :

# Permissions recommandées
find override/ -type f -exec chmod 644 {} \;
find override/ -type d -exec chmod 755 {} \;

Le CCC : Combine, Compress, Cache

Le CCC est le système natif de PrestaShop pour optimiser le chargement des assets. Il concatène et minifie les fichiers CSS et JS en un seul fichier mis en cache.

Fonctionnement

Quand le CCC est activé, la classe Media gère la concaténation. Les fichiers sont combinés, un hash est généré pour le nom du fichier cache, et le résultat est stocké dans themes/votre-theme/cache/.

Impact sur l'ordre de chargement

Sans CCC : les fichiers sont inclus dans l'ordre exact où vous les déclarez via addCSS() / addJS().

Avec CCC : les fichiers sont regroupés et l'ordre peut être modifié. Si votre JavaScript dépend d'un ordre d'exécution précis, le CCC peut casser votre thème.

Recommandations

• **En développement :** désactivez le CCC pour débugger facilement
• **En production :** préférez des solutions modernes (Webpack, Vite) au CCC natif
• **PrestaShop 8.x :** le CCC est toujours disponible mais les thèmes modernes gèrent la compilation côté build plutôt qu'à la volée

Workflow de création d'un thème (résumé)

PrestaShop 1.6

1. Dupliquer le thème `default-bootstrap`
2. Modifier `config.xml` avec vos informations
3. Personnaliser les templates `.tpl` (Smarty)
4. Ajouter vos CSS/JS dans les dossiers `css/` et `js/`
5. Utiliser les overrides pour la logique métier
6. Vider `class_index.php` et tous les caches

PrestaShop 1.7 / 8.x

1. Partir du thème `classic` ou utiliser le starter theme
2. Configurer `theme.yml` (assets, layout, hooks)
3. Personnaliser les templates `.tpl` (Smarty, toujours)
4. Gérer les assets via Webpack (`_dev/` → compilation → `assets/`)
5. Déclarer les modules nécessaires dans `theme.yml`
6. Tester avec `php bin/console cache:clear`

# Commande de vidage de cache PrestaShop 8.x
php bin/console cache:clear --env=prod
php bin/console cache:clear --env=dev

Checklist avant mise en production

• [ ] Tous les overrides fonctionnent après suppression de `class_index.php`
• [ ] Les permissions fichiers sont correctes (644/755)
• [ ] Le CCC est testé si activé
• [ ] Les assets se chargent dans le bon ordre
• [ ] Le thème est responsive (tester sur mobile)
• [ ] Les performances sont validées (PageSpeed > 80)
• [ ] Un thème enfant ou override est utilisé — jamais de modification du core