Blog / Article #159

Composer 2.11 et la Cooldown Policy : quand vos dépendances apprennent à patienter pour des déploiements sereins

C'est quoi cette fameuse 'dependency hell', ce cauchemar familier de tout développeur PHP ? Un petit composer update innocent en production, et bam, tout votre monde s'écroule. On a tous connu ça : une mise à jour de dépendance qui casse tout, une régression inattendue, et des heures passées à comprendre pourquoi une fonctionnalité qui marchait hier ne marche plus aujourd'hui. C'est précisément là que Composer 2.11, sorti le 29 octobre 2026 (oui, vous avez bien lu, les mainteneurs voient loin !), vient nous tendre une main salvatrice avec sa Cooldown Dependency Policy.

Cette nouvelle politique n'est pas là pour vous empêcher de mettre à jour, mais pour vous aider à le faire de manière plus contrôlée et prévisible. Fini les surprises du chef lors des déploiements en fin de journée. Voyons ensemble comment cette fonctionnalité peut transformer vos pratiques de déploiement.

Qu'est-ce que la Cooldown Dependency Policy et comment ça fonctionne ?

La Cooldown Dependency Policy est une fonctionnalité de Composer qui introduit un délai d'attente avant qu'une nouvelle version de paquet ne soit considérée comme éligible pour une mise à jour. En gros, si un paquet vient d'être publié, Composer peut attendre un certain temps (le "cooldown period") avant de vous proposer cette nouvelle version. L'objectif est simple : éviter les mises à jour impulsives qui pourraient introduire des bugs fraîchement poussés par l'auteur d'un paquet.

Cette politique s'appuie sur le champ published-time fourni par les dépôts de paquets comme Packagist.org. C'est la date à laquelle le paquet a été publié, et non la date à laquelle l'auteur a créé le tag. Cela empêche toute tentative d'antidatage pour contourner la politique. Si un dépôt ne fournit pas ce champ, Composer échouera par défaut, à moins que vous ne le configuriez autrement.

Il est crucial de comprendre que cette politique s'applique uniquement aux commandes composer update et composer require. Elle n'a aucun impact sur composer install, qui est là pour installer les versions déjà verrouillées dans votre fichier composer.lock. C'est une distinction fondamentale pour vos pipelines de CI/CD.

Configuration pratique : Activer et ajuster la politique dans votre composer.json

L'activation de la Cooldown Policy est un jeu d'enfant. Tout se passe dans la section config.policy.cooldown de votre composer.json. Voici un exemple basique :

{
  "config":
    { 
      "policy":
        { 
          "cooldown":
          {
            "period": "7 days"
          }
        }
    }
}

Avec cette configuration, Composer attendra 7 jours après la publication d'un paquet avant de le considérer comme éligible pour une mise à jour. La valeur de period peut être une chaîne comme "6 hours", "1 day", "7 days", ou même un nombre entier de secondes.

Vous avez d'autres options pour affiner le comportement :

• "block" (par défaut à true) : Si mis à false, Composer affichera un avertissement au lieu de bloquer la mise à jour.
• "ignore" : Permet d'exclure certains paquets de la politique de cooldown avec des raisons et des contraintes de version spécifiques.
• "audit" : Peut être "report" (par défaut) pour afficher un rapport, ou "fail" pour que la commande échoue si des paquets sont en cooldown.

Pour une configuration globale sur votre machine de développement, vous pouvez utiliser :

composer config --global policy.cooldown.period "7 days"

Et pour les environnements d'intégration continue, une variable d'environnement est souvent plus pratique :

COMPOSER_POLICY_COOLDOWN_PERIOD="1 day"

Exemples concrets :
Cooldown en développement local et en CI/CD

En développement local

Sur votre machine de développement, un cooldown de quelques jours peut être très utile. Il vous protège des versions instables publiées par erreur ou des changements majeurs qui n'auraient pas encore été signalés. Vous pouvez toujours forcer une mise à jour d'un paquet spécifique en contournant le cooldown si vous savez ce que vous faites :

COMPOSER_POLICY_COOLDOWN_PERIOD=0 composer update acme/package

Ou pour une mise à jour complète :

composer update --no-cooldown

En CI/CD

C'est en CI/CD que la Cooldown Policy révèle tout son potentiel. Imaginez un pipeline de déploiement où vous voulez une stabilité maximale. Vous pouvez configurer un cooldown d'une semaine sur vos branches de production. Si une dépendance est mise à jour sur Packagist, votre CI ne l'intégrera pas immédiatement. Cela vous laisse le temps de voir si des problèmes sont signalés par d'autres utilisateurs ou si des versions correctives sont publiées.

Pour les branches de développement, vous pourriez opter pour un cooldown plus court, voire nul, pour bénéficier des dernières fonctionnalités rapidement. L'utilisation de la variable d'environnement COMPOSER_POLICY_COOLDOWN_PERIOD est particulièrement adaptée ici pour ajuster la politique selon l'environnement ou la branche.

Bonnes pratiques et pièges à éviter pour des déploiements sereins

• composer install vs composer update : C'est la règle d'or. La Cooldown Policy ne s'applique qu'à update et require. Vos déploiements en production doivent toujours utiliser composer install pour garantir que les dépendances verrouillées dans composer.lock sont bien celles qui sont installées. Cela assure la reproductibilité de vos builds.
• Versions de développement et paquets de plateforme : Les versions de développement (comme dev-main) et les paquets de plateforme (PHP, extensions) ne sont jamais soumis au cooldown. C'est logique, car ils représentent des composants que vous gérez souvent différemment.
• Correctifs de sécurité : Attention, même les correctifs de sécurité sont soumis au cooldown. Composer ne peut pas faire la distinction automatiquement. Si une faille critique est corrigée et que le fix est publié, vous devrez peut-être contourner le cooldown manuellement pour l'appliquer sans délai. C'est un compromis à connaître.
• Le piège du published-time : Comme mentionné, Composer se base sur le published-time. Si un dépôt ne le fournit pas, Composer échouera par défaut. Si vous utilisez des dépôts privés qui n'exposent pas cette information, vous devrez peut-être définir "require-published-time": false pour ce dépôt, mais cela utilisera alors le champ time du composer.json du paquet, moins fiable.
• Le fallback dist vers source : Un changement important dans Composer 2.11 est la suppression du comportement de "fallback" de dist vers source. Si vos pipelines de build dépendaient de ce comportement (par exemple, si dist échouait et que Composer essayait de télécharger le source via Git), cela pourrait les impacter. Assurez-vous que vos environnements ont bien les dépendances binaires nécessaires (unzip, git).
• auth.json : N'oubliez jamais d'ajouter votre fichier auth.json (contenant les tokens pour les dépôts privés) à votre .gitignore. C'est une bonne pratique de sécurité fondamentale.

Verdict :
Un pas de plus vers la robustesse de nos applications PHP

La Cooldown Dependency Policy de Composer 2.11 est une excellente addition à l'arsenal du développeur PHP. Elle ne résout pas tous les problèmes de dépendances, mais elle apporte une couche de prévisibilité et de contrôle bienvenue. Fini le stress des mises à jour sauvages. En l'adoptant, vous offrez à vos applications une meilleure stabilité et vous vous donnez, à vous et à votre équipe, un précieux filet de sécurité. C'est un petit changement dans Composer, mais un grand pas pour la sérénité de vos déploiements.