Rapatrier un site Magento 2 de production sur une machine Windows 11 pour travailler en local — c’est une étape que tout développeur Magento finit par devoir franchir. Et c’est souvent une source de frustration considérable : conflits de versions PHP, base de données volumineuse, certificats SSL récalcitrants, images en 404 partout. Après avoir tâtonné et accumulé les erreurs, voici le workflow que j’utilise aujourd’hui, basé sur DDEV + WSL2, avec tous les pièges documentés.
Cet article s’adresse aux développeurs Magento débutants qui veulent monter un environnement local fonctionnel sans passer trois jours à déboguer leur configuration Docker.
La stack — pourquoi DDEV sur WSL2 ?
Travailler directement sous Windows avec XAMPP ou Laragon est possible, mais Magento 2 souffre de performances médiocres sur le système de fichiers Windows natif. La bonne approche est de faire tourner tout l’environnement dans WSL2 (Windows Subsystem for Linux), qui offre des performances proches d’un Linux natif, tout en gardant vos outils Windows (VS Code, navigateur, FileZilla) accessibles.
La stack complète
Le cœur du réacteur
Émulation Linux complète sous Windows — performances proches du natif, accès aux outils Linux
Moteur de conteneurs
Configuré pour utiliser le moteur WSL2 — indispensable pour que DDEV fonctionne correctement
L’outil magique
Orchestre PHP, Nginx, MySQL, Elasticsearch sans écrire de docker-compose à la main
Pour l’IDE, VS Code avec l’extension « Remote – WSL » est le choix le plus simple : vous éditez les fichiers directement dans WSL depuis Windows, sans friction. PhpStorm fonctionne aussi avec une configuration remote interpreter pointant vers le conteneur DDEV.
Les étapes de l’installation
Séquence d’installation
Installer WSL2 + Ubuntu
Dans PowerShell admin : wsl --install. Redémarrer, puis configurer Ubuntu. Vérifier avec wsl --list --verbose que Ubuntu tourne bien en version 2.
Installer Docker Desktop
Télécharger depuis docker.com. Dans Settings → General, activer « Use the WSL 2 based engine ». Dans Resources → WSL Integration, activer l’intégration avec Ubuntu.
Installer DDEV dans WSL2
Depuis le terminal Ubuntu : suivre la procédure d’installation officielle sur ddev.com. DDEV s’installe dans le système Linux, pas dans Windows.
Déposer les fichiers Magento dans WSL
Copier les fichiers dans le système de fichiers WSL (ex: ~/projects/monsite/) — pas dans /mnt/c/ qui est le système de fichiers Windows. Les performances seraient catastrophiques.
Configurer et démarrer DDEV
Dans le répertoire du projet : ddev config (choisir le type « magento2 » et la version PHP), puis ddev start. DDEV configure automatiquement Nginx, MySQL, PHP.
Importer la base de données
ddev import-db --file=dump.sql.gz — DDEV gère automatiquement la décompression. Sur une base volumineuse, préférer : ddev mysql < dump.sql
Compiler Magento
ddev exec php bin/magento setup:upgrade, puis setup:di:compile, puis indexer:reindex. Toutes les commandes Magento s’exécutent via ddev exec php bin/magento ....
Écueil n°1 — La reconstruction des conteneurs DDEV
Quand vous modifiez un Dockerfile ou une configuration de service DDEV, le réflexe Docker classique est d’utiliser --build. C’est faux avec DDEV. La bonne commande pour forcer la reconstruction complète en ignorant le cache :
ddev restart --no-cacheÉcueil n°2 — L’enfer de la syntaxe YAML
DDEV utilise des fichiers YAML pour les configurations de services additionnels (.ddev/docker-compose.*.yaml). Deux erreurs très fréquentes :
- Les tabulations — YAML n’accepte que des espaces. Si votre éditeur insère des tabs, DDEV plantera avec une erreur
did not find expected keypeu explicite. - L’attribut
version— les anciens tutoriels commencent parversion: "3". Avec Docker Compose V2, cet attribut est obsolète et génère des erreurs. Supprimez-le.
Écueil n°3 — L’alerte SSL sous Firefox
DDEV génère ses propres certificats SSL pour les domaines *.ddev.site. Sous WSL2, Firefox Windows ne communique pas avec le store de certificats WSL et affiche une alerte rouge « Risque potentiel de sécurité ».
Ne perdez pas de temps à faire communiquer les stores de certificats Windows et WSL. La solution pragmatique : cliquer sur « Avancé » puis « Continuer (risqué) » dans Firefox. Sur un domaine *.ddev.site qui pointe uniquement vers 127.0.0.1, c’est 100% sécurisé. Firefox ajoute une exception permanente.
Écueil n°4 — Le bug Calendar.php et ICU 74+
Sur Magento 2.4.6 et 2.4.7 avec PHP 8.x et ICU ≥ 74.1, tenter d’accéder au back-office en français produit une page blanche :
Warning: Trying to access array offset on value of type null
in vendor/magento/framework/View/Element/Html/Calendar.php on line 114ICU 74+ a supprimé les marqueurs AM/PM pour les langues qui utilisent le format 24h. Le patch rapide sur le fichier vendor :
// Avant (ligne 114)
$this->assign('am', $this->encoder->encode($localeData['calendar']['gregorian']['AmPmMarkers']['0']));
$this->assign('pm', $this->encoder->encode($localeData['calendar']['gregorian']['AmPmMarkers']['1']));
// Après
$this->assign('am', $this->encoder->encode($localeData['calendar']['gregorian']['AmPmMarkers']['0'] ?? 'AM'));
$this->assign('pm', $this->encoder->encode($localeData['calendar']['gregorian']['AmPmMarkers']['1'] ?? 'PM'));Ce bug est corrigé nativement en Magento 2.4.8. Si vous modifiez ce fichier, documentez-le — un composer update l’écrasera silencieusement.
Post-migration — les deux bloqueurs classiques
Bloqueur n°1 — Les cookies rejetés, impossible de se connecter à l’admin
La base contient encore le domaine de production dans core_config_data. Le piège classique : bin/magento config:set web/cookie/cookie_domain "" — Bash supprime les guillemets vides et la commande plante silencieusement.
La méthode imparable :
ddev mysql -e "DELETE FROM core_config_data WHERE path IN ('web/cookie/cookie_domain', 'web/cookie/cookie_path');"
ddev exec php bin/magento cache:flushBloqueur n°2 — Les images en 404
Télécharger l’intégralité de pub/media/ de production est inenvisageable. La solution : un fallback Nginx qui va chercher les images manquantes sur la prod de façon transparente. À ajouter dans .ddev/nginx_full/nginx-site.conf :
location /media/ {
try_files $uri $uri/ @production_fallback;
}
location @production_fallback {
proxy_pass https://www.votre-site-de-prod.com;
proxy_ssl_server_name on; # Indispensable si prod derrière Cloudflare ou CDN
proxy_http_version 1.1;
proxy_set_header Host www.votre-site-de-prod.com;
}Le paramètre proxy_ssl_server_name on est essentiel si votre prod est derrière Cloudflare ou un CDN — sans lui, la connexion SSL est rejetée avec une erreur 502. Après modification :
ddev restartCheat sheet — les commandes DDEV indispensables
Commandes DDEV à connaître par cœur
Un point important sur les modifications vendor/
Si vous modifiez un fichier dans vendor/ pour corriger un bug local, documentez-le immédiatement — dans un fichier PATCHES.md à la racine du projet. Un composer install ou composer update écrasera silencieusement vos modifications.
La solution pérenne est de gérer ce type de correctif via cweagans/composer-patches qui réapplique automatiquement les modifications après chaque mise à jour. C’est l’approche recommandée pour tout correctif sur les fichiers vendor dans un projet sérieux.
FAQ
Pourquoi ne pas utiliser XAMPP ou Laragon directement sous Windows ?
Magento 2 souffre de performances très dégradées sur le système de fichiers Windows natif. La compilation, la génération des assets statiques et les opérations d’indexation peuvent être deux à cinq fois plus lentes que sous Linux. WSL2 + DDEV offre des performances comparables à un serveur Linux réel.
Peut-on utiliser DDEV avec une version Magento antérieure à 2.4 ?
Oui — DDEV permet de configurer des versions PHP anciennes. Pour Magento 2.3.x, configurer PHP 7.4 dans .ddev/config.yaml. La plupart des fonctionnalités DDEV restent disponibles, mais certains services comme Elasticsearch peuvent nécessiter une version spécifique.
Comment gérer plusieurs projets Magento en parallèle ?
DDEV gère nativement plusieurs projets simultanément — chaque projet a son propre répertoire avec son propre .ddev/config.yaml, son propre domaine local et ses propres conteneurs, sans conflit de ports. La commande ddev list affiche tous les projets et leur état.