Mise à jour — 2026.

L’article d’origine date de 2020 (révisé en 2021). Je l’ai remis à jour : versions de WordPress et des packages Roots, abandon de wp-password-bcrypt (devenu inutile depuis WordPress 6.8), bascule MySQL 8.4 / Mailpit / docker compose v2. La démarche, elle, n’a pas pris une ride.

Dans cet article nous allons voir quels sont les avantages d’utiliser Composer avec WordPress, et comment le mettre en place.

Je souhaitais améliorer 4 points essentiels dans la gestion des sites sous WordPress :

  1. Installation et mise à jour du CMS
  2. Installation et mise à jour des plugins
  3. Workflow de développement en équipe
  4. Évolutivité et maintenabilité du (des) thème(s)

J’ai donc commencé à regarder ce qui existait déjà. C’est pendant ces recherches que j’ai découvert que d’autres avaient réfléchi à la question et utilisaient Composer et wpackagist dans leurs projets.

Avant d’aller plus loin, je vous invite à aller voir du côté du dépôt GitHub WordPress composer-skeleton.

Pourquoi ce dépôt

Au fil des années passées à développer des sites et applications, j’ai vite compris l’avantage d’automatiser certaines tâches, notamment la gestion des librairies et des plugins.

Quand on développe en PHP, Composer est devenu indispensable. WordPress et quelques autres CMS font figure d’exception en ne l’utilisant pas par défaut. Pourtant, en tant que développeur, il y a tout intérêt à intégrer cet outil à ses projets.

Quelques avantages :

  • Alléger votre dépôt Git en traitant WordPress et les plugins comme des dépendances : vous ne versionnez que votre code.
  • Un composer.lock qui fige précisément les versions de WordPress et de chaque plugin.
  • Installer un nouveau projet en une commande.
  • La gestion des environnements (local / staging / prod).
  • L’autoloading et les namespaces dans vos plugins et thèmes.

Le dépôt WordPress composer-skeleton condense ce que j’ai mis en place et éprouvé sur des dizaines de projets WordPress, plus ou moins complexes.

Ce projet est ouvertement inspiré de Roots (et de leur stack Bedrock). Leur travail est excellent ; j’avais simplement besoin d’un starter calé sur mes propres habitudes et contraintes du quotidien.

Quels sont les outils inclus

Roots
Comme évoqué plus haut, le projet s’appuie sur plusieurs packages de Roots :

code
"roots/wordpress": "^6.8",
"roots/wp-config": "^1.0",

roots/wordpress installe le cœur WordPress comme une dépendance Composer, et roots/wp-config permet une configuration propre, gérée par environnement.

Ce qui a changé en 2026

Le starter embarquait historiquement roots/wp-password-bcrypt pour forcer le hachage des mots de passe en bcrypt (WordPress utilisait jusque-là le vieux phpass). Depuis WordPress 6.8, bcrypt est natif dans le cœur : les fonctions wp_hash_password() et wp_check_password() s’appuient désormais sur password_hash() / password_verify() de PHP. Roots a donc officiellement abandonné le package. Sur WordPress 6.8 ou plus récent, retirez roots/wp-password-bcrypt : aucune migration n’est nécessaire, les mots de passe existants continuent de fonctionner et sont re-hachés à la prochaine connexion.

Un script est également présent dans le dossier mu-plugins (Must-Use) : il charge automatiquement tous les mu-plugins qui s’y trouvent.

WP-CLI

WP-CLI est très utile pour piloter le projet en ligne de commande : opérations de maintenance, configuration, gestion du cron WordPress…

Je l’utilise surtout pour rapatrier la base de prod en local en réécrivant l’URL et les chemins d’uploads à la volée :

terminal
$ wp db export
$ wp search-replace 'https://mon-site.fr' 'http://mon-site.test' --skip-columns=guid

Docker

J’utilise un fichier compose.yaml pour générer rapidement la base de données du projet. C’est devenu un standard chez moi : fini MySQL installé en global sur la machine. Ça permet de contrôler la version du SGBD et de garantir que chaque développeur dispose du même environnement.

Ce fichier permet aussi d’ajouter facilement d’autres services : Elasticsearch / OpenSearch, Mailpit pour intercepter les e-mails en local, etc.

