How We Built Full Composer Support For Our Premium WordPress Plugins

Composer is the dependency manager of choice for PHP. It allows you to declare a list of project dependencies and will install and update them directly from the command line, similar to npm for node. Back in 2015, Gilbert wrote about managing your WordPress themes and plugins using Composer. We’ve adopted a similar approach for managing the Delicious Brains site and thanks to WordPress Packagist we’re able to install the majority of plugins we require via Composer. We also update WordPress core using the WordPress Composer Fork, which means that 90% of our site is now managed by Composer.

The Composer Conundrum

That’s all fine and dandy for free plugins available on WordPress Packagist, but what about premium ones? For a long time now we’ve allowed our premium plugins to be installed via Composer, with one major caveat: only the latest version of each plugin can be installed. No matter what version you specified in your composer.json file, it would always download the latest.

Another issue with the current approach is that your composer.json file is tied to a license key (sometimes multiple keys if you’re using both WP Migrate DB Pro and WP Offload S3). On the surface, this might not seem like a big deal, but what if you’ve recently worked with a freelance developer who had access to your composer.json file and you’ve since parted ways? They now have your license key, which means they can continue to access the software that you’ve paid for. Not cool!

Although the solution we provided did technically allow you to install our plugins via Composer, it was a half-baked solution at best. But, it was still better than what most premium plugin shops provide. Most don’t support Composer at all. For those that don’t, we have to login to each site for each plugin, download the zip, unzip, replace the plugin folder, and commit the files to git. Not ideal, but it gets the job done.

Introducing Full Composer Support

As of today, I’m pleased to announce that we now offer full Composer support for our plugins. 🎉

This includes the ability to install older versions of our plugins using version constraints. In addition, we’ve completely decoupled license keys from the composer.json file via the introduction of Composer API keys. Remember that freelancer that you parted ways with? Now you can simply delete their Composer API key and they no longer have access to your software downloads.

Let’s take a look at the new workflow.

Composer Usage

We’ve added a new Settings tab to My Account where you can manage your Composer API keys. Any number of keys can be added. You can also label them for convenience.

Composer API keys aren’t linked to individual licenses. Each key will grant access to all of our products for which you have an active subscription. This includes any future products we may add down the line, so you don’t need to regenerate them if you purchase a new plugin, or upgrade an existing license. 😉

Once you have an API key, you can add our repository source to your composer.json file, like so:

"repositories": [
    {
        "type":"composer",
        "url":"https://composer.deliciousbrains.com/{COMPOSER_API_KEY}"
    }
]

You can then add your desired packages and version constraints. You can use “*” as the package version to make sure you are always on the latest version of a plugin.

{
    "require": {
        "deliciousbrains-plugin/wp-migrate-db-pro": "1.8.1",
        "deliciousbrains-plugin/wp-migrate-db-pro-media-files": "1.4.9",
        "deliciousbrains-plugin/wp-offload-s3": "*"
    }
}

Running composer install should give you green across the board!

The plugin files are automatically installed to wp-content/plugins, but you can customize the location, if required. Check out the docs for WP Migrate DB Pro and WP Offload S3 for more details.

How We Built It

We decided to add full Composer support back in May 2017 and created a GitHub issue. Evan was our resident Composer expert, so he outlined the project requirements.

The idea would be to mimic the workflow users are already familiar with when it comes to using wpackagist.org, with the only difference being the added unique key in the Composer repository URL.

Soon after, Brad added mockups for the UI to the GitHub issue, but we decided to hold off on the implementation until the site redesign was launched. This was due to the modifications required in My Account, which would have needed to be done for both the old and new themes.

So, what were the requirements?

packages.json

For Composer to perform the package discovery, a new /packages.json endpoint was required. We chose https://composer.deliciousbrains.com/{COMPOSER_API_KEY}/packages.json, but we rewrite this endpoint in Nginx to point to our existing API.

rewrite ^/([a-zA-Z0-9]+)/packages.json$ /?wc-api=delicious-brains&request=composer_packages&composer_key=$1 last;

This endpoint needs to provide a list of packages that our repository is responsible for in addition to every available version, in the following format:

{
    "packages": {
        "vendor/package-name": {
            "1.0.0": { @composer.json },
            "1.0.1": { @composer.json },
            "1.0.2": { @composer.json }
        }
    }
}

