Developing a WordPress Plugin

[hirasso]

I am making a WordPress plugin to generate ThumbHash placeholders for images. The plugin uses SRWieZ/thumbhash under the hood.

I used php-scoper to create a scoped release asset. This means I have a version of the plugin that is less likely to cause conflicts with other plugins. I plan to use this for the WP.org plugin directory.

Installing via Composer

Another way to install WordPress plugins is through Composer and Packagist. A popular project for this is Roots/Bedrock.

• If someone uses the command composer require hirasso/thumbhash-placeholders, they will not get the scoped version.
• They will get the unscoped version from the latest tag on the main branch.

If users get the unscoped version, it could lead to conflicts with other plugins or packages.

My Main Question

What is the best way to scope a package when releasing it to Packagist?

• I can’t just use the main branch.
• Even with a scoped vendor directory, the composer.json file might still cause conflicts with other packages.

I hope this makes sense! I think many others have similar questions.

[theofidry]

What is the best way to scope a package when releasing it to Packagist?

I think it depends on how you want to distribute your scoped asset: if it is as a PHAR only it can be part of the main project (like it is done with PHP-Scoper or Box). If you want to distribute a scoped Composer package, then you need a separate repository with the scoped code, like PHPStan does for instance. In that case you'll need a bit more work to configure the CI to push code to that scoped mirror-ish repository

[hirasso]

I want to release it via composer. Ok, seems like I need to learn even more GitHub tooling for creating that scoped version 🥴 ...or I wait until someone complains 😅

[hirasso]

An official recipe for pushing or pulling the build folder to a separate repo for composer would be amazing. That way, it would probably feel less hacky.

[theofidry]

A more automated way would be amazing, but unfortunately scoping in PHP is, unlike in JS for instance, a lot more finicky.

I couldn't really find a canonical way to do this yet as several projects that used PHP-Scoper tended to have a few steps done besides just shipping a "build" directory.

I need to learn even more GitHub tooling for creating that scoped version

And I would need to learn how to do a GitHub recipe too 😅

[hirasso]

If you'd like me to present my current state to you and discuss possible solutions together, I'd love to hear from you via email (in my profile) so that we can jump on a call sometime soon.

I can imagine talking it through could help a lot in this case 🙂

[hirasso]

I have created an issue over at the Packagist rep to discuss this further. Seems like maintaining a separate repository currently is indeed the "official" way for releasing a scoped / built package.

[hirasso]

Wanted to get back here to post my current solution. People interested can clone my plugin from here: hirasso/wp-thumbhash.

Decisions

• I decided to not publish my plugin on the official WP.org plugin repository. Instead, I support plugin updates via composer or via the normal WordPress plugin update process / WP-CLI, powered by Plugin Update Checker.
• Even for installs via composer, my plugin is being scoped (for now). The packagist package is named hirasso/wp-thumbhash, but it actually points at hirasso/wp-thumbhash-dist.

What I Did

I've created a small cli.js that takes care of all the things I need. I execute the relevant commands in my ci and release workflows. They can also be executed locally through npm scripts. Here are the most important commands:

Create a Scoped Release

config/cli/cli.js release:create

Scope all non-dev dependencies, inject other files and folders that do not have an export-ignore entry in the .gitattributes file. The scoped folder is created under ./scoped/my-plugin-slug/. The command also creates a zip file my-plugin-slug.zip at the root level, to provide an installable release asset for manual installs.

Test a Scoped Release

config/cli/cli.js test:release

Run E2E tests against the scoped release folder using a @wordpress/env container and Playwright:

Push a Scoped Release to the Dist Repo

# clone the dist repo and checkout an empty root branch
config/cli/cli.js dist:prepare
# copy all scoped files into the dist repo folder, commit, tag and push
config/cli/cli.js dist:push

These commands assume your dist repo is named exactly like your source repo, with the suffix -dist. In my case, it's hirasso/wp-thumbhash-dist. Here is an example tag, where GitHub's default zip file contains the scoped production-ready plugin files. This will be installed when running composer require hirasso/wp-thumbhash.

Other Commands

There are a few other commands available that help me with other WordPress-specific things, like, for example, keeping the version in the main plugin file up to date (I'm handling versions/git tags and CHANGELOG entries using @changesets/cli and @changesets/action).

Print all available commands to the console using the help command:

config/cli/cli.js help

Usage: cli.js <command>

Available commands:
  release:create – Create a scoped release
  version:patch – Patch the version in the main plugin file
  dist:prepare – Prepare the folder for pushing to the dist repo
  dist:push – Push the prepared dist folder to the dist repo
  test:dev – Run PHP and E2E tests against the unscoped development version of the plugin
  test:release – Run E2E tests against the scoped release version of the plugin
  help – Show available commands for this cli

Notes

• I'm maintaining a separate composer.dist.json that is being shipped with the scoped release instead of the actual composer.json. It includes only the bare minimum required to be installed as a WordPress plugin. It does not include any dependencies except for the PHP version and composer/installers. Otherwise, installs via composer could still be blocked by version conflicts, even though all dependencies are scoped and shipped with my plugin.
• For excluding WP-specific globals I'm using snicco/php-scoper-wordpress-excludes. You can see how I'm doing it in my scoper.config.php here and here.
• I somehow ended up building my cli using JavaScript – it's a little easier for me to write. But of course, PHP would also be a viable option. Maybe even a better one, as scoping is so php-centric. Maybe using a tool like Deployer would even be a good idea... because that is basically what we are doing: build, pack, deploy.
• Currently, no matter how the plugin is installed (composer, wp-cli, manual), it will always install the scoped version. That's because of a version conflict I have with snicco/better-wp-cli and psr/log.
• The scoped release will also be attached to the GitHub release as wp-thumbhash.zip from where it can be installed manually. It can update itself the classic WordPress way through an included instance of Plugin Update Checker. I would love if there was a way to point packagist towards a custom release asset zip file. If there was, I could skip the dist repo altogether.

In the future, I might go the extra mile at some point and rewrite my plugin to not make use of snicco/better-wp-cli, so that I can get rid of the version conflicts with psr/log and support clean composer installs from the source. That will also force me to use composer-dist-plugin for my compiled JS and CSS assets, should I need to introduce a build step at some point 🤦🤦 ...but at least I would then be "doing it right", as discussed in depth in this issue on the packagist repo.

I'll mark this as "The Answer" for now, until someone else comes along and shows us how it's actually done :)

[theofidry]

Feel free to add a link to this entry in the docs, e.g. in the Wordpress support