Ce qui a changé en 2026 : la commande historique docker-compose (avec tiret, v1) est dépréciée au profit du plugin docker compose (v2). Côté base, MySQL 5.7 est en fin de vie depuis octobre 2023 : partez sur MySQL 8.4 LTS (ou MariaDB). Et Mailhog n’est plus maintenu : son remplaçant moderne est Mailpit.

Comment ça marche

Initialisation

terminal
$ composer create-project agencearcange/wordpress-composer-skeleton my-project

Cette commande génère un nouveau projet avec la dernière version du squelette. C’est une « coquille vide » pour démarrer n’importe quel projet.

Composer va alors récupérer les plugins déclarés et, surtout, télécharger automatiquement la version de WordPress spécifiée dans le composer.json.

Pour comprendre le fonctionnement, regardons la structure du composer.json :

code
{
   "extra": {
        "installer-paths": {
            "public/content/mu-plugins/{$name}/": ["type:wordpress-muplugin"],
            "public/content/plugins/{$name}/": ["type:wordpress-plugin"],
            "public/content/themes/{$name}/": ["type:wordpress-theme"]
        },
        "dropin-paths": {
            "public/content/languages/"         : ["vendor:koodimonni-language"],
            "public/content/languages/plugins/" : ["vendor:koodimonni-plugin-language"],
            "public/content/languages/themes/"  : ["vendor:koodimonni-theme-language"]
        },
        "wordpress-install-dir": "public/wp"
    }
}

Composer est configuré pour fonctionner avec le dépôt wpackagist, qui « scanne » le SVN de WordPress (plugins et thèmes) et expose leurs tags sous forme de packages Composer.

La configuration extra permet :

  • la copie de WordPress dans public/wp
  • la copie des plugins et thèmes dans leurs dossiers respectifs
  • la création du fichier .env à partir de .env.dist lors de l’installation

La structure des fichiers

code
my-project/
├── config/
│   ├── environments/
│   │   └── development.php
│   └── application.php
├── public/
│   ├── wp/
│   ├── content/
│   │   ├── languages/
│   │   ├── mu-plugins/
│   │   ├── plugins/
│   │   ├── themes/
│   │   └── uploads/
│   ├── .htaccess
│   ├── index.php
│   └── wp-config.php 
├── var/
├── vendor/
├── .env
├── .env.dist
├── .gitignore
├── composer.json
├── compose.yaml
└── wp-cli.yaml

Quelques points importants :

  • les configurations sont dans config/, organisées par environnement
  • le serveur web pointe vers le dossier public/
  • plugins, thèmes et uploads vivent dans public/content/
  • les variables sensibles sont dans le fichier .env (non versionné)

Environnements

La gestion des environnements a deux dimensions.

D’abord, vous pouvez définir des configurations propres à chaque environnement (development, staging…) dans des fichiers du dossier config/environments. Elles viennent supplanter la configuration par défaut.

code
Config::define('SAVEQUERIES', true);
Config::define('WP_DEBUG', true);
Config::define('WP_DEBUG_DISPLAY', true);
Config::define('WP_DISABLE_FATAL_ERROR_HANDLER', true);
Config::define('SCRIPT_DEBUG', true);

Ensuite, les variables comme les identifiants de base de données passent par le fichier .env :

terminal
# Database
DB_NAME='wordpress'
DB_USER='root'
DB_PASSWORD='toor'

Gestion des plugins et des thèmes

La gestion des plugins, thèmes et autres librairies se fait via Composer — c’était le but 🙂

Exemple d’ajout d’un plugin :

terminal
$ composer require wpackagist-plugin/contact-form-7

Base de données

Le starter fournit un fichier compose.yaml pour créer rapidement une base MySQL :

terminal
$ docker-compose up -d

Par défaut, les variables du fichier .env permettent de se connecter à la base générée par Docker.

Aller plus loin

Le dépôt et l’utilisation de Composer ne sont qu’un point de départ pour faciliter le quotidien des développeurs sur WordPress.

Cette architecture ouvre la voie à d’autres améliorations : automatiser les process de développement en équipe, et même mettre en place du déploiement automatique. J’en parle justement dans Travailler en équipe avec WordPress.