Guide Complet : bin/magento setup:upgrade vs setup:di:compile

Si vous avez déjà fixé votre terminal avant un déploiement Magento 2 en vous demandant “Est-ce que je lance les deux ? Dans quel ordre ? Dois-je vraiment recompiler ?” — vous n’êtes pas seul.

Ces deux commandes sont les gardiennes de chaque déploiement Magento. Pourtant, la plupart des développeurs les traitent comme des formules magiques : copier, coller, prier. Dans ce guide, je vais démonter l’architecture derrière les deux commandes pour que vous sachiez exactement ce qui se passe sous le capot, quand chacune est obligatoire, et pourquoi l’ordre compte.

Pas de devinettes. Pas de DevOps par mimétisme. Juste de la clarté.

La Différence Principale en Une Phrase

setup:upgrade gère votre base de données et le cycle de vie des modules.
setup:di:compile génère le code PHP nécessaire au fonctionnement de l’application.

Elles résolvent deux problèmes complètement différents. Les confondre revient à confondre votre architecte avec votre équipe de construction — les deux sont essentiels, mais ils ne font pas le même travail.

Ce Que bin/magento setup:upgrade Fait Réellement

Quand vous exécutez cette commande, Magento effectue une vérification du cycle de vie à l’échelle du système sur quatre couches distinctes :

1. Enregistrement des Modules et Mises à Jour du Schéma

Magento scanne app/etc/config.php et le compare au système de fichiers. Si vous avez ajouté un nouveau module (ou mis à jour un existant), il :

• Enregistre le module dans la base de données (table setup_module)
• Exécute les scripts InstallSchema ou UpgradeSchema
• Applique les correctifs de données (changements dans db_schema_whitelist.json)

Considérez cela comme : La mise à jour des plans et des fondations du bâtiment.

2. Compilation de l’Injection de Dépendances (Partielle)

C’est là que ça devient intéressant. setup:upgrade déclenche effectivement un processus de compilation léger — mais seulement pour les modules nouveaux ou modifiés. Il génère le code minimum nécessaire pour rendre le nouveau module fonctionnel.

L’inconvénient : Ce n’est pas un setup:di:compile complet. Il n’optimisera pas l’intégralité de votre codebase. Il ne détectera pas les dépendances entre modules qui ont changé dans des modules que vous n’avez pas touchés.

3. Vidage du Cache

Magento vide les caches spécifiques liés à la configuration et à la mise en page. Cela garantit que la boutique reflète immédiatement vos changements de schéma.

4. Déclenchement des Correctifs de Données

Tous les nouveaux correctifs de données (versionnés ou non) s’exécutent ici. C’est là que les données d’exemple, les configurations par défaut ou les scripts de migration s’exécutent.

Quand setup:upgrade est-il Obligatoire ?

Ce Que bin/magento setup:di:compile Fait Réellement

Cette commande est le générateur de code de Magento. Elle lit l’intégralité de votre codebase — chaque di.xml, chaque constructeur, chaque préférence, chaque plugin — et génère des classes PHP optimisées qui vivent dans generated/.

Les Quatre Phases de Génération

1. Interception (plugins)     → generated/code/Magento/.../Plugin
2. Préférences & Types Virtuels → generated/code/.../Preference
3. Proxies & Factories         → generated/code/.../Proxy, Factory
4. Intercepteurs (around/before/after) → generated/code/.../Interceptor

1. Intercepteurs pour Plugins

Chaque classe avec un plugin voit une classe Interceptor générée. Ce wrapper délègue à vos méthodes before, around et after. Sans compilation, Magento devrait faire cela via une réflexion lente à l’exécution.

2. Proxies pour Dépendances Lourdes

Si un argument de constructeur est typé mais marqué comme paresseux (ou si Magento détecte un risque de dépendance circulaire), il génère une classe Proxy. Cela retarde l’instanciation jusqu’à ce que l’objet soit réellement utilisé.

3. Factories pour Classes Non-Injectables

Les classes qui ne peuvent pas être auto-câblées (comme celles nécessitant des paramètres d’exécution) reçoivent des classes Factory générées dans generated/code/.

4. Préférences & Types Virtuels

