ItinerisLtd/composify
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.
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 ToolsREADME.md
Originalcomposify
Turn WordPress plugin zip files into git repositories, so that composer version constraints work properly.
- Goal
- Requirements
- Installation
- Usage
- Examples
- FAQ
- How to install the
composify-ed plugin viacomposer? - How to
composifyplugin zip URLs which are password-protected? - Can I change default flag values via environment variables?
- Can I install
composifyinstead of using$ npx? - How about plugins on wordpress.org?
- What to do when
fatal: Could not read from remote repository? - Is it a must to use
composifywith Bedrock? - 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?
- How to install the
- Feedback
- Security
- Change log
- Credits
- License
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.urlis version-locked, therepositoriesarray has to be updated whenever a new plugin version is released - if
package.dist.urlis not version-locked,$ composer installis not deterministic (even withcomposer.lock)package.dist.urlalways points to the latest versionpackage.versionbecomes 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:
- download the plugin zip file
- unzip it
- generate
composer.json, keeping the plugin's own one (if any) ascomposer.original.json - commit plugins files and
composer.json $ git tag$ 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
--directoryis omitted because it defaults to${name}, i.e:gravityforms--fileis omitted because it defaults to${name}.php, i.e:gravityforms.php--repois omitted because it defaults tohttps://github.com/${vendor}/${name}.git--unzipDiris 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
--fileis set toacf.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-subdiris 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--repoof your choice COMPOSIFY_GITHUB_TOKENis 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, anddescriptionwhen the plugin header has none), so it ends up in the package repository. Remove or replace both withCOMPOSIFY_COMPOSER_JSONif 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. SetCOMPOSIFY_DEFAULT_BRANCHif the package repositories use another default branch --ignore-changeshas no environment variable, so pass it on the command line for vendors that regenerate a file on every download@latestpicks up new composify releases automatically. Pin a version instead if you want to review upgrades firstfail-fast: falsekeeps one broken download from stopping the other packages- Set
directoryonly when the plugin's folder differs fromname; 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?
- Download the zip files to your computer first
$ 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:
- created a git repository on remote server
- chosen remote url correctly
- configure git authentication correctly on your computer or CI server
- granted both read and write accesses to the remote repository for the git user on your computer or CI server
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?
- Release Belt - Composer repo for ZIPs
- Private Packagist Vendor - Use JSON to make any ZIP file available through Composer.
It looks awesome. Where can I find some more goodies like this?
- Articles on Itineris' blog
- More projects on Itineris' GitHub profile
- Follow @itineris_ltd and @TangRufus on Twitter
- Hire Itineris to build your next awesome site
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:
- tweet something good with mentioning @itineris_ltd and @TangRufus
- star this Github repo
- watch this Github repo
- write blog posts
- submit pull requests
- hire Itineris
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.