WordPress Plugin Boilerplate

A modern, well-structured WordPress plugin boilerplate built with best practices, following PSR-12 standards and WordPress coding guidelines.

🚀 Features

• Modern Architecture: Built with PHP 8.2+ and modern WordPress practices
• PSR-12 Compliant: Follows PHP coding standards
• WordPress Standards: Adheres to WordPress coding guidelines
• Modular Design: Clean separation of concerns with providers pattern
• Security First: Built-in security features and validation
• Performance Optimized: Caching system and performance optimizations
• REST API Ready: Built-in REST API support
• Internationalization: Full i18n support with text domain
• Testing Ready: PHPUnit configuration and test structure
• Code Quality: PHPCS, PHPStan, and automated testing setup
• Documentation: Comprehensive documentation and examples

📋 Requirements

• WordPress: 5.0 or higher
• PHP: 8.2 or higher
• MySQL: 5.7 or higher
• Composer: For dependency management

🏗️ Plugin Structure

your-plugin-name/
├── admin/                    # Admin-specific functionality
│   ├── assets/              # Admin CSS, JS, and images
│   ├── class-admin.php      # Main admin class
│   ├── templates/           # Admin page templates
│   └── index.php            # Security file
├── includes/                 # Core plugin classes
│   ├── class-activator.php  # Plugin activation handler
│   ├── class-deactivator.php # Plugin deactivation handler
│   ├── class-i18n.php       # Internationalization
│   ├── class-include.php    # Main plugin class
│   ├── class-loader.php     # Hook loader
│   ├── class-security.php   # Security utilities
│   └── index.php            # Security file
├── providers/               # Feature providers (modular)
│   ├── core/               # Core functionality provider
│   ├── api/                # REST API provider
│   ├── cache/              # Caching provider
│   └── index.php           # Provider loader
├── public/                 # Public-facing functionality
│   ├── assets/             # Public CSS, JS, and images
│   ├── class-public.php    # Public class
│   └── index.php           # Security file
├── languages/              # Translation files
├── tests/                  # Test files
│   ├── Unit/              # Unit tests
│   ├── Integration/       # Integration tests
│   ├── Feature/           # Feature tests
│   └── bootstrap.php      # Test bootstrap
├── vendor/                 # Composer dependencies
├── .env.example            # Environment variables example
├── config.php              # Plugin configuration
├── plugin-core.php         # Main plugin file
├── composer.json           # Composer configuration
├── phpunit.xml            # PHPUnit configuration
├── phpcs.xml              # PHPCS configuration
├── README.md               # This file
└── LICENSE                 # License file

🛠️ Installation

1. Clone the Boilerplate

git clone https://github.com/your-username/wordpress-plugin-boilerplate.git your-plugin-name
cd your-plugin-name

2. Install Dependencies

composer install

3. Configure Your Plugin

1. Update config.php: Modify all constants to match your plugin
2. Update plugin-core.php: Change plugin name, description, and author
3. Update composer.json: Change package name and author information
4. Copy environment file: cp env.example .env and configure variables

4. Customize the Plugin

• Update class names: Change Your_Plugin to your actual class name
• Modify providers: Add/remove providers based on your needs
• Update text domain: Change your-plugin-name to your actual text domain
• Customize admin pages: Modify admin templates and functionality

5. Activate the Plugin

Upload to your WordPress plugins directory and activate through the admin panel.

⚙️ Configuration

Environment Variables

The plugin uses environment variables for configuration. Copy env.example to .env and configure:

# Plugin Basic Settings
PLUGIN_NAME="Your Plugin Name"
PLUGIN_SLUG="your-plugin-name"
PLUGIN_VERSION="1.0.0"
PLUGIN_DEBUG_MODE=false

# Database Settings
DB_HOST="localhost"
DB_NAME="wordpress"
DB_USER="wp_user"
DB_PASSWORD="wp_password"

# Security Settings
SECURITY_RATE_LIMITING=true
SECURITY_RATE_LIMIT_REQUESTS=100

Plugin Configuration

The config.php file contains all plugin constants and settings:

// Plugin Information
define('Plugin_Core', 'Your Plugin Name');
define('YOUR_PLUGIN_SLUG', 'your-plugin-name');
define('YOUR_PLUGIN_VERSION', '1.0.0');

// Plugin Paths
define('YOUR_PLUGIN_PATH', plugin_dir_path(__FILE__));
define('YOUR_PLUGIN_URL', plugin_dir_url(__FILE__));

🔧 Development

Available Composer Scripts

# Install dependencies
composer install

# Run tests
composer test

# Run specific test suites
composer test:unit
composer test:integration
composer test:feature

# Code quality checks
composer lint
composer lint:fix
composer analyze

# Generate documentation
composer docs

# Build for production
composer build

# Clean development files
composer clean

Testing

The plugin includes a comprehensive testing setup:

# Run all tests
composer test

# Run with coverage
composer test:coverage

# Run specific test suite
composer test:unit

Code Quality

# Check coding standards
composer lint

# Fix coding standards automatically
composer lint:fix

