composer create-project roots/bedrock mon-projet : une seule commande, et l’arborescence complète d’un projet WordPress structuré à la façon d’une application PHP moderne se retrouve en place, prête à être branchée à un front découplé sans devoir réorganiser quoi que ce soit après coup.
Ce tutoriel s’adresse à un développeur déjà à l’aise avec Composer, qui découvre le squelette Bedrock du projet Roots comme point de départ d’un projet headless, plutôt qu’une installation WordPress classique téléchargée manuellement et bricolée ensuite pour y ajouter une gestion de dépendances.
Étape 1 : initialiser le projet
$ composer create-project roots/bedrock mon-projet
$ cd mon-projetL’arborescence générée sépare immédiatement trois espaces distincts : la configuration à la racine du projet, l’application WordPress dans un dossier web/wp traité comme une dépendance figée, et le contenu propre au projet — thème, extensions maison, uploads — dans web/app.
Étape 2 : configurer les variables d’environnement
Bedrock remplace la configuration classique de wp-config.php par un fichier .env, non versionné, qui contient les identifiants de base de données et les clés de sécurité :
DB_NAME='mon_projet'
DB_USER='mon_utilisateur'
DB_PASSWORD='mon_mot_de_passe'
WP_ENV='development'
WP_HOME='https://mon-projet.test'
WP_SITEURL="${WP_HOME}/wp"Cette séparation évite qu’un identifiant sensible ne se retrouve un jour versionné par erreur dans un dépôt Git, un risque bien réel avec un wp-config.php classique manipulé directement.
Étape 3 : déclarer les extensions comme dépendances
Bedrock utilise un dépôt Composer dédié aux extensions et thèmes WordPress, ce qui permet de déclarer chaque extension dans composer.json plutôt que de la copier manuellement dans le dossier plugins.
{
"require": {
"wpackagist-plugin/advanced-custom-fields": "^5.11",
"wpackagist-plugin/wp-graphql": "^1.9"
}
}Un composer install sur un nouvel environnement suffit ensuite à reconstituer exactement le même jeu d’extensions, avec les mêmes versions, ce qui élimine une classe entière de bugs liés à des versions divergentes entre environnements.
Étape 4 : brancher WP-CLI sur cette arborescence
WP-CLI fonctionne normalement avec Bedrock, à condition de préciser le chemin vers le dossier WordPress si la commande n’est pas lancée depuis web/wp :
$ wp core version --path=web/wp
$ wp plugin list --path=web/wpAdapter le thème pour un usage strictement headless
Bedrock ne fournit aucun thème par défaut : un thème minimal, réduit à un simple fichier index.php et à un fichier style.css de déclaration, suffit largement dans web/app/themes quand WordPress ne sert jamais de rendu visuel au visiteur final. Ce thème vide évite les erreurs d’activation tout en ne consommant aucune ressource de rendu inutile.
<?php
// web/app/themes/headless/index.php
// Thème volontairement vide : WordPress ne rend jamais de page ici.
http_response_code( 404 );Ce que cette structure apporte concrètement à un projet headless
- Une racine web réduite au strict nécessaire, sans exposer de fichiers de configuration sensibles
- Un versionnage propre des dépendances, y compris pour les extensions tierces
- Une configuration par environnement claire, utile quand plusieurs environnements de preview coexistent avec la production
Un projet dont les dépendances ne sont pas versionnées explicitement finit toujours par diverger, silencieusement, entre le poste d’un développeur et le serveur de production.
Ce qui reste identique malgré le changement d’arborescence
Bedrock ne modifie ni le fonctionnement du cœur WordPress, ni celui de son API REST, ni celui des hooks habituels. Un développeur qui découvre ce squelette pour la première fois retrouve exactement les mêmes fonctions et les mêmes filtres qu’il utilisait déjà sur une installation classique, seule l’organisation des fichiers autour de ce code change concrètement.
Cette continuité rassure souvent les équipes qui hésitent à adopter Bedrock par crainte d’un apprentissage trop long : le coût réel se limite presque entièrement à la prise en main de Composer et à la nouvelle localisation des fichiers, sans remise en cause du code métier déjà écrit pour un projet headless.
En résumé
Bedrock ne change rien au fonctionnement interne de WordPress ; il réorganise simplement son arborescence et sa gestion de dépendances pour l’aligner sur les pratiques courantes du développement PHP moderne, ce qui facilite d’autant la mise en place d’un projet headless propre dès le départ. Ce tutoriel ne couvre pas la mise en place du déploiement continu, qui mérite un traitement séparé une fois la structure du projet stabilisée.
