WP Packages Now Supports Composer’s Cooldown Policy

Ben Word 2026-10-29

Composer 2.11 adds a cooldown policy that holds back newly released package versions for a period you choose. Many malicious releases, like the ones that follow a hijacked maintainer account, are caught and pulled within hours or days. Waiting a few days before installing a new version keeps you out of that window.

WP Packages now supports it for every WordPress plugin and theme.

Enabling cooldown

Add a period to your project’s composer.json:

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

composer update and composer require will then skip any version published more recently than that and pick the newest one old enough to install. Dev versions like dev-trunk are never held back.

If an older version satisfies your constraint, Composer installs that instead. Run with -vv to see what was held back:

$ composer update -vv
1 package version(s) withheld by the cooldown policy:
  - wp-plugin/example-plugin (1.0.2) published 2026-10-27T22:38:47+00:00, available in 1 day 9 hours
...
  - Locking wp-plugin/example-plugin (1.0.1)

If only a held-back version fits, the update fails and tells you when it’ll be available:

Problem 1
  - Root composer.json requires wp-plugin/example-plugin 1.0.2 (exact version match: 1.0.2 or 1.0.2.0),
    found wp-plugin/example-plugin[1.0.2] but these were not loaded, because they are still in the
    cooldown period configured in "policy.cooldown" (available in 1 day 9 hours).

To skip the cooldown for specific packages, add them to policy.cooldown.ignore, or run with --no-cooldown for a one-off bypass.

How it works on WP Packages

Cooldown relies on the repository telling Composer when each version was published. That time has to come from the repository, not the plugin author, or an attacker could simply backdate a release.

WP Packages records when it first serves each version. Thanks to Nils Adermann, co-creator of Composer, for the suggestion: WordPress.org tags can be changed after release, so if a tag is modified in SVN, we reset its time and the cooldown applies again. Edits that only touch the readme, like bumping “Tested up to”, don’t count.

Enabling cooldown

How it works on WP Packages

Sponsors