Skip to content
Projects

ItinerisLtd/composify has 52 GitHub stars and 2 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-15 17:47 UTC. Last push 2026-11-13.

How these counts are measured

Measured star growth

in 24h
0
in 7 days
Update delayed
in 15 days
Update delayed
in 1 month
Update delayed

Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.

About

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

Developer Tools

README.md

Original

composify

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

oclif Version Downloads/week License Hire Itineris

Goal

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:

// https://kinsta.com/blog/bedrock-trellis/
{
  "type": "package",
  "package": {
    "name": "kinsta/kinsta-mu-plugins",
    "type": "wordpress-muplugin",
    "version": "2.0.15",
    "dist": {
      "url": "https://kinsta.com/kinsta-tools/kinsta-mu-plugins.zip",
      "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, keeping the plugin's own one (if any) as composer.original.json
  4. commit plugins files and composer.json
  5. $ git tag
  6. $ git push --follow-tags

Requirements

  • NodeJS v22 or later

Installation

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

Usage

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

USAGE
  $ composify

OPTIONS
  -b, --branch=branch
      the default branch of your remote repository [example: main]

  --composer-json=composer-json
      JSON object, or path to a JSON file, merged into the generated
      composer.json, where null removes a key [example:
      {"require":{"php":">=8.2"}}]

  -d, --directory=directory
      directory name after unzip, also used as the install folder
      (extra.installer-name) when it differs from --name [example:
      kinsta-mu-plugins]

  -f, --file=file
      main plugin file which containing the plugin header comment [example:
      kinsta-mu-plugins.php]

  -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:
      https://github.com/ItinerisLtd/kinsta-mu-plugins.git]

  -t, --type=wordpress-plugin|wordpress-muplugin|wordpress-theme
      (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:
      https://kinsta.com/kinsta-tools/kinsta-mu-plugins.zip OR
      /User/me/kinsta-mu-plugins.zip]

When --directory differs from --name, the generated composer.json sets extra.installer-name to the directory, so composer/installers installs the plugin into the folder WordPress expects (wp-content/plugins/<directory>/) rather than one named after the package. Packages built before this change install into wp-content/plugins/<name>/, so their next version moves to the new folder. Check the plugin stays active after updating.

To add or change anything else in the generated composer.json, pass --composer-json (or set COMPOSIFY_COMPOSER_JSON) with a JSON object, or a path to a file containing one. It is applied as a JSON Merge Patch: objects merge, arrays and plain values replace the generated ones, and null removes a key.

$ npx @itinerisltd/composify --composer-json='{"require":{"php":">=8.2"}}' ...
$ npx @itinerisltd/composify --composer-json=./composer-overrides.json ...

Examples

Gravity Forms

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

Note the flags:

$ wget <the-signed-s3-url>
$ tree .
.
└── gravityforms_x.y.z.zip

$ unzip -o ./gravityforms_2.4.5.zip
$ tree .
.
├── gravityforms              <-- `--directory`
│   ├── gravityforms.php      <-- `--file`
│   ├── xxx
│   └── yyy.php
└── gravityforms_x.y.z.zip
  • --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 https://github.com/${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=https://connect.advancedcustomfields.com/xxx

Note the flags:

$ wget https://connect.advancedcustomfields.com/xxx
$ tree .
.
└── advanced-custom-fields-pro.zip

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

Kinsta MU Plugins

$ npx @itinerisltd/composify --vendor=itinerisltd --name=kinsta-mu-plugins --zip=https://kinsta.com/kinsta-tools/kinsta-mu-plugins.zip --unzip-subdir --type=wordpress-muplugin

Note the flags:

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

Automatic builds with GitHub Actions

Run composify on a schedule to mirror each new plugin version as soon as the vendor releases it. Re-running for a version that is already tagged changes nothing, so a nightly run is safe. The run fails if the zip's files differ from that tag, so a vendor re-releasing a version without bumping it gets noticed.

# .github/workflows/composify.yml
name: Composify

on:
  schedule:
    - cron: '0 0 * * *'
  workflow_dispatch:

permissions:
  contents: read

jobs:
  composify:
    runs-on: ubuntu-latest
    concurrency: composify-${{ matrix.name }}
    strategy:
      fail-fast: false
      matrix:
        include:
          - name: example-plugin
            zip-secret: EXAMPLE_PLUGIN_ZIP_URL
          - name: example-plugin-pro
            directory: example-plugin
            zip-secret: EXAMPLE_PLUGIN_PRO_ZIP_URL
    steps:
      - uses: actions/[email protected]
        with:
          node-version: 22

      - name: Configure git
        env:
          GH_TOKEN: ${{ secrets.COMPOSIFY_GITHUB_TOKEN }}
        run: |
          git config --global user.name 'composify-bot'
          git config --global user.email '[email protected]'
          git config --global url."https://x-access-token:${GH_TOKEN}@github.com/".insteadOf 'https://github.com/'

      - name: Composify ${{ matrix.name }}
        env:
          COMPOSIFY_DIRECTORY: ${{ matrix.directory }}
          COMPOSIFY_NAME: ${{ matrix.name }}
          COMPOSIFY_VENDOR: example
          COMPOSIFY_ZIP: ${{ secrets[matrix.zip-secret] }}
        run: npx @itinerisltd/composify@latest

Note:

  • Each package needs an existing repository at https://github.com/${vendor}/${name}.git, or a --repo of your choice
  • COMPOSIFY_GITHUB_TOKEN is a token that can push to those repositories, such as a fine-grained personal access token or a GitHub App installation token
  • Keep licensed download URLs in secrets, not in the workflow file. GitHub masks secret values in the logs, but composify still records the URL in the generated composer.json (extra.composify.zip, and description when the plugin header has none), so it ends up in the package repository. Remove or replace both with COMPOSIFY_COMPOSER_JSON if the URL must stay private, e.g. {"description":"Example Plugin","extra":{"composify":{"zip":null}}}
  • Use a stable download URL. A signed or expiring link, like the Gravity Forms one above, stops working once it expires
  • Pushes go to main. Set COMPOSIFY_DEFAULT_BRANCH if the package repositories use another default branch
  • --ignore-changes has no environment variable, so pass it on the command line for vendors that regenerate a file on every download
  • @latest picks up new composify releases automatically. Pin a version instead if you want to review upgrades first
  • fail-fast: false keeps one broken download from stopping the other packages
  • Set directory only when the plugin's folder differs from name; the package then installs into that folder (see Usage)

FAQ

How to install the composify-ed plugin via composer?

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

{
  "repositories": [
    {
      "type": "git",
      "url": "https://github.com/<vendor>/<name>"
    }
  ]
}
$ composer require <vendor>/<name>

See: https://getcomposer.org/doc/05-repositories.md#vcs

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/the-plugin.zip -o itinerisltd -n the-plugin

Note: This is a v0.3 feature.

Can I change default flag values via environment variables?

Yes.

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 wordpress.org?

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?

No.

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 wp.org. 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 wp.org, consider:

Feedback

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.

Security

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

Change log

Please see GitHub Releases for more information on what has changed recently. See RELEASING for how to cut a new release.

Credits

composify is a Itineris Limited project created by Tang Rufus.

Full list of contributors can be found here.

License

composify is released under the MIT License.