# Static analysis
composer analyze

🏛️ Architecture

Provider Pattern

The plugin uses a provider pattern for modular functionality:

// providers/core/ServiceProvider.php
class Core_ServiceProvider {
    public function register() {
        // Register services
    }
    
    public function boot() {
        // Boot services
    }
}

Hook System

The plugin includes a robust hook management system:

// Register hooks
$this->loader->add_action('init', $this, 'init');
$this->loader->add_filter('the_content', $this, 'filter_content');

Security Features

Built-in security features include:

• Input validation and sanitization
• Nonce verification
• Rate limiting
• SQL injection protection
• XSS protection
• CSRF protection

📚 API Reference

REST API Endpoints

The plugin automatically registers REST API endpoints:

// Example endpoint registration
add_action('rest_api_init', function() {
    register_rest_route('your-plugin/v1', '/example', [
        'methods' => 'GET',
        'callback' => 'your_callback_function',
        'permission_callback' => 'your_permission_function'
    ]);
});

AJAX Actions

// Register AJAX actions
add_action('wp_ajax_your_plugin_action', 'your_ajax_callback');
add_action('wp_ajax_nopriv_your_plugin_action', 'your_ajax_callback');

Shortcodes

// Register shortcodes
add_shortcode('your_shortcode', 'your_shortcode_callback');

🌐 Internationalization

The plugin includes full i18n support:

// Load text domain
load_plugin_textdomain('your-plugin-name', false, dirname(plugin_basename(__FILE__)) . '/languages');

// Use translation functions
__('Hello World', 'your-plugin-name');
_e('Hello World', 'your-plugin-name');
esc_html__('Hello World', 'your-plugin-name');

🔒 Security

Built-in Security Features

• Input Validation: All inputs are validated and sanitized
• Nonce Verification: Security tokens for forms and AJAX
• Rate Limiting: Protection against brute force attacks
• SQL Injection Protection: Prepared statements and escaping
• XSS Protection: Output escaping and sanitization
• CSRF Protection: Cross-site request forgery protection

Security Best Practices

// Validate and sanitize input
$input = sanitize_text_field($_POST['input_field']);

// Verify nonces
if (!wp_verify_nonce($_POST['nonce'], 'action_name')) {
    wp_die('Security check failed');
}

// Escape output
echo esc_html($data);
echo esc_url($url);
echo wp_kses_post($html);

🚀 Performance

Caching System

// Cache data
wp_cache_set('cache_key', $data, 'your_plugin_cache', 3600);

// Retrieve cached data
$cached_data = wp_cache_get('cache_key', 'your_plugin_cache');

Optimization Features

• Query Optimization: Efficient database queries
• Asset Minification: Minified CSS and JS in production
• Lazy Loading: Deferred loading of resources
• Compression: Automatic response compression

🧪 Testing

Test Structure

tests/
├── Unit/                   # Unit tests
├── Integration/            # Integration tests
├── Feature/                # Feature tests
├── bootstrap.php           # Test bootstrap
└── TestCase.php            # Base test case

Writing Tests

// tests/Unit/ExampleTest.php
class ExampleTest extends TestCase {
    public function test_example_function() {
        $result = example_function();
        $this->assertEquals('expected', $result);
    }
}

Running Tests

# Run all tests
composer test

# Run specific test file
./vendor/bin/phpunit tests/Unit/ExampleTest.php

# Run with coverage
composer test:coverage

📖 Documentation

Code Documentation

The plugin follows PHPDoc standards:

/**
 * Example function
 *
 * @param string $param Parameter description
 * @return string Return description
 * @since 1.0.0
 */
function example_function($param) {
    return $param;
}

API Documentation

Generate API documentation:

composer docs

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Contribution Guidelines

• Follow PSR-12 coding standards
• Include tests for new features
• Update documentation as needed
• Ensure all tests pass before submitting

📄 License

This project is licensed under the GPL v2 or later - see the LICENSE file for details.

🆘 Support

• Documentation: docs.your-plugin.com
• Issues: GitHub Issues
• Email: support@your-plugin.com

🔄 Changelog

v1.0.0

• ✅ Initial boilerplate implementation
• ✅ Modern WordPress plugin architecture
• ✅ PSR-12 compliant code structure
• ✅ Comprehensive testing setup
• ✅ Security features and best practices
• ✅ Performance optimizations
• ✅ Full documentation

---

Developed with ❤️ by Your Name

📝 Quick Start Checklist

• Clone the boilerplate
• Install dependencies with composer install
• Update config.php with your plugin details
• Update plugin-core.php with your plugin information
• Update composer.json with your details
• Copy env.example to .env and configure
• Customize class names and text domains
• Add your custom providers and functionality
• Test the plugin with composer test
• Deploy and activate in WordPress

🎯 Next Steps

1. Customize the Plugin: Modify the boilerplate to match your needs
2. Add Features: Implement your specific functionality
3. Write Tests: Add comprehensive tests for your features
4. Document: Update documentation for your specific use case
5. Deploy: Test in a staging environment before production