Skip to content
Turn WordPress plugin zip files into git repositories, so that composer version constraints work properly.
TypeScript JavaScript Batchfile
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


Turn WordPress plugin zip files into git repositories, so that composer version constraints work properly.

oclif Version Downloads/week License Hire Itineris


Since plugin authors do not usually provide custom composer repositories (e.g: Private Packagist, satis), installing premium WordPress plugins via composer is not easy.

Lots of tutorials teach you: open composer.json and add the following within the repositories array:

  "type": "package",
  "package": {
    "name": "kinsta/kinsta-mu-plugins",
    "type": "wordpress-muplugin",
    "version": "2.0.15",
    "dist": {
      "url": "",
      "type": "zip"

The problems:

  • if package.dist.url is version-locked, the repositories array has to be updated whenever a new plugin version is released
  • if package.dist.url is not version-locked,$ composer install is not deterministic (even with composer.lock)
    • package.dist.url always points to the latest version
    • package.version becomes meaningless because the downloaded zip could be a newer version
    • running $ composer install (without changing anything) could break the site because a newer plugin version is installed
    • when composer caching invoked, there is no way to know which plugin version will be installed

The solution / what composify does:

  1. download the plugin zip file
  2. unzip it
  3. generate composer.json
  4. commit plugins files and composer.json
  5. $ git tag
  6. $ git push --follow-tags


  • NodeJS v10.0.0 or later


$ npx @itinerisltd/composify just works! No installation required.


$ npx @itinerisltd/composify --help
Turn WordPress plugin zip files into git repositories, so that composer version constraints work properly

  $ composify

  -d, --directory=directory
      directory name after unzip [example: kinsta-mu-plugins]

  -f, --file=file
      main plugin file which containing the plugin header comment [example:

  -h, --help
      show CLI help

  -n, --name=name
      (required) package name [example: kinsta-mu-plugins]

  -o, --vendor=vendor
      (required) vendor / organization name [example: itinerisltd]

  -r, --repo=repo
      remote url or local path to the gti repository [example:]

  -t, --type=wordpress-plugin|wordpress-muplugin
      (required) [default: wordpress-plugin] package type

  -u, --[no-]unzip-subdir
      unzip file into a sub-directory, only use when default options are breaking

  -v, --version
      show CLI version

  -z, --zip=zip
      (required) remote url or local path to the latest zip file [example: OR


Gravity Forms

$ npx @itinerisltd/composify --vendor=itinerisltd --name=gravityforms --zip=<the-signed-s3-url>

Note the flags:

$ wget <the-signed-s3-url>
$ tree .

$ unzip -o ./
$ tree .
├── gravityforms              <-- `--directory`
│   ├── gravityforms.php      <-- `--file`
│   ├── xxx
│   └── yyy.php
  • --directory is omitted because it defaults to ${name}, i.e: gravityforms
  • --file is omitted because it defaults to ${name}.php, i.e: gravityforms.php
  • --repo is omitted because it defaults to${vendor}/${name}.git
  • --unzipDir is omitted because main plugin file is inside --directory

Advanced Custom Fields Pro

$ npx @itinerisltd/composify --vendor=itinerisltd --name=advanced-custom-fields-pro --file=acf.php --zip=

Note the flags:

$ wget
$ tree .

$ unzip -o ./
$ tree .
├── advanced-custom-fields-pro        <-- `--directory`
│   ├── acf.php                       <-- `--file`
│   ├── readme.txt
│   └── xxx
  • --file is set to acf.php

Kinsta MU Plugins

$ npx @itinerisltd/composify --vendor=itinerisltd --name=kinsta-mu-plugins --zip= --unzip-subdir --type=wordpress-muplugin

Note the flags:

$ wget
$ tree .
$ unzip -o ./
$ tree .
├── kinsta-mu-plugins
│   ├── xxx
│   └── yyy
├── kinsta-mu-plugins.php    <-- `--file`
  • --unzip-subdir is set because the unzipped content is not contained inside a --directory


How to install the composify-ed plugin via composer?

Open composer.json and add your git remote into repositories:

  "repositories": [
      "type": "git",
      "url": "<vendor>/<name>"
$ composer require <vendor>/<name>


How to composify plugin zip URLs which are password-protected?

  1. Download the zip files to your computer first
  2. $ composify/bin/run -z /path/to/ -o itinerisltd -n the-plugin

Note: This is a v0.3 feature.

Can I change default flag values via environment variables?


These 2 commands are equivalent:

$ COMPOSIFY_VENDOR=itinerisltd COMPOSIFY_NAME=gravityforms COMPOSIFY_ZIP=<the-signed-s3-url> npx @itinerisltd/composify
$ npx @itinerisltd/composify --vendor=itinerisltd --name=gravityforms --zip=<the-signed-s3-url>

Can I install composify instead of using $ npx?

Yes. However, you are responsible for updating it.

# yarn or npm doesn't matter
$ yarn global add @itinerisltd/composify
$ composify --vendor=itinerisltd --name=gravityforms --zip=<the-signed-s3-url>

How about plugins on

Use WordPress Packagist instead.

What to do when fatal: Could not read from remote repository?

ERROR: Repository not found.
fatal: Could not read from remote repository.

Make sure you have:

Is it a must to use composify with Bedrock?


Although we prefer and sponsor Bedrock at Itineris, you can composify any plugin zip files into git repositories, and install them via composer.

Bedrock alternatives:

Any Alternatives?

It looks awesome. Where can I find some more goodies like this?

This isn't on Where can I give a ⭐️⭐️⭐️⭐️⭐️ review?

Thanks! Glad you like it. It's important to make my boss know somebody is using this project. Instead of giving reviews on, consider:


Please provide feedback! We want to make this library useful in as many projects as possible. Please submit an issue and point out what you do and don't like, or fork the project and make suggestions. No issue is too small.


If you discover any security related issues, please email instead of using the issue tracker.

Change log

Please see CHANGELOG for more information on what has changed recently.


composify is a Itineris Limited project created by Tang Rufus.

Full list of contributors can be found here.


composify is released under the MIT License.

You can’t perform that action at this time.