template-wordpress

GitHub template repository for bootstrapping WordPress plugins and themes. Ships both plugin and theme scaffolding; a setup.sh script lets developers choose their mode and configures the project accordingly.

Requirements

• PHP 8.1+
• WordPress 7.0+ (the manage-subscriptions block uses the PHP-only block.json render manifest that's reliable from 7.0 onwards; wp_admin_notice() from 6.4 is also relied on)
• Composer
• Node.js 20+ and npm (activates husky pre-commit hook, runs Playwright)
• DDEV (for local development)

Installation

1. Create a new repository from this template
2. Clone your new repository
3. Run the setup script:

bash setup.sh

The script prompts for:

• Slug (kebab-case, e.g. my-plugin)
• Namespace (e.g. Apermo\MyPlugin)
• Composer package name
• Mode (plugin or theme)

It replaces all placeholders, removes irrelevant mode files, configures DDEV, and optionally sets up GitHub labels and branch protection.

Development

composer install
npm install              # Activates husky hook + installs Playwright
composer cs              # Run PHPCS
composer cs:fix          # Fix PHPCS violations
composer analyse         # Run PHPStan
composer test            # Run all tests
composer test:unit       # Run unit tests only
composer test:integration # Run integration tests only
npm run test:e2e         # Run Playwright E2E tests (incl. WCAG 2.1 AA a11y checks)

Local WordPress Environment

ddev start && ddev orchestrate

Uses ddev-orchestrate to download WordPress, create wp-config.php, install, and activate the plugin/theme.

Git Hooks

The pre-commit hook (PHPCS + PHPStan) is managed by husky and activates automatically after npm install. No manual configuration required.

Template Sync

To pull upstream template changes into a derived project:

git remote add template https://github.com/apermo/template-wordpress.git
git fetch template
git checkout -b chore/sync-template
git merge template/main --allow-unrelated-histories

License

GPL-2.0-or-later