description: Initialize WordPress plugin development environment with testing suite, GitHub Actions, and build scripts

WordPress Plugin Development Initialization Skill

This skill automatically sets up a complete WordPress plugin development environment.

Trigger Keywords

This skill is triggered when the user says any of the following:

• "Initialize WordPress plugin development"
• "Set up WordPress plugin development environment"
• "Initialize WP plugin testing"
• "Create WordPress plugin development environment"
• "請幫我初始化 WordPress 外掛開發"
• "設定 WordPress 外掛開發環境"

Features

This skill automatically performs the following operations:

1. Detect Plugin Information

   • Automatically reads the main plugin file
   • Extracts plugin slug, name, and version
   • Formats version number (adds v prefix)

2. Configure Composer

   • Installs PHPUnit testing suite
   • Sets up PSR-4 autoload
   • Creates testing and build scripts

3. Create Testing Environment

   • Uses WP-CLI scaffold to generate test files
   • Configures test database (wordpress_test)
   • Creates test examples
   • Automatically installs test environment

4. Set Up GitHub Actions

   • Integrated testing and release workflow
   • Automated CI/CD pipeline

5. Create Build Scripts

   • Cross-platform PHP build script
   • Automatically excludes development files

6. Generate Documentation

   • TESTING.md - Testing guide
   • RELEASE.md - Release guide

7. Automated Verification

   • Automatically runs composer test:install
   • Automatically runs composer test
   • Automatically runs composer build
   • Ensures everything works before completion

Usage

In your plugin directory, tell the AI assistant:

Initialize WordPress plugin development

The skill will automatically:

1. Detect plugin information
2. Ask for necessary configurations (namespace, database, etc.)
3. Execute all initialization steps
4. Automatically install test environment
5. Automatically run tests
6. Automatically build plugin
7. Display completion message and next steps

Manual Execution

bash .agent/skills/wp-plugin-dev-init/scripts/init.sh

Requirements

• WP-CLI
• Composer
• MySQL/MariaDB
• Git
• Subversion (svn) - Required for WordPress test suite installation

Output

After completion, the following will be created:

• composer.json - Contains autoload and scripts
• bin/install-wp-tests.sh - Test environment installation script
• tests/ - Test files directory
• phpunit.xml.dist - PHPUnit configuration
• .github/workflows/release.yml - CI/CD workflow
• scripts/build.php - Build script
• TESTING.md - Testing guide
• RELEASE.md - Release guide

Configuration

The skill will ask for:

• PHP Namespace: Default is plugin name (e.g., OrderChatz)
• Autoload Directory: Default is src
• Database User: Default is root
• Database Password: Default is empty
• Database Host: Default is localhost

Database Naming

Test database will be named: wordpress_test

Note: All plugins share the same test database name. Since test data is automatically cleaned up after each test run, there's no need for separate databases per plugin.

PHP Version Compatibility

Important: The default setup uses PHPUnit 9.6+ which requires PHP 8.1+ due to dependency requirements (specifically doctrine/instantiator 2.0).

To Support PHP 7.4-8.0

If you need to support older PHP versions, you must:

1. Limit PHPUnit version in composer.json:

   "require-dev": {
     "phpunit/phpunit": "^9.3",
     "wp-phpunit/wp-phpunit": "^6.3",
     "yoast/phpunit-polyfills": "^1.0"
   }
   

2. Update PHP requirement in composer.json:

   "require": {
     "php": ">=7.4"
   }
   

3. Rebuild dependencies:

   rm -rf vendor composer.lock
   composer install
   

PHPUnit Version Compatibility

• PHPUnit 9.3-9.5 → PHP 7.4-8.0
• PHPUnit 9.6+ → PHP 8.0+ (requires PHP 8.1+ due to dependencies)
• PHPUnit 10+ → PHP 8.1+

GitHub Actions Configuration

The generated .github/workflows/release.yml includes:

Required Permissions

The workflow automatically includes:

permissions:
  contents: write

This allows GitHub Actions to create releases and upload assets.

Required Dependencies

• Subversion (svn): Automatically installed in the workflow for WordPress test suite
• Composer cache: Configured for faster dependency installation

Version Extraction

The workflow extracts version numbers directly from Git tags (e.g., v1.0.0) rather than parsing plugin files, ensuring consistency.

Troubleshooting

Common Issues

1. PHP Version Mismatch

   • Error: doctrine/instantiator is locked to version 2.0.0... requires php ^8.1
   • Solution: Either upgrade to PHP 8.1+ or follow the "To Support PHP 7.4-8.0" instructions above

2. SVN Command Not Found

   • Error: svn: command not found during test installation
   • Solution: Install Subversion (brew install svn on macOS, apt-get install subversion on Linux)

3. GitHub Actions Permission Denied (403)

   • Error: GitHub release failed with status: 403
   • Solution: Ensure permissions: contents: write is set in the workflow file

4. Composer Lock File Out of Sync

   • Error: composer.lock has some errors
   • Solution: Run composer update --lock and commit the updated file

5. Empty Changelog in Release

   • For first release: Will show "Initial release"
   • For subsequent releases: Shows commits since previous tag