Quand vous déclarez un <preference for="..." type="..."/> ou un <virtualType .../>, Magento génère la logique de routage pour que le conteneur résolve l’implémentation correcte instantanément.

Le Résultat Critique : Le Répertoire generated/

Après avoir exécuté setup:di:compile, votre répertoire generated/ contient des milliers de fichiers PHP. En mode production, Magento lit uniquement depuis ici. Il ne touche jamais vos fichiers originaux dans app/code/ ou vendor/ pour la résolution des classes.

C’est pourquoi cette commande est non négociable en production.

Quand setup:di:compile est-il Obligatoire ?

La Séquence de Déploiement Qui Fonctionne Vraiment

Maintenant que vous comprenez l’architecture, l’ordre de déploiement correct devient évident :

# Étape 1 : Mettre la boutique en mode maintenance
bin/magento maintenance:enable

# Étape 2 : Appliquer les changements de code (git pull, rsync, etc.)
# ... votre script de déploiement ...

# Étape 3 : Installer/mettre à jour les modules et le schéma
bin/magento setup:upgrade

# Étape 4 : Générer le code optimisé pour l'ENSEMBLE de la codebase
bin/magento setup:di:compile

# Étape 5 : Déployer les assets statiques (si les thèmes ont changé)
bin/magento setup:static-content:deploy -f

# Étape 6 : Vider les caches
bin/magento cache:flush

# Étape 7 : Désactiver le mode maintenance
bin/magento maintenance:disable

Pourquoi Cet Ordre est Important

1. setup:upgrade avant setup:di:compile : Les nouveaux modules doivent être enregistrés dans la base de données avant que leurs fichiers di.xml puissent être compilés. Si vous compilez d’abord, Magento ne sait pas que le nouveau module existe.

2. setup:di:compile avant cache:flush : La compilation génère des fichiers dans generated/. Vider les caches avant la compilation est inutile — vous videriez les caches pour du code généré obsolète.

3. setup:static-content:deploy après la compilation : Le déploiement statique repose parfois sur des classes générées (pour la compilation LESS, la fusion requirejs-config, etc.).

Mode Production vs Mode Développeur : Le Piège de la Compilation

C’est là que la plupart des freelances perdent des heures à déboguer des problèmes « ça marche chez moi ».

Le piège : En mode développeur, vous pouvez sauter complètement setup:di:compile. Magento générera paresseusement les intercepteurs et proxies au fur et à mesure qu’ils sont demandés. C’est plus rapide pour le développement local.

Le désastre : Vous déployez en production sans compiler. La première requête client déclenche une classe qui n’existe pas dans generated/. Magento lance une erreur fatale. Votre boutique est hors ligne.

Règle d’or : Ne déployez jamais en production sans exécuter setup:di:compile, même si vous n’avez changé aucun fichier di.xml. La compilation est idempotente — l’exécuter inutilement coûte du temps, mais l’ignorer coûte du chiffre d’affaires.

Scénarios Courants : La Matrice de Décision

Scénario A : « J’ai seulement corrigé un bug dans une classe PHP »

• Changé le corps d’une méthode dans app/code/Vendor/Module/Model/Something.php ?
• Pas de changements de constructeur ? Pas de nouvelles dépendances ?
• Action : Vide juste le cache. Aucune des deux commandes n’est strictement nécessaire.
• Déploiement sûr : Lancez les deux quand même. Prend 2 minutes de plus, élimine le doute.

Scénario B : « J’ai installé un nouveau module tiers »

• Action : setup:upgrade puis setup:di:compile.
• Pourquoi : Le module a besoin d’un enregistrement en base de données ET de la compilation de son di.xml.

Scénario C : « J’ai ajouté un plugin pour modifier le comportement du checkout »

• Action : setup:di:compile obligatoire. setup:upgrade seulement si c’est un nouveau module.
• Pourquoi : Les plugins sont compilés en intercepteurs. Sans compilation, votre plugin est invisible pour Magento.
• Connexe : Consultez le guide de personnalisation du checkout pour des exemples concrets de plugins dans le flux de checkout.

Scénario D : « J’ai mis à jour le noyau Magento via Composer »