This presented us with a problem. For us to generate this metadata we needed to know every version of our plugins that we’ve released over the years, which isn’t something we’ve ever stored in the database. Our product post type in WordPress only saves the current version available for download.

Luckily, we store all of our product downloads in a single S3 bucket, which includes all versions ever released. They’re also named in a standardized way, for example: wp-migrate-db-pro-1.0.zip. As we already use WP Offload S3 on the site, we could use the bundled AWS SDK to list the objects and extract the versions. We perform this lookup every time we update a product in WordPress, but only when the product version has changed. This data is then saved to the options table, which in turn is cached in Redis.

$objects = $as3cf->get_s3client()->listObjects( [
    'Bucket' => 'downloads.deliciousbrains.com',
    'Prefix' => 'wp',
] )->getPath( 'Contents/*/Key' );

$plugins = array();
foreach ( $objects as $object ) {
    $file = self::get_name_and_version( $object );

    if ( ! $file ) {
        continue;
    }

    $plugins[ $file['name'] ][] = $file['version'];
}

Going back to the packages.json format outlined above you’ll notice that each package has a value of { @composer.json }. This should be the information included in each plugin’s composer.json file, however we don’t ship our plugins with one. Instead, we generate this dynamically for each package.

array(
    'name'    => $name,
    'version' => $version,
    'type'    => 'wordpress-plugin',
    'dist'    => array(
        'url'  => self::get_download_url( $plugin, $version, $composer_key ),
        'type' => 'zip',
    ),
    'require' => array(
        'composer/installers' => '~1.0',
    ),
);

This is mostly self-explanatory. The url key points to another endpoint on our API (see below) where the package ZIP can be downloaded. The type and require blocks are what allow us to specify the install location for the packages. By default, they would be installed to /vendor, but using composer/installers allows the default location to become /wp-content/plugins by specifying a type of wordpress-plugin.

Download Endpoint

The download endpoint is where Composer attempts to download the requested package, once it’s been found on our packages.json endpoint. It’s here that we validate that the package is indeed accessible for the given Composer API key. If the key is attached to a user who has an active subscription for the requested package, the download will commence. Otherwise, Composer will fail and a relevant error shown.

And that’s all there is to it!

If you’ve been installing our plugins via Composer previously, I encourage you to check out the new system and upgrade soon. The old system will continue to work for now, but will eventually be deprecated.

Calling All Plugin Shops

Adding Composer support to distribute your premium plugins may seem like a daunting task at first glance, but as we’ve shown here, it’s relatively straightforward. Hopefully, this article will prompt a few other plugin shops to take action, so that as a community we can improve the experience of managing premium plugins with Composer. Looking to make your must-use plugins compatible with Composer? Check out this article.

Update: We have since improved Composer support for our premium plugins again. Find out all the details in this post.

Have you ever created your own Composer repository before? Let us know in the comments.

This entry was posted in WP Offload Media, Plugin Development and tagged WordPress, Development, Deployment, WordPress Development Tips, Composer.

.replybox-fallback, .replybox-fallback ul { list-style: none; }

Tracy Rotton says:

March 1, 2018 at 2:57 am

Love this! But does this work if our WP Migrate DB Pro license is through Mergebot? I’m not seeing an option to create Composer keys in my mergebot.com account. Thanks so much!

Xedin Unknown says:

March 1, 2018 at 4:30 am

Why didn’t you just use SSH keys, which are already supported by Composer, instead of creating your own API stuff?

Martijn says:

March 1, 2018 at 11:17 pm

Hi, Thanks for the composer option for your premium plug-ins. What do you think about using the composer auth.json aproach, then you can keep the autentication out of the composer.json and verdien control. As well all developers can have there one auth.json file.

robrecord says:

March 2, 2018 at 10:53 am

Another way to do it is with bash environment variables.

Reply

robrecord says:

March 2, 2018 at 10:52 am

Really pleased you were able to implement this! And that you cared enough to do so. Thank you.

Giuseppe Mazzapica says:

March 31, 2018 at 10:41 am

