Gérer les dépendances PHP d’un thème avec Composer, sans passer à Bedrock

Passer à Bedrock demande de restructurer un projet WordPress dans son ensemble : dossier web, configuration par variables d’environnement, gestion des plugins via WPackagist. Ce n’est pas toujours réalisable, en particulier sur un projet existant qu’on ne veut pas réécrire entièrement. Bonne nouvelle : on peut profiter de Composer dans un thème WordPress classique, sans toucher au reste de la structure.

C’est l’approche qu’on utilise sur la majorité de nos projets de thèmes sur mesure : Composer reste cantonné au dossier du thème, gère les bibliothèques PHP et l’autoload des classes, sans rien changer à l’organisation générale du site.

Initialiser Composer dans un thème

cd wp-content/themes/mon-theme
composer init --name="agence/mon-theme" --type=wordpress-theme
composer require monolog/monolog
composer require --dev squizlabs/php_codesniffer

Le fichier composer.json généré vit à la racine du thème. Il n’a besoin de rien connaître de WordPress lui-même : Composer gère les bibliothèques PHP standards (logging, gestion de dates, validation) exactement comme sur n’importe quel projet PHP.

Organiser ses classes avec l’autoload PSR-4

C’est le vrai gain au quotidien : plutôt que d’accumuler des require_once dans functions.php, on déclare un espace de noms et Composer charge automatiquement les classes à la demande.

{
  "autoload": {
    "psr-4": {
      "Agence\\Theme\\": "inc/"
    }
  }
}

<?php
namespace Agence\Theme;

class PostTypes {
    public function register(): void {
        register_post_type( 'projet', [
            'public'       => true,
            'label'        => 'Projets',
            'show_in_rest' => true,
        ] );
    }
}

Dans functions.php, il suffit alors d’inclure l’autoloader généré par Composer et d’instancier les classes nécessaires :

require_once get_template_directory() . '/vendor/autoload.php';

add_action( 'init', function () {
    ( new \Agence\Theme\PostTypes() )->register();
} );

Ce qu’on gagne concrètement

• Une organisation du code en classes, plus facile à tester et à faire évoluer qu’une suite de fonctions dans un fichier unique
• L’accès à l’écosystème complet de Packagist : validation de formulaires, génération de PDF, clients HTTP, sans réinventer la roue
• Un fichier composer.lock qui garantit les mêmes versions de bibliothèques sur tous les environnements
• Des outils de qualité de code (PHP CodeSniffer, PHPStan) installés en dépendances de développement, absentes du déploiement final

Le dossier vendor : exclu de Git, présent au déploiement

Le dossier vendor généré par Composer ne doit jamais être versionné — il se reconstruit entièrement à partir de composer.lock. Mais il doit impérativement être présent sur le serveur de production, sous peine d’erreur fatale sur vendor/autoload.php manquant.

Étape	Vendor présent ?	Comment
Dépôt Git	Non	Ignoré via .gitignore
Poste de développement	Oui	composer install manuel
Serveur de production	Oui	Généré au déploiement, jamais commité

Sur un déploiement rsync classique, on exécute composer install --no-dev --optimize-autoloader soit directement sur le serveur via SSH après le transfert, soit en amont dans le pipeline avant l’envoi des fichiers. La deuxième option évite d’avoir Composer installé sur le serveur de production, ce qui est préférable pour la sécurité.

Le conseil qu’on donne systématiquement : commencez petit. Un composer.json avec deux ou trois dépendances et un autoload PSR-4 suffit à transformer l’organisation d’un thème, sans attendre d’avoir « le temps » de migrer vers Bedrock.

Les limites de cette approche partielle

Cette méthode ne gère pas les plugins ni le cœur de WordPress via Composer — on reste sur une installation et des mises à jour classiques pour eux. C’est un compromis assumé : on gagne en organisation du code du thème sans le bénéfice complet de la reproductibilité qu’offre Bedrock sur l’ensemble du projet. Pour une petite équipe ou un projet ponctuel, c’est souvent largement suffisant.

En résumé

Composer n’est pas réservé aux projets structurés façon Bedrock. Intégré simplement dans un thème, il apporte un autoload propre, un accès à l’écosystème PHP, et une gestion de dépendances bien plus rigoureuse qu’une suite de require_once. C’est une première marche accessible avant, éventuellement, d’envisager une restructuration plus profonde du projet.