wp-plugin-starter

A GitHub template repository for a Perxel WordPress plugin. It ships the house layout every Perxel plugin shares - a namespaced, autoloaded codebase, the perxel/wp-plugin-ui admin kit wired in, PHPCS + WordPress Plugin Check in CI, and a release workflow that builds the installable zip and deploys to WordPress.org.

Out of the box it is a working plugin: activate it and Tools -> Perxel Example shows a Settings screen (a text field + a toggle, saved through admin-post) rendered in the shared UI layout, plus a hidden maintainer-only "Perxel UI" component showcase.

Creating a new plugin from it

1. Use this template

On GitHub: Use this template -> Create a new repository, named wp-<something> under perxel/. Clone it.

2. Replace the placeholder tokens

There is no build step - personalising is a find-and-replace across the tree. Every placeholder is one of these six tokens. Replace them case-sensitively, Perxel_Example before Perxel Example:

Token	What it is	Example value
Perxel_Example	PHP namespace root and @package tag - keep it Ucfirst_Snake of the slug so Plugin Check accepts it as the prefix	Perxel_Seo_Helper
Perxel Example	Display name (Plugin Name header, PXEX_NAME)	Perxel SEO Helper
perxel-example	Slug = text domain = wordpress.org slug	perxel-seo-helper
wp-example	GitHub repo name (Plugin URI, links)	wp-seo-helper
PXEX	Uppercase constant / hook prefix	PXSH
pxex	Lowercase hook / option / CSS-class prefix	pxsh

Pick the name first - a third-party name (TinyMCE, WooCommerce...) may only appear at the end after for (Perxel Accordion for TinyMCE). See CLAUDE.md -> "Naming a plugin".

One-liner (macOS sed; drop the '' after -i on Linux) - edit the six replacement values first:

git grep -lZ -e 'Perxel_Example' -e 'Perxel Example' \
             -e 'perxel-example' -e 'wp-example' -e 'PXEX' -e 'pxex' \
| xargs -0 sed -i '' \
  -e 's/Perxel_Example/Perxel_Seo_Helper/g' \
  -e 's/Perxel Example/Perxel SEO Helper/g' \
  -e 's/perxel-example/perxel-seo-helper/g' \
  -e 's/wp-example/wp-seo-helper/g' \
  -e 's/PXEX/PXSH/g' \
  -e 's/pxex/pxsh/g'

Then rename the two slug-named files:

git mv perxel-example.php perxel-seo-helper.php
git mv languages/perxel-example.pot languages/perxel-seo-helper.pot

3. Fill in the free text

Search for A short description of what this plugin does. (main file header, composer.json, readme.txt) and write the real one-liner. Then work through readme.txt - Contributors, Tags, Tested up to, Description, FAQ, Screenshots, and the External services section (delete it if the plugin calls nothing third-party) - and replace this README with the plugin's own (public-facing only - see CLAUDE.md -> "Documentation rules").

4. Vendor the UI kit (only if the plugin has an admin screen)

The kit is for admin screens. If the plugin has none (e.g. a shortcode- or editor-only plugin), skip this step and follow "Plugins without an admin screen" in CLAUDE.md instead.

bin/update-ui.sh 0.23.0        # newest tag at github.com/perxel/wp-plugin-ui

Set that same version in the main file's Perxel_UI_Loader::register( '0.23.0', ... ) call - it is what the "highest version wins" loader compares. (The plugin still activates without this step - it just shows a "UI library could not be loaded" notice until the kit is vendored.)

5. Wire up the repo

• composer install - pulls PHPCS + the WordPress standard.
• php -l <mainfile>.php && composer run lint - both must be green.
• CI runs the official WordPress Plugin Check on the built zip; see the "WordPress.org / Plugin Check compliance" table in CLAUDE.md for the rules it enforces.
• composer run build - produces the installable zip in dist/.
• Reserve the slug at https://wordpress.org/plugins/developers/add/ (the first submission is a manual review).
• After the .org review is approved: give the repo access to the org secrets SVN_USERNAME / SVN_PASSWORD (or add them as repo secrets), set the repo variable DEPLOY_TO_WPORG = true, run Actions -> Release -> Run workflow once with dry_run on to check the staging, then publish a Release
  • release.yml deploys it (details in CLAUDE.md -> Releasing). Not going on .org? Delete the deploy job.
• Add the real listing art to .wordpress-org/ (see the README there), then delete that README.

6. Delete this section

Once the new repo builds green, remove "Creating a new plugin from it" from its README.