I read this post when it was published, and now while I am preparing slides for a workshop on Composer + WP I will give at WordCamp Torino in some days, this post came out of research and decided to comment now 🙂 Me personally, and we at Inpsyde, manage 100% of all our WordPress projects via Composer, since few years now. We also (ab)use Composer for "unusual" things like deployment automation and so forth. So first of all kudos to you, and I am very very happy that you decided to fully support Composer, and hope many other shops will follow. However, in all honesty, I have to say that your current implementation would be a no-go for us, and if we would need to use your plugins, we would need to install them from our internal Composer workflow that we also use for shops that do not support Composer at all (that is put plugins in our internal VCS and serve via packagist.com). Reason is simple: put the API key in composer.json (which means also in version control), is not something that we would do, for different reasons I am sure you can guess. Can I ask the reason you decided to don’t use any of the authentication methods that Composer supports natively?

Evan says:

March 31, 2018 at 12:31 pm

Hey Giuseppe! If you’re using Packagist.com, you could mirror the Delicious Brains composer repository which would keep the API key out of your VCS, while saving you the effort of maintaining mirrored repositories for the plugins it provides. With that said, I understand not adding API keys to version control as a general rule of thumb, but as far as I know this is only used to authenticate downloads via Composer. It’s not a replacement for your license key and doesn’t grant any kind of control over your account. This method is easy and safe. Even if someone were to get your API key, it’s only authenticating downloads of the plugins. I’m curious which native Composer authentication method (other than basic http authentication) would allow for the key to not be included in the composer.json?

Reply
- Giuseppe Mazzapica says:
  
  March 31, 2018 at 1:04 pm
  
  If we have an API key as "Inpsyde" (company) and we use that API key to build an Delicious Brains repository URL to mirror on packagist.com, means that every project will have access to all the plugins in the repo, which might be (very likely is) not what we want. What we need is a granular level of control which package is available to which project/client, even if Inpsyde (key holder) has access to many/all plugins. If we use an API key per project, means we can’t buy plugins as agengy and re-use for clients, but we need to buy specific licenses for specifc clients/projects, again, not what we want. Finally, if we use per-dev API key, that’s an issue because many devs might work on same project, and that’s an issue if the API is in VCS (which of course is shared across all devs). Regarding the other questions, Composer auth methods make you have paths in the composer.json (e.g. the path to a certificate or to a key file), not the file certificate/key file itself, which makes a big difference, as every dev could use a different certificate/key file even if the configuration in composer.json is the same. But honestly a "static" API key, like the one implemented by Delicious Brains, is not much different than basic http auth, which could be managed via auth.json, which could be out of VCS. This is what is used by packagist.com itself, and it works very well for us.
  
  Reply

Cory Moore says:

January 10, 2019 at 5:32 pm

Now if it would only work.

Iain says:

January 11, 2019 at 12:30 am

Hey Cory, Seems to be working at our end – would you mind shooting us an email (contact page or plugin help tab) so I can dig in further with you? Cheers!

Reply
- Cory Moore says:
  
  January 11, 2019 at 5:28 am
  
  Well, the issue wasn’t with you guys. I am using a Bedrock and Trellis set up and I couldn’t get composer to install the plugin after updating my composer.json. I kept running composer update and composer would do it’s thing and then inform me that no updates or installs had been done. Turns out composer update needs to be run from a specific directory when trying to install plugins or themes.
  
  Reply

Samuel Horn Af Rantzien says:

March 20, 2019 at 6:25 pm

Great to read that you move this ship forwards! I wish all plugin devs would do this. I use a custom private composer repo for all premium plugins which do not support composer. I built it with a tool called Release Belt i found on Github. I Wrote a guide about it on my blog if anyone is interested on how you could have everything in composer until all your vendors support composer. I feel this is almost a "must have" when using Bedrock. It doesn’t feel good to check in other authors code in your bedrock setup. Best Regards / Samuel

Vlad Tudorie says:

March 3, 2021 at 7:36 pm

This is great. Nevermind unethical freelancers, public github and bitbucket repositories are littered with credentials. Fun fact, I committed my cloud hosting API key to a public repository without realizing what it meant. Woke up to a few dozen of their most expensive machines waking up and executing away. Took me awhile to figure out where I’d leaked it. Lucky enough the company (DO) was proactive about issuing suspicious activity notifications and refunding the costs accumulated. Anyway, my agency sets our clients up with a system that includes composer-based WordPress, so now we have the "pleasure" of maintaining a few hundred repos and are looking into Satis or Satispress to streamline the entire system.