Pluginade Scripts

Pluginade Scripts is part of the Pluginade Framework, and is a highly opinionated and simple solution to help you write code tests, standardize your WordPress plugin's code, and ship faster.

The problem:

Writing code tests and standardizing your WordPress plugin code is important, but can be a difficult and time consuming task. First, there's all the dependencies you need on your development machine. Node, PHP, Composer, and more. Once you have all those set up, and made sure you are on the right versions, you need to configure separate WordPress environments for running and testing your code. This often involves setting up something like wp-env or an equivalent environment. Then, to run unit tests with PHPUnit you need to configure PHPUnit to run inside that WordPress environments, and keep those configurations up to date if changes ever happen. To run Playwright tests for WordPress you need to do the same. Then there's code standardization for PHP, CSS, and Javacript. For PHP this involves setting up PHPCodeSniffer, and integrating it to use the WordPress Coding Standards ruleset. For CSS you'll configure to use something like wp-scripts lint-style, and for javascript lint-js. And while wp-scripts is extremely helpful in simplifying a lot of this, it doesn't cover everything, you need to manually integrate each package, remember what it does and doesn't do, keep it up to date, and even handle some additional configurations that arise. Then there's also handling things like generating a "built" version of your plugin for production, which involves automatically removing unwanted development files (like node_modules directories, package.json files, etc) before creating a zip file that can be installed in WordPress.

Not only that, but if you're working on many plugins, when changes happen to any of the above, you need to go back to each plugin and fix any broken configurations.

And that's all before you even start writing any tests!

What if there was a way to instantly handle all of that, so you could jump right into writing and testing and shipping your plugin's code? That's what inspired the Pluginade Scripts project.

The solution provided by Pluginade Scripts:

Pluginde Scripts abstracts and containerizes all of the code required for the above so it can be re-used by any plugin. It handles the following for you:

• Creating and updating package.json and composer.json files for testing and building purposes
• Scanning your plugin code to conform to WP Standards (or custom rulesets)
• Scanning your plugin code for security issues
• Scanning and auto-fixing linting issues.
• Running PHPUnit tests inside a WordPress environment using your plugin's PHPUnit test files
• Runnning Playwright inside a WordPress environment using your plugin's Playwright test files
• Building your plugin for production, and removing unused files like node_modules, package.json, markdown files, etc (see .zipignore file)
• Turning your plugin into an installable zip file
• Deploying your plugin with Github Actions or CircleCi

How it works:

Instead of manually creating and updating all those config files, Pluginade Scripts will create and update them for you.

Pluginade Scripts will manage these files for you:

• Root level configuration files
  • package.json, and keeping @wordpress packages in sync with WordPress core versions
  • node_modules
  • composer.json
  • vendor
• WordPress Coding Standards files
  • phpcs.xml
• PHPUnit files:
  • phpunit.xml.dist
  • bootstrap.php
• Jest files:
  • jest.config.js
• Playwright files:
  • playwright.config.ts
  • playwright-global-setup.ts

That means you won't have to create any of those files, and you won't need to update them either. Pluginade Scripts handles all it for you.

Important caveats

It's important to note some of the things you can't do with Pluginade Scripts as well. For example, because it manages your root-level package.json file for you, that means you can't add or remove custom packages from your root-level package.json file, or they'll get overwritten when you run Pluginade commands. However, that doesn't mean you can't use custom npm packages! Rather, it just means that your actual code dependencies don't need to be cluttered up with development dependencies.

Pluginade Scripts is built to work with the Pluginade Framework architecture. That means it expects all of your code to be modular and live inside a directory called wp-modules. Each module within wp-modules can have its own dedicated package.json file, and you can use any npm packages you like there.

If you'd like to spin up a new plugin, or migrate an existing plugin to use Pluginade Scripts, check out Pluginade Studio. It's a tool that helps to guide you through making a plugin using Pluginade.

Frequently Asked Questions

What if I dont want to use all of the WordPress coding standards?

I get it. You might not like Yoda conditionals. That's ok! Pluginade Scripts allows you to define your own PHPCS rules in a custom phpcs.xml file. Just create your own, define your ruleset, and keep the file there. Instead of creating its own ruleset file, it will use your custom ruleset file when running PHPCS linting.

What if I want to maintain my package.json file manually?

You can prevent Pluginade Scripts from overwriting your root-level package.json file. To do this, make sure the name in your package.json file is something other than pluginade-scripts.

Requirements (Docker and bash)

Pluginade Scripts allows you to instantly run PHP WordPress Coding Standards, phpunit, eslint, stylelint and more, on any machine that supports Docker and bash.

That's right, just Docker and bash. No node, no composer, nothing else. If you want to run Docker on your development computer and it isn't running Linux, install Docker Desktop. Once it's running follow the steps below to use Pluginade Scripts with your WordPress plugin.

Note: If you're using a Windows machine for development, you'll need to be able to run bash scripts in Windows.

Using Pluginade Scripts for CICD

Because the only requirements are Docker and bash, you can easily use Pluginade Scripts for CICD on services like CircleCI and Github Actions. To get started, check out some of the CICD examples.

Getting Started

1. Copy the contents of this file

2. Create a new file in the root of your plugin called pluginade.sh

3. Paste the contents into that file.

4. In that file replace these strings:

   • my-plugin-text-domain - The text domain to use for your plugin (Will be enforced by WordPress Coding Standards)
   • MyPluginNamespace - The unique namespace used for your plugin (Will be enforced as function/class prefix in WordPress Coding Standards)

5. Make sure you have Docker Desktop installed and running.

6. On the command line inside your plugin, run one of the pluginade commands.