wpallstars/wp-plugin-starter-template-for-ai-coding
Template
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request #15 from wpallstars/feature/testing-framework

Browse Source 
Merging comprehensive testing framework PR.

External check failures are expected:
- SonarCloud: 0% coverage vs 80% requirement (free plan limitation)
- Codacy: Markdown URL line lengths (unavoidable for long URLs)

All GitHub Actions workflows pass.
This commit is contained in:
Marcus Quinn
2025-11-25 00:29:03 +00:00
committed by GitHub
parent 5e65d07a4f a9d9c69b65
commit 58f5f8f71b
74 changed files with 12596 additions and 1422 deletions
Download Patch File Download Diff File Expand all files Collapse all files

62
.agents/code-review.md
View File

@@ -4,6 +4,23 @@ This document provides guidance for AI assistants to help with code review for t
## Code Review Checklist
### Testing with WordPress Playground
Before submitting code for review, test it with WordPress Playground:
* [ ] Test in single site environment:
[Open in WordPress Playground][playground-single]
* [ ] Test in multisite environment:
[Open in WordPress Playground][playground-multisite]
[playground-single]: https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/wpallstars/wp-plugin-starter-template-for-ai-coding/main/playground/blueprint.json&_t=5
[playground-multisite]: https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/wpallstars/wp-plugin-starter-template-for-ai-coding/main/playground/multisite-blueprint.json&_t=18
* [ ] Verify plugin functionality works in both environments
* [ ] Check for any JavaScript errors in the browser console
* [ ] Run Cypress tests locally: `npm run test:playground:single` and `npm run test:playground:multisite`
For more details on WordPress Playground testing, see the [Testing Framework](../.wiki/Testing.md) documentation.
When reviewing code, check for the following:
### Functionality
@@ -57,15 +74,28 @@ When reviewing code, check for the following:
* [ ] Is keyboard navigation supported?
* [ ] Is screen reader support implemented?
### Testing
* [ ] Are there appropriate unit tests for PHP code?
* [ ] Are there appropriate end-to-end tests for UI functionality?
* [ ] Do tests cover both single site and multisite scenarios?
* [ ] Are tests well-organized and maintainable?
* [ ] Do tests use appropriate assertions and expectations?
## Automated Code Review Tools
This project uses several automated code review tools to maintain high code quality standards. These tools are free to use for public repositories and should be integrated into any new repositories based on this template.
This project uses several automated code review tools to maintain high quality standards.
**Important**: Before pushing your code, run the local code quality checks as described in the [Code Quality Checks Workflow](./code-quality-checks.md) to catch issues early.
These tools are free for public repositories and should be integrated into new repositories.
**Important**: Before pushing, run local code quality checks as described in
[Code Quality Checks Workflow](./code-quality-checks.md) to catch issues early.
### 1. CodeRabbit
[CodeRabbit](https://www.coderabbit.ai/) is an AI-powered code review tool that provides automated feedback on pull requests.
[CodeRabbit](https://www.coderabbit.ai/) is an AI-powered code review tool.
It provides automated feedback on pull requests.
* **Integration**: Add the CodeRabbit GitHub App to your repository
* **Benefits**: Provides AI-powered code reviews, identifies potential issues, and suggests improvements
@@ -73,7 +103,9 @@ This project uses several automated code review tools to maintain high code qual
### 2. CodeFactor
[CodeFactor](https://www.codefactor.io/) continuously monitors code quality and provides feedback on code style, complexity, and potential issues.
[CodeFactor](https://www.codefactor.io/) continuously monitors code quality.
It provides feedback on code style, complexity, and potential issues.
* **Integration**: Add the CodeFactor GitHub App to your repository
* **Benefits**: Provides a grade for your codebase, identifies issues, and tracks code quality over time
@@ -81,7 +113,9 @@ This project uses several automated code review tools to maintain high code qual
### 3. Codacy
[Codacy](https://www.codacy.com/) is a code quality tool that provides static analysis, code coverage, and code duplication detection.
[Codacy](https://www.codacy.com/) is a code quality tool.
It provides static analysis, code coverage, and code duplication detection.
* **Integration**: Add the Codacy GitHub App to your repository
* **Benefits**: Provides a grade for your codebase, identifies issues, and tracks code quality over time
@@ -97,7 +131,9 @@ This project uses several automated code review tools to maintain high code qual
### 5. PHP Mess Detector
[PHP Mess Detector](https://phpmd.org/) is a tool that looks for potential problems in your code such as possible bugs, suboptimal code, overcomplicated expressions, and unused parameters, variables, and methods.
[PHP Mess Detector](https://phpmd.org/) looks for potential problems in your code.
It detects bugs, suboptimal code, overcomplicated expressions, and unused code.
* **Integration**: Included in the project's composer.json and GitHub Actions workflow
* **Benefits**: Identifies code smells, complexity issues, unused code, naming problems, and more
@@ -226,10 +262,20 @@ In function `handle_remove_reference()`:
3. The success message should be translatable:
```php
// Change this:
add_settings_error('fpden', 'fpden_removed', 'Plugin reference removed successfully.', 'updated');
add_settings_error(
'fpden',
'fpden_removed',
'Plugin reference removed successfully.',
'updated'
);
// To this:
add_settings_error('fpden', 'fpden_removed', __('Plugin reference removed successfully.', 'fix-plugin-does-not-exist-notices'), 'updated');
add_settings_error(
'fpden',
'fpden_removed',
__( 'Plugin reference removed successfully.', 'fix-plugin-does-not-exist-notices' ),
'updated'
);
```
```

548
.agents/error-checking-feedback-loops.md Normal file
View File

@@ -0,0 +1,548 @@
# Error Checking and Feedback Loops
This document outlines the processes for error checking, debugging, and establishing feedback loops.
The goal is to create a seamless, autonomous CI/CD pipeline.
The AI can identify, diagnose, and fix issues with minimal human intervention.
## Table of Contents
* [GitHub Actions Workflow Monitoring](#github-actions-workflow-monitoring)
* [Local Build and Test Feedback](#local-build-and-test-feedback)
* [Code Quality Tool Integration](#code-quality-tool-integration)
* [Automated Error Resolution](#automated-error-resolution)
* [Feedback Loop Architecture](#feedback-loop-architecture)
* [When to Consult Humans](#when-to-consult-humans)
## GitHub Actions Workflow Monitoring
### Checking Workflow Status via GitHub API
AI assistants can directly monitor GitHub Actions workflows using the GitHub API.
This helps identify failures and diagnose issues:
```
github-api /repos/{owner}/{repo}/actions/runs
```
#### Step-by-Step Process
1. **Get Recent Workflow Runs**:
```
github-api /repos/wpallstars/wp-plugin-starter-template-for-ai-coding/actions/runs
```
2. **Filter for Failed Runs**:
```
github-api /repos/wpallstars/wp-plugin-starter-template-for-ai-coding/actions/runs?status=failure
```
3. **Get Details for a Specific Run**:
```
github-api /repos/wpallstars/wp-plugin-starter-template-for-ai-coding/actions/runs/{run_id}
```
4. **Get Jobs for a Workflow Run**:
```
github-api /repos/wpallstars/wp-plugin-starter-template-for-ai-coding/actions/runs/{run_id}/jobs
```
5. **Analyze Job Logs** (if accessible via API):
```
github-api /repos/wpallstars/wp-plugin-starter-template-for-ai-coding/actions/jobs/{job_id}/logs
```
### Common GitHub Actions Errors and Solutions
#### Missing or Outdated Action Versions
**Error**: `Missing download info for actions/upload-artifact@v3`
**Solution**: Update to the latest version of the action:
```yaml
uses: actions/upload-artifact@v4
```
#### Port Configuration Issues for WordPress Multisite
**Error**: `The current host is 127.0.0.1:8888, but WordPress multisites do not support custom ports.`
**Solution**: Use port 80 for multisite environments:
```yaml
npx @wp-playground/cli server --blueprint playground/multisite-blueprint.json --port 80 --login &
```
#### Artifact Path Syntax Issues
**Error**: Invalid path syntax for artifacts
**Solution**: Use multi-line format for better readability:
```yaml
path: |
cypress/videos
cypress/screenshots
```
#### Concurrency Control
**Problem**: Redundant workflow runs when multiple commits land quickly
**Solution**: Add concurrency control to cancel in-progress runs:
```yaml
concurrency:
group: playground-tests-${{ github.ref }}
cancel-in-progress: true
```
## Local Build and Test Feedback
### Monitoring Local Test Runs
AI assistants can monitor local test runs by analyzing the output of test commands.
#### PHP Unit Tests
```bash
composer run phpunit
```
#### Cypress Tests
```bash
npm run test:single
npm run test:multisite
```
#### WordPress Playground Tests
```bash
npm run test:playground:single
npm run test:playground:multisite
```
### Capturing and Analyzing Test Output
1. **Run Tests with Output Capture**:
```bash
npm run test:single > test-output.log 2>&1
```
2. **Analyze Output for Errors**:
```bash
cat test-output.log | grep -i 'error\|fail\|exception'
```
3. **Parse Structured Test Results** (if available):
```bash
cat cypress/results/results.json
```
### Common Local Test Errors and Solutions
#### WordPress Playground Port Issues
**Error**: `The current host is 127.0.0.1:8888, but WordPress multisites do not support custom ports.`
**Solution**: Modify the port in the blueprint or test configuration:
```json
{
"features": {
"networking": true
}
}
```
#### Cypress Selector Errors
**Error**: `Timed out retrying after 4000ms: expected '<body...>' to have class 'wp-admin'`
**Solution**: Update selectors to be more robust and handle login states:
```javascript
cy.get('body').then(($body) => {
if ($body.hasClass('login')) {
cy.get('#user_login').type('admin');
cy.get('#user_pass').type('password');
cy.get('#wp-submit').click();
}
});
// Check for admin bar instead of body class
cy.get('#wpadminbar').should('exist');
```
## Code Quality Tool Integration
### Automated Code Quality Checks
AI assistants can integrate with various code quality tools to identify and fix issues.
#### PHPCS (PHP CodeSniffer)
```bash
composer run phpcs
```
#### ESLint (JavaScript)
```bash
npm run lint:js
```
#### Stylelint (CSS)
```bash
npm run lint:css
```
### Parsing Code Quality Tool Output
1. **Run Code Quality Check**:
```bash
composer run phpcs > phpcs-output.log 2>&1
```
2. **Analyze Output for Errors**:
```bash
cat phpcs-output.log | grep -i 'ERROR\|WARNING'
```
3. **Automatically Fix Issues** (when possible):
```bash
composer run phpcbf
```
### Monitoring Code Quality Feedback in Pull Requests
Automated code quality tools often provide feedback directly in pull requests.
AI assistants can check these comments to identify and address issues.
#### Accessing PR Comments via GitHub API
```
github-api /repos/wpallstars/wp-plugin-starter-template-for-ai-coding/pulls/{pull_number}/comments
```
#### Accessing PR Review Comments
```
github-api /repos/wpallstars/wp-plugin-starter-template-for-ai-coding/pulls/{pull_number}/reviews
```
#### Checking CodeRabbit Feedback
CodeRabbit provides AI-powered code review comments via the GitHub API.
1. **Get PR Comments**:
```
github-api /repos/wpallstars/wp-plugin-starter-template-for-ai-coding/pulls/{pull_number}/comments
```
2. **Filter for CodeRabbit Comments**:
Look for comments from the `coderabbitai` user.
3. **Parse Actionable Feedback**:
* Code quality issues
* Suggested improvements
* Best practice recommendations
* Specific code snippets to fix
#### Checking Codacy and CodeFactor Feedback
These tools provide automated code quality checks and post results as PR comments.
1. **Check PR Status Checks**:
```
github-api /repos/wpallstars/wp-plugin-starter-template-for-ai-coding/commits/{sha}/check-runs
```
2. **Get Detailed Reports** (if available via API):
```
github-api /repos/wpallstars/wp-plugin-starter-template-for-ai-coding/commits/{sha}/check-runs/{id}
```
3. **Parse Common Issues**:
* Code style violations
* Potential bugs
* Security vulnerabilities
* Performance issues
* Duplication
#### Checking SonarCloud Analysis
SonarCloud provides detailed code quality and security analysis.
1. **Check SonarCloud Status**:
```
github-api /repos/wpallstars/wp-plugin-starter-template-for-ai-coding/commits/{sha}/check-runs?check_name=SonarCloud
```
2. **Parse SonarCloud Issues**:
* Code smells
* Bugs
* Vulnerabilities
* Security hotspots
* Coverage gaps
### Common Code Quality Issues and Solutions
#### WordPress Coding Standards
**Error**: `ERROR: Expected snake_case for function name, but found camelCase`
**Solution**: Rename functions to follow snake_case convention:
```php
// Before
function getPluginVersion() { ... }
// After
function get_plugin_version() { ... }
```
#### Missing Docblocks
**Error**: `ERROR: Missing doc comment for function`
**Solution**: Add proper docblocks:
```php
/**
* Get the plugin version.
*
* @since 1.0.0
* @return string The plugin version.
*/
function get_plugin_version() { ... }
```
## Automated Error Resolution
### Error Resolution Workflow
1. **Identify Error**: Use GitHub API or local test output to identify errors
2. **Categorize Error**: Determine error type and severity
3. **Search for Solution**: Look for patterns in known solutions
4. **Apply Fix**: Make necessary code changes
5. **Verify Fix**: Run tests again to confirm the issue is resolved
6. **Document Solution**: Update documentation with the solution
### Processing Code Quality Feedback
#### Extracting Actionable Items from PR Comments
1. **Collect All Feedback**:
```
github-api /repos/wpallstars/wp-plugin-starter-template-for-ai-coding/pulls/{number}/comments
github-api /repos/wpallstars/wp-plugin-starter-template-for-ai-coding/pulls/{number}/reviews
```
2. **Categorize Issues**:
* Critical: Security vulnerabilities, breaking bugs
* High: Code quality violations, potential bugs
* Medium: Style issues, best practices
* Low: Documentation, minor improvements
3. **Prioritize Fixes**:
* Address critical issues first
* Group related issues for efficient fixing
* Consider dependencies between issues
4. **Create Fix Plan**:
* Document files that need changes
* Outline specific changes needed
* Note any potential side effects
#### Responding to Code Quality Tool Comments
1. **Acknowledge Feedback**: React to or reply to comments
2. **Implement Fixes**: Make the necessary code changes
3. **Explain Changes** (if needed): Add comments explaining decisions
4. **Request Review** (if needed): Ask for re-review after fixes
## Feedback Loop Architecture
### Complete Feedback Loop System
```
Code Changes ──► Local Testing ──► GitHub Actions
│ │ │
▼ ▼ ▼
AI Assistant ◀── Error Analysis ◀── Status Check
│
▼
Fix Generation ──► Human Review (only when necessary)
```
### Key Components
1. **Code Changes**: Initial code modifications
2. **Local Testing**: Immediate feedback on local environment
3. **GitHub Actions**: Remote CI/CD pipeline validation
4. **Status Check**: Monitoring workflow status via GitHub API
5. **Error Analysis**: Parsing and categorizing errors
6. **AI Assistant**: Central intelligence for error resolution
7. **Fix Generation**: Creating and implementing solutions
8. **Human Review**: Optional step for complex decisions
## Handling Direct Feedback from Code Review Tools
### Accessing and Processing CodeRabbit Feedback
CodeRabbit provides detailed AI-powered code reviews.
These can be directly accessed and processed.
#### Example CodeRabbit Feedback
```
coderabbitai bot left a comment
Actionable comments posted: 1
🧹 Nitpick comments (3)
.github/workflows/playground-tests-fix.yml (3)
9-13: Add concurrency control to avoid redundant runs.
```
#### Processing Steps
1. **Extract Specific Recommendations**:
* Identify file paths and line numbers
* Parse suggested code changes
* Understand the rationale for changes
2. **Implement Recommendations**: Apply the suggested changes
3. **Verify Implementation**:
* Run local tests if applicable
* Commit changes with descriptive message
* Monitor CI/CD pipeline for success
### Handling SonarCloud and Codacy Feedback
These tools provide structured feedback that can be systematically addressed.
#### Example SonarCloud Feedback
```
SonarCloud Quality Gate failed
- 3 Bugs
- 5 Code Smells
- 1 Security Hotspot
```
#### Processing Steps
1. **Access Detailed Reports**:
* Use the SonarCloud API or web interface
* Categorize issues by severity and type
2. **Address Issues Systematically**:
* Fix bugs first
* Address security hotspots
* Resolve code smells
3. **Document Resolutions**:
* Note patterns of issues for future prevention
* Update coding guidelines if necessary
## When to Consult Humans
While the goal is to create an autonomous system, there are scenarios where human input is necessary.
### Scenarios Requiring Human Consultation
1. **Product Design Decisions**: Features, UX, and strategic direction
2. **Security-Critical Changes**: Changes that could impact security posture
3. **Architectural Decisions**: Major structural changes to the codebase
4. **Deployment Approvals**: Final approval for production releases
5. **Access Requirements**: When additional permissions are needed
6. **Ambiguous Errors**: When errors have multiple possible interpretations
7. **Novel Problems**: Issues without precedent or documented solutions
8. **External Service Issues**: Problems with third-party services
### Effective Human Consultation
When consulting humans, provide:
1. **Clear Context**: Explain what you were trying to accomplish
2. **Error Details**: Provide specific error messages and logs
3. **Attempted Solutions**: Document what you've already tried
4. **Specific Questions**: Ask targeted questions rather than open-ended ones
5. **Recommendations**: Suggest possible solutions for approval
## Contributing to External Repositories
When issues are caused by bugs or missing features in external dependencies or GitHub Actions,
AI assistants can contribute fixes upstream.
### Workflow for External Contributions
1. **Clone the Repository Locally**:
```bash
cd ~/Git
git clone https://github.com/owner/repo.git
cd repo
git checkout -b feature/descriptive-branch-name
```
2. **Make Changes and Commit**:
```bash
# Make your changes
git add -A
git commit -m "Descriptive commit message
Detailed explanation of what the change does and why.
Fixes #issue-number"
```
3. **Fork and Push**:
```bash
# Create a fork (if not already forked)
gh repo fork owner/repo --clone=false --remote=true
# Add fork as remote
git remote add fork https://github.com/your-username/repo.git
# Push to fork
git push fork feature/descriptive-branch-name
```
4. **Create Pull Request**:
```bash
gh pr create \
--repo owner/repo \
--head your-username:feature/descriptive-branch-name \
--title "Clear, descriptive title" \
--body "## Summary
Description of changes...
Fixes #issue-number"
```
### Best Practices for External Contributions
* Always clone to `~/Git/` for consistency
* Check existing issues and PRs before starting work
* Follow the project's contribution guidelines
* Keep changes focused and minimal
* Include tests if the project has a test suite
* Reference the issue number in commits and PR description
### Local Repository Management
Keep cloned repositories in `~/Git/` organized:
* `~/Git/wp-plugin-starter-template-for-ai-coding/` - Main project
* `~/Git/wp-performance-action/` - Forked for contributions
* Other cloned repos as needed
## Conclusion
This error checking and feedback loop system creates a comprehensive framework for AI-driven development.
By systematically monitoring, analyzing, and resolving errors, the AI assistant can maintain high code quality.
For related workflows, refer to the other documents in the `.agents/` directory.

331
.agents/local-testing-guide.md Normal file
View File

@@ -0,0 +1,331 @@
# Local Testing Guide for AI Assistants
This guide provides instructions for AI coding assistants to set up and run local
WordPress testing environments for this plugin.
## Overview
Three testing approaches are available:
1. **WordPress Playground CLI** - Quick browser-based testing (recommended for AI)
2. **LocalWP** - Full local WordPress environment
3. **wp-env** - Docker-based WordPress environment
Each approach has trade-offs. Choose based on the testing needs.
## Quick Reference
```bash
# Playground CLI (fastest for AI testing)
npm run playground:start # Start single site
npm run playground:start:multisite # Start multisite
npm run playground:stop # Stop server
npm run playground:status # Check status
# LocalWP (full environment)
npm run localwp:create # Create single site
npm run localwp:create:multisite # Create multisite
npm run localwp:sync # Sync plugin changes
npm run localwp:reset # Reset to clean state
# wp-env (Docker-based)
npm run start # Start wp-env
npm run stop # Stop wp-env
```
## WordPress Playground CLI
Uses `@wp-playground/cli` version 3.0.22+ for instant WordPress testing.
### When to Use
* Quick plugin functionality testing
* Verifying admin UI changes
* Testing single site vs multisite behavior
* CI/CD pipeline testing (note: may be flaky in GitHub Actions)
### Starting Playground
```bash
# Single site on port 8888
npm run playground:start
# Multisite on port 8889
npm run playground:start:multisite
```
### Accessing the Site
After starting, the script provides access details:
* **Single Site**: http://localhost:8888
* **Multisite**: http://localhost:8889
* **Admin Login**: admin / password
### Blueprint Configuration
Blueprints define the WordPress setup. Located in `playground/`:
* `blueprint.json` - Single site configuration
* `multisite-blueprint.json` - Multisite configuration
Blueprints install:
* Plugin Toggle (debugging helper)
* Kadence Blocks (testing with block plugins)
### Stopping Playground
```bash
npm run playground:stop
```
### Status Check
```bash
npm run playground:status
```
Shows running processes and port usage.
### Troubleshooting
If Playground fails to start:
1. Check if ports 8888/8889 are in use: `lsof -i :8888`
2. Check logs: `cat .playground.log`
3. Stop any orphaned processes: `npm run playground:stop`
4. Ensure npm dependencies are installed: `npm install`
## LocalWP Integration
LocalWP provides a full WordPress environment with database persistence.
### Prerequisites
* LocalWP installed at `/Applications/Local.app` (macOS)
* Local Sites directory at `~/Local Sites/`
### When to Use
* Testing database migrations
* Long-term development environment
* Testing with specific PHP/MySQL versions
* Network/multisite configuration testing
* Testing WP-CLI commands
### Creating Sites
LocalWP requires manual site creation through the GUI.
```bash
npm run localwp:create
```
This guides you through:
1. Opening LocalWP
2. Creating a site with standardized name
3. Syncing plugin files
### URL Patterns
Sites use consistent naming:
* **Single Site**: `wp-plugin-starter-template-single.local`
* **Multisite**: `wp-plugin-starter-template-multisite.local`
### Syncing Plugin Files
After making code changes:
```bash
npm run localwp:sync
```
This uses rsync to copy plugin files, excluding:
* node_modules
* vendor
* tests
* .git
* dist
### Resetting
To reset the plugin to a clean state:
```bash
npm run localwp:reset
```
### Site Information
View all LocalWP sites:
```bash
./bin/localwp-setup.sh info
```
## wp-env (Docker)
Docker-based environment using `@wordpress/env`.
### When to Use
* Consistent environment across machines
* PHPUnit testing
* WP-CLI operations
* CI/CD testing
### Starting
```bash
npm run start # or: wp-env start
```
### Running Tests
```bash
npm run test:phpunit # Single site tests
npm run test:phpunit:multisite # Multisite tests
```
### Running WP-CLI Commands
```bash
wp-env run cli wp plugin list
wp-env run cli wp option get siteurl
```
## Testing Workflows for AI Assistants
### Verifying a Code Change
1. Make the code change
2. Start Playground: `npm run playground:start`
3. Navigate to relevant admin page
4. Verify expected behavior
5. Stop Playground: `npm run playground:stop`
### Testing Multisite Functionality
1. Start multisite: `npm run playground:start:multisite`
2. Navigate to Network Admin
3. Test network-wide functionality
4. Test per-site functionality
5. Stop: `npm run playground:stop`
### Running PHPUnit Tests
```bash
# Single site
composer test
# Multisite
WP_MULTISITE=1 composer test
# Specific test file
vendor/bin/phpunit tests/phpunit/test-core.php
```
### Running Cypress E2E Tests
```bash
# With Playground (headless)
npm run test:playground:single
npm run test:playground:multisite
# With wp-env (headless)
npm run test:e2e:single
npm run test:e2e:multisite
```
## Environment Comparison
| Feature | Playground CLI | LocalWP | wp-env |
|---------|---------------|---------|--------|
| Setup Time | Instant | 5-10 min | 2-5 min |
| Persistence | None | Full | Partial |
| PHP Versions | Limited | Many | Limited |
| Database | In-memory | MySQL | MySQL |
| WP-CLI | Yes | Yes | Yes |
| Multisite | Yes | Yes | Yes |
| GitHub Actions | Flaky | N/A | Works |
| Best For | Quick testing | Full dev | CI/Testing |
## Common Issues
### Port Already in Use
```bash
# Check what's using the port
lsof -i :8888
# Kill the process if needed
kill $(lsof -t -i :8888)
```
### Playground Won't Start
1. Ensure dependencies installed: `npm install`
2. Check Node.js version: `node --version` (requires 18+)
3. Check logs: `cat .playground.log`
### LocalWP Site Not Found
The script expects sites at:
* `~/Local Sites/wp-plugin-starter-template-single/`
* `~/Local Sites/wp-plugin-starter-template-multisite/`
Verify the site name matches exactly.
### wp-env Docker Issues
```bash
# Restart Docker
wp-env stop
docker system prune -f
wp-env start
```
## Blueprint Reference
Blueprints use JSON format. Key steps:
```json
{
"$schema": "https://playground.wordpress.net/blueprint-schema.json",
"landingPage": "/wp-admin/",
"login": true,
"features": {
"networking": true,
"phpVersion": "7.4"
},
"steps": [
{
"step": "defineWpConfigConsts",
"consts": {
"WP_DEBUG": true
}
},
{
"step": "wp-cli",
"command": "wp plugin install plugin-toggle --activate"
}
]
}
```
For multisite, add:
```json
{
"step": "enableMultisite"
}
```
## Resources
* [WordPress Playground CLI](https://wordpress.github.io/wordpress-playground/)
* [WordPress Playground Blueprints](https://wordpress.github.io/wordpress-playground/blueprints)
* [LocalWP Documentation](https://localwp.com/help-docs/)
* [@wordpress/env Documentation](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-env/)

37
.eslintrc.js Normal file
View File

@@ -0,0 +1,37 @@
module.exports = {
env: {
browser: true,
es2021: true,
node: true,
'cypress/globals': true
},
extends: [
'eslint:recommended'
],
plugins: [
'cypress'
],
parserOptions: {
ecmaVersion: 'latest',
sourceType: 'module'
},
rules: {
'no-console': 'warn',
'no-unused-vars': 'warn'
},
globals: {
cy: 'readonly',
Cypress: 'readonly',
describe: 'readonly',
it: 'readonly',
expect: 'readonly',
beforeEach: 'readonly',
afterEach: 'readonly',
before: 'readonly',
after: 'readonly',
jQuery: 'readonly',
wpstData: 'readonly',
wpstModalData: 'readonly',
wp: 'readonly'
}
};

1
.eslintrc.json
View File

@@ -14,6 +14,7 @@
"describe": "readonly",
"it": "readonly",
"before": "readonly",
"beforeEach": "readonly",
"module": "readonly"
},
"parserOptions": {

14
.github/actions/create-plugin-zip/action.yml vendored Normal file
View File

@@ -0,0 +1,14 @@
name: 'Create Plugin Zip'
description: 'Creates a zip file of the WordPress plugin, excluding unnecessary files'
runs:
using: 'composite'
steps:
- name: Create plugin zip
shell: bash
run: |
mkdir -p dist
echo "Creating plugin zip file..."
zip -r dist/plugin.zip . \
-x "node_modules/**" "dist/**" ".git/**" ".github/**" ".wiki/**" "cypress/**" "playground/**" "tests/**" "vendor/**"
echo "Plugin zip created at dist/plugin.zip"
ls -la dist/

72
.github/instructions/codacy.instructions.md vendored Normal file
View File

@@ -0,0 +1,72 @@
---
description: Configuration for AI behavior when interacting with Codacy's MCP Server
applyTo: '**'
---
---
# Codacy Rules
Configuration for AI behavior when interacting with Codacy's MCP Server
## CRITICAL: After ANY successful `edit_file` or `reapply` operation
- YOU MUST IMMEDIATELY run the `codacy_cli_analyze` tool from Codacy's MCP Server for each file that was edited, with:
- `rootPath`: set to the workspace path
- `file`: set to the path of the edited file
- `tool`: leave empty or unset
- If any issues are found in the new edits, propose and apply fixes for them.
- > NOTE: Failure to follow this rule is considered a critical error.
## When you tried to run the `codacy_cli_analyze` tool and the Codacy CLI is not installed
- Ask the user 'Codacy CLI is not installed. Would you like me to install it now?'
- If the user responds with "yes", run the `codacy_cli_install` tool and then continue with the original task
- If the user responds with "no", instruct the user that they can disable automatic analysis in the extension settings
- Wait for the user to respond before proceeding with any other actions
## After every response
- If you made any file edits in this conversation, verify you ran `codacy_cli_analyze` tool from Codacy's MCP Server
## When there are no Codacy MCP Server tools available, or the MCP Server is not reachable
- Suggest the user the following troubleshooting steps:
- Try to reset the MCP on the extension
- If the user is using VSCode, suggest them to review their Copilot > MCP settings in Github, under their organization or personal account. Refer them to Settings > Copilot > Enable MCP servers in Copilot. Suggested URL (https://github.com/settings/copilot/features) or https://github.com/organizations/{organization-name}/settings/copilot/features (This can only be done by their organization admins / owners)
- If none of the above steps work, suggest the user to contact Codacy support
## Trying to call a tool that needs a rootPath as a parameter
- Always use the standard, non-URL-encoded file system path
## CRITICAL: Dependencies and Security Checks
- IMMEDIATELY after ANY of these actions:
- Running npm/yarn/pnpm install
- Adding dependencies to package.json
- Adding requirements to requirements.txt
- Adding dependencies to pom.xml
- Adding dependencies to build.gradle
- Any other package manager operations
- You MUST run the `codacy_cli_analyze` tool with:
- `rootPath`: set to the workspace path
- `tool`: set to "trivy"
- `file`: leave empty or unset
- If any vulnerabilities are found because of the newly added packages:
- Stop all other operations
- Propose and apply fixes for the security issues
- Only continue with the original task after security issues are resolved
- EXAMPLE:
- After: npm install react-markdown
- Do: Run codacy_cli_analyze with trivy
- Before: Continuing with any other tasks
## General
- Repeat the relevant steps for each modified file.
- "Propose fixes" means to both suggest and, if possible, automatically apply the fixes.
- You MUST NOT wait for the user to ask for analysis or remind you to run the tool.
- Do not run `codacy_cli_analyze` looking for changes in duplicated code or code complexity metrics.
- Complexity metrics are different from complexity issues. When trying to fix complexity in a repository or file, focus on solving the complexity issues and ignore the complexity metric.
- Do not run `codacy_cli_analyze` looking for changes in code coverage.
- Do not try to manually install Codacy CLI using either brew, npm, npx, or any other package manager.
- If the Codacy CLI is not installed, just run the `codacy_cli_analyze` tool from Codacy's MCP Server.
- When calling `codacy_cli_analyze`, only send provider, organization and repository if the project is a git repository.
## Whenever a call to a Codacy tool that uses `repository` or `organization` as a parameter returns a 404 error
- Offer to run the `codacy_setup_repository` tool to add the repository to Codacy
- If the user accepts, run the `codacy_setup_repository` tool
- Do not ever try to run the `codacy_setup_repository` tool on your own
- After setup, immediately retry the action that failed (only retry once)
---

109
.github/workflows/code-quality.yml vendored
View File

@@ -1,10 +1,13 @@
name: Code Quality
on:
# Only run on push to main (not feature branches) to avoid duplicate runs.
# Feature branches get CI via pull_request trigger.
push:
branches: [ main ]
pull_request:
branches: [ main ]
workflow_dispatch:
jobs:
phpcs:
@@ -12,7 +15,7 @@ jobs:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
with:
clean: 'true'
@@ -46,7 +49,7 @@ jobs:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
- name: Setup PHP
uses: shivammathur/setup-php@v2
@@ -70,7 +73,7 @@ jobs:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
- name: Setup PHP
uses: shivammathur/setup-php@v2
@@ -86,53 +89,78 @@ jobs:
run: composer phpmd
continue-on-error: true
sonarcloud:
name: SonarCloud Analysis
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Set up JDK 17
uses: actions/setup-java@v3
with:
java-version: 17
distribution: 'temurin'
- name: Cache SonarCloud packages
uses: actions/cache@v3
with:
path: ~/.sonar/cache
key: ${{ runner.os }}-sonar
restore-keys: ${{ runner.os }}-sonar
- name: SonarCloud Scan
uses: SonarSource/sonarqube-scan-action@master
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
with:
args: >
-Dsonar.projectKey=wpallstars_wp-plugin-starter-template-for-ai-coding
-Dsonar.organization=wpallstars
-Dsonar.sources=.
-Dsonar.exclusions=vendor/**,node_modules/**,tests/**,bin/**,build/**,dist/**
-Dsonar.sourceEncoding=UTF-8
continue-on-error: true
# NOTE: SonarCloud job is disabled because SONAR_TOKEN is not properly configured.
# To enable, configure a valid SONAR_TOKEN secret and uncomment this job.
# Generate a token at: https://sonarcloud.io/account/security
#
# sonarcloud:
# name: SonarCloud Analysis
# runs-on: ubuntu-latest
# steps:
# - name: Checkout code
# uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
# with:
# fetch-depth: 0
#
# - name: Set up JDK 17
# uses: actions/setup-java@v4
# with:
# java-version: 17
# distribution: 'temurin'
#
# - name: Cache SonarCloud packages
# uses: actions/cache@v4
# with:
# path: ~/.sonar/cache
# key: ${{ runner.os }}-sonar
# restore-keys: ${{ runner.os }}-sonar
#
# - name: Check if SonarCloud token is set
# id: check_sonar_token
# run: |
# if [ -z "${{ secrets.SONAR_TOKEN }}" ]; then
# echo "SONAR_TOKEN is not set, skipping SonarCloud analysis"
# echo "skip=true" >> $GITHUB_OUTPUT
# else
# echo "skip=false" >> $GITHUB_OUTPUT
# fi
#
# - name: SonarCloud Scan
# if: steps.check_sonar_token.outputs.skip != 'true'
# uses: SonarSource/sonarqube-scan-action@master
# env:
# GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
# SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
# with:
# args: >
# -Dsonar.projectKey=wpallstars_wp-plugin-starter-template-for-ai-coding
# -Dsonar.organization=wpallstars
# -Dsonar.sources=.
# -Dsonar.exclusions=vendor/**,node_modules/**,tests/**,bin/**,build/**,dist/**,.github/**,.git/**,cypress/**,playground/**,.wiki/**
# -Dsonar.sourceEncoding=UTF-8
# continue-on-error: true
codacy:
name: Codacy Analysis
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
with:
fetch-depth: 0
- name: Check if Codacy token is set
id: check_codacy_token
run: |
if [ -z "${{ secrets.CODACY_PROJECT_TOKEN }}" ]; then
echo "CODACY_PROJECT_TOKEN is not set, running Codacy without upload"
echo "skip_upload=true" >> $GITHUB_OUTPUT
else
echo "skip_upload=false" >> $GITHUB_OUTPUT
fi
- name: Run Codacy Analysis CLI
uses: codacy/codacy-analysis-cli-action@v4.3.0
uses: codacy/codacy-analysis-cli-action@v4
with:
project-token: ${{ secrets.CODACY_PROJECT_TOKEN }}
verbose: true
@@ -146,6 +174,7 @@ jobs:
continue-on-error: true
- name: Upload SARIF results file
if: steps.check_codacy_token.outputs.skip_upload != 'true'
uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: results.sarif

70
.github/workflows/phpunit.yml vendored Normal file
View File

@@ -0,0 +1,70 @@
name: PHPUnit Tests
on:
# Only run on push to main (not feature branches) to avoid duplicate runs.
# Feature branches get CI via pull_request trigger.
push:
branches: [ main ]
pull_request:
branches: [ main ]
workflow_dispatch:
permissions:
contents: read
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
jobs:
test:
name: PHP ${{ matrix.php }} - WP ${{ matrix.wp }} - ${{ matrix.multisite && 'Multisite' || 'Single Site' }}
runs-on: ubuntu-latest
strategy:
matrix:
php: [ '7.4', '8.0' ]
wp: [ 'latest' ]
multisite: [ false, true ]
services:
mysql:
image: mysql:5.7
env:
MYSQL_ROOT_PASSWORD: root
MYSQL_DATABASE: wordpress_test
ports:
- 3306:3306
options: --health-cmd="mysqladmin ping" --health-interval=10s --health-timeout=5s --health-retries=3
steps:
- name: Checkout code
uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
- name: Setup PHP
uses: shivammathur/setup-php@v2
with:
php-version: ${{ matrix.php }}
extensions: dom, curl, libxml, mbstring, zip, pdo, mysql, pdo_mysql, bcmath, soap, intl, gd, exif, iconv
coverage: none
- name: Install Composer dependencies
uses: ramsey/composer-install@83af392bf5f031813d25e6fe4cd626cdba9a2df6 # v2.2.0
- name: Install WordPress test suite
run: |
set -e
echo "Installing WordPress test suite with multisite=${{ matrix.multisite }}"
bash bin/install-wp-tests.sh wordpress_test root root 127.0.0.1 ${{ matrix.wp }} false ${{ matrix.multisite && 'true' || 'false' }}
echo "WordPress test suite installed successfully"
- name: Run PHPUnit tests
env:
WP_PHPUNIT__DIR: /tmp/wordpress-tests-lib
WP_TESTS_DIR: /tmp/wordpress-tests-lib
run: |
if [ "${{ matrix.multisite }}" = "true" ]; then
WP_MULTISITE=1 composer test
else
composer test
fi

106
.github/workflows/playground-tests-fix.yml vendored Normal file
View File

@@ -0,0 +1,106 @@
name: WordPress Playground Tests Fix
# DISABLED: WordPress Playground CLI doesn't work reliably in GitHub Actions CI environments
# The server fails to start within timeout periods. These tests should be run locally instead.
on:
# Disable automatic triggers - only run manually if needed for debugging
workflow_dispatch:
inputs:
debug:
description: 'Enable debug mode'
required: false
default: 'false'
# Commented out triggers that cause CI noise:
# push:
# branches: [ main, feature/* ]
# pull_request:
# branches: [ main ]
permissions:
contents: read
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
jobs:
playground-test:
name: WordPress Playground Tests
runs-on: ubuntu-latest
# Allow failures since WordPress Playground CLI can be unreliable in CI environments
continue-on-error: true
steps:
- uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
- name: Install dependencies
run: npm install --legacy-peer-deps
- name: Add WordPress Playground CLI to dependencies
run: |
echo "Installing WordPress Playground CLI..."
npm install --save-dev @wp-playground/cli @wp-playground/blueprints @wp-playground/client
echo "WordPress Playground CLI installed"
npx @wp-playground/cli --version
- name: Create plugin zip
uses: ./.github/actions/create-plugin-zip
- name: Run tests with WordPress Playground
run: |
# Set base URL for Cypress
export CYPRESS_BASE_URL=http://localhost:8888
# Check if blueprint file exists
echo "Checking blueprint file..."
ls -la playground/
cat playground/blueprint.json
# Start WordPress Playground with our blueprint
echo "Starting WordPress Playground server..."
npx @wp-playground/cli server --blueprint playground/blueprint.json --port 8888 --login &
SERVER_PID=$!
# Wait for WordPress Playground to be ready (increased timeout to 180s)
echo "Waiting for WordPress Playground to be ready..."
TIMEOUT=180
ELAPSED=0
while ! curl -s http://localhost:8888 > /dev/null 2>&1; do
if [ $ELAPSED -ge $TIMEOUT ]; then
echo "Timeout waiting for WordPress Playground to start"
kill $SERVER_PID || true
exit 1
fi
echo "Waiting... ($ELAPSED/$TIMEOUT seconds)"
sleep 5
ELAPSED=$((ELAPSED + 5))
done
echo "WordPress Playground is ready after $ELAPSED seconds"
# Run Cypress tests against WordPress Playground
echo "Running Cypress tests..."
npx cypress run --spec "cypress/e2e/playground-single-site.cy.js"
TEST_EXIT_CODE=$?
# Kill the server process
kill $SERVER_PID || true
# Return the test exit code
exit $TEST_EXIT_CODE
- name: Upload Cypress artifacts
if: always()
uses: actions/upload-artifact@v4
with:
name: cypress-playground-results
path: |
cypress/videos
cypress/screenshots

276
.github/workflows/playground-tests.yml vendored Normal file
View File

@@ -0,0 +1,276 @@
name: WordPress Playground Tests
# Re-enabled with @wp-playground/cli v3.0.22 which has improved CI stability.
# Tests use continue-on-error: true so they won't block PRs if flaky.
#
# To run locally:
# npm run playground:start
# npm run playground:start:multisite
on:
# Only run on push to main (not feature branches) to avoid duplicate runs.
# Feature branches get CI via pull_request trigger.
push:
branches: [ main ]
pull_request:
branches: [ main ]
workflow_dispatch:
inputs:
debug:
description: 'Enable debug mode'
required: false
default: 'false'
permissions:
contents: read
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
jobs:
code-quality:
name: Code Quality Check
runs-on: ubuntu-latest
strategy:
matrix:
node-version: [20]
steps:
- uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node-version }}
cache: 'npm'
- name: Install dependencies
run: npm install --legacy-peer-deps
- name: Verify package.json and package-lock.json
run: |
echo "Verifying package.json and package-lock.json are in sync"
npm install --dry-run --legacy-peer-deps
- name: Lint JavaScript files
run: npm run lint:js
playground-single-test:
name: WordPress Playground Single Site Tests
runs-on: ubuntu-latest
needs: code-quality
# Allow failures since WordPress Playground CLI can be unreliable in CI environments
continue-on-error: true
steps:
- uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
- name: Install dependencies
run: npm install --legacy-peer-deps
- name: Verify WordPress Playground CLI
run: |
echo "WordPress Playground CLI version:"
npx @wp-playground/cli --version
- name: Create plugin zip
uses: ./.github/actions/create-plugin-zip
- name: Run tests with WordPress Playground
run: |
# Set base URL for Cypress
export CYPRESS_BASE_URL=http://127.0.0.1:8888
# Check if blueprint file exists
echo "Checking blueprint file..."
ls -la playground/
cat playground/blueprint.json
# Start WordPress Playground with our blueprint (using @wp-playground/cli 3.x)
echo "Starting WordPress Playground server..."
npx @wp-playground/cli server \
--blueprint playground/blueprint.json \
--port 8888 \
--login \
--php 8.0 \
--verbosity normal \
2>&1 | tee playground-server.log &
SERVER_PID=$!
# Wait for WordPress Playground to be ready
echo "Waiting for WordPress Playground to be ready..."
TIMEOUT=120
ELAPSED=0
while ! curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:8888 2>/dev/null | grep -q "200\|302"; do
if [ $ELAPSED -ge $TIMEOUT ]; then
echo "Timeout waiting for WordPress Playground to start"
echo "=== Server log ==="
cat playground-server.log || true
kill $SERVER_PID 2>/dev/null || true
exit 1
fi
# Check if server process is still running
if ! kill -0 $SERVER_PID 2>/dev/null; then
echo "Server process died unexpectedly"
echo "=== Server log ==="
cat playground-server.log || true
exit 1
fi
echo "Waiting... ($ELAPSED/$TIMEOUT seconds)"
sleep 5
ELAPSED=$((ELAPSED + 5))
done
echo "WordPress Playground is ready after $ELAPSED seconds"
# Run Cypress tests against WordPress Playground
echo "Running Cypress tests..."
npx cypress run --spec "cypress/e2e/playground-single-site.cy.js"
TEST_EXIT_CODE=$?
# Kill the server process
kill $SERVER_PID 2>/dev/null || true
# Return the test exit code
exit $TEST_EXIT_CODE
- name: Upload Cypress artifacts
if: always()
uses: actions/upload-artifact@v4
with:
name: cypress-single-site-results
path: |
cypress/videos
cypress/screenshots
playground-multisite-test:
name: WordPress Playground Multisite Tests
runs-on: ubuntu-latest
needs: [code-quality, playground-single-test]
# DISABLED: WordPress Multisite does not support custom ports (requires port 80/443).
# This is a fundamental WordPress limitation. Multisite tests can only run locally
# where port 80 can be used. See: https://developer.wordpress.org/advanced-administration/multisite/
if: false
continue-on-error: true
steps:
- uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
- name: Install dependencies
run: npm install --legacy-peer-deps
- name: Verify WordPress Playground CLI
run: |
echo "WordPress Playground CLI version:"
npx @wp-playground/cli --version
- name: Create plugin zip
uses: ./.github/actions/create-plugin-zip
- name: Run tests with WordPress Playground
run: |
# Set base URL for Cypress
export CYPRESS_BASE_URL=http://127.0.0.1:8889
# Check if blueprint file exists
echo "Checking multisite blueprint file..."
ls -la playground/
cat playground/multisite-blueprint.json
# Start WordPress Playground with our blueprint (using @wp-playground/cli 3.x)
# Use a different port for multisite to avoid conflicts with single site tests
echo "Starting WordPress Playground server for multisite..."
npx @wp-playground/cli server \
--blueprint playground/multisite-blueprint.json \
--port 8889 \
--login \
--php 8.0 \
--verbosity normal \
2>&1 | tee playground-server.log &
SERVER_PID=$!
# Wait for WordPress Playground to be ready
echo "Waiting for WordPress Playground to be ready..."
TIMEOUT=120
ELAPSED=0
while ! curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:8889 2>/dev/null | grep -q "200\|302"; do
if [ $ELAPSED -ge $TIMEOUT ]; then
echo "Timeout waiting for WordPress Playground to start"
echo "=== Server log ==="
cat playground-server.log || true
kill $SERVER_PID 2>/dev/null || true
exit 1
fi
# Check if server process is still running
if ! kill -0 $SERVER_PID 2>/dev/null; then
echo "Server process died unexpectedly"
echo "=== Server log ==="
cat playground-server.log || true
exit 1
fi
echo "Waiting... ($ELAPSED/$TIMEOUT seconds)"
sleep 5
ELAPSED=$((ELAPSED + 5))
done
echo "WordPress Playground is ready after $ELAPSED seconds"
# Run Cypress tests against WordPress Playground
echo "Running Cypress multisite tests..."
npx cypress run --spec "cypress/e2e/playground-multisite.cy.js"
TEST_EXIT_CODE=$?
# Kill the server process
kill $SERVER_PID 2>/dev/null || true
# Return the test exit code
exit $TEST_EXIT_CODE
- name: Upload Cypress artifacts
if: always()
uses: actions/upload-artifact@v4
with:
name: cypress-multisite-results
path: |
cypress/videos
cypress/screenshots
performance-test:
name: WordPress Performance Tests
runs-on: ubuntu-latest
needs: code-quality
# DISABLED: Performance tests are flaky in CI due to Lighthouse/Playwright resource constraints.
# The wp-performance-action uses WordPress Playground internally and Lighthouse for metrics,
# which requires significant resources and is not reliable in shared CI runners.
# Run performance tests locally or on dedicated infrastructure for accurate results.
if: false
continue-on-error: true
steps:
- uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
- name: WordPress Performance Tests
uses: swissspidy/wp-performance-action@v2.0.3
with:
plugins: |
./
urls: |
/
/wp-admin/
# Don't pass blueprint - let the action use its own internal setup.
# Our blueprint includes features that may conflict with the action's Lighthouse setup.
wp-version: 'latest'
php-version: '8.0'
iterations: 5
repetitions: 1

66
.github/workflows/sonarcloud.yml vendored Normal file
View File

@@ -0,0 +1,66 @@
name: SonarCloud Analysis
# DISABLED: Using SonarCloud Automatic Analysis instead of CI-based analysis.
# Custom Quality Gates require a paid plan, which isn't suitable for FOSS projects.
# The free Automatic Analysis provides code quality feedback without coverage requirements.
#
# To re-enable CI-based analysis:
# 1. Uncomment the triggers below
# 2. Disable Automatic Analysis on SonarCloud.io
# 3. Consider upgrading to a paid plan for custom Quality Gate settings
on:
# Disabled - using Automatic Analysis instead
# push:
# branches: [ main, feature/* ]
# pull_request:
# branches: [ main ]
# types: [opened, synchronize, reopened]
workflow_dispatch: # Keep manual trigger for testing
permissions:
contents: read
pull-requests: read
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
jobs:
sonarcloud:
name: SonarCloud
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
with:
fetch-depth: 0 # Shallow clones should be disabled for a better relevancy of analysis
- name: Check if SonarCloud token is set
id: check_token
run: |
if [ -z "${{ secrets.SONARCLOUD_GITHUB }}" ]; then
echo "SONARCLOUD_GITHUB is not set, skipping SonarCloud analysis"
echo "skip=true" >> $GITHUB_OUTPUT
else
echo "skip=false" >> $GITHUB_OUTPUT
fi
- name: SonarCloud Scan
if: steps.check_token.outputs.skip != 'true'
uses: SonarSource/sonarqube-scan-action@master
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
SONAR_TOKEN: ${{ secrets.SONARCLOUD_GITHUB }}
with:
args: >
-Dsonar.projectKey=wpallstars_wp-plugin-starter-template-for-ai-coding
-Dsonar.organization=wpallstars
-Dsonar.sources=.
-Dsonar.tests=tests
-Dsonar.sourceEncoding=UTF-8
-Dsonar.cpd.exclusions=tests/**
-Dsonar.exclusions=vendor/**,node_modules/**,tests/**,bin/**,build/**,dist/**,.github/**,.git/**,cypress/**,playground/**,.wiki/**
-Dsonar.php.coverage.reportPaths=coverage.xml
-Dsonar.php.tests.reportPath=test-report.xml

132
.github/workflows/wordpress-tests.yml vendored Normal file
View File

@@ -0,0 +1,132 @@
name: WordPress Tests
# DISABLED: WordPress Playground CLI doesn't work reliably in GitHub Actions CI environments
# The server fails to start within timeout periods. These tests should be run locally instead.
on:
# Disable automatic triggers - only run manually if needed for debugging
workflow_dispatch:
inputs:
debug:
description: 'Enable debug mode'
required: false
default: 'false'
# Commented out triggers that cause CI noise:
# push:
# branches: [ main, feature/* ]
# pull_request:
# branches: [ main ]
permissions:
contents: read
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
jobs:
code-quality:
name: Code Quality Check
runs-on: ubuntu-latest
strategy:
matrix:
node-version: [20]
steps:
- uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node-version }}
cache: 'npm'
- name: Install dependencies
run: npm install --legacy-peer-deps
- name: Verify package.json and package-lock.json
run: |
echo "Verifying package.json and package-lock.json are in sync"
npm install --dry-run --legacy-peer-deps
- name: Lint JavaScript files
run: npm run lint:js
# Note about e2e tests
- name: Note about e2e tests
run: |
echo "Note: We now use WordPress Playground for e2e tests instead of Docker."
echo "Please run tests locally before submitting PRs using:"
echo "npm run test:playground:single"
echo "npm run test:playground:multisite"
echo "Or use the online WordPress Playground links in the documentation."
# Use WordPress Playground for e2e tests
e2e-test:
name: WordPress Playground Tests
runs-on: ubuntu-latest
needs: code-quality
# Allow failures since WordPress Playground CLI can be unreliable in CI environments
continue-on-error: true
steps:
- uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
- name: Install dependencies
run: npm install --legacy-peer-deps
- name: Install WordPress Playground CLI
run: npm install --save-dev @wp-playground/cli
- name: Create plugin zip
uses: ./.github/actions/create-plugin-zip
- name: Run tests with WordPress Playground
run: |
# Set base URL for Cypress
export CYPRESS_BASE_URL=http://localhost:8888
# Start WordPress Playground with our blueprint
npx @wp-playground/cli server --blueprint playground/blueprint.json --port 8888 --login &
SERVER_PID=$!
# Wait for WordPress Playground to be ready (increased timeout to 180s)
echo "Waiting for WordPress Playground to be ready..."
TIMEOUT=180
ELAPSED=0
while ! curl -s http://localhost:8888 > /dev/null 2>&1; do
if [ $ELAPSED -ge $TIMEOUT ]; then
echo "Timeout waiting for WordPress Playground to start"
kill $SERVER_PID || true
exit 1
fi
echo "Waiting... ($ELAPSED/$TIMEOUT seconds)"
sleep 5
ELAPSED=$((ELAPSED + 5))
done
echo "WordPress Playground is ready after $ELAPSED seconds"
# Run tests against WordPress Playground
npx cypress run --spec "cypress/e2e/playground-single-site.cy.js"
TEST_EXIT_CODE=$?
# Kill the server process
kill $SERVER_PID || true
# Return the test exit code
exit $TEST_EXIT_CODE
- name: Upload Cypress artifacts
if: always()
uses: actions/upload-artifact@v4
with:
name: cypress-results
path: |
cypress/videos
cypress/screenshots

23
.markdownlint.json
View File

@@ -1,16 +1,15 @@
{
"default": true,
"MD004": {
"style": "asterisk"
"MD012": false,
"MD022": false,
"MD031": false,
"MD032": false,
"MD013": {
"line_length": 120,
"code_blocks": false
},
"MD007": {
"indent": 2
"MD024": {
"siblings_only": true
},
"MD013": false,
"MD033": false,
"MD040": true,
"MD041": false,
"MD046": {
"style": "fenced"
}
"MD040": false,
"MD041": false
}

14
.qoder/settings.json Normal file
View File

@@ -0,0 +1,14 @@
{
"permissions": {
"ask": [
"Read(!./**)",
"Edit(!./**)"
],
"allow": [
"Read(./**)",
"Edit(./**)"
]
},
"memoryImport": {},
"monitoring": {}
}

39
.wiki/Architecture-Overview.md
View File

@@ -18,15 +18,22 @@ wp-plugin-starter-template/
│ └── images/ # Images used by the plugin
├── includes/ # Core plugin functionality
│ ├── core.php # Core functionality class
│ └── plugin.php # Main plugin class
│ ├── plugin.php # Main plugin class
│ └── Multisite/ # Multisite-specific functionality
├── languages/ # Translation files
├── tests/ # Test files
│ ├── e2e/ # End-to-end tests
│ └── unit/ # Unit tests
├── cypress/ # Cypress testing files
│ └── e2e/ # End-to-end test specifications
├── bin/ # Utility scripts
│ └── setup-test-env.sh # Test environment setup script
├── .github/ # GitHub-specific files
│ └── workflows/ # GitHub Actions workflows
├── .agents/ # AI workflow documentation
├── .agents/ # AI workflow documentation
├── .wiki/ # Wiki documentation
│ ├── Testing-Framework.md # Testing framework documentation
│ └── Multisite-Development.md # Multisite development guide
└── wp-plugin-starter-template.php # Main plugin file
```
@@ -38,8 +45,9 @@ The `wp-plugin-starter-template.php` file serves as the entry point for WordPres
1. Defines plugin metadata
2. Prevents direct access
3. Loads the main plugin class
4. Initializes the plugin
3. Defines plugin constants
4. Loads the main plugin class
5. Initializes the plugin
### Plugin Class
@@ -67,6 +75,16 @@ The `Admin` class in `admin/lib/admin.php` handles all admin-specific functional
3. Enqueues admin assets
4. Processes admin form submissions
### Multisite Support
The `Multisite` class in `includes/Multisite/class-multisite.php` provides a foundation for multisite functionality.
It:
1. Serves as a placeholder for multisite features
2. Can be extended for custom multisite functionality
3. Provides examples of multisite-specific methods
## Object-Oriented Approach
The plugin follows object-oriented programming principles:
@@ -105,7 +123,18 @@ The plugin includes a comprehensive testing framework:
1. **Unit Tests**: For testing individual components
2. **End-to-End Tests**: For testing the plugin as a whole
3. **WordPress Environment**: Using wp-env for local testing
4. **Multisite Testing**: Support for testing in multisite environments
5. **Continuous Integration**: Automated tests via GitHub Actions
## Conclusion
This architecture provides a solid foundation for WordPress plugin development, following best practices and modern coding standards. It's designed to be maintainable, extensible, and easy to understand.
This architecture provides a solid foundation for WordPress plugin development.
It follows best practices and modern coding standards.
It's designed to be maintainable, extensible, and easy to understand.
For testing framework details, see [Testing Framework](Testing-Framework.md).
For multisite development, refer to [Multisite Development](Multisite-Development.md).

126
.wiki/Error-Checking-Feedback-Loops.md Normal file
View File

@@ -0,0 +1,126 @@
# Error Checking and Feedback Loops
This document explains how to check for code quality issues and get feedback from automated tools in our development workflow.
## Table of Contents
* [Overview](#overview)
* [Local Error Checking](#local-error-checking)
* [CI/CD Feedback Loops](#cicd-feedback-loops)
* [Common Issues and Solutions](#common-issues-and-solutions)
* [Improving Code Quality](#improving-code-quality)
## Overview
Our development process includes multiple layers of error checking and feedback loops to ensure high code quality:
1. **Local Development**: Run linters and tests locally before committing
2. **Pull Request**: Automated checks run when you create or update a PR
3. **Code Review**: Human reviewers provide feedback on your code
4. **Continuous Integration**: Tests run in various environments to ensure compatibility
## Local Error Checking
### PHP Code Quality Checks
Run these commands locally to check for PHP code quality issues:
```bash
# Run all PHP code quality checks
npm run lint:php
# Run specific checks
npm run lint:phpcs # PHP CodeSniffer
npm run lint:phpstan # PHPStan static analysis
npm run lint:phpmd # PHP Mess Detector
```
### JavaScript/CSS Checks
```bash
# Run ESLint for JavaScript files
npm run lint:js
# Run stylelint for CSS files
npm run lint:css
```
### Running Tests Locally
```bash
# Run Cypress tests for single site
npm run test:playground:single
# Run Cypress tests for multisite
npm run test:playground:multisite
```
## CI/CD Feedback Loops
When you push code or create a pull request, several automated checks run:
### GitHub Actions Workflows
* **Code Quality**: Runs PHP CodeSniffer, PHPStan, and PHP Mess Detector
* **WordPress Tests**: Runs tests in WordPress environments
* **WordPress Playground Tests**: Runs tests in WordPress Playground environments
* **Tests - Run PHP compatibility and unit tests**: Checks compatibility with different PHP versions
### Third-Party Code Quality Services
* **CodeFactor**: Provides automated code reviews and quality grades
* **Codacy**: Analyzes code quality and security issues
* **SonarCloud**: Detects bugs, vulnerabilities, and code smells
## Common Issues and Solutions
### PHP CodeSniffer Issues
* **Indentation**: Use tabs for indentation in PHP files
* **Spacing**: Add spaces after commas, around operators, and after control structures
* **Naming Conventions**: Use snake_case for functions and variables in PHP
* **DocBlocks**: Add proper documentation for functions and classes
### PHPStan Issues
* **Undefined Variables**: Ensure all variables are defined before use
* **Type Errors**: Use proper type hints and return types
* **Null Checks**: Add null checks for variables that might be null
### JavaScript/CSS Issues
* **ESLint Errors**: Follow JavaScript best practices
* **Stylelint Errors**: Follow CSS best practices
* **Accessibility Issues**: Ensure UI elements are accessible
## Improving Code Quality
### Best Practices
* **Write Tests First**: Use test-driven development (TDD) when possible
* **Small PRs**: Keep pull requests small and focused on a single issue
* **Regular Commits**: Commit frequently with clear messages
* **Code Reviews**: Request code reviews from team members
* **Documentation**: Keep documentation up-to-date
### Using AI Assistants
AI assistants can help you understand and fix code quality issues:
1. Copy the error message or feedback
2. Paste it into your AI assistant chat
3. Ask for help understanding and fixing the issue
4. Apply the suggested fixes
5. Run the checks again to verify the issue is resolved
### Continuous Learning
* Review the code quality reports regularly
* Learn from feedback and improve your coding practices
* Stay updated on best practices for WordPress development
## Related Documentation
* [Testing Framework](Testing.md)
* [Code Review Guide](../.ai-workflows/code-review.md)
* [Architecture Overview](Architecture-Overview.md)

175
.wiki/Multisite-Development.md Normal file
View File

@@ -0,0 +1,175 @@
# Multisite Development
This guide explains how to extend the WordPress Plugin Starter Template for multisite environments.
## Overview
WordPress Multisite allows you to run multiple WordPress sites from a single installation.
The plugin template includes a basic structure for multisite-specific functionality.
You can extend this to add features for multisite environments.
## Directory Structure
The plugin includes a dedicated directory for multisite-specific functionality:
```bash
includes/
└── Multisite/
├── class-multisite.php # Base class for multisite functionality
└── README.md # Documentation for multisite development
```
## Getting Started
### 1. Understand the Base Class
The `Multisite` class in `includes/Multisite/class-multisite.php` provides a foundation for multisite functionality.
It includes:
* A constructor for initialization
* Example methods for multisite functionality
### 2. Load Multisite Classes
To use multisite-specific functionality, you need to load and initialize the classes in your main plugin file:
```php
// Load multisite support classes if in multisite environment
if ( is_multisite() ) {
require_once WP_PLUGIN_STARTER_TEMPLATE_PATH . 'includes/Multisite/class-multisite.php';
// Initialize multisite support
$multisite = new WPALLSTARS\PluginStarterTemplate\Multisite\Multisite();
}
```
### 3. Extend the Base Class
You can extend the base `Multisite` class or create additional classes in the `Multisite` directory.
This allows you to implement specific features:
```php
<?php
namespace WPALLSTARS\PluginStarterTemplate\Multisite;
class Domain_Mapping extends Multisite {
public function __construct() {
parent::__construct();
// Add hooks for domain mapping functionality
add_action( 'init', array( $this, 'register_domain_mapping' ) );
}
public function register_domain_mapping() {
// Implement domain mapping functionality
}
}
```
## Common Multisite Features
Here are some common features you might want to implement for multisite environments:
### Network Admin Pages
To add pages to the network admin menu:
```php
add_action( 'network_admin_menu', array( $this, 'add_network_menu' ) );
public function add_network_menu() {
add_submenu_page(
'settings.php',
__( 'Plugin Settings', 'your-text-domain' ),
__( 'Plugin Settings', 'your-text-domain' ),
'manage_network_options',
'your-plugin-slug',
array( $this, 'render_network_settings' )
);
}
```
### Site Creation Hooks
To perform actions when a new site is created:
```php
add_action( 'wp_initialize_site', array( $this, 'on_site_creation' ), 10, 2 );
public function on_site_creation( $new_site, $args ) {
// Get the blog ID
$blog_id = $new_site->blog_id;
// Switch to the new blog
switch_to_blog( $blog_id );
// Perform site-specific setup
update_option( 'your_plugin_option', 'default_value' );
// Restore the current blog
restore_current_blog();
}
```
### Network Settings
To save network-wide settings:
```php
// Process network settings form
add_action( 'network_admin_edit_your_plugin_action', array( $this, 'save_network_settings' ) );
public function save_network_settings() {
// Check nonce
check_admin_referer( 'your_plugin_nonce' );
// Save settings
update_site_option( 'your_plugin_network_option', sanitize_text_field( $_POST['your_option'] ) );
// Redirect back to settings page
wp_redirect( add_query_arg( array(
'page' => 'your-plugin-slug',
'updated' => 'true'
), network_admin_url( 'settings.php' ) ) );
exit;
}
```
## Testing Multisite Functionality
To test your multisite functionality, use the testing framework included in the plugin template:
```bash
# Set up multisite environment
npm run setup:multisite
# Run tests
npm run test:multisite
```
For more details on testing, see the [Testing Framework](Testing-Framework.md) documentation.
## Best Practices
1. **Always Check for Multisite**: Use `is_multisite()` to check if the current installation is a multisite network.
2. **Use Network-Specific Functions**: WordPress provides specific functions for multisite.
Use `update_site_option()` instead of `update_option()` for network-wide settings.
3. **Handle Blog Switching Properly**: When working with specific sites, use `switch_to_blog()`.
Always call `restore_current_blog()` when done.
4. **Respect Network Admin Capabilities**: Use capabilities like `manage_network_options` for network admin.
5. **Test in Both Environments**: Test in both single site and multisite to ensure compatibility.
## Conclusion
By following this guide, you can extend the WordPress Plugin Starter Template.
The included structure provides a solid foundation for multisite features.

306
.wiki/Playground-Testing.md Normal file
View File

@@ -0,0 +1,306 @@
# WordPress Playground Testing
This document explains how to use WordPress Playground for testing our plugin.
## What is WordPress Playground?
[WordPress Playground](https://wordpress.org/playground/) is a project that runs WordPress entirely in the browser.
It uses WebAssembly, which means:
* No server required - WordPress runs in the browser
* Fast startup times
* Isolated testing environment
* Works well with CI/CD pipelines
## Using WordPress Playground Online
The easiest way to test our plugin with WordPress Playground is to use the online version:
1. Single site testing: [Open in WordPress Playground][playground-single]
2. Multisite testing: [Open in WordPress Playground][playground-multisite]
[playground-single]: https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/wpallstars/wp-plugin-starter-template-for-ai-coding/main/playground/blueprint.json&_t=2
[playground-multisite]: https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/wpallstars/wp-plugin-starter-template-for-ai-coding/main/playground/multisite-blueprint.json&_t=2
These links automatically set up WordPress with multisite enabled and WP_DEBUG enabled.
Both the Plugin Toggle and Kadence Blocks plugins are pre-activated.
## WP-CLI Commands for WordPress Playground
WordPress Playground supports WP-CLI commands for programmatic interaction.
Here are some useful commands for testing:
### General Commands
```bash
# Get WordPress version
wp core version
# List installed plugins
wp plugin list
# Install a plugin
wp plugin install plugin-slug
# Activate a plugin
wp plugin activate plugin-slug
# Deactivate a plugin
wp plugin deactivate plugin-slug
# Get plugin status
wp plugin status plugin-slug
```
### Multisite Commands
```bash
# List all sites in the network
wp site list
# Create a new site
wp site create --slug=testsite
# Delete a site
wp site delete 2
# Network activate a plugin
wp plugin activate plugin-slug --network
# Activate a plugin for a specific site
wp plugin activate plugin-slug --url=example.com/testsite
# Create a new user and add them to a site
wp user create testuser test@example.com --role=editor
wp user add-role testuser editor --url=example.com/testsite
```
### Testing Commands
```bash
# Run a specific test
wp scaffold plugin-tests my-plugin
wp test run --filter=test_function_name
# Check for PHP errors
wp site health check
# Export/import content for testing
wp export
wp import
```
## Plugin Activation in Multisite
In a WordPress multisite environment, there are two ways to activate plugins:
1. **Network Activation**: Activates a plugin for all sites in the network
* In the WordPress admin, go to Network Admin > Plugins
* Click "Network Activate" under the plugin
* Or use WP-CLI: `wp plugin install plugin-name --activate-network`
2. **Per-Site Activation**: Activates a plugin for a specific site
* In the WordPress admin, go to the specific site's admin area
* Go to Plugins and activate the plugin for that site only
* Or use WP-CLI: `wp plugin activate plugin-name --url=site-url`
Our multisite blueprint uses network activation for the Plugin Toggle plugin as an example.
## Running Tests with WordPress Playground
We have two blueprints for testing:
1. `playground/blueprint.json` - For single site testing
2. `playground/multisite-blueprint.json` - For multisite testing
To run tests with WordPress Playground:
1. Open the appropriate WordPress Playground link:
* [Single site][playground-single]
* [Multisite][playground-multisite]
2. Test the plugin manually in the browser
## Local Testing with HTML Files
We've also included HTML files that embed WordPress Playground:
1. Open `playground/index.html` in your browser for single site testing
2. Open `playground/multisite.html` in your browser for multisite testing
3. Open `playground/test.html` in your browser for a unified interface with buttons
to switch between single site and multisite
You can serve these files locally with a simple HTTP server:
```bash
# Using Python
python -m http.server 8888 --directory playground
# Then open http://localhost:8888/index.html in your browser
# Or open http://localhost:8888/multisite.html for multisite testing
```
### Using wp-now
Alternatively, you can use [wp-now](https://github.com/WordPress/playground-tools/tree/trunk/packages/wp-now).
This tool from the WordPress Playground team makes it easy to run WordPress locally:
```bash
# Install wp-now globally
npm install -g @wp-playground/wp-now
# Start a WordPress instance with the current plugin
wp-now start
# Start with multisite enabled
wp-now start --multisite
# Start with specific PHP and WordPress versions
wp-now start --php 8.0 --wp 6.2
# Start with WP_DEBUG enabled
wp-now start --wp-debug
```
This will start a local WordPress instance with your plugin installed and activated.
## Customizing Blueprints
You can customize the blueprints to suit your testing needs.
See the [WordPress Playground Blueprints documentation][blueprints-docs] for details.
[blueprints-docs]: https://wordpress.github.io/wordpress-playground/blueprints/
## WordPress Playground JavaScript API
WordPress Playground provides a JavaScript API for programmatic interaction with WordPress.
This is useful for automated testing and CI/CD integration.
### Basic Usage
```javascript
// Import the WordPress Playground client
import { createWordPressPlayground } from '@wp-playground/client';
// Create a playground instance
const playground = await createWordPressPlayground({
iframe: document.getElementById('wp-playground'),
remoteUrl: 'https://playground.wordpress.net/remote.html',
});
// Run a blueprint
await playground.run({
steps: [
{ step: 'enableMultisite' },
{ step: 'wp-cli', command: 'wp site create --slug=testsite' },
{ step: 'wp-cli', command: 'wp plugin install plugin-toggle kadence-blocks --activate-network' }
]
});
// Run WP-CLI commands
const result = await playground.run({
step: 'wp-cli',
command: 'wp plugin list --format=json'
});
// Parse the JSON output
const plugins = JSON.parse(result.output);
console.log(plugins);
```
### Automated Testing
You can use the JavaScript API with testing frameworks like Jest or Cypress:
```javascript
describe('Plugin Tests', () => {
let playground;
beforeAll(async () => {
playground = await createWordPressPlayground({
iframe: document.getElementById('wp-playground'),
remoteUrl: 'https://playground.wordpress.net/remote.html',
});
// Set up WordPress with our blueprint
await playground.run({
steps: [
{ step: 'enableMultisite' },
{ step: 'wp-cli', command: 'wp site create --slug=testsite' },
{ step: 'wp-cli', command: 'wp plugin install plugin-toggle kadence-blocks --activate-network' }
]
});
});
test('Plugin is activated', async () => {
const result = await playground.run({
step: 'wp-cli',
command: 'wp plugin list --format=json'
});
const plugins = JSON.parse(result.output);
const pluginToggle = plugins.find(plugin => plugin.name === 'plugin-toggle');
expect(pluginToggle.status).toBe('active');
});
});
```
## CI/CD Integration
We have a GitHub Actions workflow that uses WordPress Playground for testing.
See `.github/workflows/playground-tests.yml` for details.
### Example GitHub Actions Workflow
```yaml
jobs:
playground-test:
name: WordPress Playground Tests
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
- name: Install dependencies
run: npm ci
- name: Install WordPress Playground CLI
run: npm install -g @wordpress/playground-tools
- name: Create plugin zip
run: |
mkdir -p dist
zip -r dist/plugin.zip . -x "node_modules/*" "dist/*" ".git/*"
- name: Run tests with WordPress Playground
run: |
# Start WordPress Playground with our blueprint
wp-playground start --blueprint playground/blueprint.json --port 8888 &
# Wait for WordPress Playground to be ready
echo "Waiting for WordPress Playground to be ready..."
timeout 60 bash -c 'until curl -s http://localhost:8888; do sleep 2; done'
# Run Cypress tests against WordPress Playground
npm run test:single:headless
```
## Performance Testing
We also use [WP Performance Tests GitHub Action](https://github.com/marketplace/actions/wp-performance-tests).
This action tests our plugin against various WordPress and PHP versions to ensure good performance.

142
.wiki/Testing-Framework.md Normal file
View File

@@ -0,0 +1,142 @@
# WordPress Plugin Testing Framework
This document outlines how to set up and run tests for our plugin.
It covers both single site and multisite WordPress environments.
## Overview
Our plugin is designed to work with both standard WordPress installations and WordPress Multisite.
This testing framework allows you to verify functionality in both environments.
## Setting Up the Test Environment
We use `@wordpress/env` and Cypress for testing our plugin.
### Prerequisites
* Node.js (v14 or higher)
* npm or yarn
* Docker and Docker Compose
### Installation
1. Clone the repository:
```bash
git clone https://github.com/wpallstars/wp-plugin-starter-template-for-ai-coding.git
cd wp-plugin-starter-template-for-ai-coding
```
2. Install dependencies:
```bash
npm install
```
## Testing in Single Site WordPress
1. Set up the single site environment:
```bash
npm run setup:single
```
This will:
* Start a WordPress environment using wp-env
* Activate our plugin
2. Run Cypress tests for single site:
```bash
npm run test:single
```
For headless testing:
```bash
npm run test:single:headless
```
3. Access the site manually:
* Site: <http://localhost:8888>
* Admin login: admin / password
## Testing in WordPress Multisite
1. Set up the multisite environment:
```bash
npm run setup:multisite
```
This will:
* Start a WordPress environment using wp-env
* Configure it as a multisite installation
* Create a test subsite
* Network activate our plugin
2. Run Cypress tests for multisite:
```bash
npm run test:multisite
```
For headless testing:
```bash
npm run test:multisite:headless
```
3. Access the sites manually:
* Main site: <http://localhost:8888>
* Test subsite: <http://localhost:8888/testsite>
* Admin login: admin / password
## Continuous Integration
We use GitHub Actions to automatically run tests on pull requests.
The workflow is defined in `.github/workflows/wordpress-tests.yml` and runs tests in both environments.
## Writing Tests
### Single Site Tests
Add new single site tests to `cypress/e2e/single-site.cy.js`.
### Multisite Tests
Add new multisite tests to `cypress/e2e/multisite.cy.js`.
## Troubleshooting
### Common Issues
1. **Database connection errors**: Make sure Docker is running and ports 8888 and 8889 are available.
2. **Multisite conversion fails**: Check the wp-env logs for details:
```bash
wp-env logs
```
3. **Plugin not activated**: Run the following command:
```bash
# For single site
wp-env run cli wp plugin activate wp-plugin-starter-template-for-ai-coding
# For multisite
wp-env run cli wp plugin activate wp-plugin-starter-template-for-ai-coding --network
```
### Getting Help
If you encounter any issues, please open an issue on our GitHub repository with:
* A description of the problem
* Steps to reproduce
* Any error messages
* Your environment details (OS, Node.js version, etc.)

263
.wiki/Testing.md Normal file
View File

@@ -0,0 +1,263 @@
# Testing Framework
This document explains how to use the testing framework for our plugin.
## Table of Contents
* [Overview](#overview)
* [Prerequisites](#prerequisites)
* [Testing Approaches](#testing-approaches)
* [wp-env Approach](#1-wp-env-approach)
* [WordPress Playground Approach](#2-wordpress-playground-approach)
* [Writing Tests](#writing-tests)
* [CI/CD Integration](#cicd-integration)
* [Troubleshooting](#troubleshooting)
* [PHPUnit Tests](#phpunit-tests)
* [Future Improvements](#future-improvements)
## Overview
Our testing framework uses:
See also:
* [Architecture Overview](Architecture-Overview.md) – high-level design
* [Multisite Development](Multisite-Development.md) – deeper multisite guidance
Components:
* **wp-env**: For setting up WordPress environments (both single site and multisite)
* **WordPress Playground**: For browser-based testing without Docker
* **Cypress**: For end-to-end testing
* **PHPUnit**: For unit testing (coming soon)
## Prerequisites
1. **Node.js**: Version 16 or higher
2. **npm**: For package management
3. **Docker**: For running WordPress environments with wp-env (not needed for WordPress Playground)
4. **PHP**: Version 7.4 or higher (for future PHPUnit tests)
5. **Composer**: For managing PHP dependencies
## Testing Approaches
We provide two main approaches for testing:
1. **wp-env**: Traditional approach using Docker
2. **WordPress Playground**: Browser-based approach without Docker
### 1. wp-env Approach
#### Setting Up Test Environments
We provide scripts to easily set up test environments:
##### Single Site Environment
```bash
# Set up a single site environment
npm run setup:single
# You can also use the unified setup script:
bash bin/setup-test-env.sh single
```
This will:
1. Start a WordPress single site environment using wp-env
2. Install and activate our plugin
3. Configure WordPress for testing
##### Multisite Environment
```bash
# Set up a multisite environment
npm run setup:multisite
# Or via the setup script:
bash bin/setup-test-env.sh multisite
```
This will:
1. Start a WordPress multisite environment using wp-env
2. Install and activate our plugin network-wide
3. Create a test subsite
4. Configure WordPress for testing
#### Running Tests
We have Cypress tests for both single site and multisite environments:
##### Single Site Tests
```bash
# Run tests in browser (interactive mode)
npm run test:single
# Run tests headless (CI mode)
npm run test:single:headless
```
##### Multisite Tests
```bash
# Run tests in browser (interactive mode)
npm run test:multisite
# Run tests headless (CI mode)
npm run test:multisite:headless
```
##### All-in-One Commands
We also provide all-in-one commands that set up the environment and run the tests:
```bash
# Set up single site environment and run tests
npm run test:e2e:single
# Set up multisite environment and run tests
npm run test:e2e:multisite
```
### 2. WordPress Playground Approach
WordPress Playground runs WordPress entirely in the browser using WebAssembly. This means:
* No server required - WordPress runs in the browser
* Fast startup times
* Isolated testing environment
* Works well with CI/CD pipelines
#### Using WordPress Playground Online
The easiest way to test our plugin with WordPress Playground is to use the online version:
1. Single site testing: [Open in WordPress Playground][playground-single]
2. Multisite testing: [Open in WordPress Playground][playground-multisite]
[playground-single]: https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/wpallstars/wp-plugin-starter-template-for-ai-coding/main/playground/blueprint.json&_t=2
[playground-multisite]: https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/wpallstars/wp-plugin-starter-template-for-ai-coding/main/playground/multisite-blueprint.json&_t=2
These links automatically set up WordPress with multisite enabled and WP_DEBUG enabled.
Both the Plugin Toggle and Kadence Blocks plugins are pre-activated.
#### Local Testing with HTML Files
We've also included HTML files that embed WordPress Playground:
1. Open `playground/index.html` in your browser for single site testing
2. Open `playground/multisite.html` in your browser for multisite testing
3. Open `playground/test.html` in your browser for a unified interface with buttons
to switch between single site and multisite
You can serve these files locally with a simple HTTP server:
```bash
# Using Python
python -m http.server 8888 --directory playground
# Then open http://localhost:8888/index.html in your browser
# Or open http://localhost:8888/test.html for a unified single/multisite switcher
```
## Writing Tests
### Cypress Tests
We have custom Cypress commands to make testing WordPress easier:
* `cy.loginAsAdmin()`: Logs in as the admin user
* `cy.activatePlugin(pluginSlug)`: Activates a plugin
* `cy.networkActivatePlugin(pluginSlug)`: Network activates a plugin in multisite
Example test:
```javascript
describe('WordPress Single Site Tests', () => {
it('Can login to the admin area', () => {
cy.loginAsAdmin();
cy.get('body.wp-admin').should('exist');
});
it('Plugin is activated', () => {
cy.loginAsAdmin();
cy.visit('/wp-admin/plugins.php');
cy.get('tr[data-slug="wp-plugin-starter-template-for-ai-coding"]')
.should('have.class', 'active');
});
});
```
## CI/CD Integration
We have GitHub Actions workflows for running tests in CI/CD:
* `.github/workflows/wordpress-tests.yml`: Runs wp-env e2e tests
* `.github/workflows/playground-tests.yml`: Runs Playground e2e tests
* `.github/workflows/phpunit.yml`: Runs PHPUnit tests (coming soon)
## Troubleshooting
### Common Issues
1. **Docker not running**: Make sure Docker is running before starting wp-env
2. **Port conflicts**: If ports 8888 or 8889 are in use, wp-env will fail to start
3. **wp-env not installed**: Run `npm install -g @wordpress/env` to install wp-env globally
4. **WordPress Playground not loading**: Check your network connection and try refreshing the page
5. **Tests failing**: Check the error messages in the console and fix the issues
### Error Checking and Feedback Loops
For information on code quality issues and automated tool feedback, see the
[Error Checking and Feedback Loops](Error-Checking-Feedback-Loops.md) documentation.
### Debugging
1. **Cypress debugging**: Use `cy.debug()` to pause test execution
2. **wp-env debugging**: Run `wp-env logs` to see WordPress logs
3. **GitHub Actions debugging**: Check the workflow logs for detailed error messages
## PHPUnit Tests
We use PHPUnit for unit testing PHP code. The tests are located in the `tests/phpunit` directory.
### Running PHPUnit Tests
```bash
# Run PHPUnit tests for single site
npm run test:phpunit
# Run PHPUnit tests for multisite
npm run test:phpunit:multisite
```
### Writing PHPUnit Tests
Here's an example of a PHPUnit test for the Multisite class:
```php
<?php
class MultisiteTest extends WP_UnitTestCase {
public function test_is_multisite_compatible() {
$multisite = new WP_Plugin_Starter_Template_For_AI_Coding\Multisite\Multisite();
$this->assertTrue($multisite->is_multisite_compatible());
}
public function test_get_network_sites() {
$multisite = new WP_Plugin_Starter_Template_For_AI_Coding\Multisite\Multisite();
$sites = $multisite->get_network_sites();
$this->assertIsArray($sites);
}
}
```
## Future Improvements
1. **Performance tests**: Add performance testing
2. **Accessibility tests**: Add accessibility testing

2
.wiki/_Sidebar.md
View File

@@ -13,6 +13,8 @@
* [Customization Guide](Customization-Guide)
* [Extending the Plugin](Extending-the-Plugin)
* [Coding Standards](Coding-Standards)
* [Testing Framework](Testing-Framework)
* [Multisite Development](Multisite-Development)
* [Release Process](Release-Process)
## AI Documentation

16
.wp-env.json Normal file
View File

@@ -0,0 +1,16 @@
{
"core": null,
"plugins": [
"."
],
"themes": [],
"config": {
"WP_DEBUG": true,
"WP_DEBUG_LOG": true,
"WP_DEBUG_DISPLAY": false
},
"mappings": {
"wp-content/mu-plugins": "./mu-plugins",
"wp-content/plugins/wp-plugin-starter-template-for-ai-coding": "."
}
}

22
.wp-env.multisite.json Normal file
View File

@@ -0,0 +1,22 @@
{
"core": null,
"plugins": [
"."
],
"themes": [],
"config": {
"WP_DEBUG": true,
"WP_DEBUG_LOG": true,
"WP_DEBUG_DISPLAY": false,
"WP_ALLOW_MULTISITE": true,
"MULTISITE": true,
"SUBDOMAIN_INSTALL": false,
"PATH_CURRENT_SITE": "/",
"SITE_ID_CURRENT_SITE": 1,
"BLOG_ID_CURRENT_SITE": 1
},
"mappings": {
"wp-content/mu-plugins": "./mu-plugins",
"wp-content/plugins/wp-plugin-starter-template-for-ai-coding": "."
}
}

69
AGENTS.md
View File

@@ -4,11 +4,15 @@ This guide helps AI assistants understand the project structure, workflows, and
## IMPORTANT: Repository Context
This workspace may contain multiple repository folders. Always focus ONLY on the current repository you're working in and avoid hallucinating functionality from other repositories in the workspace.
This workspace may contain multiple repository folders.
Always focus ONLY on the current repository you're working in.
Avoid hallucinating functionality from other repositories in the workspace.
* **Current Repository**: wp-plugin-starter-template-for-ai-coding
* **Repository Purpose**: A comprehensive starter template for WordPress plugins with best practices for AI-assisted development
* **Repository Scope**: All code changes, documentation, and functionality discussions should be limited to THIS repository only
* **Repository Purpose**: A starter template for WordPress plugins with AI-assisted development
* **Repository Scope**: All code changes and discussions should be limited to THIS repository only
## Project Overview
@@ -16,9 +20,9 @@ This workspace may contain multiple repository folders. Always focus ONLY on the
* **Plugin Slug**: wp-plugin-starter-template
* **Text Domain**: wp-plugin-starter-template
* **Namespace**: WPALLSTARS\PluginStarterTemplate
* **Version**: 0.1.13
* **Version**: 0.1.15
* **Requires WordPress**: 5.0+
* **Requires PHP**: 7.0+
* **Requires PHP**: 7.4+
* **License**: GPL-2.0+
## Repository Structure
@@ -39,7 +43,7 @@ This workspace may contain multiple repository folders. Always focus ONLY on the
## Coding Standards
This project follows the [WordPress Coding Standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/):
This project follows the [WordPress Coding Standards](https://developer.wordpress.org/coding-standards/):
* Use 4 spaces for indentation, not tabs (this is a project-specific override of WordPress standards)
* Follow WordPress naming conventions:
@@ -87,23 +91,31 @@ Always run PHPCS and PHPCBF locally before committing code to ensure it meets th
## Common Tasks
For detailed instructions on common tasks like creating releases, adding features, fixing bugs, and testing previous versions, see **@.agents/release-process.md**.
For detailed instructions on releases, features, bugs, and testing, see **@.agents/release-process.md**.
For local testing with WordPress Playground, LocalWP, and wp-env, see **@.agents/local-testing-guide.md**.
## Avoiding Cross-Repository Confusion
When working in a multi-repository workspace, follow these guidelines to avoid confusion:
1. **Verify Repository Context**: Always check which repository you're currently working in before making any changes or recommendations.
1. **Verify Repository Context**: Always check which repository you're currently working in
before making any changes or recommendations.
2. **Limit Code Search Scope**: When searching for code or functionality, explicitly limit your search to the current repository.
2. **Limit Code Search Scope**: When searching for code or functionality,
explicitly limit your search to the current repository.
3. **Don't Assume Features**: Never assume that features present in one repository should be implemented in another. Each repository has its own specific purpose and feature set.
3. **Don't Assume Features**: Never assume that features present in one repository
should be implemented in another. Each repository has its own specific purpose and feature set.
4. **Repository-Specific Documentation**: Documentation should only reflect the actual features and functionality of the current repository.
4. **Repository-Specific Documentation**: Documentation should only reflect the actual features
and functionality of the current repository.
5. **Cross-Repository Inspiration**: If you want to implement a feature inspired by another repository, explicitly mention that it's a new feature being added, not an existing one.
5. **Cross-Repository Inspiration**: If you want to implement a feature inspired by another
repository, explicitly mention that it's a new feature being added, not an existing one.
6. **Verify Before Implementation**: Before implementing or documenting a feature, verify that it actually exists in the current repository by checking the codebase.
6. **Verify Before Implementation**: Before implementing or documenting a feature, verify that
it actually exists in the current repository by checking the codebase.
7. **Consistent Markdown Formatting**: Always use asterisks (*) for bullet points in Markdown files, not hyphens (-).
@@ -153,6 +165,33 @@ When working with this repository, remember these preferences:
1. Follow WordPress coding standards
2. Use OOP approach with namespaced classes
3. Keep code modular and maintainable
3. Reference these preferences in future interactions
4. Reference these preferences in future interactions
This ensures consistency across coding sessions and reduces the need for developers to repeatedly explain their preferences.
This ensures consistency across coding sessions.
It reduces the need for developers to repeatedly explain their preferences.
## Autonomous CI/CD and Error Handling
This repository is set up for autonomous CI/CD with minimal human intervention.
As an AI assistant, you should:
1. **Monitor CI/CD Pipelines**: Use the GitHub API to check workflow status and identify failures
2. **Diagnose Issues**: Analyze error logs and determine root causes
3. **Implement Fixes**: Make necessary code changes to resolve issues
4. **Verify Solutions**: Ensure fixes pass all tests and quality checks
5. **Document Resolutions**: Update documentation with solutions for future reference
For detailed instructions on feedback loops and error checking, see
**@.agents/error-checking-feedback-loops.md**.
### When to Consult Humans
Only consult humans for:
* Product design decisions
* Security-critical changes
* Major architectural decisions
* Access to information not available through APIs or terminal
* Novel problems without precedent or documented solutions

60
PR-DESCRIPTION.md Normal file
View File

@@ -0,0 +1,60 @@
# Add Comprehensive Testing Framework for Single Site and Multisite
This PR adds a comprehensive testing framework for our WordPress plugin template.
It allows testing in both single site and multisite WordPress environments.
The focus is purely on testing functionality, not on adding multisite-specific features.
## Changes
* Added wp-env configuration for both single site and multisite environments
* Created Cypress e2e tests for both environments
* Added GitHub Actions workflow to run tests automatically on PRs
* Created a unified setup script for test environments
* Added detailed documentation in the wiki
* Updated README.md to reference the new testing approach
* Added placeholder files for multisite functionality
## Testing
The testing framework can be used as follows:
### Single Site Testing
```bash
# Set up single site environment
npm run setup:single
# Run tests in interactive mode
npm run test:single
# Run tests in headless mode
npm run test:single:headless
```
### Multisite Testing
```bash
# Set up multisite environment
npm run setup:multisite
# Run tests in interactive mode
npm run test:multisite
# Run tests in headless mode
npm run test:multisite:headless
```
## Documentation
Detailed documentation is available in the [Testing Framework](.wiki/Testing-Framework.md) wiki page.
## Inspiration
This implementation was inspired by the e2e testing approach in
[wp-multisite-waas issue #55](https://github.com/superdav42/wp-multisite-waas/issues/55).
It focuses on testing our plugin in different WordPress environments.
It does not add domain mapping or other multisite-specific functionality from that plugin.

165
README.md
View File

@@ -1,14 +1,43 @@
# WordPress Plugin Starter Template for AI Coding
[![License](https://img.shields.io/badge/license-GPL--2.0%2B-blue.svg)](https://www.gnu.org/licenses/gpl-2.0.html) [![Build Status](https://github.com/wpallstars/wp-plugin-starter-template-for-ai-coding/actions/workflows/tests.yml/badge.svg)](https://github.com/wpallstars/wp-plugin-starter-template-for-ai-coding/actions/workflows/tests.yml) [![Requires PHP](https://img.shields.io/badge/php-%3E%3D%207.4-blue.svg)](https://wordpress.org/about/requirements/) [![Requires WordPress](https://img.shields.io/badge/WordPress-%3E%3D%205.0-blue.svg)](https://wordpress.org/about/requirements/) [![Tested up to](https://img.shields.io/wordpress/plugin/tested/your-plugin-slug.svg)](https://wordpress.org/plugins/your-plugin-slug/) [![WordPress rating](https://img.shields.io/wordpress/plugin/r/your-plugin-slug.svg)](https://wordpress.org/plugins/your-plugin-slug/reviews/) [![WordPress downloads](https://img.shields.io/wordpress/plugin/dt/your-plugin-slug.svg)](https://wordpress.org/plugins/your-plugin-slug/) [![Latest Release](https://img.shields.io/github/v/release/wpallstars/wp-plugin-starter-template-for-ai-coding)](https://github.com/wpallstars/wp-plugin-starter-template-for-ai-coding/releases) [![GitHub issues](https://img.shields.io/github/issues/wpallstars/wp-plugin-starter-template-for-ai-coding)](https://github.com/wpallstars/wp-plugin-starter-template-for-ai-coding/issues) [![GitHub contributors](https://img.shields.io/github/contributors/wpallstars/wp-plugin-starter-template-for-ai-coding)](https://github.com/wpallstars/wp-plugin-starter-template-for-ai-coding/graphs/contributors) [![Wiki](https://img.shields.io/badge/documentation-wiki-blue.svg)](https://github.com/wpallstars/wp-plugin-starter-template-for-ai-coding/wiki) ![CodeRabbit Pull Request Reviews](https://img.shields.io/coderabbit/prs/github/wpallstars/wp-plugin-starter-template-for-ai-coding?utm_source=oss&utm_medium=github&utm_campaign=wpallstars%2Fwp-plugin-starter-template-for-ai-coding&labelColor=171717&color=FF570A&link=https%3A%2F%2Fcoderabbit.ai&label=CodeRabbit+Reviews) [![CodeFactor](https://www.codefactor.io/repository/github/wpallstars/wp-plugin-starter-template-for-ai-coding/badge)](https://www.codefactor.io/repository/github/wpallstars/wp-plugin-starter-template-for-ai-coding) [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=wpallstars_wp-plugin-starter-template-for-ai-coding&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=wpallstars_wp-plugin-starter-template-for-ai-coding) [![Bugs](https://sonarcloud.io/api/project_badges/measure?project=wpallstars_wp-plugin-starter-template-for-ai-coding&metric=bugs)](https://sonarcloud.io/summary/new_code?id=wpallstars_wp-plugin-starter-template-for-ai-coding) [![Code Smells](https://sonarcloud.io/api/project_badges/measure?project=wpallstars_wp-plugin-starter-template-for-ai-coding&metric=code_smells)](https://sonarcloud.io/summary/new_code?id=wpallstars_wp-plugin-starter-template-for-ai-coding) [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=wpallstars_wp-plugin-starter-template-for-ai-coding&metric=coverage)](https://sonarcloud.io/summary/new_code?id=wpallstars_wp-plugin-starter-template-for-ai-coding) [![Duplicated Lines (%)](https://sonarcloud.io/api/project_badges/measure?project=wpallstars_wp-plugin-starter-template-for-ai-coding&metric=duplicated_lines_density)](https://sonarcloud.io/summary/new_code?id=wpallstars_wp-plugin-starter-template-for-ai-coding) [![Codacy Badge](https://app.codacy.com/project/badge/Grade/905754fd010b481490b496fb800e6144)](https://app.codacy.com/gh/wpallstars/wp-plugin-starter-template-for-ai-coding/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
[![License][badge-license]][url-license]
[![Build Status][badge-build]][url-build]
[![Requires PHP][badge-php]][url-requirements]
[![Requires WordPress][badge-wp]][url-requirements]
[![Wiki][badge-wiki]][url-wiki]
[![CodeRabbit Reviews][badge-coderabbit]][url-coderabbit]
[![CodeFactor][badge-codefactor]][url-codefactor]
[![Quality Gate Status][badge-sonar-gate]][url-sonar]
[![Codacy Badge][badge-codacy]][url-codacy]
[badge-license]: https://img.shields.io/badge/license-GPL--2.0%2B-blue.svg
[badge-build]: https://github.com/wpallstars/wp-plugin-starter-template-for-ai-coding/actions/workflows/tests.yml/badge.svg
[badge-php]: https://img.shields.io/badge/php-%3E%3D%207.4-blue.svg
[badge-wp]: https://img.shields.io/badge/WordPress-%3E%3D%205.0-blue.svg
[badge-wiki]: https://img.shields.io/badge/documentation-wiki-blue.svg
[badge-coderabbit]: https://img.shields.io/coderabbit/prs/github/wpallstars/wp-plugin-starter-template-for-ai-coding?labelColor=171717&color=FF570A&label=CodeRabbit+Reviews
[badge-codefactor]: https://www.codefactor.io/repository/github/wpallstars/wp-plugin-starter-template-for-ai-coding/badge
[badge-sonar-gate]: https://sonarcloud.io/api/project_badges/measure?project=wpallstars_wp-plugin-starter-template-for-ai-coding&metric=alert_status
[badge-codacy]: https://app.codacy.com/project/badge/Grade/905754fd010b481490b496fb800e6144
[url-license]: https://www.gnu.org/licenses/gpl-2.0.html
[url-build]: https://github.com/wpallstars/wp-plugin-starter-template-for-ai-coding/actions/workflows/tests.yml
[url-requirements]: https://wordpress.org/about/requirements/
[url-wiki]: https://github.com/wpallstars/wp-plugin-starter-template-for-ai-coding/wiki
[url-coderabbit]: https://coderabbit.ai
[url-codefactor]: https://www.codefactor.io/repository/github/wpallstars/wp-plugin-starter-template-for-ai-coding
[url-sonar]: https://sonarcloud.io/summary/new_code?id=wpallstars_wp-plugin-starter-template-for-ai-coding
[url-codacy]: https://app.codacy.com/gh/wpallstars/wp-plugin-starter-template-for-ai-coding/dashboard
A comprehensive starter template for WordPress plugins with best practices for AI-assisted development.
## Description
The WordPress Plugin Starter Template provides a solid foundation for developing WordPress plugins. It incorporates best practices, modern coding standards, and a comprehensive structure that makes it easy to get started with plugin development.
The WordPress Plugin Starter Template provides a solid foundation for developing WordPress plugins.
This template is based on the experience gained from developing the "Fix 'Plugin file does not exist' Notices" plugin and other successful WordPress plugins.
It incorporates best practices, modern coding standards, and a comprehensive structure.
This template is based on experience from developing successful WordPress plugins.
### Key Features
@@ -39,9 +68,11 @@ This template includes comprehensive documentation for AI-assisted development:
* **AGENTS.md**: Guide for AI assistants to understand the project structure
* **.agents/**: Detailed workflow documentation for common development tasks
* **Starter Prompt**: Comprehensive prompt for AI tools to help customize the template (available in the [wiki](.wiki/Starter-Prompt.md))
* **Starter Prompt**: Prompt for AI tools to customize the template ([wiki](.wiki/Starter-Prompt.md))
**Important**: For the best AI assistance, add the AGENTS.md file and .agents/ directory to your AI IDE chat context. In most AI IDEs, you can pin these files to ensure they're considered in each message.
**Important**: For the best AI assistance, add AGENTS.md and .agents/ to your AI IDE chat context.
In most AI IDEs, you can pin these files to ensure they're considered in each message.
## Installation
@@ -60,16 +91,18 @@ This template includes comprehensive documentation for AI-assisted development:
To get started with this template, follow these steps:
1. In your terminal, navigate to the folder you keep you Git repositories (eg: `~/Git/`), then clone this repository to your local machine:
1. Navigate to your Git repositories folder (e.g., `~/Git/`), then clone:
```bash
git clone https://github.com/wpallstars/wp-plugin-starter-template-for-ai-coding.git
```
2. Open the [Starter Prompt](.wiki/Starter-Prompt.md) file and follow the instructions to customize the template for your plugin.
2. Open the [Starter Prompt](.wiki/Starter-Prompt.md) file and follow the instructions
to customize the template for your plugin.
3. Add the AGENTS.md file and .agents/ directory to your AI IDE chat context.
4. Use an AI assistant like GitHub Copilot, Claude, or ChatGPT to help you customize the template by providing the prompt from the Starter Prompt file.
4. Use an AI assistant like GitHub Copilot, Claude, or ChatGPT to help customize
the template by providing the prompt from the Starter Prompt file.
### Development Environment
@@ -85,16 +118,38 @@ This template includes configuration for WordPress Environment (wp-env) to make
npm run start
```
3. For multisite testing:
3. For testing in different WordPress environments:
```bash
npm run multisite
# For single site testing
npm run setup:single
# For multisite testing
npm run setup:multisite
```
See [Testing Framework](.wiki/Testing-Framework.md) for more details on our testing approach.
4. Access your local WordPress site at <http://localhost:8888> (admin credentials: admin/password)
### Testing
The template includes both PHP unit tests and end-to-end tests:
The template includes multiple testing approaches:
#### WordPress Playground Testing (No Docker Required)
Test your plugin directly in the browser without any local setup:
1. Single site testing:
[Open in WordPress Playground][playground-single-readme]
2. Multisite testing:
[Open in WordPress Playground][playground-multisite-readme]
[playground-single-readme]: https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/wpallstars/wp-plugin-starter-template-for-ai-coding/feature/testing-framework/playground/blueprint.json&_t=5
[playground-multisite-readme]: https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/wpallstars/wp-plugin-starter-template-for-ai-coding/feature/testing-framework/playground/multisite-blueprint.json&_t=18
For more details, see the [Playground Testing](.wiki/Playground-Testing.md) documentation.
#### PHP Unit Tests
@@ -176,7 +231,11 @@ This template includes functionality that allows users to choose where they want
### How do I customize this template for my plugin?
See the [Starter Prompt](.wiki/Starter-Prompt.md) file for detailed instructions on customizing this template for your specific plugin needs. Make sure to add the AGENTS.md file and .agents/ directory to your AI IDE chat context for the best results.
See the [Starter Prompt](.wiki/Starter-Prompt.md) file for detailed instructions on
customizing this template for your specific plugin needs.
Make sure to add the AGENTS.md file and .agents/ directory to your AI IDE chat context
for the best results.
### What files do I need to update with my plugin information?
@@ -208,15 +267,27 @@ This will create a ZIP file that you can install in WordPress.
### How do I add custom functionality to my plugin?
Customize the includes/core.php file to implement your core functionality and the admin/lib/admin.php file for admin-specific functionality.
Customize the `includes/core.php` file to implement your core functionality and the
`admin/lib/admin.php` file for admin-specific functionality.
### Is this template compatible with WordPress multisite?
Yes, this template is fully compatible with WordPress multisite installations. You can test multisite compatibility by running:
Yes, this template is fully compatible with WordPress multisite installations.
```bash
npm run multisite
```
We have a testing framework that allows you to verify functionality in both environments.
You can test multisite compatibility in two ways:
1. Using WordPress Playground (no Docker required):
* [Open Multisite in WordPress Playground][playground-multisite-readme]
2. Using wp-env (requires Docker):
```bash
npm run setup:multisite
```
For more details on our testing approach, see the [Testing Framework](.wiki/Testing-Framework.md)
and [Playground Testing](.wiki/Playground-Testing.md) documentation.
## Support & Feedback
@@ -229,7 +300,10 @@ If you need help with this template, there are several ways to get support:
Contributions are welcome! Please feel free to submit a Pull Request.
1. Fork the repository on [GitHub](https://github.com/wpallstars/wp-plugin-starter-template-for-ai-coding/) or [Gitea](https://gitea.wpallstars.com/wpallstars/wp-plugin-starter-template-for-ai-coding/)
1. Fork the repository on [GitHub][repo-github] or [Gitea][repo-gitea]
[repo-github]: https://github.com/wpallstars/wp-plugin-starter-template-for-ai-coding/
[repo-gitea]: https://gitea.wpallstars.com/wpallstars/wp-plugin-starter-template-for-ai-coding/
2. Create your feature branch: `git checkout -b feature/amazing-feature`
3. Commit your changes: `git commit -m 'Add some amazing feature'`
4. Push to the branch: `git push origin feature/amazing-feature`
@@ -239,7 +313,10 @@ For more detailed information, see the [Contributing Guide](.wiki/Contributing.m
### Code Quality Tools
This project uses several automated code quality tools to ensure high standards. These tools are free for public repositories and should be integrated into any new repositories based on this template:
This project uses several automated code quality tools to ensure high standards.
These tools are free for public repositories and should be integrated into any new
repositories based on this template:
1. **CodeRabbit**: AI-powered code review tool
* [Website](https://www.coderabbit.ai/)
@@ -259,7 +336,9 @@ This project uses several automated code quality tools to ensure high standards.
3. Go to your project settings > Integrations > Project API
4. Generate a project API token
5. Add the token as a secret named `CODACY_PROJECT_TOKEN` in your GitHub repository settings
6. Note: Codacy tokens are project-specific, so they need to be added at the repository level. However, you can use GitHub Actions to securely pass these tokens between repositories if needed.
6. Note: Codacy tokens are project-specific, so they need to be added at the
repository level. You can use GitHub Actions to securely pass tokens
between repositories if needed.
4. **SonarCloud**: Code quality and security analysis
* [Website](https://sonarcloud.io/)
@@ -270,7 +349,8 @@ This project uses several automated code quality tools to ensure high standards.
2. Create a new organization or use an existing one
3. Add your repository to SonarCloud
4. Generate a token in SonarCloud (Account > Security > Tokens)
5. Add the token as a secret named `SONAR_TOKEN` in your GitHub repository or organization settings (see "GitHub Secrets Management" section below)
5. Add the token as a secret named `SONAR_TOKEN` in your GitHub repository or
organization settings (see "GitHub Secrets Management" section below)
5. **PHP_CodeSniffer (PHPCS)**: PHP code style checker
* Enforces WordPress Coding Standards
@@ -300,7 +380,8 @@ When you receive feedback from these code quality tools, you can use AI assistan
4. Apply the suggested fixes
5. Commit the changes and verify that the issues are resolved
For more information on coding standards and how to pass code quality checks, see the [Coding Standards Guide](.wiki/Coding-Standards.md).
For more information on coding standards and how to pass code quality checks,
see the [Coding Standards Guide](.wiki/Coding-Standards.md).
### GitHub Secrets Management
@@ -318,7 +399,8 @@ GitHub offers three levels of secrets management, each with different scopes and
* Available at: Repository > Settings > Secrets and variables > Actions
* Scope: Limited to a single repository
* Benefits: Repository-specific, higher isolation
* Recommended for: `CODACY_PROJECT_TOKEN` and other repository-specific credentials or tokens that shouldn't be shared
* Recommended for: `CODACY_PROJECT_TOKEN` and other repository-specific credentials
or tokens that shouldn't be shared
3. **Environment Secrets**:
* Available at: Repository > Settings > Environments > (select environment) > Environment secrets
@@ -326,7 +408,12 @@ GitHub offers three levels of secrets management, each with different scopes and
* Benefits: Environment-specific, can have approval requirements
* Recommended for: Deployment credentials that vary between environments
For code quality tools like SonarCloud, organization secrets are recommended if you have multiple repositories that use these tools. This approach reduces management overhead and ensures consistent configuration across projects. For Codacy, since tokens are project-specific, they should be set at the repository level.
For code quality tools like SonarCloud, organization secrets are recommended if you have
multiple repositories that use these tools.
This approach reduces management overhead and ensures consistent configuration across
projects. For Codacy, since tokens are project-specific, they should be set at the
repository level.
### Local Environment Setup for Code Quality Tools
@@ -432,13 +519,16 @@ To run code quality tools locally before committing to GitHub:
For more detailed instructions, see the [Code Quality Setup Guide](docs/code-quality-setup.md).
By running these tools locally, you can identify and fix issues before pushing your code to GitHub, ensuring smoother CI/CD workflows.
By running these tools locally, you can identify and fix issues before pushing your code
to GitHub, ensuring smoother CI/CD workflows.
## Developers
### AI-Powered Development
This repository is configured to work with various AI-powered development tools. You can use any of the following AI IDEs to contribute to this project:
This repository is configured to work with various AI-powered development tools.
You can use any of the following AI IDEs to contribute to this project:
* [Augment Code](https://www.augmentcode.com/) - AI-powered coding assistant
* [Bolt](https://www.bolt.new/) - AI-powered code editor
@@ -455,9 +545,11 @@ The repository includes configuration files for all these tools to ensure a cons
### Git Updater Integration
This template is designed to work seamlessly with the Git Updater plugin for updates from GitHub and Gitea. To ensure proper integration:
This template is designed to work seamlessly with the Git Updater plugin for updates from
GitHub and Gitea. To ensure proper integration:
1. **Required Headers**: The plugin includes specific headers in the main plugin file that Git Updater uses to determine update sources and branches:
1. **Required Headers**: The plugin includes specific headers in the main plugin file
that Git Updater uses to determine update sources and branches:
```php
* GitHub Plugin URI: wpallstars/wp-plugin-starter-template-for-ai-coding
* GitHub Branch: main
@@ -468,13 +560,17 @@ This template is designed to work seamlessly with the Git Updater plugin for upd
* Gitea Branch: main
```
2. **Tagging Releases**: When creating a new release, always tag it with the 'v' prefix (e.g., `v0.1.2`) to ensure GitHub Actions can create the proper release assets.
2. **Tagging Releases**: When creating a new release, always tag it with the 'v' prefix
(e.g., `v0.1.2`) to ensure GitHub Actions can create the proper release assets.
3. **GitHub Actions**: The repository includes a GitHub Actions workflow that automatically builds the plugin and creates a release with the .zip file when a new tag is pushed.
3. **GitHub Actions**: The repository includes a GitHub Actions workflow that automatically
builds the plugin and creates a release with the .zip file when a new tag is pushed.
4. **Update Source Selection**: The template includes a feature that allows users to choose their preferred update source (WordPress.org, GitHub, or Gitea).
4. **Update Source Selection**: The template includes a feature that allows users to choose
their preferred update source (WordPress.org, GitHub, or Gitea).
For more information on Git Updater integration, see the [Git Updater Required Headers documentation](https://git-updater.com/knowledge-base/required-headers/).
For more information on Git Updater integration, see the
[Git Updater Required Headers documentation](https://git-updater.com/knowledge-base/required-headers/).
## Changelog
@@ -571,4 +667,7 @@ This project is licensed under the GPL-2.0+ License - see the [LICENSE](LICENSE)
## Credits
This template is based on the experience gained from developing the ["Fix 'Plugin file does not exist' Notices"](https://github.com/wpallstars/wp-fix-plugin-does-not-exist-notices) plugin by WPALLSTARS.
This template is based on the experience gained from developing the
["Fix 'Plugin file does not exist' Notices"][fix-plugin-notices] plugin by WPALLSTARS.
[fix-plugin-notices]: https://github.com/wpallstars/wp-fix-plugin-does-not-exist-notices

342
WARP.md Normal file
View File

@@ -0,0 +1,342 @@
# WARP.md
This file provides guidance to WARP (warp.dev) when working with code in this repository.
## Project Overview
**WordPress Plugin Starter Template** - A comprehensive starter template for WordPress plugins with best practices for AI-assisted development.
* **Plugin Slug**: wp-plugin-starter-template
* **Namespace**: `WPALLSTARS\PluginStarterTemplate`
* **Text Domain**: wp-plugin-starter-template
* **Requirements**: WordPress 5.0+, PHP 7.4+
* **License**: GPL-2.0+
## Common Development Commands
### Environment Setup
```bash
# Install dependencies
npm install
composer install
# Start local WordPress environment (requires Docker)
npm run start
# Stop WordPress environment
npm run stop
# Setup single-site test environment
npm run setup:single
# Setup multisite test environment
npm run setup:multisite
```
Local WordPress site runs at: <http://localhost:8888> (admin: admin/password)
### Testing
```bash
# PHP unit tests
npm run test:php
composer test
# E2E tests (Cypress)
npm run test:e2e:single
npm run test:e2e:multisite
# Run specific test configurations
npm run test:single # Interactive single-site
npm run test:multisite # Interactive multisite
npm run test:single:headless # Headless single-site
npm run test:multisite:headless # Headless multisite
# Playground tests (no Docker required)
npm run test:playground:single
npm run test:playground:multisite
```
### Code Quality & Linting
```bash
# PHP linting and fixing
npm run lint:php # Run PHPCS
npm run fix:php # Run PHPCBF
composer run phpcs # Run PHPCS directly
composer run phpcbf # Run PHPCBF directly
# Static analysis
npm run lint:phpstan # PHPStan
composer run phpstan
npm run lint:phpmd # PHP Mess Detector
composer run phpmd
# JavaScript linting
npm run lint:js
# Run all linters
npm run lint # Runs phpcs, phpstan, phpmd
composer run lint
# Run quality checks and tests
npm run quality
```
### Building & Release
```bash
# Build plugin ZIP for distribution
npm run build
# or
./build.sh {VERSION}
# Example:
./build.sh 1.0.0
```
The build script creates a deployable ZIP file in the repository root.
## Architecture Overview
### Plugin Initialization Flow
1. **Main Plugin File** (`wp-plugin-starter-template.php`):
* Defines constants (`WP_PLUGIN_STARTER_TEMPLATE_FILE`, `_PATH`, `_URL`, `_VERSION`)
* Registers custom autoloader for namespaced classes
* Instantiates `Plugin` class
* Calls `init()` method
2. **Autoloader**:
* Converts namespace `WPALLSTARS\PluginStarterTemplate` to file paths
* Looks for class files in `includes/` directory
* Uses PSR-4 naming with class file prefix conversion
3. **Plugin Class** (`includes/class-plugin.php`):
* Main orchestration class
* Instantiates `Core` and `Admin` classes
* Registers hooks and loads text domain
* Provides getters for version and admin instance
4. **Core Class** (`includes/class-core.php`):
* Contains core plugin functionality
* Provides version management
* Houses filter/action methods
5. **Admin Class** (`includes/Admin/class-admin.php`):
* Manages admin-specific functionality
* Handles admin menu, pages, and UI
### Directory Structure
```
wp-plugin-starter-template-for-ai-coding/
├── wp-plugin-starter-template.php # Main plugin file with headers
├── includes/ # Core plugin classes
│ ├── class-plugin.php # Main plugin orchestration
│ ├── class-core.php # Core functionality
│ ├── updater.php # Update mechanism
│ ├── Admin/ # Admin-specific classes
│ └── Multisite/ # Multisite-specific functionality
├── admin/ # Admin UI resources
│ ├── lib/ # Admin classes
│ ├── css/ # Admin stylesheets
│ ├── js/ # Admin JavaScript
│ └── templates/ # Admin template files
├── tests/ # PHPUnit and test files
├── cypress/ # E2E tests
├── .github/workflows/ # CI/CD workflows
├── .agents/ # AI assistant documentation
├── .wiki/ # Wiki documentation
└── languages/ # Translation files
```
### Key Architectural Patterns
* **Object-Oriented**: All functionality in namespaced classes
* **PSR-4 Autoloading**: Automatic class loading without require statements
* **Dependency Injection**: `Admin` receives `Core` instance via constructor
* **Separation of Concerns**: Core functionality, admin UI, and multisite features are isolated
* **Hook-Based**: WordPress hooks for extensibility
## Coding Standards
### PHP Standards (WordPress Coding Standards)
* **Indentation**: 4 spaces (project-specific override of WordPress tabs)
* **Naming Conventions**:
* Classes: `Class_Name`
* Functions: `function_name`
* Variables: `$variable_name`
* **Documentation**: DocBlocks required for all classes, methods, and functions
* **Internationalization**: All user-facing strings must be translatable with text domain `wp-plugin-starter-template`
### Markdown Standards
* Use asterisks (`*`) for bullet points, never hyphens (`-`)
* Add periods to the end of all inline comments
### Code Quality Tools
The project uses several automated tools integrated via CI/CD:
* **PHP_CodeSniffer**: Enforces WordPress Coding Standards
* **PHPCBF**: Auto-fixes coding standard violations
* **PHPStan**: Static analysis (level 5)
* **PHPMD**: Detects code complexity issues
* **ESLint**: JavaScript linting
* **Stylelint**: CSS linting
* **CodeRabbit, CodeFactor, Codacy, SonarCloud**: Continuous quality monitoring
Always run `npm run lint` or `composer run lint` before committing.
## Security Requirements
* Validate and sanitize all inputs (use `sanitize_*()` functions)
* Escape all outputs (use `esc_*()` functions)
* Use nonces for form submissions
* Check user capabilities before allowing actions
* Never expose secrets in plain text
## Release Process
### Version Numbering
Follow semantic versioning (MAJOR.MINOR.PATCH):
* **PATCH**: Bug fixes (1.0.0 → 1.0.1)
* **MINOR**: New features, backward-compatible (1.0.0 → 1.1.0)
* **MAJOR**: Breaking changes (1.0.0 → 2.0.0)
### Release Steps
1. Create version branch from main: `git checkout -b v{MAJOR}.{MINOR}.{PATCH}`
2. Update version in:
* `wp-plugin-starter-template.php` (header and constant)
* `readme.txt` (Stable tag and changelog)
* `README.md` (changelog)
* `CHANGELOG.md`
* `languages/wp-plugin-starter-template.pot`
3. Run code quality checks: `npm run quality`
4. Build plugin: `./build.sh {VERSION}`
5. Test thoroughly (single-site and multisite)
6. Commit: `git commit -m "Version {VERSION} - [description]"`
7. Tag: `git tag -a v{VERSION} -m "Version {VERSION}"`
8. Tag stable: `git tag -a v{VERSION}-stable -m "Stable version {VERSION}"`
9. Push to remotes: `git push github main --tags && git push gitea main --tags`
**Important**: Tags with 'v' prefix trigger GitHub Actions to build and create releases automatically.
## Git Updater Integration
This template works with the Git Updater plugin for updates from GitHub and Gitea.
Required headers in main plugin file:
```php
* GitHub Plugin URI: wpallstars/wp-plugin-starter-template-for-ai-coding
* GitHub Branch: main
* Gitea Plugin URI: https://gitea.wpallstars.com/wpallstars/wp-plugin-starter-template-for-ai-coding
* Gitea Branch: main
```
Users can choose their update source (WordPress.org, GitHub, or Gitea) via plugin settings.
## Testing Framework
### WordPress Playground Testing
Test without Docker using WordPress Playground blueprints:
* Single-site: <https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/wpallstars/wp-plugin-starter-template-for-ai-coding/feature/testing-framework/playground/blueprint.json>
* Multisite: <https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/wpallstars/wp-plugin-starter-template-for-ai-coding/feature/testing-framework/playground/multisite-blueprint.json>
### Local Testing with wp-env
`.wp-env.json` and `.wp-env.multisite.json` configure WordPress environments.
## AI-Assisted Development
This repository includes comprehensive AI workflow documentation in `.agents/`:
* `feature-development.md`: Adding new features
* `bug-fixing.md`: Diagnosing and fixing issues
* `release-process.md`: Creating releases
* `code-quality-checks.md`: Running quality tools
* `error-checking-feedback-loops.md`: Monitoring CI/CD
* `git-workflow.md`: Git best practices
* `wiki-documentation.md`: Maintaining documentation
Reference these workflows with `@.agents/{filename}` syntax.
## Multi-Repository Workspace Context
When working in a workspace with multiple repositories:
1. Always verify you're in the correct repository: `pwd` and `git remote -v`
2. Never assume features from other repositories exist here
3. Don't hallucinate functionality from other repositories in the workspace
4. Each repository has its own specific purpose and feature set
5. Repository-specific documentation reflects only actual features in this repository
## GitHub Actions Workflows
* `tests.yml`: PHPUnit tests
* `phpunit.yml`: Additional PHPUnit configurations
* `code-quality.yml`: Runs PHPCS, PHPStan, PHPMD
* `sonarcloud.yml`: SonarCloud analysis
* `playground-tests.yml`: Tests in WordPress Playground
* `release.yml`: Creates releases when tags are pushed
* `sync-wiki.yml`: Syncs `.wiki/` to GitHub wiki
Workflows run automatically on push and pull requests.
## Internationalization (i18n)
All user-facing strings must use translation functions:
```php
// Simple strings
__('Text', 'wp-plugin-starter-template')
// Echoed strings
_e('Text', 'wp-plugin-starter-template')
// Escaped strings
esc_html__('Text', 'wp-plugin-starter-template')
// Escaped and echoed
esc_html_e('Text', 'wp-plugin-starter-template')
```
Translation files are in `languages/` directory.
## Multisite Compatibility
Fully compatible with WordPress multisite. Multisite-specific functionality is in `includes/Multisite/`.
Test multisite with:
* `npm run setup:multisite`
* `npm run test:e2e:multisite`
* WordPress Playground multisite blueprint
## Documentation Maintenance
When adding features or making changes:
1. Update `CHANGELOG.md` and `readme.txt` changelog
2. Update `README.md` if user-facing functionality changes
3. Update `.wiki/` documentation (syncs to GitHub wiki)
4. Update inline code comments and DocBlocks
5. Follow markdown standards (asterisks for bullets, periods in comments)
## Reference
* WordPress Coding Standards: <https://developer.wordpress.org/coding-standards/>
* Git Updater Headers: <https://git-updater.com/knowledge-base/required-headers/>
* Testing Framework: `.wiki/Testing-Framework.md`
* Playground Testing: `.wiki/Playground-Testing.md`
* Code Quality Setup: `docs/code-quality-setup.md`

160
bin/install-wp-tests.sh Executable file
View File

@@ -0,0 +1,160 @@
#!/usr/bin/env bash
if [ $# -lt 3 ]; then
echo "usage: $0 <db-name> <db-user> <db-pass> [db-host] [wp-version] [skip-database-creation] [multisite]"
exit 1
fi
DB_NAME=$1
DB_USER=$2
DB_PASS=$3
DB_HOST=${4-localhost}
WP_VERSION=${5-latest}
SKIP_DB_CREATE=${6-false}
MULTISITE=${7-false}
WP_TESTS_DIR=${WP_TESTS_DIR-/tmp/wordpress-tests-lib}
WP_CORE_DIR=${WP_CORE_DIR-/tmp/wordpress/}
download() {
if command -v curl > /dev/null; then
curl -s "$1" > "$2";
elif command -v wget > /dev/null; then
wget -nv -O "$2" "$1"
fi
}
if [[ $WP_VERSION =~ ^[0-9]+\.[0-9]+\-(beta|RC)[0-9]+$ ]]; then
WP_BRANCH=${WP_VERSION%\-*}
elif [[ $WP_VERSION =~ ^[0-9]+\.[0-9]+$ ]]; then
WP_TESTS_TAG="branches/$WP_VERSION"
elif [[ $WP_VERSION =~ [0-9]+\.[0-9]+\.[0-9]+ ]]; then
if [[ $WP_VERSION =~ [0-9]+\.[0-9]+\.[0] ]]; then
# version x.x.0 means the first release of the major version, so strip off the .0 and download version x.x
WP_TESTS_TAG="tags/${WP_VERSION%??}"
else
WP_TESTS_TAG="tags/$WP_VERSION"
fi
elif [[ $WP_VERSION == 'nightly' || $WP_VERSION == 'trunk' ]]; then
WP_TESTS_TAG="trunk"
else
# http serves a single offer, whereas https serves multiple. we only want one
download http://api.wordpress.org/core/version-check/1.7/ /tmp/wp-latest.json
grep '[0-9]+\.[0-9]+(\.[0-9]+)?' /tmp/wp-latest.json
LATEST_VERSION=$(grep -o '"version":"[^"]*' /tmp/wp-latest.json | sed 's/"version":"//')
if [[ -z "$LATEST_VERSION" ]]; then
echo "Latest WordPress version could not be found"
exit 1
fi
WP_TESTS_TAG="tags/$LATEST_VERSION"
fi
set -ex
install_wp() {
if [ -d "$WP_CORE_DIR" ]; then
return;
fi
mkdir -p "$WP_CORE_DIR"
if [[ $WP_VERSION == 'nightly' || $WP_VERSION == 'trunk' ]]; then
mkdir -p "$WP_CORE_DIR"
download https://wordpress.org/nightly-builds/wordpress-latest.zip "$WP_CORE_DIR/wordpress-nightly.zip"
unzip -q "$WP_CORE_DIR/wordpress-nightly.zip" -d "$WP_CORE_DIR"
rm "$WP_CORE_DIR/wordpress-nightly.zip"
else
if [ "$WP_VERSION" == 'latest' ]; then
local ARCHIVE_NAME='latest'
elif [[ $WP_VERSION =~ [0-9]+\.[0-9]+ ]]; then
download https://api.wordpress.org/core/version-check/1.7/ "$WP_CORE_DIR/wp-latest.json"
if [[ $WP_VERSION =~ [0-9]+\.[0-9]+\.[0] ]]; then
LATEST_VERSION=${WP_VERSION%??}
else
VERSION_ESCAPED=$(echo "$WP_VERSION" | sed 's/\./\\\\./g')
LATEST_VERSION=$(grep -o '"version":"'"$VERSION_ESCAPED"'[^"]*' "$WP_CORE_DIR/wp-latest.json" | sed 's/"version":"//' | head -1)
fi
if [[ -z "$LATEST_VERSION" ]]; then
local ARCHIVE_NAME="wordpress-$WP_VERSION"
else
local ARCHIVE_NAME="wordpress-$LATEST_VERSION"
fi
else
local ARCHIVE_NAME="wordpress-$WP_VERSION"
fi
download https://wordpress.org/"${ARCHIVE_NAME}".tar.gz "$WP_CORE_DIR/wordpress.tar.gz"
tar --strip-components=1 -zxmf "$WP_CORE_DIR/wordpress.tar.gz" -C "$WP_CORE_DIR"
rm "$WP_CORE_DIR/wordpress.tar.gz"
fi
download https://raw.github.com/markoheijnen/wp-mysqli/master/db.php "$WP_CORE_DIR/wp-content/db.php"
}
install_test_suite() {
# portable in-place argument for both GNU sed and Mac OSX sed
if [[ $(uname -s) == 'Darwin' ]]; then
local ioption='-i.bak'
else
local ioption='-i'
fi
# set up testing suite if it doesn't yet exist
if [ ! -d "$WP_TESTS_DIR" ]; then
mkdir -p "$WP_TESTS_DIR"
git clone --quiet --depth=1 https://github.com/WordPress/wordpress-develop.git /tmp/wordpress-develop
if [ -d /tmp/wordpress-develop/tests/phpunit/includes ]; then
cp -r /tmp/wordpress-develop/tests/phpunit/includes "$WP_TESTS_DIR/"
fi
if [ -d /tmp/wordpress-develop/tests/phpunit/data ]; then
cp -r /tmp/wordpress-develop/tests/phpunit/data "$WP_TESTS_DIR/"
fi
fi
if [ ! -f wp-tests-config.php ]; then
if [ -f /tmp/wordpress-develop/wp-tests-config-sample.php ]; then
cp /tmp/wordpress-develop/wp-tests-config-sample.php "$WP_TESTS_DIR"/wp-tests-config.php
else
download https://raw.githubusercontent.com/WordPress/wordpress-develop/master/wp-tests-config-sample.php "$WP_TESTS_DIR"/wp-tests-config.php
fi
WP_CORE_DIR=$(echo "$WP_CORE_DIR" | sed "s:/\+$::")
sed $ioption "s:dirname( __FILE__ ) . '/src/':'$WP_CORE_DIR/':" "$WP_TESTS_DIR"/wp-tests-config.php
sed $ioption "s/youremptytestdbnamehere/$DB_NAME/" "$WP_TESTS_DIR"/wp-tests-config.php
sed $ioption "s/yourusernamehere/$DB_USER/" "$WP_TESTS_DIR"/wp-tests-config.php
sed $ioption "s/yourpasswordhere/$DB_PASS/" "$WP_TESTS_DIR"/wp-tests-config.php
sed $ioption "s|localhost|${DB_HOST}|" "$WP_TESTS_DIR"/wp-tests-config.php
if [ "$MULTISITE" = "true" ]; then
sed $ioption "s:// define( 'WP_TESTS_MULTISITE', true );:define( 'WP_TESTS_MULTISITE', true );:" "$WP_TESTS_DIR"/wp-tests-config.php
fi
fi
}
install_db() {
if [ ${SKIP_DB_CREATE} = "true" ]; then
return 0
fi
local PARTS
IFS=':' read -ra PARTS <<< "$DB_HOST"
local DB_HOSTNAME=${PARTS[0]};
local DB_SOCK_OR_PORT=${PARTS[1]};
local EXTRA=""
if [ -n "$DB_HOSTNAME" ] ; then
if [[ $DB_SOCK_OR_PORT =~ ^[0-9]+$ ]]; then
EXTRA=" --host=$DB_HOSTNAME --port=$DB_SOCK_OR_PORT --protocol=tcp"
elif [ -n "$DB_SOCK_OR_PORT" ] ; then
EXTRA=" --socket=$DB_SOCK_OR_PORT"
elif [ -n "$DB_HOSTNAME" ] ; then
EXTRA=" --host=$DB_HOSTNAME --protocol=tcp"
fi
fi
mysqladmin create "$DB_NAME" --user="$DB_USER" --password="$DB_PASS"$EXTRA || true
}
install_wp
install_test_suite
install_db

413
bin/localwp-setup.sh Executable file
View File

@@ -0,0 +1,413 @@
#!/bin/bash
# LocalWP Integration Script for WordPress Plugin Development
# For use by AI coding assistants and developers
#
# This script manages LocalWP sites for testing the plugin.
# Creates standardized test sites with consistent URLs.
#
# URL Patterns:
# Single site: {plugin-slug}-single.local
# Multisite: {plugin-slug}-multisite.local
#
# Usage:
# ./bin/localwp-setup.sh create [--multisite]
# ./bin/localwp-setup.sh sync
# ./bin/localwp-setup.sh reset
# ./bin/localwp-setup.sh info
#
# Examples:
# npm run localwp:create # Create single site
# npm run localwp:create:multisite # Create multisite
# npm run localwp:sync # Sync plugin files
# npm run localwp:reset # Reset to clean state
set -e
# Configuration
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PROJECT_DIR="$(dirname "$SCRIPT_DIR")"
PLUGIN_SLUG="wp-plugin-starter-template"
PLUGIN_TEXT_DOMAIN="wp-plugin-starter-template"
# LocalWP paths (macOS)
LOCAL_SITES_DIR="$HOME/Local Sites"
LOCAL_APP="/Applications/Local.app"
LOCAL_WP_CLI="$LOCAL_APP/Contents/Resources/extraResources/bin/wp-cli/posix/wp"
# Site configurations
SINGLE_SITE_NAME="${PLUGIN_SLUG}-single"
MULTISITE_NAME="${PLUGIN_SLUG}-multisite"
SINGLE_SITE_DOMAIN="${SINGLE_SITE_NAME}.local"
MULTISITE_DOMAIN="${MULTISITE_NAME}.local"
# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
CYAN='\033[0;36m'
NC='\033[0m' # No Color
# Helper functions
log_info() {
echo -e "${BLUE}[INFO]${NC} $1"
}
log_success() {
echo -e "${GREEN}[SUCCESS]${NC} $1"
}
log_warning() {
echo -e "${YELLOW}[WARNING]${NC} $1"
}
log_error() {
echo -e "${RED}[ERROR]${NC} $1"
}
log_step() {
echo -e "${CYAN}[STEP]${NC} $1"
}
# Check if LocalWP is installed
check_localwp() {
if [ ! -d "$LOCAL_APP" ]; then
log_error "LocalWP is not installed at $LOCAL_APP"
log_info "Download from: https://localwp.com/"
exit 1
fi
if [ ! -f "$LOCAL_WP_CLI" ]; then
log_error "WP-CLI not found in LocalWP installation"
exit 1
fi
local version=$("$LOCAL_WP_CLI" --version 2>/dev/null || echo "unknown")
log_info "LocalWP WP-CLI version: $version"
}
# Get site path
get_site_path() {
local site_name="$1"
echo "$LOCAL_SITES_DIR/$site_name"
}
# Get WordPress path within site
get_wp_path() {
local site_name="$1"
local site_path=$(get_site_path "$site_name")
# LocalWP uses app/public for WordPress files
echo "$site_path/app/public"
}
# Check if site exists
site_exists() {
local site_name="$1"
local site_path=$(get_site_path "$site_name")
[ -d "$site_path" ]
}
# Get plugin destination path
get_plugin_path() {
local site_name="$1"
local wp_path=$(get_wp_path "$site_name")
echo "$wp_path/wp-content/plugins/$PLUGIN_SLUG"
}
# Sync plugin files to LocalWP site
sync_plugin() {
local site_name="$1"
local plugin_dest=$(get_plugin_path "$site_name")
if ! site_exists "$site_name"; then
log_error "Site '$site_name' does not exist"
return 1
fi
log_info "Syncing plugin to $site_name..."
# Create plugin directory if it doesn't exist
mkdir -p "$plugin_dest"
# Sync files using rsync (excludes dev files)
rsync -av --delete \
--exclude 'node_modules' \
--exclude 'vendor' \
--exclude '.git' \
--exclude 'dist' \
--exclude 'tests' \
--exclude 'cypress' \
--exclude '.github' \
--exclude '.agents' \
--exclude '.wiki' \
--exclude 'reference-plugins' \
--exclude '*.zip' \
--exclude '.playground.*' \
--exclude 'composer.lock' \
--exclude 'package-lock.json' \
"$PROJECT_DIR/" "$plugin_dest/"
log_success "Plugin synced to: $plugin_dest"
}
# Create a new LocalWP site
create_site() {
local multisite=false
# Parse arguments
while [[ $# -gt 0 ]]; do
case "$1" in
--multisite)
multisite=true
shift
;;
*)
shift
;;
esac
done
local site_name="$SINGLE_SITE_NAME"
local domain="$SINGLE_SITE_DOMAIN"
local mode="single site"
if [ "$multisite" = true ]; then
site_name="$MULTISITE_NAME"
domain="$MULTISITE_DOMAIN"
mode="multisite"
fi
check_localwp
local site_path=$(get_site_path "$site_name")
if site_exists "$site_name"; then
log_warning "Site '$site_name' already exists at: $site_path"
log_info "Use 'npm run localwp:reset' to reset it, or 'npm run localwp:sync' to update files"
return 0
fi
echo ""
echo "============================================"
echo " LocalWP Site Setup ($mode)"
echo "============================================"
echo ""
echo "This script will guide you through creating a"
echo "LocalWP site for testing the plugin."
echo ""
echo "Site Details:"
echo " Name: $site_name"
echo " Domain: $domain"
echo " Path: $site_path"
echo ""
log_step "Creating LocalWP Site"
echo ""
log_info "LocalWP doesn't have a CLI for site creation."
log_info "Please create the site manually in LocalWP:"
echo ""
echo "1. Open LocalWP application"
echo "2. Click the '+' button to create a new site"
echo "3. Use these settings:"
echo " - Site name: ${CYAN}$site_name${NC}"
echo " - Local site domain: ${CYAN}$domain${NC}"
echo " - PHP version: 8.0 or higher"
echo " - Web server: nginx (preferred)"
echo " - MySQL version: 8.0+"
if [ "$multisite" = true ]; then
echo ""
echo "4. After site creation, convert to multisite:"
echo " - Open Site Shell in LocalWP"
echo " - Run: wp core multisite-convert --subdomains=0"
echo " - Update wp-config.php if needed"
fi
echo ""
log_info "After creating the site, run: npm run localwp:sync"
echo ""
# Wait for user to create site
read -p "Press Enter after you've created the site in LocalWP..."
if site_exists "$site_name"; then
log_success "Site detected at: $site_path"
sync_plugin "$site_name"
# Install recommended plugins
install_recommended_plugins "$site_name"
show_site_info "$site_name" "$domain" "$multisite"
else
log_warning "Site not found at expected location"
log_info "Expected path: $site_path"
log_info "You can run 'npm run localwp:sync' later to sync files"
fi
}
# Install recommended plugins (matching Playground blueprint)
install_recommended_plugins() {
local site_name="$1"
local wp_path=$(get_wp_path "$site_name")
log_info "Note: Install these plugins to match Playground environment:"
echo " - Plugin Toggle (plugin-toggle)"
echo " - Kadence Blocks (kadence-blocks)"
echo ""
log_info "You can install them via LocalWP's WP Admin or Site Shell"
}
# Show site information
show_site_info() {
local site_name="$1"
local domain="$2"
local multisite="$3"
local site_path=$(get_site_path "$site_name")
local plugin_path=$(get_plugin_path "$site_name")
echo ""
echo "============================================"
echo " LocalWP Site Ready"
echo "============================================"
echo " Site: $site_name"
echo " URL: http://$domain"
echo " Admin: http://$domain/wp-admin/"
echo " Plugin Path: $plugin_path"
echo "============================================"
if [ "$multisite" = true ]; then
echo " Network Admin: http://$domain/wp-admin/network/"
echo "============================================"
fi
echo ""
log_info "Remember to:"
echo " 1. Start the site in LocalWP"
echo " 2. Activate the plugin in WordPress admin"
echo " 3. Run 'npm run localwp:sync' after making changes"
echo ""
}
# Reset site to clean state
reset_site() {
local site_name="${1:-$SINGLE_SITE_NAME}"
if ! site_exists "$site_name"; then
log_error "Site '$site_name' does not exist"
exit 1
fi
log_warning "This will delete the plugin files and resync them."
read -p "Continue? (y/n) " -n 1 -r
echo
if [[ $REPLY =~ ^[Yy]$ ]]; then
local plugin_path=$(get_plugin_path "$site_name")
log_info "Removing plugin files..."
rm -rf "$plugin_path"
log_info "Resyncing plugin..."
sync_plugin "$site_name"
log_success "Site reset complete"
else
log_info "Reset cancelled"
fi
}
# Sync all existing sites
sync_all() {
local synced=0
for site_name in "$SINGLE_SITE_NAME" "$MULTISITE_NAME"; do
if site_exists "$site_name"; then
sync_plugin "$site_name"
synced=$((synced + 1))
fi
done
if [ $synced -eq 0 ]; then
log_warning "No LocalWP sites found for this plugin"
log_info "Run 'npm run localwp:create' to create one"
else
log_success "Synced $synced site(s)"
fi
}
# Show info about all sites
show_info() {
echo ""
echo "LocalWP Sites for $PLUGIN_SLUG"
echo "==============================="
for site_name in "$SINGLE_SITE_NAME" "$MULTISITE_NAME"; do
local site_path=$(get_site_path "$site_name")
if site_exists "$site_name"; then
echo ""
echo " ${GREEN}✓${NC} $site_name"
echo " Path: $site_path"
local plugin_path=$(get_plugin_path "$site_name")
if [ -d "$plugin_path" ]; then
echo " Plugin: ${GREEN}Installed${NC}"
else
echo " Plugin: ${YELLOW}Not synced${NC}"
fi
else
echo ""
echo " ${YELLOW}○${NC} $site_name (not created)"
fi
done
echo ""
echo "Commands:"
echo " npm run localwp:create Create single site"
echo " npm run localwp:create:multisite Create multisite"
echo " npm run localwp:sync Sync plugin files"
echo " npm run localwp:reset Reset plugin files"
echo ""
}
# Main command handler
case "${1:-}" in
create)
shift
create_site "$@"
;;
sync)
sync_all
;;
reset)
shift
reset_site "$@"
;;
info)
show_info
;;
*)
echo "LocalWP Integration Script"
echo ""
echo "Usage:"
echo " $0 create [--multisite] Create a new LocalWP site"
echo " $0 sync Sync plugin files to all sites"
echo " $0 reset [site-name] Reset site plugin to clean state"
echo " $0 info Show info about LocalWP sites"
echo ""
echo "npm scripts:"
echo " npm run localwp:create Create single site"
echo " npm run localwp:create:multisite Create multisite"
echo " npm run localwp:sync Sync plugin files"
echo " npm run localwp:reset Reset plugin files"
echo ""
echo "URL Patterns:"
echo " Single site: http://${PLUGIN_SLUG}-single.local"
echo " Multisite: http://${PLUGIN_SLUG}-multisite.local"
echo ""
exit 1
;;
esac

303
bin/playground-test.sh Executable file
View File

@@ -0,0 +1,303 @@
#!/bin/bash
# WordPress Playground CLI Testing Script
# For use by AI coding assistants and developers
#
# This script provides a simple interface to start/stop WordPress Playground
# for local testing with the plugin. Uses @wp-playground/cli 3.0.22+
#
# Usage:
# ./bin/playground-test.sh start [--multisite] [--port PORT]
# ./bin/playground-test.sh stop
# ./bin/playground-test.sh status
#
# Examples:
# npm run playground:start # Start single site on port 8888
# npm run playground:start:multisite # Start multisite on port 8889
# npm run playground:stop # Stop all playground instances
# npm run playground:status # Check if playground is running
set -e
# Configuration
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PROJECT_DIR="$(dirname "$SCRIPT_DIR")"
PID_FILE="$PROJECT_DIR/.playground.pid"
DEFAULT_PORT=8888
MULTISITE_PORT=8889
PLUGIN_SLUG="wp-plugin-starter-template"
# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m' # No Color
# Helper functions
log_info() {
echo -e "${BLUE}[INFO]${NC} $1"
}
log_success() {
echo -e "${GREEN}[SUCCESS]${NC} $1"
}
log_warning() {
echo -e "${YELLOW}[WARNING]${NC} $1"
}
log_error() {
echo -e "${RED}[ERROR]${NC} $1"
}
# Check if @wp-playground/cli is installed
check_cli() {
if ! npx @wp-playground/cli --version > /dev/null 2>&1; then
log_error "@wp-playground/cli is not installed"
log_info "Run: npm install"
exit 1
fi
local version=$(npx @wp-playground/cli --version 2>/dev/null)
log_info "Using @wp-playground/cli version: $version"
}
# Create plugin zip for installation
create_plugin_zip() {
log_info "Creating plugin zip..."
mkdir -p "$PROJECT_DIR/dist"
cd "$PROJECT_DIR"
zip -r "dist/$PLUGIN_SLUG.zip" . \
-x "node_modules/*" \
-x "dist/*" \
-x ".git/*" \
-x "vendor/*" \
-x "tests/*" \
-x "cypress/*" \
-x "*.zip" \
-x ".github/*" \
-x ".agents/*" \
-x ".wiki/*" \
-x "reference-plugins/*" \
> /dev/null 2>&1
log_success "Plugin zip created: dist/$PLUGIN_SLUG.zip"
}
# Start WordPress Playground
start_playground() {
local multisite=false
local port=$DEFAULT_PORT
local blueprint="$PROJECT_DIR/playground/blueprint.json"
# Parse arguments
while [[ $# -gt 0 ]]; do
case "$1" in
--multisite)
multisite=true
port=$MULTISITE_PORT
blueprint="$PROJECT_DIR/playground/multisite-blueprint.json"
shift
;;
--port)
port="$2"
shift 2
;;
*)
shift
;;
esac
done
# Check if already running
if [ -f "$PID_FILE" ]; then
local old_pid=$(cat "$PID_FILE")
if kill -0 "$old_pid" 2>/dev/null; then
log_warning "Playground is already running (PID: $old_pid)"
log_info "Run 'npm run playground:stop' first to restart"
exit 1
else
rm -f "$PID_FILE"
fi
fi
# Check port availability
if lsof -i ":$port" > /dev/null 2>&1; then
log_error "Port $port is already in use"
exit 1
fi
check_cli
create_plugin_zip
local mode="single site"
if [ "$multisite" = true ]; then
mode="multisite"
fi
log_info "Starting WordPress Playground ($mode) on port $port..."
log_info "Blueprint: $blueprint"
# Start the server in background
cd "$PROJECT_DIR"
npx @wp-playground/cli server \
--blueprint "$blueprint" \
--port "$port" \
--login \
> "$PROJECT_DIR/.playground.log" 2>&1 &
local server_pid=$!
echo "$server_pid" > "$PID_FILE"
# Wait for server to be ready
log_info "Waiting for server to be ready..."
local timeout=120
local elapsed=0
while ! curl -s "http://localhost:$port" > /dev/null 2>&1; do
if [ $elapsed -ge $timeout ]; then
log_error "Timeout waiting for WordPress Playground to start"
log_info "Check logs: cat $PROJECT_DIR/.playground.log"
kill "$server_pid" 2>/dev/null || true
rm -f "$PID_FILE"
exit 1
fi
# Check if process is still running
if ! kill -0 "$server_pid" 2>/dev/null; then
log_error "Server process died unexpectedly"
log_info "Check logs: cat $PROJECT_DIR/.playground.log"
rm -f "$PID_FILE"
exit 1
fi
sleep 2
elapsed=$((elapsed + 2))
echo -ne "\r${BLUE}[INFO]${NC} Waiting... $elapsed/$timeout seconds"
done
echo ""
log_success "WordPress Playground is ready!"
echo ""
echo "============================================"
echo " WordPress Playground ($mode)"
echo "============================================"
echo " URL: http://localhost:$port"
echo " Admin: http://localhost:$port/wp-admin/"
echo " Login: admin / password"
echo " PID: $server_pid"
echo "============================================"
echo ""
log_info "Run 'npm run playground:stop' to stop the server"
log_info "Logs: $PROJECT_DIR/.playground.log"
}
# Stop WordPress Playground
stop_playground() {
if [ -f "$PID_FILE" ]; then
local pid=$(cat "$PID_FILE")
if kill -0 "$pid" 2>/dev/null; then
log_info "Stopping WordPress Playground (PID: $pid)..."
kill "$pid" 2>/dev/null || true
# Wait for process to stop
local timeout=10
local elapsed=0
while kill -0 "$pid" 2>/dev/null && [ $elapsed -lt $timeout ]; do
sleep 1
elapsed=$((elapsed + 1))
done
# Force kill if still running
if kill -0 "$pid" 2>/dev/null; then
log_warning "Force killing process..."
kill -9 "$pid" 2>/dev/null || true
fi
log_success "WordPress Playground stopped"
else
log_warning "Process not running"
fi
rm -f "$PID_FILE"
else
log_warning "No PID file found. Playground may not be running."
fi
# Clean up any orphaned processes on common ports
for port in $DEFAULT_PORT $MULTISITE_PORT; do
local orphan_pid=$(lsof -t -i ":$port" 2>/dev/null || true)
if [ -n "$orphan_pid" ]; then
log_info "Found process on port $port (PID: $orphan_pid), stopping..."
kill "$orphan_pid" 2>/dev/null || true
fi
done
}
# Check status
check_status() {
echo ""
echo "WordPress Playground Status"
echo "============================"
if [ -f "$PID_FILE" ]; then
local pid=$(cat "$PID_FILE")
if kill -0 "$pid" 2>/dev/null; then
log_success "Running (PID: $pid)"
else
log_warning "PID file exists but process not running"
rm -f "$PID_FILE"
fi
else
log_info "Not running (no PID file)"
fi
echo ""
echo "Port Status:"
for port in $DEFAULT_PORT $MULTISITE_PORT; do
if lsof -i ":$port" > /dev/null 2>&1; then
local port_pid=$(lsof -t -i ":$port" 2>/dev/null || echo "unknown")
echo " Port $port: ${GREEN}IN USE${NC} (PID: $port_pid)"
# Test if it's responding
if curl -s "http://localhost:$port" > /dev/null 2>&1; then
echo " └─ HTTP: ${GREEN}OK${NC}"
else
echo " └─ HTTP: ${RED}NOT RESPONDING${NC}"
fi
else
echo " Port $port: ${YELLOW}AVAILABLE${NC}"
fi
done
echo ""
}
# Main command handler
case "${1:-}" in
start)
shift
start_playground "$@"
;;
stop)
stop_playground
;;
status)
check_status
;;
*)
echo "WordPress Playground CLI Testing Script"
echo ""
echo "Usage:"
echo " $0 start [--multisite] [--port PORT] Start WordPress Playground"
echo " $0 stop Stop WordPress Playground"
echo " $0 status Check playground status"
echo ""
echo "npm scripts:"
echo " npm run playground:start Start single site"
echo " npm run playground:start:multisite Start multisite"
echo " npm run playground:stop Stop playground"
echo " npm run playground:status Check status"
echo ""
exit 1
;;
esac

289
bin/setup-test-env.sh Executable file
View File

@@ -0,0 +1,289 @@
#!/bin/bash
# Make this script executable
chmod +x "$0"
# Check if environment type is provided
if [ -z "$1" ]; then
echo "Usage: $0 [single|multisite|playground-single|playground-multisite]"
exit 1
fi
ENV_TYPE=$1
# Function to check if a command exists
command_exists() {
command -v "$1" &> /dev/null
}
# Function to install wp-env if needed
install_wp_env() {
if ! command_exists wp-env; then
echo "wp-env is not installed. Installing..."
npm install -g @wordpress/env
fi
}
# Function to install wp-playground if needed
install_wp_playground() {
# Check if we have a local installation
if [ ! -d "node_modules/@wp-playground" ]; then
echo "WordPress Playground is not installed locally. Installing..."
npm install --save-dev @wp-playground/client @wp-playground/blueprints
fi
}
if [ "$ENV_TYPE" == "single" ]; then
echo "Setting up single site environment..."
# Install wp-env if needed
install_wp_env
# Start the environment
wp-env start
# Wait for WordPress to be ready with a timeout
MAX_ATTEMPTS=30
ATTEMPT=0
echo "Waiting for WordPress to be ready..."
until wp-env run cli wp core is-installed || [ $ATTEMPT -ge $MAX_ATTEMPTS ]; do
ATTEMPT=$((ATTEMPT+1))
echo "Attempt $ATTEMPT/$MAX_ATTEMPTS..."
sleep 2
done
if [ $ATTEMPT -ge $MAX_ATTEMPTS ]; then
echo "Timed out waiting for WordPress to be ready."
exit 1
fi
# Activate our plugin
if ! wp-env run cli wp plugin activate wp-plugin-starter-template-for-ai-coding; then
echo "Failed to activate plugin. Exiting."
exit 1
fi
echo "WordPress Single Site environment is ready!"
echo "Site: http://localhost:8888"
echo "Admin login: admin / password"
elif [ "$ENV_TYPE" == "multisite" ]; then
echo "Setting up multisite environment..."
# Install wp-env if needed
install_wp_env
# Start the environment with multisite configuration
wp-env start --config=.wp-env.multisite.json
# Wait for WordPress to be ready with a timeout
MAX_ATTEMPTS=30
ATTEMPT=0
echo "Waiting for WordPress to be ready..."
until wp-env run cli wp core is-installed || [ $ATTEMPT -ge $MAX_ATTEMPTS ]; do
ATTEMPT=$((ATTEMPT+1))
echo "Attempt $ATTEMPT/$MAX_ATTEMPTS..."
sleep 2
done
if [ $ATTEMPT -ge $MAX_ATTEMPTS ]; then
echo "Timed out waiting for WordPress to be ready."
exit 1
fi
# Create a test site
if ! wp-env run cli wp site create --slug=testsite --title="Test Site" --email=admin@example.com; then
echo "Failed to create test site. Exiting."
exit 1
fi
# Network activate our plugin
if ! wp-env run cli wp plugin activate wp-plugin-starter-template-for-ai-coding --network; then
echo "Failed to activate plugin. Exiting."
exit 1
fi
echo "WordPress Multisite environment is ready!"
echo "Main site: http://localhost:8888"
echo "Test site: http://localhost:8888/testsite"
echo "Admin login: admin / password"
elif [ "$ENV_TYPE" == "playground-single" ]; then
echo "Setting up WordPress Playground single site environment..."
# Install wp-playground if needed
install_wp_playground
# Create plugin zip
echo "Creating plugin zip..."
mkdir -p dist
zip -r dist/plugin.zip . -x "node_modules/*" "dist/*" ".git/*"
# Update blueprint to use local plugin
cat > playground/blueprint.json << EOF
{
"landingPage": "/wp-admin/",
"preferredVersions": {
"php": "8.0",
"wp": "latest"
},
"steps": [
{
"step": "login",
"username": "admin",
"password": "password"
},
{
"step": "installPlugin",
"pluginZipFile": {
"resource": "local",
"path": "dist/plugin.zip"
}
},
{
"step": "activatePlugin",
"pluginSlug": "wp-plugin-starter-template-for-ai-coding"
}
]
}
EOF
# Start WordPress Playground
echo "Starting WordPress Playground..."
if command_exists python3; then
python3 -m http.server 8888 --directory playground &
echo "Opening WordPress Playground in your browser..."
if command_exists open; then
open http://localhost:8888/index.html
elif command_exists xdg-open; then
xdg-open http://localhost:8888/index.html
elif command_exists start; then
start http://localhost:8888/index.html
else
echo "Please open http://localhost:8888/index.html in your browser"
fi
else
echo "Python3 is not installed. Please open playground/index.html in your browser."
fi
# Wait for WordPress Playground to be ready
echo "Waiting for WordPress Playground to be ready..."
sleep 5
echo "WordPress Playground Single Site environment is ready!"
echo "Site: http://localhost:8888"
echo "Admin login: admin / password"
echo "Press Ctrl+C to stop the server when done."
elif [ "$ENV_TYPE" == "playground-multisite" ]; then
echo "Setting up WordPress Playground multisite environment..."
# Install wp-playground if needed
install_wp_playground
# Create plugin zip
echo "Creating plugin zip..."
mkdir -p dist
zip -r dist/plugin.zip . -x "node_modules/*" "dist/*" ".git/*"
# Update blueprint to use local plugin
cat > playground/multisite-blueprint.json << EOF
{
"landingPage": "/wp-admin/network/",
"preferredVersions": {
"php": "8.0",
"wp": "latest"
},
"steps": [
{
"step": "defineWpConfig",
"name": "WP_ALLOW_MULTISITE",
"value": true
},
{
"step": "defineWpConfig",
"name": "MULTISITE",
"value": true
},
{
"step": "defineWpConfig",
"name": "SUBDOMAIN_INSTALL",
"value": false
},
{
"step": "defineWpConfig",
"name": "DOMAIN_CURRENT_SITE",
"value": "localhost"
},
{
"step": "defineWpConfig",
"name": "PATH_CURRENT_SITE",
"value": "/"
},
{
"step": "defineWpConfig",
"name": "SITE_ID_CURRENT_SITE",
"value": 1
},
{
"step": "defineWpConfig",
"name": "BLOG_ID_CURRENT_SITE",
"value": 1
},
{
"step": "login",
"username": "admin",
"password": "password"
},
{
"step": "installPlugin",
"pluginZipFile": {
"resource": "local",
"path": "dist/plugin.zip"
}
},
{
"step": "activatePlugin",
"pluginSlug": "wp-plugin-starter-template-for-ai-coding",
"networkWide": true
},
{
"step": "runPHP",
"code": "<?php\n// Create a test subsite\n$domain = 'localhost';\n$path = '/testsite/';\n$title = 'Test Subsite';\n$user_id = 1;\n\nif (!get_site_by_path($domain, $path)) {\n $blog_id = wpmu_create_blog($domain, $path, $title, $user_id);\n if (is_wp_error($blog_id)) {\n echo 'Error creating subsite: ' . $blog_id->get_error_message();\n } else {\n echo 'Created subsite with ID: ' . $blog_id;\n }\n} else {\n echo 'Subsite already exists';\n}\n"
}
]
}
EOF
# Start WordPress Playground
echo "Starting WordPress Playground..."
if command_exists python3; then
python3 -m http.server 8888 --directory playground &
echo "Opening WordPress Playground in your browser..."
if command_exists open; then
open http://localhost:8888/multisite.html
elif command_exists xdg-open; then
xdg-open http://localhost:8888/multisite.html
elif command_exists start; then
start http://localhost:8888/multisite.html
else
echo "Please open http://localhost:8888/multisite.html in your browser"
fi
else
echo "Python3 is not installed. Please open playground/multisite.html in your browser."
fi
# Wait for WordPress Playground to be ready
echo "Waiting for WordPress Playground to be ready..."
sleep 5
echo "WordPress Playground Multisite environment is ready!"
echo "Main site: http://localhost:8888"
echo "Test site: http://localhost:8888/testsite"
echo "Admin login: admin / password"
echo "Press Ctrl+C to stop the server when done."
else
echo "Invalid environment type. Use 'single', 'multisite', 'playground-single', or 'playground-multisite'."
exit 1
fi

9
composer.json
View File

@@ -16,6 +16,7 @@
},
"require-dev": {
"phpunit/phpunit": "^9.5.0",
"yoast/phpunit-polyfills": "^2.0",
"10up/wp_mock": "^1.0",
"dealerdirect/phpcodesniffer-composer-installer": "^1.0",
"wp-coding-standards/wpcs": "^3.0",
@@ -32,12 +33,14 @@
},
"autoload": {
"psr-4": {
"WPALLSTARS\\PluginStarterTemplate\\": "includes/"
"WPALLSTARS\\PluginStarterTemplate\\": "includes/",
"WP_Plugin_Starter_Template_For_AI_Coding\\": "includes/"
}
},
"autoload-dev": {
"classmap": [
"includes/Admin/class-admin.php"
"includes/Admin/class-admin.php",
"tests/phpunit/"
]
},
"config": {
@@ -51,7 +54,7 @@
"phpcbf": "vendor/bin/phpcbf --standard=phpcs.xml",
"phpcbf:simple": "vendor/bin/phpcbf --standard=phpcs-simple.xml",
"phpstan": "vendor/bin/phpstan analyse --level=5 .",
"phpmd": "vendor/bin/phpmd . text cleancode,codesize,controversial,design,naming,unusedcode --exclude vendor,node_modules,tests,bin,build,dist",
"phpmd": "vendor/bin/phpmd . text phpmd.xml --exclude vendor,node_modules,tests,bin,build,dist",
"test": "vendor/bin/phpunit",
"lint": ["@phpcs", "@phpstan", "@phpmd"],
"fix": ["@phpcbf"]

235
composer.lock generated
View File

@@ -4,7 +4,7 @@
"Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies",
"This file is @generated automatically"
],
"content-hash": "0fd3ab35fc0dfbc05c8057409f758104",
"content-hash": "5759c820289b50690d6ce01f85ada5ee",
"packages": [],
"packages-dev": [
{
@@ -538,16 +538,16 @@
},
{
"name": "myclabs/deep-copy",
"version": "1.13.0",
"version": "1.13.4",
"source": {
"type": "git",
"url": "https://github.com/myclabs/DeepCopy.git",
"reference": "024473a478be9df5fdaca2c793f2232fe788e414"
"reference": "07d290f0c47959fd5eed98c95ee5602db07e0b6a"
},
"dist": {
"type": "zip",
"url": "https://api.github.com/repos/myclabs/DeepCopy/zipball/024473a478be9df5fdaca2c793f2232fe788e414",
"reference": "024473a478be9df5fdaca2c793f2232fe788e414",
"url": "https://api.github.com/repos/myclabs/DeepCopy/zipball/07d290f0c47959fd5eed98c95ee5602db07e0b6a",
"reference": "07d290f0c47959fd5eed98c95ee5602db07e0b6a",
"shasum": ""
},
"require": {
@@ -586,7 +586,7 @@
],
"support": {
"issues": "https://github.com/myclabs/DeepCopy/issues",
"source": "https://github.com/myclabs/DeepCopy/tree/1.13.0"
"source": "https://github.com/myclabs/DeepCopy/tree/1.13.4"
},
"funding": [
{
@@ -594,20 +594,20 @@
"type": "tidelift"
}
],
"time": "2025-02-12T12:17:51+00:00"
"time": "2025-08-01T08:46:24+00:00"
},
{
"name": "nikic/php-parser",
"version": "v5.4.0",
"version": "v5.6.2",
"source": {
"type": "git",
"url": "https://github.com/nikic/PHP-Parser.git",
"reference": "447a020a1f875a434d62f2a401f53b82a396e494"
"reference": "3a454ca033b9e06b63282ce19562e892747449bb"
},
"dist": {
"type": "zip",
"url": "https://api.github.com/repos/nikic/PHP-Parser/zipball/447a020a1f875a434d62f2a401f53b82a396e494",
"reference": "447a020a1f875a434d62f2a401f53b82a396e494",
"url": "https://api.github.com/repos/nikic/PHP-Parser/zipball/3a454ca033b9e06b63282ce19562e892747449bb",
"reference": "3a454ca033b9e06b63282ce19562e892747449bb",
"shasum": ""
},
"require": {
@@ -626,7 +626,7 @@
"type": "library",
"extra": {
"branch-alias": {
"dev-master": "5.0-dev"
"dev-master": "5.x-dev"
}
},
"autoload": {
@@ -650,9 +650,9 @@
],
"support": {
"issues": "https://github.com/nikic/PHP-Parser/issues",
"source": "https://github.com/nikic/PHP-Parser/tree/v5.4.0"
"source": "https://github.com/nikic/PHP-Parser/tree/v5.6.2"
},
"time": "2024-12-30T11:07:19+00:00"
"time": "2025-10-21T19:32:17+00:00"
},
{
"name": "pdepend/pdepend",
@@ -1722,16 +1722,16 @@
},
{
"name": "phpunit/phpunit",
"version": "9.6.22",
"version": "9.6.29",
"source": {
"type": "git",
"url": "https://github.com/sebastianbergmann/phpunit.git",
"reference": "f80235cb4d3caa59ae09be3adf1ded27521d1a9c"
"reference": "9ecfec57835a5581bc888ea7e13b51eb55ab9dd3"
},
"dist": {
"type": "zip",
"url": "https://api.github.com/repos/sebastianbergmann/phpunit/zipball/f80235cb4d3caa59ae09be3adf1ded27521d1a9c",
"reference": "f80235cb4d3caa59ae09be3adf1ded27521d1a9c",
"url": "https://api.github.com/repos/sebastianbergmann/phpunit/zipball/9ecfec57835a5581bc888ea7e13b51eb55ab9dd3",
"reference": "9ecfec57835a5581bc888ea7e13b51eb55ab9dd3",
"shasum": ""
},
"require": {
@@ -1742,7 +1742,7 @@
"ext-mbstring": "*",
"ext-xml": "*",
"ext-xmlwriter": "*",
"myclabs/deep-copy": "^1.12.1",
"myclabs/deep-copy": "^1.13.4",
"phar-io/manifest": "^2.0.4",
"phar-io/version": "^3.2.1",
"php": ">=7.3",
@@ -1753,11 +1753,11 @@
"phpunit/php-timer": "^5.0.3",
"sebastian/cli-parser": "^1.0.2",
"sebastian/code-unit": "^1.0.8",
"sebastian/comparator": "^4.0.8",
"sebastian/comparator": "^4.0.9",
"sebastian/diff": "^4.0.6",
"sebastian/environment": "^5.1.5",
"sebastian/exporter": "^4.0.6",
"sebastian/global-state": "^5.0.7",
"sebastian/exporter": "^4.0.8",
"sebastian/global-state": "^5.0.8",
"sebastian/object-enumerator": "^4.0.4",
"sebastian/resource-operations": "^3.0.4",
"sebastian/type": "^3.2.1",
@@ -1805,7 +1805,7 @@
"support": {
"issues": "https://github.com/sebastianbergmann/phpunit/issues",
"security": "https://github.com/sebastianbergmann/phpunit/security/policy",
"source": "https://github.com/sebastianbergmann/phpunit/tree/9.6.22"
"source": "https://github.com/sebastianbergmann/phpunit/tree/9.6.29"
},
"funding": [
{
@@ -1816,12 +1816,20 @@
"url": "https://github.com/sebastianbergmann",
"type": "github"
},
{
"url": "https://liberapay.com/sebastianbergmann",
"type": "liberapay"
},
{
"url": "https://thanks.dev/u/gh/sebastianbergmann",
"type": "thanks_dev"
},
{
"url": "https://tidelift.com/funding/github/packagist/phpunit/phpunit",
"type": "tidelift"
}
],
"time": "2024-12-05T13:48:26+00:00"
"time": "2025-09-24T06:29:11+00:00"
},
{
"name": "psr/container",
@@ -2090,16 +2098,16 @@
},
{
"name": "sebastian/comparator",
"version": "4.0.8",
"version": "4.0.9",
"source": {
"type": "git",
"url": "https://github.com/sebastianbergmann/comparator.git",
"reference": "fa0f136dd2334583309d32b62544682ee972b51a"
"reference": "67a2df3a62639eab2cc5906065e9805d4fd5dfc5"
},
"dist": {
"type": "zip",
"url": "https://api.github.com/repos/sebastianbergmann/comparator/zipball/fa0f136dd2334583309d32b62544682ee972b51a",
"reference": "fa0f136dd2334583309d32b62544682ee972b51a",
"url": "https://api.github.com/repos/sebastianbergmann/comparator/zipball/67a2df3a62639eab2cc5906065e9805d4fd5dfc5",
"reference": "67a2df3a62639eab2cc5906065e9805d4fd5dfc5",
"shasum": ""
},
"require": {
@@ -2152,15 +2160,27 @@
],
"support": {
"issues": "https://github.com/sebastianbergmann/comparator/issues",
"source": "https://github.com/sebastianbergmann/comparator/tree/4.0.8"
"source": "https://github.com/sebastianbergmann/comparator/tree/4.0.9"
},
"funding": [
{
"url": "https://github.com/sebastianbergmann",
"type": "github"
},
{
"url": "https://liberapay.com/sebastianbergmann",
"type": "liberapay"
},
{
"url": "https://thanks.dev/u/gh/sebastianbergmann",
"type": "thanks_dev"
},
{
"url": "https://tidelift.com/funding/github/packagist/sebastian/comparator",
"type": "tidelift"
}
],
"time": "2022-09-14T12:41:17+00:00"
"time": "2025-08-10T06:51:50+00:00"
},
{
"name": "sebastian/complexity",
@@ -2350,16 +2370,16 @@
},
{
"name": "sebastian/exporter",
"version": "4.0.6",
"version": "4.0.8",
"source": {
"type": "git",
"url": "https://github.com/sebastianbergmann/exporter.git",
"reference": "78c00df8f170e02473b682df15bfcdacc3d32d72"
"reference": "14c6ba52f95a36c3d27c835d65efc7123c446e8c"
},
"dist": {
"type": "zip",
"url": "https://api.github.com/repos/sebastianbergmann/exporter/zipball/78c00df8f170e02473b682df15bfcdacc3d32d72",
"reference": "78c00df8f170e02473b682df15bfcdacc3d32d72",
"url": "https://api.github.com/repos/sebastianbergmann/exporter/zipball/14c6ba52f95a36c3d27c835d65efc7123c446e8c",
"reference": "14c6ba52f95a36c3d27c835d65efc7123c446e8c",
"shasum": ""
},
"require": {
@@ -2415,28 +2435,40 @@
],
"support": {
"issues": "https://github.com/sebastianbergmann/exporter/issues",
"source": "https://github.com/sebastianbergmann/exporter/tree/4.0.6"
"source": "https://github.com/sebastianbergmann/exporter/tree/4.0.8"
},
"funding": [
{
"url": "https://github.com/sebastianbergmann",
"type": "github"
},
{
"url": "https://liberapay.com/sebastianbergmann",
"type": "liberapay"
},
{
"url": "https://thanks.dev/u/gh/sebastianbergmann",
"type": "thanks_dev"
},
{
"url": "https://tidelift.com/funding/github/packagist/sebastian/exporter",
"type": "tidelift"
}
],
"time": "2024-03-02T06:33:00+00:00"
"time": "2025-09-24T06:03:27+00:00"
},
{
"name": "sebastian/global-state",
"version": "5.0.7",
"version": "5.0.8",
"source": {
"type": "git",
"url": "https://github.com/sebastianbergmann/global-state.git",
"reference": "bca7df1f32ee6fe93b4d4a9abbf69e13a4ada2c9"
"reference": "b6781316bdcd28260904e7cc18ec983d0d2ef4f6"
},
"dist": {
"type": "zip",
"url": "https://api.github.com/repos/sebastianbergmann/global-state/zipball/bca7df1f32ee6fe93b4d4a9abbf69e13a4ada2c9",
"reference": "bca7df1f32ee6fe93b4d4a9abbf69e13a4ada2c9",
"url": "https://api.github.com/repos/sebastianbergmann/global-state/zipball/b6781316bdcd28260904e7cc18ec983d0d2ef4f6",
"reference": "b6781316bdcd28260904e7cc18ec983d0d2ef4f6",
"shasum": ""
},
"require": {
@@ -2479,15 +2511,27 @@
],
"support": {
"issues": "https://github.com/sebastianbergmann/global-state/issues",
"source": "https://github.com/sebastianbergmann/global-state/tree/5.0.7"
"source": "https://github.com/sebastianbergmann/global-state/tree/5.0.8"
},
"funding": [
{
"url": "https://github.com/sebastianbergmann",
"type": "github"
},
{
"url": "https://liberapay.com/sebastianbergmann",
"type": "liberapay"
},
{
"url": "https://thanks.dev/u/gh/sebastianbergmann",
"type": "thanks_dev"
},
{
"url": "https://tidelift.com/funding/github/packagist/sebastian/global-state",
"type": "tidelift"
}
],
"time": "2024-03-02T06:35:11+00:00"
"time": "2025-08-10T07:10:35+00:00"
},
{
"name": "sebastian/lines-of-code",
@@ -2660,16 +2704,16 @@
},
{
"name": "sebastian/recursion-context",
"version": "4.0.5",
"version": "4.0.6",
"source": {
"type": "git",
"url": "https://github.com/sebastianbergmann/recursion-context.git",
"reference": "e75bd0f07204fec2a0af9b0f3cfe97d05f92efc1"
"reference": "539c6691e0623af6dc6f9c20384c120f963465a0"
},
"dist": {
"type": "zip",
"url": "https://api.github.com/repos/sebastianbergmann/recursion-context/zipball/e75bd0f07204fec2a0af9b0f3cfe97d05f92efc1",
"reference": "e75bd0f07204fec2a0af9b0f3cfe97d05f92efc1",
"url": "https://api.github.com/repos/sebastianbergmann/recursion-context/zipball/539c6691e0623af6dc6f9c20384c120f963465a0",
"reference": "539c6691e0623af6dc6f9c20384c120f963465a0",
"shasum": ""
},
"require": {
@@ -2711,15 +2755,27 @@
"homepage": "https://github.com/sebastianbergmann/recursion-context",
"support": {
"issues": "https://github.com/sebastianbergmann/recursion-context/issues",
"source": "https://github.com/sebastianbergmann/recursion-context/tree/4.0.5"
"source": "https://github.com/sebastianbergmann/recursion-context/tree/4.0.6"
},
"funding": [
{
"url": "https://github.com/sebastianbergmann",
"type": "github"
},
{
"url": "https://liberapay.com/sebastianbergmann",
"type": "liberapay"
},
{
"url": "https://thanks.dev/u/gh/sebastianbergmann",
"type": "thanks_dev"
},
{
"url": "https://tidelift.com/funding/github/packagist/sebastian/recursion-context",
"type": "tidelift"
}
],
"time": "2023-02-03T06:07:39+00:00"
"time": "2025-08-10T06:57:39+00:00"
},
{
"name": "sebastian/resource-operations",
@@ -3272,7 +3328,7 @@
},
{
"name": "symfony/polyfill-ctype",
"version": "v1.31.0",
"version": "v1.33.0",
"source": {
"type": "git",
"url": "https://github.com/symfony/polyfill-ctype.git",
@@ -3331,7 +3387,7 @@
"portable"
],
"support": {
"source": "https://github.com/symfony/polyfill-ctype/tree/v1.31.0"
"source": "https://github.com/symfony/polyfill-ctype/tree/v1.33.0"
},
"funding": [
{
@@ -3342,6 +3398,10 @@
"url": "https://github.com/fabpot",
"type": "github"
},
{
"url": "https://github.com/nicolas-grekas",
"type": "github"
},
{
"url": "https://tidelift.com/funding/github/packagist/symfony/symfony",
"type": "tidelift"
@@ -3809,16 +3869,16 @@
},
{
"name": "theseer/tokenizer",
"version": "1.2.3",
"version": "1.3.1",
"source": {
"type": "git",
"url": "https://github.com/theseer/tokenizer.git",
"reference": "737eda637ed5e28c3413cb1ebe8bb52cbf1ca7a2"
"reference": "b7489ce515e168639d17feec34b8847c326b0b3c"
},
"dist": {
"type": "zip",
"url": "https://api.github.com/repos/theseer/tokenizer/zipball/737eda637ed5e28c3413cb1ebe8bb52cbf1ca7a2",
"reference": "737eda637ed5e28c3413cb1ebe8bb52cbf1ca7a2",
"url": "https://api.github.com/repos/theseer/tokenizer/zipball/b7489ce515e168639d17feec34b8847c326b0b3c",
"reference": "b7489ce515e168639d17feec34b8847c326b0b3c",
"shasum": ""
},
"require": {
@@ -3847,7 +3907,7 @@
"description": "A small library for converting tokenized PHP source code into XML and potentially other formats",
"support": {
"issues": "https://github.com/theseer/tokenizer/issues",
"source": "https://github.com/theseer/tokenizer/tree/1.2.3"
"source": "https://github.com/theseer/tokenizer/tree/1.3.1"
},
"funding": [
{
@@ -3855,7 +3915,7 @@
"type": "github"
}
],
"time": "2024-03-03T12:36:25+00:00"
"time": "2025-11-17T20:03:58+00:00"
},
{
"name": "wp-coding-standards/wpcs",
@@ -3922,6 +3982,69 @@
}
],
"time": "2024-03-25T16:39:00+00:00"
},
{
"name": "yoast/phpunit-polyfills",
"version": "2.0.5",
"source": {
"type": "git",
"url": "https://github.com/Yoast/PHPUnit-Polyfills.git",
"reference": "1a6aecc9ebe4a9cea4e1047d0e6c496e52314c27"
},
"dist": {
"type": "zip",
"url": "https://api.github.com/repos/Yoast/PHPUnit-Polyfills/zipball/1a6aecc9ebe4a9cea4e1047d0e6c496e52314c27",
"reference": "1a6aecc9ebe4a9cea4e1047d0e6c496e52314c27",
"shasum": ""
},
"require": {
"php": ">=5.6",
"phpunit/phpunit": "^5.7.21 || ^6.0 || ^7.0 || ^8.0 || ^9.0 || ^10.0"
},
"require-dev": {
"php-parallel-lint/php-console-highlighter": "^1.0.0",
"php-parallel-lint/php-parallel-lint": "^1.4.0",
"yoast/yoastcs": "^3.2.0"
},
"type": "library",
"extra": {
"branch-alias": {
"dev-main": "4.x-dev"
}
},
"autoload": {
"files": [
"phpunitpolyfills-autoload.php"
]
},
"notification-url": "https://packagist.org/downloads/",
"license": [
"BSD-3-Clause"
],
"authors": [
{
"name": "Team Yoast",
"email": "support@yoast.com",
"homepage": "https://yoast.com"
},
{
"name": "Contributors",
"homepage": "https://github.com/Yoast/PHPUnit-Polyfills/graphs/contributors"
}
],
"description": "Set of polyfills for changed PHPUnit functionality to allow for creating PHPUnit cross-version compatible tests",
"homepage": "https://github.com/Yoast/PHPUnit-Polyfills",
"keywords": [
"phpunit",
"polyfill",
"testing"
],
"support": {
"issues": "https://github.com/Yoast/PHPUnit-Polyfills/issues",
"security": "https://github.com/Yoast/PHPUnit-Polyfills/security/policy",
"source": "https://github.com/Yoast/PHPUnit-Polyfills"
},
"time": "2025-08-10T05:13:49+00:00"
}
],
"aliases": [],

17
cypress.config.js Normal file
View File

@@ -0,0 +1,17 @@
/* eslint-env node, mocha */
const { defineConfig } = require('cypress');
module.exports = defineConfig({
e2e: {
baseUrl: 'http://localhost:8888',
setupNodeEvents(on, config) {
// This function can be used to register custom Cypress plugins or event listeners.
// Currently not in use, but left for future extensibility.
return config;
},
// Add configuration for WordPress Playground
experimentalWebKitSupport: true,
chromeWebSecurity: false
}
});

47
cypress/e2e/multisite.cy.js Normal file
View File

@@ -0,0 +1,47 @@
describe('WordPress Multisite Tests', () => {
it('Can access the main site', () => {
cy.visit('/');
cy.get('body').should('exist');
cy.get('h1').should('exist');
cy.title().should('include', 'WordPress');
});
it('Can access the test subsite', () => {
cy.visit('/testsite');
cy.get('body').should('exist');
cy.get('h1').should('exist');
cy.title().should('include', 'Test Site');
});
it('Can login to the admin area', () => {
cy.loginAsAdmin();
cy.get('#wpadminbar').should('exist');
cy.get('#dashboard-widgets').should('exist');
});
it('Can access network admin', () => {
cy.loginAsAdmin();
// Go to network admin
cy.visit('/wp-admin/network/');
cy.get('body.network-admin').should('exist');
});
it('Plugin is network activated', () => {
// Use our custom command to check and network activate the plugin if needed
cy.networkActivatePlugin('wp-plugin-starter-template-for-ai-coding');
// Verify it's network active
cy.get('tr[data-slug="wp-plugin-starter-template-for-ai-coding"] .network_active').should('exist');
});
it('Network settings page loads correctly', () => {
cy.loginAsAdmin();
// Navigate to the network settings page (if it exists)
cy.visit('/wp-admin/network/settings.php');
// This is a basic check for the network settings page
cy.get('h1').should('contain', 'Network Settings');
});
});

43
cypress/e2e/playground-multisite.cy.js Normal file
View File

@@ -0,0 +1,43 @@
/* eslint-env mocha, jquery, cypress */
describe('WordPress Playground Multisite Tests', () => {
beforeEach(() => {
cy.visit('/', { timeout: 30000 });
});
it('Can access the site', () => {
cy.get('body', { timeout: 15000 }).should('exist');
});
it('Can access the network admin area', () => {
cy.loginAsAdmin();
cy.visit('/wp-admin/network/', { timeout: 30000 });
cy.get('#wpadminbar', { timeout: 15000 }).should('exist');
cy.get('#wpbody-content').should('exist');
});
it('Plugin is network activated', () => {
cy.loginAsAdmin();
cy.visit('/wp-admin/network/plugins.php', { timeout: 30000 });
cy.get('body', { timeout: 15000 }).then(($body) => {
if ($body.text().includes('Plugin Toggle')) {
cy.contains('tr', 'Plugin Toggle').should('exist');
cy.contains('tr', 'Plugin Toggle').find('.network_active, .deactivate').should('exist');
} else {
cy.log('Plugin Toggle not found, skipping check');
}
if ($body.text().includes('Kadence Blocks')) {
cy.contains('tr', 'Kadence Blocks').find('.network_active, .deactivate').should('exist');
} else {
cy.log('Kadence Blocks plugin not found, skipping check');
}
});
});
it('Network settings page loads correctly', () => {
cy.loginAsAdmin();
cy.visit('/wp-admin/network/settings.php', { timeout: 30000 });
cy.get('#wpbody-content', { timeout: 15000 }).should('exist');
});
});

43
cypress/e2e/playground-single-site.cy.js Normal file
View File

@@ -0,0 +1,43 @@
/* eslint-env mocha, jquery, cypress */
describe('WordPress Playground Single Site Tests', () => {
beforeEach(() => {
cy.visit('/', { timeout: 30000 });
});
it('Can access the site', () => {
cy.get('body', { timeout: 15000 }).should('exist');
});
it('Can access the admin area', () => {
cy.loginAsAdmin();
cy.get('#wpadminbar', { timeout: 15000 }).should('exist');
});
it('Plugin is activated', () => {
cy.loginAsAdmin();
cy.visit('/wp-admin/plugins.php', { timeout: 30000 });
cy.get('body', { timeout: 15000 }).then(($body) => {
if ($body.text().includes('Plugin Toggle')) {
cy.contains('tr', 'Plugin Toggle').should('exist');
cy.contains('tr', 'Plugin Toggle').find('.deactivate').should('exist');
} else {
cy.log('Plugin Toggle not found, skipping check');
}
if ($body.text().includes('Kadence Blocks')) {
cy.contains('tr', 'Kadence Blocks').find('.deactivate').should('exist');
} else {
cy.log('Kadence Blocks plugin not found, skipping check');
}
});
});
it('Plugin settings page loads correctly', () => {
cy.loginAsAdmin();
cy.visit('/wp-admin/options-general.php', { timeout: 30000 });
cy.get('#wpbody-content', { timeout: 15000 }).should('exist');
cy.get('h1').should('be.visible');
cy.title().should('include', 'Settings');
});
});

30
cypress/e2e/single-site.cy.js Normal file
View File

@@ -0,0 +1,30 @@
describe('WordPress Single Site Tests', () => {
it('Can access the site', () => {
cy.visit('/');
cy.get('body').should('exist');
});
it('Can login to the admin area', () => {
cy.loginAsAdmin();
cy.get('#wpadminbar').should('exist');
cy.get('#dashboard-widgets').should('exist');
});
it('Plugin is activated', () => {
// Use our custom command to check and activate the plugin if needed
cy.activatePlugin('wp-plugin-starter-template-for-ai-coding');
// Verify it's active
cy.get('tr[data-slug="wp-plugin-starter-template-for-ai-coding"] .deactivate').should('exist');
});
it('Plugin settings page loads correctly', () => {
cy.loginAsAdmin();
// Navigate to the plugin settings page (if it exists)
cy.visit('/wp-admin/options-general.php?page=wp-plugin-starter-template');
// This is a basic check - adjust based on your actual plugin's settings page
cy.get('h1').should('contain', 'WP Plugin Starter Template');
});
});

74
cypress/support/commands.js Normal file
View File

@@ -0,0 +1,74 @@
// ***********************************************
// This example commands.js shows you how to
// create various custom commands and overwrite
// existing commands.
//
// For more comprehensive examples of custom
// commands please read more here:
// https://on.cypress.io/custom-commands
// ***********************************************
/**
* Custom command to login as admin
*/
Cypress.Commands.add('loginAsAdmin', () => {
cy.visit('/wp-admin', { timeout: 30000 });
cy.get('body', { timeout: 15000 }).then(($body) => {
if ($body.find('#wpadminbar').length > 0) {
cy.log('Already logged in as admin');
return;
}
if ($body.find('#user_login').length > 0) {
cy.get('#user_login').should('be.visible').type('admin');
cy.get('#user_pass').should('be.visible').type('password');
cy.get('#wp-submit').should('be.visible').click();
cy.get('#wpadminbar', { timeout: 15000 }).should('exist');
} else {
cy.log('Login form not found, assuming already logged in');
}
});
});
/**
* Custom command to activate plugin
*/
Cypress.Commands.add('activatePlugin', (pluginSlug) => {
cy.loginAsAdmin();
cy.visit('/wp-admin/plugins.php');
// Check if plugin is already active
cy.contains('tr', pluginSlug).then(($tr) => {
if ($tr.find('.deactivate').length > 0) {
// Plugin is already active
cy.log(`Plugin ${pluginSlug} is already active`);
return;
}
// Activate the plugin
cy.contains('tr', pluginSlug).find('.activate a').click();
cy.contains('tr', pluginSlug).find('.deactivate').should('exist');
});
});
/**
* Custom command to network activate plugin
*/
Cypress.Commands.add('networkActivatePlugin', (pluginSlug) => {
cy.loginAsAdmin();
cy.visit('/wp-admin/network/plugins.php');
// Check if plugin is already network active
cy.contains('tr', pluginSlug).then(($tr) => {
if ($tr.find('.network_active').length > 0) {
// Plugin is already network active
cy.log(`Plugin ${pluginSlug} is already network active`);
return;
}
// Network activate the plugin
cy.contains('tr', pluginSlug).find('.activate a').click();
cy.contains('tr', pluginSlug).find('.network_active').should('exist');
});
});

17
cypress/support/e2e.js Normal file
View File

@@ -0,0 +1,17 @@
// ***********************************************************
// This example support/e2e.js is processed and
// loaded automatically before your test files.
//
// This is a great place to put global configuration and
// behavior that modifies Cypress.
//
// You can change the location of this file or turn off
// automatically serving support files with the
// 'supportFile' configuration option.
//
// You can read more here:
// https://on.cypress.io/configuration
// ***********************************************************
// Import commands.js using ES2015 syntax:
import './commands';

3
includes/Admin/class-admin.php
View File

@@ -43,9 +43,6 @@ class Admin {
*
* This method is hooked into 'admin_enqueue_scripts'. It checks if the current
* screen is relevant to the plugin before enqueueing assets.
*
*/
public function enqueue_admin_assets(): void {

29
includes/Multisite/README.md Normal file
View File

@@ -0,0 +1,29 @@
# Multisite Support
This directory contains placeholder files for multisite-specific functionality.
When developing a plugin based on this template, you can extend these files.
Create additional classes in this directory to implement multisite features.
## Usage
To implement multisite-specific functionality:
1. Create your multisite-specific classes in this directory
2. Load and initialize these classes in your main plugin file when in a multisite environment:
```php
// Load multisite support classes if in multisite environment
if ( is_multisite() ) {
require_once WP_PLUGIN_STARTER_TEMPLATE_PATH . 'includes/Multisite/class-multisite.php';
// Initialize multisite support
$multisite = new WPALLSTARS\PluginStarterTemplate\Multisite\Multisite();
}
```
## Testing
For information on testing your plugin in a multisite environment, see the
[Testing Framework](../../.wiki/Testing.md) documentation.

68
includes/Multisite/class-multisite.php Normal file
View File

@@ -0,0 +1,68 @@
<?php
/**
* Multisite Class
*
* This is a placeholder file for multisite-specific functionality.
* Extend this file or create additional classes in this directory
* to implement multisite features for your plugin.
*
* @package WP_Plugin_Starter_Template_For_AI_Coding
*/
namespace WP_Plugin_Starter_Template_For_AI_Coding\Multisite;
// Exit if accessed directly.
if ( ! defined( 'ABSPATH' ) ) {
exit;
}
/**
* Class Multisite
*
* Base class for multisite-specific functionality.
*/
class Multisite {
/**
* Constructor.
*/
public function __construct() {
// This is just a placeholder class.
// Add your multisite-specific initialization here.
}
/**
* Initialize hooks.
*/
public function initialize_hooks() {
add_action( 'network_admin_menu', array( $this, 'add_network_menu' ) );
}
/**
* Add network admin menu.
*/
public function add_network_menu() {
// This is a placeholder method.
// In a real implementation, you would add network admin menu items here.
}
/**
* Example method for multisite functionality.
*
* @return bool Always returns true.
*/
public function is_multisite_compatible() {
return true;
}
/**
* Example method to get all sites in the network.
*
* @return array An array of sites or an empty array if not in multisite.
*/
public function get_network_sites() {
// This is just a placeholder method.
// In a real implementation, you might use get_sites() or a custom query.
return function_exists( 'get_sites' ) ? get_sites( array( 'public' => 1 ) ) : array();
}
}

22
includes/class-plugin.php
View File

@@ -60,7 +60,7 @@ class Plugin {
*/
public function init(): void {
// Register hooks and filters.
add_action('plugins_loaded', array($this, 'load_textdomain'));
add_action( 'plugins_loaded', array( $this, 'load_textdomain' ) );
// Initialize any other plugin functionality.
}
@@ -74,7 +74,25 @@ class Plugin {
load_plugin_textdomain(
'wp-plugin-starter-template',
false,
dirname(plugin_basename($this->pluginFile)) . '/languages/'
dirname( plugin_basename( $this->pluginFile ) ) . '/languages/'
);
}
/**
* Get the plugin version.
*
* @return string The plugin version.
*/
public function get_version(): string {
return $this->version;
}
/**
* Get the admin instance.
*
* @return Admin The admin instance.
*/
public function get_admin(): Admin {
return $this->admin;
}
}

60
mu-plugins/multisite-setup.php Normal file
View File

@@ -0,0 +1,60 @@
<?php
/**
* Plugin Name: Multisite Setup Helper
* Description: Helper plugin to set up multisite testing environment
* Version: 1.0.0
* Author: WPALLSTARS
* License: GPL-2.0-or-later
*
* @package WP_Plugin_Starter_Template_For_AI_Coding
*/
// Exit if accessed directly.
if ( ! defined( 'ABSPATH' ) ) {
exit;
}
/**
* Add a filter to allow subdirectory multisite on localhost
*/
add_filter( 'allow_subdirectory_install', '__return_true' );
/**
* Add a filter to skip domain verification for multisite
*/
add_filter( 'multisite_domain_check', '__return_true' );
/**
* Add a filter to allow wildcard subdomains
*/
add_filter( 'wp_is_large_network', '__return_false' );
/**
* Add a filter to allow domain mapping
*/
add_filter( 'domain_mapping_warning', '__return_false' );
/**
* Helper function to check if we're in a multisite environment.
*
* @return bool True if multisite is enabled, false otherwise.
*/
function wpst_is_multisite() {
return defined( 'MULTISITE' ) && MULTISITE;
}
/**
* Helper function to get all sites in the network.
*
* @return array Array of site objects.
*/
function wpst_get_network_sites() {
if ( ! wpst_is_multisite() ) {
return array();
}
return get_sites( array( 'public' => 1 ) );
}
// Add a filter to enable multisite testing in PHPUnit.
add_filter( 'wpst_is_multisite_compatible', '__return_true' );

6671
package-lock.json generated Normal file
View File

File diff suppressed because it is too large Load Diff

33
package.json
View File

@@ -7,10 +7,28 @@
"start": "wp-env start",
"stop": "wp-env stop",
"wp-env": "wp-env",
"multisite": "wp-env start --config=.wp-env.multisite.json",
"test:e2e": "cypress open --config-file tests/e2e/cypress.json",
"test:e2e:headless": "cypress run --config-file tests/e2e/cypress.json",
"setup:single": "bash bin/setup-test-env.sh single",
"setup:multisite": "bash bin/setup-test-env.sh multisite",
"test:single": "cypress open --config specPattern=cypress/e2e/single-site.cy.js",
"test:single:headless": "cypress run --config specPattern=cypress/e2e/single-site.cy.js",
"test:multisite": "cypress open --config specPattern=cypress/e2e/multisite.cy.js",
"test:multisite:headless": "cypress run --config specPattern=cypress/e2e/multisite.cy.js",
"test:e2e:single": "npm run setup:single && sleep 5 && npm run test:single:headless",
"test:e2e:multisite": "npm run setup:multisite && sleep 5 && npm run test:multisite:headless",
"test:playground:single": "cypress run --spec cypress/e2e/playground-single-site.cy.js",
"test:playground:multisite": "cypress run --spec cypress/e2e/playground-multisite.cy.js",
"playground:start": "bash bin/playground-test.sh start",
"playground:start:multisite": "bash bin/playground-test.sh start --multisite",
"playground:stop": "bash bin/playground-test.sh stop",
"playground:status": "bash bin/playground-test.sh status",
"localwp:create": "bash bin/localwp-setup.sh create",
"localwp:create:multisite": "bash bin/localwp-setup.sh create --multisite",
"localwp:sync": "bash bin/localwp-setup.sh sync",
"localwp:reset": "bash bin/localwp-setup.sh reset",
"test:phpunit": "composer test",
"test:phpunit:multisite": "WP_MULTISITE=1 composer test",
"build": "./build.sh",
"lint:js": "eslint cypress/",
"lint:php": "composer run-script phpcs",
"lint:php:simple": "composer run-script phpcs:simple",
"lint:phpstan": "composer run-script phpstan",
@@ -40,7 +58,12 @@
},
"homepage": "https://github.com/wpallstars/wp-plugin-starter-template-for-ai-coding#readme",
"devDependencies": {
"@wordpress/env": "^5.0.0",
"cypress": "^9.7.0"
"@wordpress/env": "^8.12.0",
"@wp-playground/blueprints": "^3.0.22",
"@wp-playground/client": "^3.0.22",
"@wp-playground/cli": "^3.0.22",
"cypress": "^13.17.0",
"eslint": "^8.57.0",
"eslint-plugin-cypress": "^2.15.1"
}
}

25
phpmd.xml Normal file
View File

@@ -0,0 +1,25 @@
<?xml version="1.0"?>
<ruleset name="WordPress PHPMD Ruleset"
xmlns="http://pmd.sf.net/ruleset/1.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://pmd.sf.net/ruleset/1.0.0 http://pmd.sf.net/ruleset_xml_schema.xsd"
xsi:noNamespaceSchemaLocation="http://pmd.sf.net/ruleset_xml_schema.xsd">
<description>Custom PHPMD ruleset for WordPress plugin development</description>
<!-- Import rulesets -->
<rule ref="rulesets/cleancode.xml">
<exclude name="StaticAccess" />
</rule>
<rule ref="rulesets/codesize.xml" />
<rule ref="rulesets/controversial.xml">
<exclude name="CamelCaseMethodName" />
<exclude name="CamelCaseParameterName" />
<exclude name="CamelCaseVariableName" />
</rule>
<rule ref="rulesets/design.xml" />
<rule ref="rulesets/naming.xml">
<exclude name="ShortVariable" />
<exclude name="LongVariable" />
</rule>
<rule ref="rulesets/unusedcode.xml" />
</ruleset>

9
phpstan.neon
View File

@@ -5,7 +5,14 @@ parameters:
- admin
- wp-plugin-starter-template.php
excludePaths:
paths:
analyse:
- vendor
- node_modules
- tests
- bin
- build
- dist
analyseAndScan:
- vendor
- node_modules
- tests

3
phpunit.xml
View File

@@ -1,6 +1,6 @@
<?xml version="1.0"?>
<phpunit
bootstrap="tests/bootstrap.php"
bootstrap="tests/phpunit/bootstrap.php"
backupGlobals="false"
colors="true"
convertErrorsToExceptions="true"
@@ -10,6 +10,7 @@
<testsuites>
<testsuite name="unit">
<directory prefix="test-" suffix=".php">./tests/</directory>
<directory prefix="test-" suffix=".php">./tests/phpunit/</directory>
</testsuite>
</testsuites>
<filter>

25
phpunit.xml.dist Normal file
View File

@@ -0,0 +1,25 @@
<?xml version="1.0"?>
<phpunit
bootstrap="tests/phpunit/bootstrap.php"
backupGlobals="false"
colors="true"
convertErrorsToExceptions="true"
convertNoticesToExceptions="true"
convertWarningsToExceptions="true"
>
<testsuites>
<testsuite name="plugin">
<directory prefix="test-" suffix=".php">./tests/phpunit/</directory>
</testsuite>
</testsuites>
<filter>
<whitelist>
<directory suffix=".php">./includes</directory>
<exclude>
<directory suffix=".php">./vendor</directory>
<directory suffix=".php">./tests</directory>
<directory suffix=".php">./node_modules</directory>
</exclude>
</whitelist>
</filter>
</phpunit>

45
playground/blueprint.json Normal file
View File

@@ -0,0 +1,45 @@
{
"$schema": "https://playground.wordpress.net/blueprint-schema.json",
"landingPage": "/wp-admin/plugins.php",
"login": true,
"preferredVersions": {
"php": "8.0",
"wp": "latest"
},
"features": {
"networking": true
},
"steps": [
{
"step": "defineWpConfigConsts",
"consts": {
"WP_DEBUG": true,
"WP_DEBUG_LOG": true,
"WP_DEBUG_DISPLAY": true,
"SCRIPT_DEBUG": true
}
},
{
"step": "installPlugin",
"pluginData": {
"resource": "wordpress.org/plugins",
"slug": "plugin-toggle"
}
},
{
"step": "installPlugin",
"pluginData": {
"resource": "wordpress.org/plugins",
"slug": "kadence-blocks"
}
},
{
"step": "activatePlugin",
"pluginPath": "plugin-toggle/plugin-toggle.php"
},
{
"step": "activatePlugin",
"pluginPath": "kadence-blocks/kadence-blocks.php"
}
]
}

26
playground/index.html Normal file
View File

@@ -0,0 +1,26 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>WordPress Playground</title>
<style>
body, html {
margin: 0;
padding: 0;
height: 100%;
width: 100%;
overflow: hidden;
}
iframe {
width: 100%;
height: 100%;
border: none;
}
</style>
</head>
<body>
<iframe src="https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/wpallstars/wp-plugin-starter-template-for-ai-coding/main/playground/blueprint.json&_t=2" title="WordPress Playground Single Site Environment"></iframe>
</body>
</html>

52
playground/multisite-blueprint.json Normal file
View File

@@ -0,0 +1,52 @@
{
"$schema": "https://playground.wordpress.net/blueprint-schema.json",
"landingPage": "/wp-admin/network/plugins.php",
"login": true,
"preferredVersions": {
"php": "8.0",
"wp": "latest"
},
"features": {
"networking": true
},
"steps": [
{
"step": "defineWpConfigConsts",
"consts": {
"WP_DEBUG": true,
"WP_DEBUG_LOG": true,
"WP_DEBUG_DISPLAY": true,
"SCRIPT_DEBUG": true
}
},
{
"step": "enableMultisite"
},
{
"step": "wp-cli",
"command": "wp site create --slug=testsite --title='Test Site'"
},
{
"step": "installPlugin",
"pluginData": {
"resource": "wordpress.org/plugins",
"slug": "plugin-toggle"
}
},
{
"step": "installPlugin",
"pluginData": {
"resource": "wordpress.org/plugins",
"slug": "kadence-blocks"
}
},
{
"step": "wp-cli",
"command": "wp plugin activate plugin-toggle --network"
},
{
"step": "wp-cli",
"command": "wp plugin activate kadence-blocks --network"
}
]
}

26
playground/multisite.html Normal file
View File

@@ -0,0 +1,26 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>WordPress Playground - Multisite</title>
<style>
body, html {
margin: 0;
padding: 0;
height: 100%;
width: 100%;
overflow: hidden;
}
iframe {
width: 100%;
height: 100%;
border: none;
}
</style>
</head>
<body>
<iframe src="https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/wpallstars/wp-plugin-starter-template-for-ai-coding/main/playground/multisite-blueprint.json&_t=2" title="WordPress Playground Multisite Environment"></iframe>
</body>
</html>

120
playground/test.html Normal file
View File

@@ -0,0 +1,120 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>WordPress Playground Test</title>
<style>
body, html {
margin: 0;
padding: 0;
height: 100%;
overflow: hidden;
}
iframe {
width: 100%;
height: 100%;
border: none;
}
.buttons {
position: fixed;
top: 10px;
left: 10px;
z-index: 1000;
}
button {
padding: 10px;
margin-right: 10px;
background-color: #0073aa;
color: white;
border: none;
border-radius: 4px;
cursor: pointer;
}
button:hover {
background-color: #005177;
}
</style>
</head>
<body>
<div class="buttons">
<button type="button" id="singleSiteBtn">Single Site</button>
<button type="button" id="multisiteBtn">Multisite</button>
</div>
<iframe id="playground" src="about:blank" title="WordPress Playground Test Environment"></iframe>
<script>
// Use unobtrusive event listeners instead of inline handlers
document.addEventListener('DOMContentLoaded', function() {
document.getElementById('singleSiteBtn').addEventListener('click', loadSingleSite);
document.getElementById('multisiteBtn').addEventListener('click', loadMultisite);
});
function loadSingleSite() {
document.getElementById('playground').src = "https://playground.wordpress.net/?blueprint=" + encodeURIComponent(JSON.stringify(singleSiteBlueprint));
}
function loadMultisite() {
document.getElementById('playground').src = "https://playground.wordpress.net/?blueprint=" + encodeURIComponent(JSON.stringify(multisiteBlueprint));
}
// Single site blueprint
const singleSiteBlueprint = {
"$schema": "https://playground.wordpress.net/blueprint-schema.json",
"landingPage": "/wp-admin/",
"login": true,
"features": {
"networking": true
},
"steps": [
{
"step": "defineWpConfigConsts",
"consts": {
"WP_DEBUG": true
}
},
{
"step": "wp-cli",
"command": "wp plugin install plugin-toggle kadence-blocks --activate"
}
]
};
// Multisite blueprint
const multisiteBlueprint = {
"$schema": "https://playground.wordpress.net/blueprint-schema.json",
"landingPage": "/wp-admin/network/",
"login": true,
"features": {
"networking": true
},
"steps": [
{
"step": "defineWpConfigConsts",
"consts": {
"WP_DEBUG": true
}
},
{
"step": "enableMultisite"
},
{
"step": "wp-cli",
"command": "wp site create --slug=testsite"
},
{
"step": "wp-cli",
"command": "wp plugin install plugin-toggle kadence-blocks --activate-network"
}
]
};
// Load single site by default
loadSingleSite();
</script>
</body>
</html>

4
sonar-project.properties
View File

@@ -17,7 +17,7 @@ sonar.sourceEncoding=UTF-8
sonar.cpd.exclusions=tests/**
# Exclude directories and files
sonar.exclusions=vendor/**,node_modules/**,tests/**,bin/**,build/**,dist/**,.github/**,.git/**
sonar.exclusions=vendor/**,node_modules/**,tests/**,bin/**,build/**,dist/**,.github/**,.git/**,cypress/**,playground/**,.wiki/**
# PHP specific configuration
sonar.php.coverage.reportPaths=coverage.xml
@@ -27,4 +27,4 @@ sonar.php.tests.reportPath=test-report.xml
sonar.verbose=true
# Disable automatic analysis
sonar.projectKey.analysis.mode=manual
# sonar.projectKey.analysis.mode=manual

29
tests/bootstrap.php
View File

@@ -1,29 +0,0 @@
<?php
/**
* PHPUnit bootstrap file
*
* @package WPALLSTARS\PluginStarterTemplate
*/
// First, we need to load the composer autoloader so we can use WP Mock.
require_once dirname(__DIR__) . '/vendor/autoload.php';
// No need to import WP_Mock classes here
// Now call the bootstrap method of WP Mock.
WP_Mock::bootstrap();
/**
* Now we define a few constants to help us with testing.
*/
define('WPST_PLUGIN_DIR', dirname(__DIR__) . '/');
define('WPST_PLUGIN_URL', 'http://example.org/wp-content/plugins/wp-plugin-starter-template/');
define('WPST_VERSION', '0.1.0');
/**
* Now we include any plugin files that we need to be able to run the tests.
* This should be files that define the functions and classes you're going to test.
*/
require_once WPST_PLUGIN_DIR . 'includes/class-core.php';
require_once WPST_PLUGIN_DIR . 'includes/class-plugin.php';
require_once WPST_PLUGIN_DIR . 'admin/lib/admin.php';

52
tests/phpunit/bootstrap.php Normal file
View File

@@ -0,0 +1,52 @@
<?php
/**
* PHPUnit bootstrap file.
*
* @package WP_Plugin_Starter_Template_For_AI_Coding
*/
// Composer autoloader must be loaded before WP_PHPUNIT__DIR will be available.
require_once dirname( dirname( __DIR__ ) ) . '/vendor/autoload.php';
// Check if we're running the WordPress tests.
if ( getenv( 'WP_PHPUNIT__DIR' ) ) {
// Define PHPUnit Polyfills path for WordPress test suite.
if ( ! defined( 'WP_TESTS_PHPUNIT_POLYFILLS_PATH' ) ) {
define( 'WP_TESTS_PHPUNIT_POLYFILLS_PATH', dirname( dirname( __DIR__ ) ) . '/vendor/yoast/phpunit-polyfills/' );
}
// Give access to tests_add_filter() function.
require_once getenv( 'WP_PHPUNIT__DIR' ) . '/includes/functions.php';
/**
* Manually load the plugin being tested.
*
* @return void
*/
function _manually_load_plugin() {
require_once dirname( dirname( __DIR__ ) ) . '/wp-plugin-starter-template.php';
// Load the multisite class for testing.
$multisite_file = dirname( dirname( __DIR__ ) ) . '/includes/multisite/class-multisite.php';
if ( file_exists( $multisite_file ) ) {
require_once $multisite_file;
}
}
// Start up the WP testing environment.
require_once getenv( 'WP_PHPUNIT__DIR' ) . '/includes/bootstrap.php';
} else {
// We're running the WP_Mock tests.
WP_Mock::bootstrap();
// Define constants for testing.
define( 'WPST_PLUGIN_DIR', dirname( dirname( __DIR__ ) ) . '/' );
define( 'WPST_PLUGIN_URL', 'http://example.org/wp-content/plugins/wp-plugin-starter-template/' );
define( 'WPST_VERSION', '0.1.0' );
// Include plugin files needed for tests.
require_once WPST_PLUGIN_DIR . 'includes/class-core.php';
require_once WPST_PLUGIN_DIR . 'includes/class-plugin.php';
if ( file_exists( WPST_PLUGIN_DIR . 'admin/lib/admin.php' ) ) {
require_once WPST_PLUGIN_DIR . 'admin/lib/admin.php';
}
}

37
tests/test-admin.php → tests/phpunit/test-admin.php
View File

@@ -3,11 +3,22 @@
* Class AdminTest
*
* @package WPALLSTARS\PluginStarterTemplate
* @group wpmock
*/
// Skip this test file if WP_Mock is not available or WordPress test framework is loaded.
if ( ! class_exists( 'WP_Mock' ) || class_exists( 'WP_UnitTestCase' ) ) {
return; // phpcs:ignore -- Early return is intentional.
}
use WPALLSTARS\PluginStarterTemplate\Admin\Admin;
use WPALLSTARS\PluginStarterTemplate\Core;
/**
* Test version constant.
*/
const TEST_VERSION = '1.0.0';
/**
* Admin test case.
*/
@@ -29,18 +40,19 @@ class AdminTest extends \WP_Mock\Tools\TestCase {
/**
* Set up the test environment.
*
* @return void
*/
public function setUp(): void
{
public function setUp(): void {
parent::setUp();
// Set up mocks
// Set up mocks.
WP_Mock::setUp();
// Mock the Core class dependency using Mockery.
$this->core = \Mockery::mock( '\WPALLSTARS\PluginStarterTemplate\Core' );
// Add expectation for get_plugin_version BEFORE Admin is instantiated.
$this->core->shouldReceive( 'get_plugin_version' )->andReturn( '1.0.0' );
$this->core->shouldReceive( 'get_plugin_version' )->andReturn( TEST_VERSION );
// Expect the action hook to be added BEFORE Admin is instantiated.
\WP_Mock::expectActionAdded( 'admin_enqueue_scripts', array( \Mockery::any(), 'enqueue_admin_assets' ) );
@@ -50,7 +62,9 @@ class AdminTest extends \WP_Mock\Tools\TestCase {
}
/**
* Tear down test environment
* Tear down test environment.
*
* @return void
*/
public function tearDown(): void {
WP_Mock::tearDown();
@@ -58,18 +72,21 @@ class AdminTest extends \WP_Mock\Tools\TestCase {
}
/**
* Test constructor
* Test constructor.
*
* @return void
*/
public function test_constructor() {
// Verify that the constructor initializes hooks
$this->assertInstanceOf(Admin::class, $this->admin);
// Verify that the constructor initializes hooks.
$this->assertInstanceOf( Admin::class, $this->admin );
}
/**
* Test the enqueue_admin_assets method.
*
* @return void
*/
public function test_enqueue_admin_assets(): void
{
public function test_enqueue_admin_assets(): void {
// Define the PHPUNIT_RUNNING constant
if ( ! defined( 'PHPUNIT_RUNNING' ) ) {
define( 'PHPUNIT_RUNNING', true );

74
tests/phpunit/test-core.php Normal file
View File

@@ -0,0 +1,74 @@
<?php
/**
* Class CoreTest
*
* @package WPALLSTARS\PluginStarterTemplate
* @group wpmock
*/
// Skip this test file if WP_Mock is not available or WordPress test framework is loaded.
if ( ! class_exists( 'WP_Mock' ) || class_exists( 'WP_UnitTestCase' ) ) {
return; // phpcs:ignore -- Early return is intentional.
}
use WPALLSTARS\PluginStarterTemplate\Core;
/**
* Core test case.
*/
class CoreTest extends \WP_Mock\Tools\TestCase {
/**
* Test instance
*
* @var Core
*/
private $core;
/**
* Set up the test environment.
*
* @return void
*/
public function setUp(): void {
parent::setUp();
// Set up mocks.
WP_Mock::setUp();
// Create instance of Core class.
$this->core = new Core();
}
/**
* Tear down the test environment.
*
* @return void
*/
public function tearDown(): void {
WP_Mock::tearDown();
parent::tearDown();
}
/**
* Test constructor.
*
* @return void
*/
public function test_constructor() {
// Verify that the constructor initializes hooks.
$this->assertInstanceOf( Core::class, $this->core );
}
/**
* Test example method.
*
* @return void
*/
public function test_filter_content() {
$content = 'Test content';
// Test that filter_content returns the content.
$this->assertEquals( $content, $this->core->filter_content( $content ) );
}
}

98
tests/phpunit/test-multisite.php Normal file
View File

@@ -0,0 +1,98 @@
<?php
/**
* Class MultisiteTest
*
* @package WP_Plugin_Starter_Template_For_AI_Coding
* @group wordpress
*/
use WP_Plugin_Starter_Template_For_AI_Coding\Multisite\Multisite;
// Skip this test file if WordPress test framework is not available.
if ( ! class_exists( 'WP_UnitTestCase' ) ) {
return; // phpcs:ignore -- Early return is intentional.
}
/**
* Multisite class name constant for testing.
*/
const MULTISITE_CLASS = 'WP_Plugin_Starter_Template_For_AI_Coding\Multisite\Multisite';
/**
* Skip message constant.
*/
const MULTISITE_SKIP_MSG = 'Multisite class not available';
/**
* Sample test case for the Multisite class.
*/
class MultisiteTest extends WP_UnitTestCase {
/**
* Test instance creation.
*
* @return void
*/
public function test_instance() {
if ( ! class_exists( MULTISITE_CLASS ) ) {
$this->markTestSkipped( MULTISITE_SKIP_MSG );
}
$multisite = new Multisite();
$this->assertInstanceOf( MULTISITE_CLASS, $multisite );
}
/**
* Test is_multisite_compatible method.
*
* @return void
*/
public function test_is_multisite_compatible() {
if ( ! class_exists( MULTISITE_CLASS ) ) {
$this->markTestSkipped( MULTISITE_SKIP_MSG );
}
$multisite = new Multisite();
$this->assertTrue( $multisite->is_multisite_compatible() );
}
/**
* Test get_network_sites method.
*
* @return void
*/
public function test_get_network_sites() {
if ( ! class_exists( MULTISITE_CLASS ) ) {
$this->markTestSkipped( MULTISITE_SKIP_MSG );
}
$multisite = new Multisite();
// Mock the get_sites function if we're not in a multisite environment.
if ( ! function_exists( 'get_sites' ) ) {
$this->assertEquals( array(), $multisite->get_network_sites() );
} else {
$sites = $multisite->get_network_sites();
$this->assertIsArray( $sites );
}
}
/**
* Test initialize_hooks method.
*
* @return void
*/
public function test_initialize_hooks() {
if ( ! class_exists( MULTISITE_CLASS ) ) {
$this->markTestSkipped( MULTISITE_SKIP_MSG );
}
$multisite = new Multisite();
// Call the method.
$multisite->initialize_hooks();
// Check if the action was added.
$this->assertEquals( 10, has_action( 'network_admin_menu', array( $multisite, 'add_network_menu' ) ) );
}
}

62
tests/test-core.php
View File

@@ -1,62 +0,0 @@
<?php
/**
* Class CoreTest
*
* @package WPALLSTARS\PluginStarterTemplate
*/
use WPALLSTARS\PluginStarterTemplate\Core;
/**
* Core test case.
*/
class CoreTest extends \WP_Mock\Tools\TestCase {
/**
* Test instance
*
* @var Core
*/
private $core;
/**
* Set up the test environment.
*/
public function setUp(): void
{
parent::setUp();
// Set up mocks
WP_Mock::setUp();
// Create instance of Core class
$this->core = new Core();
}
/**
* Tear down the test environment.
*/
public function tearDown(): void
{
WP_Mock::tearDown();
parent::tearDown();
}
/**
* Test constructor
*/
public function test_constructor() {
// Verify that the constructor initializes hooks
$this->assertInstanceOf(Core::class, $this->core);
}
/**
* Test example method
*/
public function test_filter_content() {
$content = 'Test content';
// Test that filter_content returns the content
$this->assertEquals($content, $this->core->filter_content($content));
}
}

86
wiki/Changelog.md
View File

@@ -1,86 +0,0 @@
# Changelog
All notable changes to this project should be documented both here and in the main Readme files.
#### [0.1.9] - 2025-04-18
#### Changed
- Alphabetized AI IDE list in README.md
#### [0.1.8] - 2025-04-19
#### Added
- More informative badges to README.md (Build Status, Requirements, WP.org placeholders, Release, Issues, Contributors, Wiki).
#### [0.1.7] - 2025-04-19
#### Fixed
- GitHub Actions tests workflow with proper file paths and dependencies
#### Improved
- Workflow names for better clarity in GitHub Actions UI
#### [0.1.6] - 2025-04-19
#### Fixed
- GitHub Actions workflows permissions for releases and wiki sync
#### [0.1.5] - 2025-04-19
#### Fixed
- Release workflow to use correct plugin directory name
#### Added
- Testing setup with wp-env and Cypress
- Multisite compatibility
- npm scripts for development and testing
#### [0.1.3] - 2025-04-19
#### Added
- Improved AI IDE context recommendations in documentation
- Enhanced Starter Prompt with guidance on pinning AGENTS.md and .agents/
#### Changed
- Updated README.md and readme.txt with AI IDE context recommendations
- Improved documentation for AI-assisted development
- Moved Starter Prompt to the wiki for better organization
#### [0.1.2] - 2025-04-18
#### Added
- STARTER-PROMPT.md with comprehensive guide for customizing the template
- Additional AI workflow files for better development guidance
#### Changed
- Updated documentation files with improved instructions
#### [0.1.1] - 2025-04-18
#### Changed
- Updated LICENSE file with correct GPL-2.0 text
#### [0.1.0] - 2025-04-17
#### Added
- Initial release with basic template structure
- Core plugin architecture with OOP approach
- Admin interface components and styling
- Update mechanism with multiple source options
- Documentation templates for users and developers
- AI workflow documentation for AI-assisted development
- GitHub Actions workflows for automated tasks
- Wiki documentation templates

290
wiki/Coding-Standards.md
View File

@@ -1,290 +0,0 @@
# Coding Standards
This document outlines the coding standards used in this plugin. Following these standards ensures consistency, readability, and maintainability of the codebase.
## PHP Coding Standards
This plugin follows the [WordPress Coding Standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/) with some additional guidelines.
### File Structure
* Each PHP file should begin with the PHP opening tag `<?php` (no closing tag)
* Files should use the Unix line endings (LF)
* Files should be encoded in UTF-8 without BOM
### Naming Conventions
* **Classes**: Use `PascalCase` for class names
```php
class MyClassName {}
```
* **Methods and Functions**: Use `snake_case` for method and function names
```php
function my_function_name() {}
public function my_method_name() {}
```
* **Variables**: Use `snake_case` for variable names
```php
$my_variable_name = 'value';
```
* **Constants**: Use `UPPERCASE_WITH_UNDERSCORES` for constants
```php
define('MY_CONSTANT', 'value');
const MY_CLASS_CONSTANT = 'value';
```
* **Namespaces**: Use `PascalCase` for namespace segments
```php
namespace WPALLSTARS\PluginStarterTemplate;
```
* **Hooks**: Prefix hooks with the plugin's prefix
```php
do_action('wpst_hook_name');
apply_filters('wpst_filter_name', $value);
```
### Indentation and Formatting
* Use 4 spaces for indentation (not tabs)
* Opening braces for classes and functions should be on the same line
* Control structures should have one space between the statement and the opening parenthesis
* Each line should be no longer than 100 characters
```php
if ($condition) {
// Code here
} elseif ($another_condition) {
// More code
} else {
// Default code
}
```
### Documentation
* All classes, methods, and functions should be documented using PHPDoc
* Include a description, parameters, return values, and exceptions
```php
/**
* Short description of the function.
*
* Longer description if needed.
*
* @param string $param1 Description of the parameter.
* @param int $param2 Description of the parameter.
* @return bool Description of the return value.
* @throws Exception When something goes wrong.
*/
function my_function($param1, $param2) {
// Function code
}
```
### Object-Oriented Programming
* Each class should have a single responsibility
* Use visibility declarations for all properties and methods (public, protected, private)
* Use type hints for parameters and return types when possible
```php
class MyClass {
/**
* Property description.
*
* @var string
*/
private $property;
/**
* Method description.
*
* @param string $param Description of the parameter.
* @return bool Description of the return value.
*/
public function my_method(string $param): bool {
// Method code
}
}
```
## JavaScript Coding Standards
This plugin follows the [WordPress JavaScript Coding Standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/javascript/).
### Naming Conventions
* **Variables and Functions**: Use `camelCase` for variable and function names
```javascript
var myVariableName = 'value';
function myFunctionName() {}
```
* **Constants**: Use `UPPERCASE_WITH_UNDERSCORES` for constants
```javascript
var MY_CONSTANT = 'value';
```
### Indentation and Formatting
* Use 4 spaces for indentation (not tabs)
* Opening braces should be on the same line as the statement
* Each line should be no longer than 100 characters
```javascript
if (condition) {
// Code here
} else if (anotherCondition) {
// More code
} else {
// Default code
}
```
### Documentation
* Use JSDoc for documenting functions and objects
```javascript
/**
* Short description of the function.
*
* @param {string} param1 - Description of the parameter.
* @param {number} param2 - Description of the parameter.
* @returns {boolean} Description of the return value.
*/
function myFunction(param1, param2) {
// Function code
}
```
## CSS Coding Standards
This plugin follows the [WordPress CSS Coding Standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/css/).
### Naming Conventions
* Use lowercase for selectors
* Use hyphens to separate words in class and ID names
* Prefix classes and IDs with the plugin's prefix
```css
.wpst-container {
margin: 0;
}
#wpst-header {
padding: 10px;
}
```
### Indentation and Formatting
* Use 4 spaces for indentation (not tabs)
* Each property should be on its own line
* Include a space after the colon in property declarations
* End each declaration with a semicolon
* Use single quotes for attribute selectors and property values
```css
.wpst-container {
margin: 0;
padding: 10px;
font-family: 'Helvetica', sans-serif;
}
```
## Automated Code Checking
This plugin uses automated tools to enforce coding standards:
### Local Development Tools
1. **PHP_CodeSniffer (PHPCS)**: Checks PHP code against the WordPress Coding Standards
```bash
composer run phpcs
```
2. **PHP Code Beautifier and Fixer (PHPCBF)**: Automatically fixes some coding standard violations
```bash
composer run phpcbf
```
3. **ESLint**: Checks JavaScript code against the WordPress Coding Standards
```bash
npm run lint:js
```
4. **Stylelint**: Checks CSS code against the WordPress Coding Standards
```bash
npm run lint:css
```
### Continuous Integration Tools
This project integrates with several code quality tools that automatically analyze your code when you create a pull request. These tools are free for public repositories and should be integrated into any new repositories based on this template.
1. **CodeRabbit**: AI-powered code review tool
* Provides automated feedback on pull requests
* Identifies potential issues and suggests improvements
* [Website](https://www.coderabbit.ai/)
2. **CodeFactor**: Continuous code quality monitoring
* Provides a grade for your codebase
* Identifies issues related to code style, complexity, and potential bugs
* Tracks code quality over time
* [Website](https://www.codefactor.io/)
3. **Codacy**: Code quality and static analysis
* Provides a grade for your codebase
* Identifies issues related to code style, security, and performance
* Tracks code quality over time
* [Website](https://www.codacy.com/)
4. **SonarCloud**: Code quality and security analysis
* Provides detailed analysis of code quality
* Identifies security vulnerabilities and technical debt
* Tracks code quality over time
* [Website](https://sonarcloud.io/)
### How to Pass Code Quality Checks
To ensure your code passes the quality checks from these tools, follow these guidelines:
1. **Run Local Checks First**
* Before pushing your code, run PHPCS and PHPCBF locally
* Fix any issues identified by these tools
2. **Address Common Issues**
* **Indentation**: Use 4 spaces for indentation (not tabs)
* **Line Length**: Keep lines under 100 characters
* **Naming Conventions**: Follow WordPress naming conventions
* **Documentation**: Add PHPDoc comments to classes, methods, and functions
* **Error Handling**: Implement proper error handling
* **Security**: Validate and sanitize input, escape output
* **Markdown**: Use asterisks (*) for bullet points, not hyphens (-)
3. **Using AI Assistants with Code Quality Tools**
* When you receive feedback from code quality tools, you can use AI assistants to help address the issues
* Copy the output from the code quality tool and paste it into your AI assistant chat
* Ask the AI to help you understand and resolve the issues
* Example prompt:
```text
I received the following feedback from [Tool Name]. Please help me understand and resolve these issues:
[Paste the tool output here]
```
4. **Iterative Improvement**
* Address issues one at a time, starting with the most critical
* Commit and push your changes to see if they resolve the issues
* Continue this process until all issues are resolved
## Conclusion
Following these coding standards ensures that the plugin's code is consistent, readable, and maintainable. All contributors should adhere to these standards when submitting code to the project.

180
wiki/Contributing.md
View File

@@ -1,180 +0,0 @@
# Contributing
Thank you for considering contributing to this project! This document provides guidelines and instructions for contributing.
## Code of Conduct
By participating in this project, you agree to abide by our code of conduct:
- Be respectful and inclusive
- Be patient and welcoming
- Be considerate
- Be collaborative
- Be open-minded
## How to Contribute
### Reporting Bugs
If you find a bug, please report it by creating an issue on GitHub:
1. Go to the [Issues](https://github.com/wpallstars/wp-plugin-starter-template-for-ai-coding/issues) page
2. Click "New Issue"
3. Select "Bug Report"
4. Fill out the template with as much detail as possible
5. Submit the issue
Please include:
- A clear, descriptive title
- Steps to reproduce the bug
- Expected behavior
- Actual behavior
- Screenshots (if applicable)
- Your environment (WordPress version, PHP version, browser, etc.)
### Suggesting Enhancements
If you have an idea for an enhancement:
1. Go to the [Issues](https://github.com/wpallstars/wp-plugin-starter-template-for-ai-coding/issues) page
2. Click "New Issue"
3. Select "Feature Request"
4. Fill out the template with as much detail as possible
5. Submit the issue
Please include:
- A clear, descriptive title
- A detailed description of the enhancement
- Why this enhancement would be useful
- Any relevant examples or mockups
### Pull Requests
If you want to contribute code:
1. Fork the repository
2. Create a new branch for your feature or bugfix
3. Make your changes
4. Run tests to ensure your changes don't break anything
5. Submit a pull request
#### Pull Request Process
1. Fork the repository on [GitHub](https://github.com/wpallstars/wp-plugin-starter-template-for-ai-coding/) or [Gitea](https://gitea.wpallstars.com/wpallstars/wp-plugin-starter-template-for-ai-coding/)
2. Clone your fork: `git clone https://github.com/YOUR-USERNAME/wp-plugin-starter-template-for-ai-coding.git`
3. Create your feature branch: `git checkout -b feature/amazing-feature`
4. Make your changes
5. Commit your changes: `git commit -m 'Add some amazing feature'`
6. Push to the branch: `git push origin feature/amazing-feature`
7. Submit a pull request
#### Pull Request Guidelines
- Follow the coding standards (see [Coding Standards](Coding-Standards))
- Write tests for your changes
- Update documentation as needed
- Keep pull requests focused on a single change
- Write a clear, descriptive title and description
- Reference any related issues
- Ensure your code passes the automated code quality checks (see below)
#### Code Quality Tools
This project uses several automated code quality tools to ensure high standards. These tools are free for public repositories and will automatically analyze your code when you create a pull request:
1. **CodeRabbit**: AI-powered code review tool
- [Website](https://www.coderabbit.ai/)
- Provides automated feedback on pull requests
2. **CodeFactor**: Continuous code quality monitoring
- [Website](https://www.codefactor.io/)
- Provides a grade for your codebase
3. **Codacy**: Code quality and static analysis
- [Website](https://www.codacy.com/)
- Identifies issues related to code style, security, and performance
4. **SonarCloud**: Code quality and security analysis
- [Website](https://sonarcloud.io/)
- Provides detailed analysis of code quality and security
#### Using AI Assistants with Code Quality Tools
When you receive feedback from these code quality tools, you can use AI assistants to help address the issues:
1. Copy the output from the code quality tool
2. Paste it into your AI assistant chat
3. Ask the AI to help you understand and resolve the issues
4. Apply the suggested fixes
5. Commit the changes and verify that the issues are resolved
Example prompt for AI assistants:
```text
I received the following feedback from [Tool Name]. Please help me understand and resolve these issues:
[Paste the tool output here]
```
## Development Environment
To set up your development environment:
1. Clone the repository: `git clone https://github.com/wpallstars/wp-plugin-starter-template-for-ai-coding.git`
2. Install dependencies: `composer install && npm install`
3. Start the development environment: `npm run start`
### Testing
Before submitting a pull request, make sure to run the tests:
* PHP Unit Tests: `npm run test:php`
* End-to-End Tests: `npm run test:e2e`
* Coding Standards: `npm run lint:php`
#### Code Quality Checks
To ensure your code meets the quality standards, run these commands before submitting a pull request:
* Check coding standards: `composer run phpcs`
* Fix coding standards automatically: `composer run phpcbf`
* Check JavaScript coding standards: `npm run lint:js`
* Check CSS coding standards: `npm run lint:css`
These checks will help identify and fix issues before they are caught by the automated code quality tools in the pull request process.
## Documentation
If you're adding a new feature or changing existing functionality, please update the documentation:
* Update the README.md file if necessary
* Update the readme.txt file if necessary
* Update or create wiki pages as needed
* Update code comments
## Community
Join our community to discuss the project:
* [GitHub Discussions](https://github.com/wpallstars/wp-plugin-starter-template-for-ai-coding/discussions)
* [Gitea Issues](https://gitea.wpallstars.com/wpallstars/wp-plugin-starter-template-for-ai-coding/issues)
## Recognition
Contributors will be recognized in the following ways:
* Added to the contributors list in readme.txt
* Mentioned in release notes for significant contributions
* Thanked in the Changelog for specific contributions
## License
By contributing to this project, you agree that your contributions will be licensed under the project's [GPL-2.0+ License](https://www.gnu.org/licenses/gpl-2.0.html).
## Questions?
If you have any questions about contributing, please open an issue or contact the maintainers.
Thank you for your contributions!

119
wiki/Frequently-Asked-Questions.md
View File

@@ -1,119 +0,0 @@
# Frequently Asked Questions
This page answers common questions about the WordPress Plugin Starter Template.
## General Questions
### What is the WordPress Plugin Starter Template?
The WordPress Plugin Starter Template is a comprehensive starting point for developing WordPress plugins. It provides a well-structured codebase, documentation templates, and best practices to help you create high-quality WordPress plugins efficiently.
### Who is this template for?
This template is designed for:
- WordPress plugin developers looking for a solid foundation
- Developers who want to leverage AI assistance in their development workflow
- Anyone who wants to create a WordPress plugin following best practices
### Is this template suitable for all types of plugins?
Yes, this template provides a solid foundation for most WordPress plugins. It's designed to be flexible and can be adapted for various types of plugins, from simple utilities to complex applications.
## Usage Questions
### How do I use this template?
This template is meant to be a starting point for your own plugin development. You should:
1. Copy the template files to your new plugin directory
2. Rename files and update namespaces to match your plugin name
3. Update plugin headers in the main PHP file
4. Customize the functionality to meet your specific needs
5. Update documentation to reflect your plugin's features
For detailed instructions, see the [Usage Instructions](Usage-Instructions) page.
### Do I need to keep the original credits?
While not strictly required, we appreciate if you keep a reference to the original template in your plugin's documentation. This helps others discover the template and contributes to the open-source community.
### Can I use this template for commercial plugins?
Yes, you can use this template for both free and commercial plugins. The template is licensed under GPL-2.0+, which allows for commercial use.
## Technical Questions
### What PHP version is required?
The template requires PHP 7.0 or higher, which is the minimum recommended version for WordPress plugins today.
### Does this template support Gutenberg blocks?
The template doesn't include Gutenberg blocks by default, but it provides a structure that makes it easy to add them. You can extend the template to include block registration and block-specific assets.
### How do I add custom post types or taxonomies?
To add custom post types or taxonomies:
1. Create a new class in `includes/` for your post type or taxonomy
2. Register the post type or taxonomy in the class constructor
3. Initialize the class in `includes/plugin.php`
### How do I handle plugin updates?
The template includes an update mechanism that supports multiple sources:
- WordPress.org
- GitHub
- Gitea
To configure the update mechanism:
1. Update the plugin headers in the main PHP file
2. Customize the `updater.php` file if needed
3. Ensure your repository follows the required structure for updates
## AI-Assisted Development Questions
### How does this template support AI-assisted development?
The template includes:
1. Detailed documentation in the `AGENTS.md` file
2. Workflow guidelines in the `.agents/` directory
3. Clear code structure and comments that help AI understand the codebase
4. Best practices for AI-friendly code organization
### What AI tools work best with this template?
This template is designed to work well with various AI coding assistants, including:
- GitHub Copilot
- Claude
- ChatGPT
- Other AI coding assistants
### How do I use the AI workflow documentation?
The AI workflow documentation in the `.agents/` directory provides guidelines for AI assistants working with this template. These files help ensure consistent, high-quality code and documentation when using AI tools for development.
## Contributing Questions
### How can I contribute to this template?
Contributions are welcome! Please feel free to:
1. Report bugs or issues
2. Suggest new features or improvements
3. Submit pull requests with bug fixes or enhancements
For more information, see the [Contributing](Contributing) page.
### Where can I report issues?
You can report issues on the [GitHub repository](https://github.com/wpallstars/wp-plugin-starter-template-for-ai-coding/issues).
### Is there a roadmap for future development?
Yes, we maintain a roadmap of planned features and improvements. You can find it in the [GitHub repository](https://github.com/wpallstars/wp-plugin-starter-template-for-ai-coding/projects).

41
wiki/Home.md
View File

@@ -1,41 +0,0 @@
# WordPress Plugin Starter Template
Welcome to the documentation wiki for the WordPress Plugin Starter Template.
This template provides a solid foundation for developing WordPress plugins with best practices for AI-assisted development.
## Quick Links
- [Starter Prompt](Starter-Prompt)
- [Installation Guide](Installation-Guide)
- [Usage Instructions](Usage-Instructions)
- [Frequently Asked Questions](Frequently-Asked-Questions)
- [Contributing](Contributing)
- [Changelog](Changelog)
## About This Template
The WordPress Plugin Starter Template is designed to help developers quickly create new WordPress plugins with a solid foundation of best practices. It incorporates modern coding standards, comprehensive documentation, and AI-assisted development workflows.
This template is based on the experience gained from developing the "Fix 'Plugin file does not exist' Notices" plugin and other successful WordPress plugins.
## Key Features
- **Object-Oriented Architecture**: Well-structured, maintainable code using OOP principles
- **Namespace Support**: Modern PHP namespacing for better organization and avoiding conflicts
- **Comprehensive Documentation**: Detailed documentation for both users and developers
- **Testing Framework**: PHPUnit setup for unit testing
- **Internationalization Ready**: Full support for translation and localization
- **Update Source Selection**: Choose between WordPress.org, GitHub, or Gitea for plugin updates
- **AI Workflow Documentation**: Detailed guides for AI-assisted development
- **Wiki Documentation**: Ready-to-use wiki structure for comprehensive documentation
## Getting Started
To get started with this template, check out the [Starter Prompt](Starter-Prompt) for a comprehensive guide on customizing the template for your specific plugin needs.
**Important**: For the best AI assistance, add the AGENTS.md file and .agents/ directory to your AI IDE chat context. In most AI IDEs, you can pin these files to ensure they're considered in each message.
## Support
If you encounter any issues or have questions about the template, please check the [Frequently Asked Questions](Frequently-Asked-Questions) section. If you still need help, you can [open an issue](https://github.com/wpallstars/wp-plugin-starter-template-for-ai-coding/issues) on GitHub.

81
wiki/Installation-Guide.md
View File

@@ -1,81 +0,0 @@
# Installation Guide
This guide provides instructions for installing and setting up the WordPress Plugin Starter Template.
## Prerequisites
Before installing the plugin, ensure you have:
- WordPress 5.0 or higher
- PHP 7.0 or higher
- A WordPress site with administrator access
## Installation Methods
### Method 1: From WordPress.org (For Released Plugins)
1. Log in to your WordPress admin dashboard.
2. Navigate to **Plugins > Add New**.
3. Search for "WordPress Plugin Starter Template".
4. Click **Install Now** next to the plugin.
5. After installation, click **Activate**.
### Method 2: Manual Installation
1. Download the latest release from the [GitHub repository](https://github.com/wpallstars/wp-plugin-starter-template-for-ai-coding/releases).
2. Log in to your WordPress admin dashboard.
3. Navigate to **Plugins > Add New**.
4. Click the **Upload Plugin** button at the top of the page.
5. Click **Choose File** and select the downloaded ZIP file.
6. Click **Install Now**.
7. After installation, click **Activate**.
### Method 3: Using as a Template for Your Plugin
1. Clone or download the repository:
```bash
git clone https://github.com/wpallstars/wp-plugin-starter-template-for-ai-coding.git your-plugin-name
```
2. Navigate to your plugin directory:
```bash
cd your-plugin-name
```
3. Rename files and update namespaces:
- Rename `wp-plugin-starter-template.php` to your plugin name (e.g., `your-plugin-name.php`)
- Update the namespace from `WPALLSTARS\PluginStarterTemplate` to your own
- Update text domain from `wp-plugin-starter-template` to your own
4. Update plugin headers in the main PHP file.
5. Install dependencies:
```bash
composer install
```
6. Upload the plugin to your WordPress site or use the local development script:
```bash
./scripts/deploy-local.sh
```
## Post-Installation
After installing and activating the plugin, you should:
1. Review the plugin settings (if applicable).
2. Customize the plugin for your specific needs.
3. Update documentation to reflect your plugin's features.
## Troubleshooting Installation Issues
If you encounter any issues during installation, please check the following:
1. **Plugin Conflicts**: Deactivate other plugins to check for conflicts.
2. **Server Requirements**: Ensure your server meets the minimum requirements.
3. **File Permissions**: Check that your WordPress installation has the correct file permissions.
4. **Memory Limit**: Increase PHP memory limit if you encounter memory-related errors.
## Next Steps
After installation, refer to the [Usage Instructions](Usage-Instructions) to learn how to use and customize the plugin.

190
wiki/Starter-Prompt.md
View File

@@ -1,190 +0,0 @@
# WordPress Plugin Starter Template - AI Assistant Prompt
This document provides a comprehensive prompt to help you get started with creating your own WordPress plugin using this starter template with the assistance of AI tools like GitHub Copilot, Claude, or ChatGPT.
## Important: Optimize AI Context
**Before starting, add the AGENTS.md file and .agents/ directory to your AI IDE chat context.** In most AI IDEs, you can pin these files to ensure they're considered in each message. This will help the AI understand the project structure and follow the established best practices.
## Initial Setup Prompt
Use the following prompt to guide the AI assistant in helping you set up your new plugin based on this template:
```
I'm creating a new WordPress plugin based on the wp-plugin-starter-template-for-ai-coding template. Please help me customize this template for my specific plugin needs.
Here are the details for my new plugin:
- Plugin Name: [YOUR PLUGIN NAME]
- Plugin Slug: [YOUR-PLUGIN-SLUG]
- Text Domain: [your-plugin-text-domain]
- Namespace: [VENDOR]\[PluginName]
- Description: [BRIEF DESCRIPTION OF YOUR PLUGIN]
- Version: 0.1.0 (starting version)
- Author: [YOUR NAME/ORGANIZATION]
- Author URI: [YOUR WEBSITE]
- License: GPL-2.0+ (or specify another compatible license)
- Requires WordPress: [MINIMUM WP VERSION, e.g., 5.0]
- Requires PHP: [MINIMUM PHP VERSION, e.g., 7.0]
- GitHub Repository: [YOUR GITHUB REPO URL]
- Gitea Repository (if applicable): [YOUR GITEA REPO URL]
I need help with the following tasks:
1. Updating all template placeholders with my plugin information
2. Customizing the plugin structure for my specific needs
3. Setting up the initial functionality for my plugin
I've added the AGENTS.md and .agents/ directory to the chat context to ensure you have all the necessary information about the project structure and best practices.
Please guide me through this process step by step, starting with identifying all files that need to be updated with my plugin information.
```
## Files That Need Updating
The AI will help you identify and update the following files with your plugin information:
1. **Main Plugin File**: Rename `wp-plugin-starter-template.php` to `your-plugin-slug.php` and update all plugin header information
2. **README.md**: Update with your plugin details, features, and installation instructions
3. **readme.txt**: Update WordPress.org plugin repository information
4. **CHANGELOG.md**: Initialize with your starting version
5. **composer.json**: Update package name and description
6. **languages/pot file**: Rename and update the POT file
7. **.github/workflows/**: Update GitHub Actions workflows with your repository information
8. **.wiki/**: Update wiki documentation with your plugin information
9. **AGENTS.md**: Update AI assistant guidance for your specific plugin
10. **includes/plugin.php**: Update namespace and class references
11. **includes/core.php**: Update namespace and customize core functionality
12. **admin/lib/admin.php**: Update namespace and customize admin functionality
## Customization Process
After providing the initial information, follow this process with your AI assistant:
### 1. File Renaming
Ask the AI to help you identify all files that need to be renamed:
```
Please list all files that need to be renamed to match my plugin slug, and provide the commands to rename them.
```
### 2. Namespace Updates
Ask the AI to help you update all namespace references:
```
Please help me update all namespace references from WPALLSTARS\PluginStarterTemplate to [VENDOR]\[PluginName] throughout the codebase.
```
### 3. Text Domain Updates
Ask the AI to help you update all text domain references:
```
Please help me update all text domain references from 'wp-plugin-starter-template' to '[your-plugin-text-domain]' throughout the codebase.
```
### 4. Function Prefix Updates
Ask the AI to help you update any function prefixes:
```
Please help me update any function prefixes from 'wpst_' to '[your_prefix]_' throughout the codebase.
```
### 5. Customizing Core Functionality
Ask the AI to help you customize the core functionality for your specific plugin needs:
```
Now I'd like to customize the core functionality for my plugin. Here's what my plugin should do:
[DESCRIBE YOUR PLUGIN'S CORE FUNCTIONALITY]
Please help me modify the includes/core.php file to implement this functionality.
```
### 6. Customizing Admin Interface
Ask the AI to help you customize the admin interface for your specific plugin needs:
```
I'd like to customize the admin interface for my plugin. Here's what I need in the admin area:
[DESCRIBE YOUR PLUGIN'S ADMIN INTERFACE NEEDS]
Please help me modify the admin/lib/admin.php file and any other necessary files to implement this.
```
### 7. Testing Setup
Ask the AI to help you set up testing for your plugin:
```
Please help me update the testing setup to match my plugin's namespace and functionality. I want to ensure I have proper test coverage for the core features.
```
## Additional Customization Areas
Depending on your plugin's needs, you might want to ask the AI for help with:
1. **Custom Post Types**: Setting up custom post types and taxonomies
2. **Settings API**: Implementing WordPress Settings API for your plugin options
3. **Shortcodes**: Creating shortcodes for front-end functionality
4. **Widgets**: Developing WordPress widgets
5. **REST API**: Adding custom REST API endpoints
6. **Blocks**: Creating Gutenberg blocks
7. **Internationalization**: Ensuring proper i18n setup
8. **Database Tables**: Creating custom database tables if needed
9. **Cron Jobs**: Setting up WordPress cron jobs
10. **User Roles and Capabilities**: Managing custom user roles and capabilities
## Final Review
Once you've completed the customization, ask the AI to help you review everything:
```
Please help me review all the changes we've made to ensure:
1. All template placeholders have been replaced with my plugin information
2. All namespaces, text domains, and function prefixes have been updated consistently
3. The plugin structure matches my specific needs
4. The initial functionality is properly implemented
5. All documentation (README.md, readme.txt, wiki) is updated and consistent
Are there any issues or inconsistencies that need to be addressed?
```
## Building and Testing
Finally, ask the AI to guide you through building and testing your plugin:
```
Please guide me through the process of building and testing my plugin:
1. How do I use the build script to create a deployable version?
2. What tests should I run to ensure everything is working correctly?
3. How do I set up a local testing environment?
4. What should I check before releasing the first version?
```
## Optimizing AI Assistance
To ensure the AI assistant has all the necessary context about your plugin's structure and best practices:
```
Please add the AGENTS.md and .agents/ directory to your AI IDE chat context. In most AI IDEs, you can pin these files to ensure they're considered in each message. This will help the AI understand the project structure and follow the established best practices.
```
## Remember
- This template is designed to be a starting point. Feel free to add, remove, or modify components as needed for your specific plugin.
- The AI assistant can help you understand the existing code and make appropriate modifications, but you should review all changes to ensure they meet your requirements.
- Always test your plugin thoroughly before releasing it.
- Keep documentation updated as you develop your plugin.
- Pin the AGENTS.md and .agents/ files in your AI IDE chat to ensure the AI has the necessary context for each interaction.
## Credits
This plugin is based on the [WordPress Plugin Starter Template for AI Coding](https://github.com/wpallstars/wp-plugin-starter-template-for-ai-coding) by WPALLSTARS.

121
wiki/Usage-Instructions.md
View File

@@ -1,121 +0,0 @@
# Usage Instructions
This guide provides instructions for using and customizing the WordPress Plugin Starter Template for your own plugin development.
## Basic Usage
The WordPress Plugin Starter Template is designed to be a starting point for your WordPress plugin development. It provides a well-structured codebase that you can customize to create your own plugin.
### Template Structure
The template follows a modular structure:
- `wp-plugin-starter-template.php`: Main plugin file with plugin headers
- `includes/`: Core plugin functionality
- `plugin.php`: Main plugin class that initializes everything
- `core.php`: Core functionality class
- `updater.php`: Update mechanism for multiple sources
- `admin/`: Admin-specific functionality
- `lib/`: Admin classes
- `css/`: Admin stylesheets
- `js/`: Admin JavaScript files
- `languages/`: Translation files
- `.github/workflows/`: GitHub Actions workflows
- `.agents/`: Documentation for AI assistants
- `.wiki/`: Wiki documentation templates
### Customizing for Your Plugin
1. **Rename Files and Update Namespaces**:
- Rename `wp-plugin-starter-template.php` to your plugin name
- Update the namespace from `WPALLSTARS\PluginStarterTemplate` to your own
- Update text domain from `wp-plugin-starter-template` to your own
2. **Update Plugin Headers**:
- Edit the plugin headers in the main PHP file
- Update GitHub/Gitea repository URLs
3. **Customize Functionality**:
- Modify the core functionality in `includes/core.php`
- Add your own classes as needed
- Customize admin interfaces in the `admin/` directory
4. **Update Documentation**:
- Update README.md and readme.txt with your plugin information
- Customize wiki documentation in the `.wiki/` directory
## Advanced Usage
### Adding Admin Pages
The template includes a structure for adding admin pages to the WordPress dashboard. To add an admin page:
1. Uncomment the `add_admin_menu` method in `admin/lib/admin.php`
2. Customize the menu parameters to match your plugin
3. Create the corresponding render method for your admin page
4. Create template files in an `admin/templates/` directory
### Adding Settings
To add settings to your plugin:
1. Create a settings class in `includes/settings.php`
2. Register settings using the WordPress Settings API
3. Create form fields for your settings
4. Handle settings validation and sanitization
### Adding Custom Post Types or Taxonomies
To add custom post types or taxonomies:
1. Create a new class in `includes/` for your post type or taxonomy
2. Register the post type or taxonomy in the class constructor
3. Initialize the class in `includes/plugin.php`
### Internationalization
The template is ready for internationalization. To make your plugin translatable:
1. Use translation functions for all user-facing strings:
- `__()` for simple strings
- `_e()` for echoed strings
- `esc_html__()` for escaped strings
2. Update the text domain in all translation functions
3. Generate a POT file for translations
### Update Mechanism
The template includes an update mechanism that supports multiple sources:
- WordPress.org
- GitHub
- Gitea
To configure the update mechanism:
1. Update the plugin headers in the main PHP file
2. Customize the `updater.php` file if needed
3. Ensure your repository follows the required structure for updates
## Building and Releasing
The template includes scripts for building and releasing your plugin:
1. **Building the Plugin**:
```bash
./build.sh <version>
```
2. **Deploying to a Local WordPress Installation**:
```bash
./scripts/deploy-local.sh
```
3. **Creating a Release**:
- Tag a new version in Git
- Push the tag to GitHub
- The GitHub Actions workflow will create a release
## Next Steps
After customizing the template for your needs, refer to the [Architecture Overview](Architecture-Overview) to understand the plugin's structure in more detail.

24
wiki/_Sidebar.md
View File

@@ -1,24 +0,0 @@
## User Documentation
* [Home](Home)
* [Installation Guide](Installation-Guide)
* [Usage Instructions](Usage-Instructions)
* [Frequently Asked Questions](Frequently-Asked-Questions)
* [Troubleshooting](Troubleshooting)
## Developer Documentation
* [Architecture Overview](Architecture-Overview)
* [Customization Guide](Customization-Guide)
* [Extending the Plugin](Extending-the-Plugin)
* [Coding Standards](Coding-Standards)
* [Release Process](Release-Process)
## AI Documentation
* [AI Workflow Documentation](AI-Workflow-Documentation)
## Additional Resources
* [Changelog](Changelog)
* [Contributing](Contributing)

45
wp-plugin-starter-template.php
View File

@@ -31,11 +31,50 @@ if ( ! defined( 'WPINC' ) ) {
die;
}
// Load the main plugin class.
require_once plugin_dir_path( __FILE__ ) . 'includes/class-plugin.php';
// Define plugin constants.
define( 'WP_PLUGIN_STARTER_TEMPLATE_FILE', __FILE__ );
define( 'WP_PLUGIN_STARTER_TEMPLATE_PATH', plugin_dir_path( __FILE__ ) );
define( 'WP_PLUGIN_STARTER_TEMPLATE_URL', plugin_dir_url( __FILE__ ) );
define( 'WP_PLUGIN_STARTER_TEMPLATE_VERSION', '0.1.15' );
// Use namespace imports instead of require_once.
use WPALLSTARS\PluginStarterTemplate\Plugin;
// Register autoloader for plugin classes.
spl_autoload_register(
function ( $className ) {
// Plugin namespace prefix.
$prefix = 'WPALLSTARS\\PluginStarterTemplate\\';
// Check if the class uses our namespace.
$len = strlen( $prefix );
if ( strncmp( $prefix, $className, $len ) !== 0 ) {
return;
}
// Get the relative class name.
$relative_class = substr( $className, $len );
// Convert namespace to path.
$file = WP_PLUGIN_STARTER_TEMPLATE_PATH . 'includes/' . str_replace( '\\', '/', $relative_class ) . '.php';
// Convert class name format to file name format.
$file = str_replace( 'class-', '', $file );
$file = preg_replace( '/([a-z])([A-Z])/', '$1-$2', $file );
$file = strtolower( $file );
// If the file exists, require it.
if ( file_exists( $file ) ) {
require_once $file;
}
}
);
// Plugin is multisite compatible - see .wiki/Testing-Framework.md for testing instructions.
// For multisite-specific functionality, see the includes/Multisite directory.
// Initialize the plugin and store the instance in a global variable.
$wpst_plugin = new WPALLSTARS\PluginStarterTemplate\Plugin( __FILE__, '0.1.15' );
$wpst_plugin = new Plugin( __FILE__, WP_PLUGIN_STARTER_TEMPLATE_VERSION );
// Initialize the plugin.
$wpst_plugin->init();