premio

Concept

Premio is a tool to automate fetching private stuff, crowbarring it into a Composer friendly format, and committing it to remote Git repository.

It was originally designed to be used with paid-for Wordpress plugins and themes so they could be installed with Composer, but theoretically it could be adapted to other stuff. Where this document referes to 'plugins' please substiturte 'themes', 'libraries' etc.

Installation

npm install --global premio. If your global NPM bin folder is in your path this will make the premio command available.

Usage

# premio --help

Usage: premio [options]

Options:
  -V, --version  output the version number
  -d --debug     Debug mode (default: false)
  -h, --help     output usage information

I run this as a cron job on a server, so premio will check for updated versions each night, and update my repositories if available.

Configuration

• Create a premio-libs.json file. See /premio-libs.json.example for a full list of supported plugins. Entries should contain the following:
  • name: (required) The name of the plugin, also the repository it will get pushed to. Must be at least in the format <namespace>/<project>, which will be put into the composer.json file. Anything before this will be prepended to the repository path. e.g. wp-premium/wpml/sitepress-multilingual-cms will be listed as wpml/sitepress-multilingual-cms in the composer.json files, and will be pushed to https://git.example.com/wp-premium/wpml/sitepress-multilingual-cms.git
  • type: (required) The composer.json type field e.g. wordpress-plugin
  • pluginFolder: The 'main' folder for the plugin, relative to the root folder the getter returns. This will default to the last bit of name above, appended with .php e.g. sitepress-multilingual-cms.php
  • pluginFile: The 'main' plugin file to check for current version. This will default to the last bit of name above, appended with .php e.g. sitepress-multilingual-cms.php
• Create a .premiorc file. An example file can me found at /.premiorc.example
• Both .premiorc and premio-libs.json can be in your home folder, or the folder you run the premio command in. This will cascade, so variables set in each will be available but variables set in the current folder will overwrite those set in the home folder.
• Create remote repositories for each of the libraries being fetched. Premio will not create repositories if they do not exist. The library will fail and move onto the next item if it cannot find the repository.

Process

When premio is run it will go through the list of libraries contained in config/libs.json and for each one:

• Fetch the plugin using a defined getter (see below)
• Determine the version of the fetched plugin
• Check if the version fetched exists in the associated git repository
• If not, generate a minimal composer.json file for the new plugin, commit and tag it with the new version, and push it to the repository.

Development

Each library needs a getter, as defined in the scripts/getters folder. Note that the path to the getter format must match that defined in the libraries name entry. What a getter does depends on how the plugin / theme / whatever must be fetched. It is a callback which is passed a temporary file path, and should return a Promise that resolves once the filepath contains the contents that should be pushed. A simple example follows the following lifecycle:

• Getter is called with /tmp/my-tmp-plugin
• Getter downloads zipped plugin file to example.com/my-secret-key/my-private-plugin.zip to /tmp/my-private-plugin.zip
• Getter unzips /tmp/my-private-plugin.zip to /tmp/my-tmp-plugin
• Getter resolves

See the scripts/getters folder for real life examples.

Notes

• This library is not intended to be a way to steal plugins from authors. You should still have a licence for each and every plugin you use, as per the terms agreed with the author. The intent of this plugin is to facilitate easy programatic installation of plugins.
• The getters here rely on bits and pieces out of control of this libraries authors. Things may break as APIs change, websites are redesigned. Keep this in mind.