mahimahi / composator

dev-main 2026-09-09 11:48 UTC

Requires

• php: >=8.0
• composer/composer: ^2.7
• wp-cli/wp-cli: ^2.9

Requires (Dev)

• phpunit/phpunit: ^9 || ^10
• wp-cli/wp-cli-tests: ^5

MIT

• MahiMahi

Published on Packagist.org on 2026-09-09 11:50 UTC

README

A WP-CLI command that syncs the plugins physically installed in wp-content/plugins into composer.json, using wp-packages.org as the source of truth for package names.

It never touches Composer repositories other than wp-packages.org: the command refuses to run unless composer.json already declares the https://repo.wp-packages.org Composer repository.

Why

If plugins get installed by hand (uploaded via wp-admin, unzipped over FTP, etc.) on a site that's otherwise managed with Composer, composer.json drifts out of sync with what's actually on disk. composator finds that drift and, on request, closes it by adding the missing wp-plugin/{slug} requirements.

Installing

wp package install [e-mail]:Mahi-Mahi/composator.git

Your site's composer.json must already declare the wp-packages.org repository:

composer config repositories.wp-packages composer https://repo.wp-packages.org

Using

wp composator status

Read-only. Reports installed plugins that are missing from composer.json, plus any installed plugins that can't be resolved via wp-packages.org (premium/custom plugins). Never modifies composer.json.

$ wp composator status
+-------------+------------------------+-------------+---------+--------+--------------+------------+
| slug        | package                | name        | version | active | status       | constraint |
+-------------+------------------------+-------------+---------+--------+--------------+------------+
| woocommerce | wp-plugin/woocommerce  | WooCommerce | 9.4.2   | yes    | missing      | ^9.4       |
| acme-suite  | wp-plugin/acme-suite   | Acme Suite  | 2.1     | no     | unmanageable |            |
+-------------+------------------------+-------------+---------+--------+--------------+------------+

Options:

• --composer-json=<path> — path to composer.json (defaults to composer.json in ABSPATH).
• --constraint=<caret|exact|wildcard> — version constraint style shown in the report (default: caret).
• --format=<table|csv|json|yaml|count> — output format (default: table).
• --all — also list plugins already tracked in composer.json.

wp composator sync

Adds every missing, resolvable plugin to composer.json's require section, using Composer\Json\JsonManipulator so the rest of the file's formatting is left untouched. Plugins that can't be resolved via wp-packages.org are reported but never written.

$ wp composator sync --yes
Success: Added 1 package(s) to /var/www/example.com/composer.json. Run `composer update` to install them.

Options:

• --dry-run — show what would be added without writing anything.
• --yes — skip the confirmation prompt.
• --constraint=<caret|exact|wildcard> — version constraint style used for newly added requirements (default: caret).
• --composer-json=<path>, --format=<...>, --all — same as status.

sync never runs composer update for you and never touches composer.lock — run composer update yourself once you're happy with the diff.

Constraint styles

Style	Installed version	Written constraint
caret (default)	6.3.1	^6.3
exact	6.3.1	6.3.1
wildcard	6.3.1	*

Scope (v1)

• Scans wp-content/plugins only — themes, mu-plugins and drop-ins are out of scope.
• Includes every installed plugin, active or not.
• Only ever adds missing require entries; existing entries (even with a different constraint) are left untouched.
• Does not detect or remove orphaned wp-plugin/* entries whose plugin folder no longer exists on disk.

Development

composer install
composer lint      # PHP syntax check
composer phpcs      # coding standards
composer phpunit     # unit tests (no WordPress required)
composer prepare-tests   # one-time: set up the Behat test database
composer behat       # functional tests (spins up a real WP install)
composer test        # all of the above