• Action : Toujours les deux commandes, dans l’ordre.
• Pourquoi : Les mises à jour du noyau changent di.xml, les schémas de base de données, et ajoutent souvent de nouveaux modules. Ne supposez jamais qu’un correctif est « sûr » à déployer sans les commandes complètes du cycle de vie.

Scénario E : « Mon client hurle parce que le site est tombé après le déploiement »

• Vérification 1 : Avez-vous exécuté setup:upgrade ? Vérifiez la table setup_module pour les incohérences de version.
• Vérification 2 : Avez-vous exécuté setup:di:compile ? Vérifiez generated/ pour les fichiers intercepteur manquants.
• Vérification 3 : La boutique est-elle en mode production ? Lancez bin/magento deploy:mode:show.
• Option nucléaire : rm -rf generated/* var/cache/* var/page_cache/* et relancez la séquence complète.

Implications de Performance Que Tout Entrepreneur Devrait Connaître

En tant que freelance ou propriétaire d’agence, vous ne faites pas qu’écrire du code — vous gérez les attentes des clients et les coûts serveur.

Durée de setup:di:compile

Conseil pro pour les appels clients : Ne dites jamais “Je compile” — dites “Je génère le code d’application optimisé pour garantir des temps de réponse inférieurs à la seconde.” Même action, valeur perçue complètement différente.

Besoins en RAM

La compilation est intensive en mémoire. Si votre serveur de déploiement a moins de 2GB de RAM, la compilation échouera ou utilisera le swap (la rendant 10× plus lente). Prévoyez une infrastructure adéquate — c’est moins cher que des temps d’arrêt.

Compilation Parallèle

Magento 2.4.6+ prend en charge la compilation parallèle via :

bin/magento setup:di:compile --multi-threads=4

Cela peut réduire le temps de compilation de 40 à 60% sur les serveurs multi-cœurs. Ajoutez ceci à vos scripts de déploiement immédiatement.

La Boîte à Outils de Communication du Freelance

Quand votre client demande “Pourquoi le déploiement prend 10 minutes ?”, voici votre script :

“Magento génère des milliers de fichiers PHP optimisés pendant le déploiement — considérez cela comme pré-construire chaque porte et fenêtre avant que les clients n’entrent dans le magasin. Ignorer cette étape rendrait le site 10× plus lent ou planterait complètement. Les 10 minutes maintenant évitent des heures d’interruption plus tard.”

Et quand ils demandent “Pouvons-nous sauter l’étape de compilation pour déployer plus vite ?” :

“Nous pouvons, mais seulement si vous êtes d’accord pour que le site plante potentiellement et charge en 8+ secondes au lieu de moins d’une seconde. La compilation est ce qui rend Magento rapide en production.”

Cadrez les nécessités techniques comme des protections commerciales, pas des inconvénients techniques.

Référence Rapide : L’Aide-Mémoire

Sauvegardez ceci. Imprimez-le. Collez-le sur votre écran.

Séquence obligatoire : setup:upgrade → setup:di:compile → setup:static-content:deploy → cache:flush

Conclusion : Arrêtez de Deviner, Commencez à Architecturer

La différence entre un développeur junior et un consultant senior n’est pas de savoir quelles commandes exécuter — c’est de comprendre pourquoi elles existent dans l’architecture de Magento.

setup:upgrade est votre gestionnaire de schéma et de cycle de vie des modules.
setup:di:compile est votre générateur de code et optimiseur de performances.

Exécutez-les dans le mauvais ordre, sautez-les en production, ou confondez leurs objectifs, et vous ne cassez pas seulement un déploiement — vous cassez une entreprise.

Maîtrisez ces deux commandes, et vous maîtrisez les fondations de chaque déploiement Magento. Tout le reste n’est que détails.

Vous planifiez une mise à jour Magento ou besoin d’aide avec les workflows de déploiement ? Consultez mes services de migration et mise à niveau .

Ce guide vous a été utile ? Je publie des analyses approfondies comme celle-ci chaque semaine pour les entrepreneurs et développeurs francophones qui construisent des projets e-commerce sérieux. Suivez-moi pour plus de contenu sur l’architecture Magento sans fioritures.

Tags : #Magento2 #Ecommerce #Deployment #Backend #CLI #DevOps #FreelanceTips