339 lines
11 KiB
Markdown
339 lines
11 KiB
Markdown
---
|
|
name: wordpress-plugin-scaffold
|
|
description: Scaffold WordPress plugins using WP-CLI commands (wp scaffold plugin, wp scaffold plugin-tests). Use this skill when creating new WordPress plugins or adding test infrastructure to existing plugins.
|
|
---
|
|
|
|
# WordPress Plugin Scaffold
|
|
|
|
This skill provides guidance for scaffolding WordPress plugins using WP-CLI's scaffold commands. It supports both creating new plugins from scratch and adding test infrastructure to existing plugins.
|
|
|
|
**Note:** This skill works seamlessly with the **wp-env skill (if available)**. When wp-env setup or management is needed, activate the wp-env skill for comprehensive environment handling.
|
|
|
|
## About WP-CLI Scaffold Commands
|
|
|
|
WP-CLI provides two primary scaffolding commands for plugin development:
|
|
|
|
### wp scaffold plugin
|
|
|
|
Generates starter code for a new plugin, including:
|
|
|
|
- Main plugin PHP file
|
|
- `readme.txt` for WordPress.org
|
|
- `package.json` with Grunt tasks for i18n and readme conversion
|
|
- Editor configuration files (`.editorconfig`, `.gitignore`, `.distignore`)
|
|
- Optional: PHPUnit test suite, CI configuration, and PHP_CodeSniffer rules
|
|
|
|
### wp scaffold plugin-tests
|
|
|
|
Adds PHPUnit test infrastructure to an existing plugin, including:
|
|
|
|
- `phpunit.xml.dist` configuration
|
|
- CI configuration (CircleCI, GitHub Actions, GitLab, Bitbucket)
|
|
- `bin/install-wp-tests.sh` for WordPress test suite setup
|
|
- `tests/bootstrap.php` to activate the plugin during tests
|
|
- `tests/test-sample.php` with example test cases
|
|
- `.phpcs.xml.dist` for PHP_CodeSniffer rules
|
|
|
|
## Prerequisites
|
|
|
|
Verify WP-CLI is installed and accessible:
|
|
|
|
```bash
|
|
wp --version
|
|
```
|
|
|
|
If WP-CLI is not installed, see [references/wp-cli-installation.md](references/wp-cli-installation.md) for comprehensive installation instructions across all platforms.
|
|
|
|
## Environment Detection
|
|
|
|
**IMPORTANT:** Before running any scaffold commands, detect which WordPress environment is available:
|
|
|
|
### Detection Strategy
|
|
|
|
1. **Check for existing WordPress installation** (preferred):
|
|
|
|
```bash
|
|
wp core version 2>/dev/null
|
|
```
|
|
|
|
- If successful → Use `wp scaffold plugin` directly
|
|
- You're already in a WordPress installation, no additional setup needed
|
|
|
|
2. **Check for wp-env configuration**:
|
|
|
|
```bash
|
|
# Look for wp-env config files
|
|
[ -f .wp-env.json ] || [ -f .wp-env.override.json ]
|
|
```
|
|
|
|
- If found → Check if wp-env is running
|
|
- If running → Use `wp-env run cli wp scaffold plugin`
|
|
- If not running → **Activate the wp-env skill (if available)** to start the environment
|
|
|
|
3. **Check for wp-env availability** (fallback):
|
|
|
|
```bash
|
|
wp-env --version 2>/dev/null
|
|
```
|
|
|
|
- If available → Ask user if they want to use wp-env
|
|
- **Activate the wp-env skill (if available)** for environment setup and management
|
|
|
|
4. **No environment available** (error):
|
|
- Inform user they need either:
|
|
- A WordPress installation with `--path` flag
|
|
- wp-env setup (see wp-env skill if available)
|
|
|
|
### Command Prefix Selection
|
|
|
|
Based on detection, use the appropriate command prefix throughout this skill:
|
|
|
|
- **In WordPress installation:** `wp scaffold plugin`
|
|
- **Using wp-env:** `wp-env run cli wp scaffold plugin`
|
|
|
|
All examples below show the base command. Prepend `wp-env run cli` when using wp-env.
|
|
|
|
## Workflow: Creating a New Plugin
|
|
|
|
When creating a new WordPress plugin, follow this interactive workflow:
|
|
|
|
### 1. Gather Plugin Metadata
|
|
|
|
Collect the following information from the user, offering smart defaults:
|
|
|
|
- **Plugin slug** (required) - Internal name, lowercase with hyphens
|
|
- Default: Infer from current directory name or user's request
|
|
|
|
- **Plugin name** - Display name for the plugin header
|
|
- Default: Title-case version of slug
|
|
|
|
- **Plugin description** - What the plugin does
|
|
- Default: Ask user to provide
|
|
|
|
- **Plugin author** - Author name
|
|
- Default: Use `git config user.name` if available
|
|
|
|
- **Plugin author URI** - Author website URL
|
|
- Default: Use `git config user.url` if available, otherwise skip
|
|
|
|
- **Plugin URI** - Plugin project URL
|
|
- Default: Skip unless user provides
|
|
|
|
### 2. Determine Additional Options
|
|
|
|
Ask the user about these options:
|
|
|
|
- **Include tests?** - Whether to generate PHPUnit test files
|
|
- Default: Yes (recommended for all plugins)
|
|
- Use `--skip-tests` flag to omit
|
|
|
|
- **CI provider** - Which continuous integration service to use
|
|
- Options: `circle` (default), `github`, `gitlab`, `bitbucket`
|
|
- Use `--ci=<provider>` flag
|
|
|
|
- **Target directory** - Where to create the plugin
|
|
- Default: Current working directory
|
|
- Use `--dir=<path>` to specify custom location
|
|
|
|
### 3. Construct and Execute Command
|
|
|
|
Build the `wp scaffold plugin` command with gathered information:
|
|
|
|
```bash
|
|
wp scaffold plugin <slug> \
|
|
--plugin_name="<name>" \
|
|
--plugin_description="<description>" \
|
|
--plugin_author="<author>" \
|
|
--plugin_author_uri="<author-uri>" \
|
|
--plugin_uri="<plugin-uri>" \
|
|
--ci=<provider>
|
|
```
|
|
|
|
Add `--skip-tests` if user declined test files.
|
|
Add `--dir=<path>` if custom directory specified.
|
|
|
|
### 4. Post-Scaffold Actions
|
|
|
|
After successfully scaffolding the plugin:
|
|
|
|
1. **Verify creation** - Confirm files were generated:
|
|
|
|
```bash
|
|
ls -la <plugin-directory>
|
|
```
|
|
|
|
2. **Ask about activation** - If wp-env is running, offer to activate:
|
|
- "Would you like me to activate this plugin in your wp-env environment?"
|
|
- If yes, run: `wp-env run cli wp plugin activate <slug>`
|
|
- For network activation: `wp-env run cli wp plugin activate <slug> --network`
|
|
|
|
3. **Next steps guidance** - Inform user about:
|
|
- Main plugin file location: `<slug>/<slug>.php`
|
|
- How to run tests if included: `wp-env run tests-cli --env-cwd=wp-content/plugins/<slug> phpunit`
|
|
- NPM scripts available: `npm run readme`, `npm run i18n`
|
|
|
|
## Workflow: Adding Tests to Existing Plugin
|
|
|
|
When adding test infrastructure to an existing plugin:
|
|
|
|
### 1. Identify Plugin
|
|
|
|
Determine which plugin needs tests:
|
|
|
|
- **Plugin slug** - The plugin directory name
|
|
- **Plugin directory** - Path to the plugin (use `--dir` if non-standard)
|
|
|
|
### 2. Determine CI Provider
|
|
|
|
Ask which CI service the user wants:
|
|
|
|
- Options: `circle` (default), `github`, `gitlab`, `bitbucket`
|
|
|
|
### 3. Execute Command
|
|
|
|
Run the scaffold plugin-tests command:
|
|
|
|
```bash
|
|
# Standard plugin location
|
|
wp scaffold plugin-tests <plugin-slug> --ci=<provider>
|
|
|
|
# Non-standard location
|
|
wp scaffold plugin-tests --dir=<path/to/plugin> --ci=<provider>
|
|
```
|
|
|
|
Add `--force` flag to overwrite existing test files if needed.
|
|
|
|
### 4. Post-Scaffold Actions
|
|
|
|
After generating test files:
|
|
|
|
1. **Set up test environment** - Guide user through test setup:
|
|
|
|
```bash
|
|
# Install WordPress test suite (if not using wp-env)
|
|
bash bin/install-wp-tests.sh wordpress_test root password localhost latest
|
|
|
|
# Or use wp-env for testing
|
|
wp-env run tests-cli --env-cwd=wp-content/plugins/<slug> phpunit
|
|
```
|
|
|
|
2. **Verify test execution** - Run the sample test:
|
|
|
|
```bash
|
|
wp-env run tests-cli --env-cwd=wp-content/plugins/<slug> phpunit
|
|
```
|
|
|
|
3. **Next steps** - Inform user about:
|
|
- Writing additional tests in `tests/` directory
|
|
- Running specific test files or test cases
|
|
- CI/CD integration based on chosen provider
|
|
|
|
## Common Options Reference
|
|
|
|
| Option | Description | Example |
|
|
| -------------------- | ---------------------------------------------------- | -------------------- |
|
|
| `--skip-tests` | Don't generate PHPUnit test files | `--skip-tests` |
|
|
| `--ci=<provider>` | CI configuration (circle, github, gitlab, bitbucket) | `--ci=github` |
|
|
| `--activate` | Activate plugin after creation | `--activate` |
|
|
| `--activate-network` | Network activate plugin after creation | `--activate-network` |
|
|
| `--force` | Overwrite existing files | `--force` |
|
|
| `--dir=<path>` | Custom directory for plugin | `--dir=/custom/path` |
|
|
|
|
**Note:** `--activate` and `--activate-network` flags work with local wp-cli WordPress installations but not with wp-env. For wp-env, use `wp-env run cli wp plugin activate` instead.
|
|
|
|
## Best Practices
|
|
|
|
### Plugin Naming
|
|
|
|
- Use lowercase letters, numbers, and hyphens only
|
|
- Be descriptive but concise
|
|
- Follow WordPress plugin naming conventions
|
|
- Examples: `my-contact-form`, `analytics-dashboard`, `custom-post-types`
|
|
|
|
### When to Skip Tests
|
|
|
|
Skip tests (`--skip-tests`) only when:
|
|
|
|
- Creating a quick prototype or proof-of-concept
|
|
- Building a personal plugin that won't be distributed
|
|
- Planning to add tests later with `wp scaffold plugin-tests`
|
|
|
|
**Always include tests for:**
|
|
|
|
- Plugins intended for public distribution
|
|
- Team projects with multiple contributors
|
|
- Plugins with complex business logic
|
|
- Any production-ready code
|
|
|
|
### CI Provider Selection
|
|
|
|
Choose a CI provider based on your repository host:
|
|
|
|
- **GitHub repositories** → `--ci=github` (GitHub Actions)
|
|
- **GitLab repositories** → `--ci=gitlab` (GitLab CI)
|
|
- **Bitbucket repositories** → `--ci=bitbucket` (Bitbucket Pipelines)
|
|
- **Other/unknown** → `--ci=circle` (CircleCI)
|
|
|
|
### Working with wp-env
|
|
|
|
When developing with wp-env:
|
|
|
|
1. **Scaffold inside wp-env directory structure:**
|
|
|
|
```bash
|
|
# Create plugin in wp-env's plugin directory
|
|
cd /path/to/wp-env-project
|
|
wp scaffold plugin my-plugin --dir=plugins/
|
|
```
|
|
|
|
2. **Or scaffold separately and configure .wp-env.json:**
|
|
|
|
```json
|
|
{
|
|
"plugins": [".", "../other-plugin"]
|
|
}
|
|
```
|
|
|
|
3. **Activate after scaffolding:**
|
|
|
|
```bash
|
|
wp-env run cli wp plugin activate my-plugin
|
|
```
|
|
|
|
4. **Run tests in wp-env:**
|
|
|
|
```bash
|
|
wp-env run tests-cli --env-cwd=wp-content/plugins/my-plugin phpunit
|
|
```
|
|
|
|
## Example Interactions
|
|
|
|
### Creating a New Plugin
|
|
|
|
**User:** "Create a new WordPress plugin called 'site-analytics' for tracking visitor analytics"
|
|
|
|
**Process:**
|
|
|
|
1. Gather metadata (use smart defaults from git config)
|
|
2. Ask about tests (default: yes) and CI provider (default: github)
|
|
3. Execute: `wp scaffold plugin site-analytics --plugin_name="Site Analytics" --plugin_description="Track visitor analytics and generate reports" --plugin_author="Em" --ci=github`
|
|
4. Ask: "Would you like me to activate this plugin in wp-env?"
|
|
|
|
### Adding Tests to Existing Plugin
|
|
|
|
**User:** "Add tests to my existing 'custom-widgets' plugin"
|
|
|
|
**Process:**
|
|
|
|
1. Identify plugin location
|
|
2. Ask about CI provider
|
|
3. Execute: `wp scaffold plugin-tests custom-widgets --ci=github`
|
|
4. Guide user through running tests with wp-env
|
|
|
|
## Additional Resources
|
|
|
|
- [WP-CLI Scaffold Plugin Documentation](https://developer.wordpress.org/cli/commands/scaffold/plugin/)
|
|
- [WP-CLI Scaffold Plugin Tests Documentation](https://developer.wordpress.org/cli/commands/scaffold/plugin-tests/)
|
|
- [Plugin Unit Tests Handbook](https://make.wordpress.org/cli/handbook/misc/plugin-unit-tests/)
|
|
- [WordPress Plugin Handbook](https://developer.wordpress.org/plugins/)
|