composify

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

• Goal
• Requirements
• Installation
• Usage
• Examples
  • Gravity Forms
  • Advanced Custom Fields Pro
  • Kinsta MU Plugins
• FAQ
  • How to install the composify-ed plugin via composer?
  • How to composify plugin zip URLs which are password-protected?
  • Can I change default flag values via environment variables?
  • Can I install composify instead 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 composify with 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?
• 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.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

Requirements

• NodeJS v10.0.0 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]

  -d, --directory=directory
      directory name after unzip [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]

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

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:

• 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:

• Composer in WordPress
• WP Starter

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 CHANGELOG for more information on what has changed recently.

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.