@mytechtoday/augment-extensions 0.7.0 → 1.2.1

package/augment-extensions/workflows/wordpress-plugin/rules/best-practices.md

@@ -1,942 +1,942 @@
-# WordPress Plugin Development Best Practices
-
-## Overview
-
-This document provides comprehensive best practices for WordPress plugin development, covering code organization, naming conventions, security, performance, accessibility, and backward compatibility.
-
-## Code Organization
-
-### Directory Structure
-
-**Standard Plugin Structure**:
-
-```
-plugin-name/
-├── plugin-name.php              # Main plugin file
-├── uninstall.php                # Uninstall cleanup
-├── readme.txt                   # WordPress.org readme
-├── LICENSE                      # License file
-├── includes/                    # Core plugin classes
-│   ├── class-plugin-name.php
-│   ├── class-activator.php
-│   ├── class-deactivator.php
-│   └── class-loader.php
-├── admin/                       # Admin-specific functionality
-│   ├── class-admin.php
-│   ├── partials/                # Admin view templates
-│   ├── css/
-│   └── js/
-├── public/                      # Public-facing functionality
-│   ├── class-public.php
-│   ├── partials/                # Public view templates
-│   ├── css/
-│   └── js/
-├── languages/                   # Translation files
-├── assets/                      # Plugin assets for WordPress.org
-│   ├── banner-772x250.png
-│   ├── banner-1544x500.png
-│   ├── icon-128x128.png
-│   └── icon-256x256.png
-└── tests/                       # PHPUnit tests
-    ├── bootstrap.php
-    ├── unit/
-    └── integration/
-```
-
-### File Organization Best Practices
-
-**DO**:
-- ✅ One class per file
-- ✅ Group related functionality in subdirectories
-- ✅ Separate admin and public functionality
-- ✅ Keep templates in `partials/` directories
-- ✅ Organize assets by type (css, js, images)
-
-**DON'T**:
-- ❌ Mix multiple classes in one file
-- ❌ Put all code in main plugin file
-- ❌ Mix admin and public code
-- ❌ Hardcode HTML in PHP classes
-- ❌ Put assets in root directory
-
-## Naming Conventions
-
-### File Naming
-
-**PHP Files**:
-```
-class-plugin-name.php           # Class files (lowercase, hyphens)
-class-admin.php
-class-public.php
-plugin-name-functions.php       # Function files
-```
-
-**Template Files**:
-```
-admin-display.php               # Admin templates
-public-display.php              # Public templates
-settings-page.php
-```
-
-**Asset Files**:
-```
-plugin-name-admin.css           # Prefixed with plugin name
-plugin-name-public.js
-plugin-name-icon.png
-```
-
-### Code Naming
-
-**Classes**:
-```php
-class Plugin_Name {}                    # Capitalized with underscores
-class Plugin_Name_Admin {}
-class Plugin_Name_Public {}
-```
-
-**Functions**:
-```php
-function plugin_name_activate() {}      # Lowercase with underscores
-function plugin_name_get_data() {}
-function plugin_name_sanitize_input() {}
-```
-
-**Variables**:
-```php
-$plugin_name = 'value';                 # Lowercase with underscores
-$user_data = array();
-$is_active = true;
-```
-
-**Constants**:
-```php
-define( 'PLUGIN_NAME_VERSION', '1.0.0' );  # Uppercase with underscores
-define( 'PLUGIN_NAME_PATH', plugin_dir_path( __FILE__ ) );
-```
-
-**Hooks**:
-```php
-// Actions
-do_action( 'plugin_name_before_save' );
-do_action( 'plugin_name_after_save' );
-
-// Filters
-apply_filters( 'plugin_name_data', $data );
-apply_filters( 'plugin_name_settings', $settings );
-```
-
-### Database Naming
-
-**Tables**:
-```php
-global $wpdb;
-$table_name = $wpdb->prefix . 'plugin_name_items';  # Prefixed, lowercase, underscores
-```
-
-**Options**:
-```php
-get_option( 'plugin_name_settings' );    # Prefixed with plugin name
-get_option( 'plugin_name_version' );
-```
-
-**Post Meta**:
-```php
-get_post_meta( $post_id, '_plugin_name_meta_key', true );  # Prefixed, leading underscore for hidden
-```
-
-**User Meta**:
-```php
-get_user_meta( $user_id, 'plugin_name_preference', true );
-```
-
-**Transients**:
-```php
-get_transient( 'plugin_name_cache_key' );  # Prefixed, max 172 characters
-```
-
-## WordPress Coding Standards
-
-### Indentation and Spacing
-
-**Use Tabs for Indentation**:
-```php
-function plugin_name_example() {
-	if ( $condition ) {
-		// Code here (indented with tab)
-	}
-}
-```
-
-**Space After Control Structures**:
-```php
-if ( $condition ) {  // Space after 'if', space inside parentheses
-	// Code
-}
-
-foreach ( $items as $item ) {  // Space after 'foreach'
-	// Code
-}
-```
-
-**No Space Before Function Parentheses**:
-```php
-function my_function( $param ) {  // No space before (
-	// Code
-}
-```
-
-### Braces and Brackets
-
-**Opening Braces on Same Line**:
-```php
-if ( $condition ) {
-	// Code
-}
-
-function my_function() {
-	// Code
-}
-```
-
-**Arrays**:
-```php
-$array = array(
-	'key1' => 'value1',
-	'key2' => 'value2',
-);
-```
-
-### Quotes
-
-**Use Single Quotes for Strings**:
-```php
-$string = 'Hello World';
-$html = '<div class="wrapper">';  // Single quotes for HTML
-```
-
-**Use Double Quotes for Interpolation**:
-```php
-$name = 'John';
-$greeting = "Hello, $name";  // Double quotes for variable interpolation
-```
-
-### Yoda Conditions
-
-**Use Yoda Conditions for Comparisons**:
-```php
-if ( 'value' === $variable ) {  // Constant on left
-	// Code
-}
-
-if ( true === $is_active ) {
-	// Code
-}
-```
-
-## Security Checklist
-
-### Input Validation and Sanitization
-
-**Always Sanitize User Input**:
-
-```php
-// Text fields
-$text = sanitize_text_field( $_POST['text'] );
-
-// Email
-$email = sanitize_email( $_POST['email'] );
-
-// URL
-$url = esc_url_raw( $_POST['url'] );
-
-// Integer
-$number = absint( $_POST['number'] );
-
-// Array
-$array = array_map( 'sanitize_text_field', $_POST['array'] );
-
-// HTML (allowed tags)
-$html = wp_kses_post( $_POST['content'] );
-```
-
-### Output Escaping
-
-**Always Escape Output**:
-
-```php
-// HTML
-echo esc_html( $text );
-
-// Attributes
-echo '<div class="' . esc_attr( $class ) . '">';
-
-// URL
-echo '<a href="' . esc_url( $url ) . '">';
-
-// JavaScript
-echo '<script>var data = ' . wp_json_encode( $data ) . ';</script>';
-
-// Translation with escaping
-echo esc_html__( 'Text', 'text-domain' );
-```
-
-### Nonce Verification
-
-**Always Use Nonces for Forms**:
-
-```php
-// Create nonce
-wp_nonce_field( 'action_name', 'nonce_name' );
-
-// Verify nonce
-if ( ! isset( $_POST['nonce_name'] ) || ! wp_verify_nonce( $_POST['nonce_name'], 'action_name' ) ) {
-	wp_die( __( 'Security check failed', 'text-domain' ) );
-}
-```
-
-**Nonces for AJAX**:
-
-```php
-// Create nonce for AJAX
-wp_localize_script( 'script-handle', 'ajax_object', array(
-	'ajax_url' => admin_url( 'admin-ajax.php' ),
-	'nonce' => wp_create_nonce( 'ajax_nonce' ),
-) );
-
-// Verify in AJAX handler
-check_ajax_referer( 'ajax_nonce', 'nonce' );
-```
-
-### Capability Checks
-
-**Always Check User Capabilities**:
-
-```php
-// Admin actions
-if ( ! current_user_can( 'manage_options' ) ) {
-	wp_die( __( 'Insufficient permissions', 'text-domain' ) );
-}
-
-// Post editing
-if ( ! current_user_can( 'edit_post', $post_id ) ) {
-	return;
-}
-
-// Custom capability
-if ( ! current_user_can( 'plugin_name_custom_capability' ) ) {
-	return;
-}
-```
-
-### Database Security
-
-**Use Prepared Statements**:
-
-```php
-global $wpdb;
-
-// Prepared statement
-$results = $wpdb->get_results( $wpdb->prepare(
-	"SELECT * FROM {$wpdb->prefix}table WHERE column = %s AND id = %d",
-	$string_value,
-	$int_value
-) );
-
-// Never use direct queries
-// BAD: $wpdb->query( "SELECT * FROM table WHERE id = " . $_GET['id'] );
-```
-
-### File Security
-
-**Prevent Direct Access**:
-
-```php
-// Add to all PHP files
-if ( ! defined( 'ABSPATH' ) ) {
-	exit; // Exit if accessed directly
-}
-```
-
-**Validate File Uploads**:
-
-```php
-function plugin_name_validate_upload( $file ) {
-	// Check file type
-	$allowed_types = array( 'image/jpeg', 'image/png', 'image/gif' );
-	if ( ! in_array( $file['type'], $allowed_types, true ) ) {
-		return new WP_Error( 'invalid_type', __( 'Invalid file type', 'text-domain' ) );
-	}
-
-	// Check file size (5MB max)
-	if ( $file['size'] > 5 * 1024 * 1024 ) {
-		return new WP_Error( 'file_too_large', __( 'File too large', 'text-domain' ) );
-	}
-
-	return $file;
-}
-```
-
-### Security Checklist
-
-- [ ] All user input is sanitized
-- [ ] All output is escaped
-- [ ] Nonces are used for all forms
-- [ ] Capability checks are in place
-- [ ] Database queries use prepared statements
-- [ ] Direct file access is prevented
-- [ ] File uploads are validated
-- [ ] No eval() or exec() usage
-- [ ] No unserialize() on user input
-- [ ] No file_get_contents() on user input
-- [ ] HTTPS is used for external requests
-- [ ] API keys are stored securely (not in code)
-
-## Performance Checklist
-
-### Database Optimization
-
-**Optimize Queries**:
-
-```php
-// Use WP_Query efficiently
-$args = array(
-	'post_type' => 'post',
-	'posts_per_page' => 10,
-	'no_found_rows' => true,  // Skip pagination count
-	'update_post_meta_cache' => false,  // Skip meta cache if not needed
-	'update_post_term_cache' => false,  // Skip term cache if not needed
-);
-$query = new WP_Query( $args );
-
-// Avoid N+1 queries
-// BAD: Loop through posts and get meta for each
-// GOOD: Use update_post_meta_cache or get all meta at once
-```
-
-**Use Transients for Caching**:
-
-```php
-function plugin_name_get_expensive_data() {
-	$cache_key = 'plugin_name_expensive_data';
-	$data = get_transient( $cache_key );
-
-	if ( false === $data ) {
-		// Expensive operation
-		$data = perform_expensive_operation();
-
-		// Cache for 1 hour
-		set_transient( $cache_key, $data, HOUR_IN_SECONDS );
-	}
-
-	return $data;
-}
-```
-
-**Use Object Caching**:
-
-```php
-function plugin_name_get_data( $id ) {
-	$cache_key = 'plugin_name_data_' . $id;
-	$data = wp_cache_get( $cache_key, 'plugin_name' );
-
-	if ( false === $data ) {
-		$data = get_data_from_database( $id );
-		wp_cache_set( $cache_key, $data, 'plugin_name', 3600 );
-	}
-
-	return $data;
-}
-```
-
-### Asset Optimization
-
-**Conditional Loading**:
-
-```php
-function plugin_name_enqueue_scripts() {
-	// Only load on specific pages
-	if ( is_singular( 'post' ) ) {
-		wp_enqueue_script( 'plugin-name-script', plugins_url( 'js/script.js', __FILE__ ), array( 'jquery' ), '1.0.0', true );
-	}
-
-	// Only load in admin
-	if ( is_admin() ) {
-		wp_enqueue_style( 'plugin-name-admin', plugins_url( 'css/admin.css', __FILE__ ), array(), '1.0.0' );
-	}
-}
-add_action( 'wp_enqueue_scripts', 'plugin_name_enqueue_scripts' );
-```
-
-**Minify and Combine Assets**:
-
-```php
-// Use .min versions in production
-$suffix = ( defined( 'SCRIPT_DEBUG' ) && SCRIPT_DEBUG ) ? '' : '.min';
-wp_enqueue_script( 'plugin-name-script', plugins_url( "js/script{$suffix}.js", __FILE__ ), array( 'jquery' ), '1.0.0', true );
-```
-
-**Lazy Load Images**:
-
-```php
-function plugin_name_add_lazy_loading( $content ) {
-	if ( is_singular() ) {
-		$content = str_replace( '<img ', '<img loading="lazy" ', $content );
-	}
-	return $content;
-}
-add_filter( 'the_content', 'plugin_name_add_lazy_loading' );
-```
-
-### Cron Job Optimization
-
-**Use WP-Cron Efficiently**:
-
-```php
-// Schedule event
-if ( ! wp_next_scheduled( 'plugin_name_daily_task' ) ) {
-	wp_schedule_event( time(), 'daily', 'plugin_name_daily_task' );
-}
-
-// Hook callback
-add_action( 'plugin_name_daily_task', 'plugin_name_do_daily_task' );
-
-function plugin_name_do_daily_task() {
-	// Batch process large datasets
-	$offset = get_option( 'plugin_name_batch_offset', 0 );
-	$batch_size = 100;
-
-	// Process batch
-	$items = get_items( $offset, $batch_size );
-	foreach ( $items as $item ) {
-		process_item( $item );
-	}
-
-	// Update offset
-	update_option( 'plugin_name_batch_offset', $offset + $batch_size );
-}
-```
-
-### Performance Checklist
-
-- [ ] Database queries are optimized
-- [ ] Transients are used for expensive operations
-- [ ] Object caching is implemented
-- [ ] Assets are loaded conditionally
-- [ ] Assets are minified
-- [ ] Images use lazy loading
-- [ ] Cron jobs are optimized
-- [ ] No queries in loops
-- [ ] Pagination is implemented for large datasets
-- [ ] External API calls are cached
-
-## Accessibility Considerations
-
-### Semantic HTML
-
-**Use Proper HTML Elements**:
-
-```php
-// Good
-echo '<button type="button">' . esc_html__( 'Click Me', 'text-domain' ) . '</button>';
-
-// Bad
-echo '<div onclick="doSomething()">' . esc_html__( 'Click Me', 'text-domain' ) . '</div>';
-```
-
-### ARIA Labels
-
-**Add ARIA Labels for Screen Readers**:
-
-```php
-echo '<button type="button" aria-label="' . esc_attr__( 'Close dialog', 'text-domain' ) . '">';
-echo '<span aria-hidden="true">&times;</span>';
-echo '</button>';
-```
-
-### Keyboard Navigation
-
-**Ensure Keyboard Accessibility**:
-
-```php
-// Add tabindex for custom interactive elements
-echo '<div tabindex="0" role="button" onkeypress="handleKeyPress(event)">';
-echo esc_html__( 'Custom Button', 'text-domain' );
-echo '</div>';
-```
-
-### Form Labels
-
-**Always Label Form Fields**:
-
-```php
-echo '<label for="plugin-name-field">' . esc_html__( 'Field Label', 'text-domain' ) . '</label>';
-echo '<input type="text" id="plugin-name-field" name="field_name" />';
-```
-
-### Color Contrast
-
-**Ensure Sufficient Color Contrast**:
-
-```css
-/* WCAG AA requires 4.5:1 contrast ratio for normal text */
-.plugin-name-text {
-	color: #333333;  /* Dark gray on white background */
-	background-color: #ffffff;
-}
-
-/* WCAG AAA requires 7:1 contrast ratio */
-.plugin-name-important {
-	color: #000000;  /* Black on white background */
-	background-color: #ffffff;
-}
-```
-
-### Accessibility Checklist
-
-- [ ] Semantic HTML is used
-- [ ] ARIA labels are provided
-- [ ] Keyboard navigation works
-- [ ] Form fields have labels
-- [ ] Color contrast meets WCAG AA standards
-- [ ] Images have alt text
-- [ ] Focus indicators are visible
-- [ ] Skip links are provided
-- [ ] Headings are hierarchical
-- [ ] Error messages are descriptive
-
-## Backward Compatibility
-
-### WordPress Version Compatibility
-
-**Check WordPress Version**:
-
-```php
-function plugin_name_check_version() {
-	global $wp_version;
-
-	if ( version_compare( $wp_version, '6.0', '<' ) ) {
-		add_action( 'admin_notices', 'plugin_name_version_notice' );
-		return false;
-	}
-
-	return true;
-}
-
-function plugin_name_version_notice() {
-	echo '<div class="notice notice-error"><p>';
-	echo esc_html__( 'Plugin Name requires WordPress 6.0 or higher.', 'text-domain' );
-	echo '</p></div>';
-}
-```
-
-### PHP Version Compatibility
-
-**Check PHP Version**:
-
-```php
-if ( version_compare( PHP_VERSION, '7.4', '<' ) ) {
-	add_action( 'admin_notices', function() {
-		echo '<div class="notice notice-error"><p>';
-		echo esc_html__( 'Plugin Name requires PHP 7.4 or higher.', 'text-domain' );
-		echo '</p></div>';
-	} );
-	return;
-}
-```
-
-### Deprecation Handling
-
-**Handle Deprecated Functions**:
-
-```php
-function plugin_name_old_function() {
-	_deprecated_function( __FUNCTION__, '2.0.0', 'plugin_name_new_function' );
-	return plugin_name_new_function();
-}
-
-function plugin_name_new_function() {
-	// New implementation
-}
-```
-
-### Database Schema Updates
-
-**Version Database Schema**:
-
-```php
-function plugin_name_update_database() {
-	$current_version = get_option( 'plugin_name_db_version', '1.0' );
-
-	if ( version_compare( $current_version, '2.0', '<' ) ) {
-		plugin_name_upgrade_to_2_0();
-		update_option( 'plugin_name_db_version', '2.0' );
-	}
-}
-
-function plugin_name_upgrade_to_2_0() {
-	global $wpdb;
-
-	// Add new column
-	$wpdb->query( "ALTER TABLE {$wpdb->prefix}plugin_name_table ADD COLUMN new_column VARCHAR(255)" );
-}
-```
-
-### Backward Compatibility Checklist
-
-- [ ] Minimum WordPress version is specified
-- [ ] Minimum PHP version is specified
-- [ ] Version checks are in place
-- [ ] Deprecated functions use _deprecated_function()
-- [ ] Database schema updates are versioned
-- [ ] Settings migration is handled
-- [ ] Old hooks are maintained (with deprecation notices)
-- [ ] Breaking changes are documented
-- [ ] Upgrade path is tested
-
-## Internationalization (i18n)
-
-### Text Domain
-
-**Use Consistent Text Domain**:
-
-```php
-// In plugin header
-/*
- * Text Domain: plugin-name
- * Domain Path: /languages
- */
-
-// In code
-__( 'Text', 'plugin-name' );
-_e( 'Text', 'plugin-name' );
-esc_html__( 'Text', 'plugin-name' );
-esc_html_e( 'Text', 'plugin-name' );
-```
-
-### Load Text Domain
-
-**Load Translations**:
-
-```php
-function plugin_name_load_textdomain() {
-	load_plugin_textdomain( 'plugin-name', false, dirname( plugin_basename( __FILE__ ) ) . '/languages' );
-}
-add_action( 'plugins_loaded', 'plugin_name_load_textdomain' );
-```
-
-### Translatable Strings
-
-**Make All User-Facing Strings Translatable**:
-
-```php
-// Simple string
-echo esc_html__( 'Hello World', 'plugin-name' );
-
-// String with context
-echo esc_html_x( 'Post', 'noun', 'plugin-name' );
-
-// Plural
-echo esc_html( sprintf(
-	_n( '%d item', '%d items', $count, 'plugin-name' ),
-	$count
-) );
-```
-
-## Documentation Standards
-
-### PHPDoc Comments
-
-**Document All Functions and Classes**:
-
-```php
-/**
- * Process user data
- *
- * @since 1.0.0
- * @param array $data The user data to process.
- * @param bool  $validate Whether to validate the data.
- * @return array|WP_Error Processed data or error.
- */
-function plugin_name_process_data( $data, $validate = true ) {
-	// Implementation
-}
-```
-
-### Inline Comments
-
-**Add Explanatory Comments**:
-
-```php
-// Check if user has permission
-if ( ! current_user_can( 'manage_options' ) ) {
-	return;
-}
-
-// Process data in batches to avoid memory issues
-$batch_size = 100;
-for ( $i = 0; $i < count( $items ); $i += $batch_size ) {
-	$batch = array_slice( $items, $i, $batch_size );
-	process_batch( $batch );
-}
-```
-
-### README Documentation
-
-**Maintain Comprehensive README**:
-
-```markdown
-# Plugin Name
-
-## Description
-Brief description of what the plugin does.
-
-## Installation
-1. Upload plugin files
-2. Activate plugin
-3. Configure settings
-
-## Usage
-How to use the plugin.
-
-## Hooks
-List of available hooks and filters.
-
-## Changelog
-Version history with changes.
-```
-
-## Testing Best Practices
-
-### Write Tests First (TDD)
-
-```php
-// Write test first
-public function test_sanitizes_email() {
-	$input = 'test@EXAMPLE.com';
-	$expected = 'test@example.com';
-	$result = plugin_name_sanitize_email( $input );
-	$this->assertEquals( $expected, $result );
-}
-
-// Then implement function
-function plugin_name_sanitize_email( $email ) {
-	return sanitize_email( strtolower( $email ) );
-}
-```
-
-### Test Coverage
-
-**Aim for > 80% Code Coverage**:
-
-```bash
-vendor/bin/phpunit --coverage-html coverage/
-```
-
-### Test Different Scenarios
-
-```php
-public function test_handles_empty_input() {
-	$result = plugin_name_process( '' );
-	$this->assertWPError( $result );
-}
-
-public function test_handles_invalid_input() {
-	$result = plugin_name_process( 'invalid' );
-	$this->assertWPError( $result );
-}
-
-public function test_handles_valid_input() {
-	$result = plugin_name_process( 'valid' );
-	$this->assertNotWPError( $result );
-}
-```
-
-## Version Control Best Practices
-
-### Git Workflow
-
-**Use Feature Branches**:
-
-```bash
-git checkout -b feature/new-feature
-# Make changes
-git commit -m "feat: Add new feature"
-git push origin feature/new-feature
-```
-
-### Commit Messages
-
-**Use Conventional Commits**:
-
-```
-feat: Add new feature
-fix: Fix bug in data processing
-docs: Update README
-style: Format code
-refactor: Refactor data processing
-test: Add tests for new feature
-chore: Update dependencies
-```
-
-### .gitignore
-
-**Ignore Unnecessary Files**:
-
-```
-# .gitignore
-node_modules/
-vendor/
-.DS_Store
-*.log
-coverage/
-.phpunit.result.cache
-```
-
-## Release Checklist
-
-### Pre-Release
-
-- [ ] All tests pass
-- [ ] Code coverage > 80%
-- [ ] Security audit complete
-- [ ] WPCS compliance verified
-- [ ] Documentation updated
-- [ ] Changelog updated
-- [ ] Version number updated
-- [ ] Translation files generated
-
-### Release
-
-- [ ] Create git tag
-- [ ] Create release notes
-- [ ] Update WordPress.org SVN
-- [ ] Test in clean WordPress install
-- [ ] Monitor for issues
-
-### Post-Release
-
-- [ ] Monitor support forums
-- [ ] Respond to user feedback
-- [ ] Track bug reports
-- [ ] Plan next release
-
-## Resources
-
-- [WordPress Plugin Handbook](https://developer.wordpress.org/plugins/)
-- [WordPress Coding Standards](https://developer.wordpress.org/coding-standards/)
-- [WordPress Security Best Practices](https://developer.wordpress.org/plugins/security/)
-- [WCAG Guidelines](https://www.w3.org/WAI/WCAG21/quickref/)
-- [Semantic Versioning](https://semver.org/)
-
-## Related Workflows
-
-- `development-workflow.md` - Feature development cycle
-- `testing-workflow.md` - Testing setup and execution
-- `submission-workflow.md` - WordPress.org submission
-
-## Related Domain Rules
-
-- `domain-rules/wordpress-plugin/security-best-practices.md`
-- `domain-rules/wordpress-plugin/performance-optimization.md`
-- `domain-rules/wordpress-plugin/internationalization.md`
-
+# WordPress Plugin Development Best Practices
+
+## Overview
+
+This document provides comprehensive best practices for WordPress plugin development, covering code organization, naming conventions, security, performance, accessibility, and backward compatibility.
+
+## Code Organization
+
+### Directory Structure
+
+**Standard Plugin Structure**:
+
+```
+plugin-name/
+├── plugin-name.php              # Main plugin file
+├── uninstall.php                # Uninstall cleanup
+├── readme.txt                   # WordPress.org readme
+├── LICENSE                      # License file
+├── includes/                    # Core plugin classes
+│   ├── class-plugin-name.php
+│   ├── class-activator.php
+│   ├── class-deactivator.php
+│   └── class-loader.php
+├── admin/                       # Admin-specific functionality
+│   ├── class-admin.php
+│   ├── partials/                # Admin view templates
+│   ├── css/
+│   └── js/
+├── public/                      # Public-facing functionality
+│   ├── class-public.php
+│   ├── partials/                # Public view templates
+│   ├── css/
+│   └── js/
+├── languages/                   # Translation files
+├── assets/                      # Plugin assets for WordPress.org
+│   ├── banner-772x250.png
+│   ├── banner-1544x500.png
+│   ├── icon-128x128.png
+│   └── icon-256x256.png
+└── tests/                       # PHPUnit tests
+    ├── bootstrap.php
+    ├── unit/
+    └── integration/
+```
+
+### File Organization Best Practices
+
+**DO**:
+- ✅ One class per file
+- ✅ Group related functionality in subdirectories
+- ✅ Separate admin and public functionality
+- ✅ Keep templates in `partials/` directories
+- ✅ Organize assets by type (css, js, images)
+
+**DON'T**:
+- ❌ Mix multiple classes in one file
+- ❌ Put all code in main plugin file
+- ❌ Mix admin and public code
+- ❌ Hardcode HTML in PHP classes
+- ❌ Put assets in root directory
+
+## Naming Conventions
+
+### File Naming
+
+**PHP Files**:
+```
+class-plugin-name.php           # Class files (lowercase, hyphens)
+class-admin.php
+class-public.php
+plugin-name-functions.php       # Function files
+```
+
+**Template Files**:
+```
+admin-display.php               # Admin templates
+public-display.php              # Public templates
+settings-page.php
+```
+
+**Asset Files**:
+```
+plugin-name-admin.css           # Prefixed with plugin name
+plugin-name-public.js
+plugin-name-icon.png
+```
+
+### Code Naming
+
+**Classes**:
+```php
+class Plugin_Name {}                    # Capitalized with underscores
+class Plugin_Name_Admin {}
+class Plugin_Name_Public {}
+```
+
+**Functions**:
+```php
+function plugin_name_activate() {}      # Lowercase with underscores
+function plugin_name_get_data() {}
+function plugin_name_sanitize_input() {}
+```
+
+**Variables**:
+```php
+$plugin_name = 'value';                 # Lowercase with underscores
+$user_data = array();
+$is_active = true;
+```
+
+**Constants**:
+```php
+define( 'PLUGIN_NAME_VERSION', '1.0.0' );  # Uppercase with underscores
+define( 'PLUGIN_NAME_PATH', plugin_dir_path( __FILE__ ) );
+```
+
+**Hooks**:
+```php
+// Actions
+do_action( 'plugin_name_before_save' );
+do_action( 'plugin_name_after_save' );
+
+// Filters
+apply_filters( 'plugin_name_data', $data );
+apply_filters( 'plugin_name_settings', $settings );
+```
+
+### Database Naming
+
+**Tables**:
+```php
+global $wpdb;
+$table_name = $wpdb->prefix . 'plugin_name_items';  # Prefixed, lowercase, underscores
+```
+
+**Options**:
+```php
+get_option( 'plugin_name_settings' );    # Prefixed with plugin name
+get_option( 'plugin_name_version' );
+```
+
+**Post Meta**:
+```php
+get_post_meta( $post_id, '_plugin_name_meta_key', true );  # Prefixed, leading underscore for hidden
+```
+
+**User Meta**:
+```php
+get_user_meta( $user_id, 'plugin_name_preference', true );
+```
+
+**Transients**:
+```php
+get_transient( 'plugin_name_cache_key' );  # Prefixed, max 172 characters
+```
+
+## WordPress Coding Standards
+
+### Indentation and Spacing
+
+**Use Tabs for Indentation**:
+```php
+function plugin_name_example() {
+	if ( $condition ) {
+		// Code here (indented with tab)
+	}
+}
+```
+
+**Space After Control Structures**:
+```php
+if ( $condition ) {  // Space after 'if', space inside parentheses
+	// Code
+}
+
+foreach ( $items as $item ) {  // Space after 'foreach'
+	// Code
+}
+```
+
+**No Space Before Function Parentheses**:
+```php
+function my_function( $param ) {  // No space before (
+	// Code
+}
+```
+
+### Braces and Brackets
+
+**Opening Braces on Same Line**:
+```php
+if ( $condition ) {
+	// Code
+}
+
+function my_function() {
+	// Code
+}
+```
+
+**Arrays**:
+```php
+$array = array(
+	'key1' => 'value1',
+	'key2' => 'value2',
+);
+```
+
+### Quotes
+
+**Use Single Quotes for Strings**:
+```php
+$string = 'Hello World';
+$html = '<div class="wrapper">';  // Single quotes for HTML
+```
+
+**Use Double Quotes for Interpolation**:
+```php
+$name = 'John';
+$greeting = "Hello, $name";  // Double quotes for variable interpolation
+```
+
+### Yoda Conditions
+
+**Use Yoda Conditions for Comparisons**:
+```php
+if ( 'value' === $variable ) {  // Constant on left
+	// Code
+}
+
+if ( true === $is_active ) {
+	// Code
+}
+```
+
+## Security Checklist
+
+### Input Validation and Sanitization
+
+**Always Sanitize User Input**:
+
+```php
+// Text fields
+$text = sanitize_text_field( $_POST['text'] );
+
+// Email
+$email = sanitize_email( $_POST['email'] );
+
+// URL
+$url = esc_url_raw( $_POST['url'] );
+
+// Integer
+$number = absint( $_POST['number'] );
+
+// Array
+$array = array_map( 'sanitize_text_field', $_POST['array'] );
+
+// HTML (allowed tags)
+$html = wp_kses_post( $_POST['content'] );
+```
+
+### Output Escaping
+
+**Always Escape Output**:
+
+```php
+// HTML
+echo esc_html( $text );
+
+// Attributes
+echo '<div class="' . esc_attr( $class ) . '">';
+
+// URL
+echo '<a href="' . esc_url( $url ) . '">';
+
+// JavaScript
+echo '<script>var data = ' . wp_json_encode( $data ) . ';</script>';
+
+// Translation with escaping
+echo esc_html__( 'Text', 'text-domain' );
+```
+
+### Nonce Verification
+
+**Always Use Nonces for Forms**:
+
+```php
+// Create nonce
+wp_nonce_field( 'action_name', 'nonce_name' );
+
+// Verify nonce
+if ( ! isset( $_POST['nonce_name'] ) || ! wp_verify_nonce( $_POST['nonce_name'], 'action_name' ) ) {
+	wp_die( __( 'Security check failed', 'text-domain' ) );
+}
+```
+
+**Nonces for AJAX**:
+
+```php
+// Create nonce for AJAX
+wp_localize_script( 'script-handle', 'ajax_object', array(
+	'ajax_url' => admin_url( 'admin-ajax.php' ),
+	'nonce' => wp_create_nonce( 'ajax_nonce' ),
+) );
+
+// Verify in AJAX handler
+check_ajax_referer( 'ajax_nonce', 'nonce' );
+```
+
+### Capability Checks
+
+**Always Check User Capabilities**:
+
+```php
+// Admin actions
+if ( ! current_user_can( 'manage_options' ) ) {
+	wp_die( __( 'Insufficient permissions', 'text-domain' ) );
+}
+
+// Post editing
+if ( ! current_user_can( 'edit_post', $post_id ) ) {
+	return;
+}
+
+// Custom capability
+if ( ! current_user_can( 'plugin_name_custom_capability' ) ) {
+	return;
+}
+```
+
+### Database Security
+
+**Use Prepared Statements**:
+
+```php
+global $wpdb;
+
+// Prepared statement
+$results = $wpdb->get_results( $wpdb->prepare(
+	"SELECT * FROM {$wpdb->prefix}table WHERE column = %s AND id = %d",
+	$string_value,
+	$int_value
+) );
+
+// Never use direct queries
+// BAD: $wpdb->query( "SELECT * FROM table WHERE id = " . $_GET['id'] );
+```
+
+### File Security
+
+**Prevent Direct Access**:
+
+```php
+// Add to all PHP files
+if ( ! defined( 'ABSPATH' ) ) {
+	exit; // Exit if accessed directly
+}
+```
+
+**Validate File Uploads**:
+
+```php
+function plugin_name_validate_upload( $file ) {
+	// Check file type
+	$allowed_types = array( 'image/jpeg', 'image/png', 'image/gif' );
+	if ( ! in_array( $file['type'], $allowed_types, true ) ) {
+		return new WP_Error( 'invalid_type', __( 'Invalid file type', 'text-domain' ) );
+	}
+
+	// Check file size (5MB max)
+	if ( $file['size'] > 5 * 1024 * 1024 ) {
+		return new WP_Error( 'file_too_large', __( 'File too large', 'text-domain' ) );
+	}
+
+	return $file;
+}
+```
+
+### Security Checklist
+
+- [ ] All user input is sanitized
+- [ ] All output is escaped
+- [ ] Nonces are used for all forms
+- [ ] Capability checks are in place
+- [ ] Database queries use prepared statements
+- [ ] Direct file access is prevented
+- [ ] File uploads are validated
+- [ ] No eval() or exec() usage
+- [ ] No unserialize() on user input
+- [ ] No file_get_contents() on user input
+- [ ] HTTPS is used for external requests
+- [ ] API keys are stored securely (not in code)
+
+## Performance Checklist
+
+### Database Optimization
+
+**Optimize Queries**:
+
+```php
+// Use WP_Query efficiently
+$args = array(
+	'post_type' => 'post',
+	'posts_per_page' => 10,
+	'no_found_rows' => true,  // Skip pagination count
+	'update_post_meta_cache' => false,  // Skip meta cache if not needed
+	'update_post_term_cache' => false,  // Skip term cache if not needed
+);
+$query = new WP_Query( $args );
+
+// Avoid N+1 queries
+// BAD: Loop through posts and get meta for each
+// GOOD: Use update_post_meta_cache or get all meta at once
+```
+
+**Use Transients for Caching**:
+
+```php
+function plugin_name_get_expensive_data() {
+	$cache_key = 'plugin_name_expensive_data';
+	$data = get_transient( $cache_key );
+
+	if ( false === $data ) {
+		// Expensive operation
+		$data = perform_expensive_operation();
+
+		// Cache for 1 hour
+		set_transient( $cache_key, $data, HOUR_IN_SECONDS );
+	}
+
+	return $data;
+}
+```
+
+**Use Object Caching**:
+
+```php
+function plugin_name_get_data( $id ) {
+	$cache_key = 'plugin_name_data_' . $id;
+	$data = wp_cache_get( $cache_key, 'plugin_name' );
+
+	if ( false === $data ) {
+		$data = get_data_from_database( $id );
+		wp_cache_set( $cache_key, $data, 'plugin_name', 3600 );
+	}
+
+	return $data;
+}
+```
+
+### Asset Optimization
+
+**Conditional Loading**:
+
+```php
+function plugin_name_enqueue_scripts() {
+	// Only load on specific pages
+	if ( is_singular( 'post' ) ) {
+		wp_enqueue_script( 'plugin-name-script', plugins_url( 'js/script.js', __FILE__ ), array( 'jquery' ), '1.0.0', true );
+	}
+
+	// Only load in admin
+	if ( is_admin() ) {
+		wp_enqueue_style( 'plugin-name-admin', plugins_url( 'css/admin.css', __FILE__ ), array(), '1.0.0' );
+	}
+}
+add_action( 'wp_enqueue_scripts', 'plugin_name_enqueue_scripts' );
+```
+
+**Minify and Combine Assets**:
+
+```php
+// Use .min versions in production
+$suffix = ( defined( 'SCRIPT_DEBUG' ) && SCRIPT_DEBUG ) ? '' : '.min';
+wp_enqueue_script( 'plugin-name-script', plugins_url( "js/script{$suffix}.js", __FILE__ ), array( 'jquery' ), '1.0.0', true );
+```
+
+**Lazy Load Images**:
+
+```php
+function plugin_name_add_lazy_loading( $content ) {
+	if ( is_singular() ) {
+		$content = str_replace( '<img ', '<img loading="lazy" ', $content );
+	}
+	return $content;
+}
+add_filter( 'the_content', 'plugin_name_add_lazy_loading' );
+```
+
+### Cron Job Optimization
+
+**Use WP-Cron Efficiently**:
+
+```php
+// Schedule event
+if ( ! wp_next_scheduled( 'plugin_name_daily_task' ) ) {
+	wp_schedule_event( time(), 'daily', 'plugin_name_daily_task' );
+}
+
+// Hook callback
+add_action( 'plugin_name_daily_task', 'plugin_name_do_daily_task' );
+
+function plugin_name_do_daily_task() {
+	// Batch process large datasets
+	$offset = get_option( 'plugin_name_batch_offset', 0 );
+	$batch_size = 100;
+
+	// Process batch
+	$items = get_items( $offset, $batch_size );
+	foreach ( $items as $item ) {
+		process_item( $item );
+	}
+
+	// Update offset
+	update_option( 'plugin_name_batch_offset', $offset + $batch_size );
+}
+```
+
+### Performance Checklist
+
+- [ ] Database queries are optimized
+- [ ] Transients are used for expensive operations
+- [ ] Object caching is implemented
+- [ ] Assets are loaded conditionally
+- [ ] Assets are minified
+- [ ] Images use lazy loading
+- [ ] Cron jobs are optimized
+- [ ] No queries in loops
+- [ ] Pagination is implemented for large datasets
+- [ ] External API calls are cached
+
+## Accessibility Considerations
+
+### Semantic HTML
+
+**Use Proper HTML Elements**:
+
+```php
+// Good
+echo '<button type="button">' . esc_html__( 'Click Me', 'text-domain' ) . '</button>';
+
+// Bad
+echo '<div onclick="doSomething()">' . esc_html__( 'Click Me', 'text-domain' ) . '</div>';
+```
+
+### ARIA Labels
+
+**Add ARIA Labels for Screen Readers**:
+
+```php
+echo '<button type="button" aria-label="' . esc_attr__( 'Close dialog', 'text-domain' ) . '">';
+echo '<span aria-hidden="true">&times;</span>';
+echo '</button>';
+```
+
+### Keyboard Navigation
+
+**Ensure Keyboard Accessibility**:
+
+```php
+// Add tabindex for custom interactive elements
+echo '<div tabindex="0" role="button" onkeypress="handleKeyPress(event)">';
+echo esc_html__( 'Custom Button', 'text-domain' );
+echo '</div>';
+```
+
+### Form Labels
+
+**Always Label Form Fields**:
+
+```php
+echo '<label for="plugin-name-field">' . esc_html__( 'Field Label', 'text-domain' ) . '</label>';
+echo '<input type="text" id="plugin-name-field" name="field_name" />';
+```
+
+### Color Contrast
+
+**Ensure Sufficient Color Contrast**:
+
+```css
+/* WCAG AA requires 4.5:1 contrast ratio for normal text */
+.plugin-name-text {
+	color: #333333;  /* Dark gray on white background */
+	background-color: #ffffff;
+}
+
+/* WCAG AAA requires 7:1 contrast ratio */
+.plugin-name-important {
+	color: #000000;  /* Black on white background */
+	background-color: #ffffff;
+}
+```
+
+### Accessibility Checklist
+
+- [ ] Semantic HTML is used
+- [ ] ARIA labels are provided
+- [ ] Keyboard navigation works
+- [ ] Form fields have labels
+- [ ] Color contrast meets WCAG AA standards
+- [ ] Images have alt text
+- [ ] Focus indicators are visible
+- [ ] Skip links are provided
+- [ ] Headings are hierarchical
+- [ ] Error messages are descriptive
+
+## Backward Compatibility
+
+### WordPress Version Compatibility
+
+**Check WordPress Version**:
+
+```php
+function plugin_name_check_version() {
+	global $wp_version;
+
+	if ( version_compare( $wp_version, '6.0', '<' ) ) {
+		add_action( 'admin_notices', 'plugin_name_version_notice' );
+		return false;
+	}
+
+	return true;
+}
+
+function plugin_name_version_notice() {
+	echo '<div class="notice notice-error"><p>';
+	echo esc_html__( 'Plugin Name requires WordPress 6.0 or higher.', 'text-domain' );
+	echo '</p></div>';
+}
+```
+
+### PHP Version Compatibility
+
+**Check PHP Version**:
+
+```php
+if ( version_compare( PHP_VERSION, '7.4', '<' ) ) {
+	add_action( 'admin_notices', function() {
+		echo '<div class="notice notice-error"><p>';
+		echo esc_html__( 'Plugin Name requires PHP 7.4 or higher.', 'text-domain' );
+		echo '</p></div>';
+	} );
+	return;
+}
+```
+
+### Deprecation Handling
+
+**Handle Deprecated Functions**:
+
+```php
+function plugin_name_old_function() {
+	_deprecated_function( __FUNCTION__, '2.0.0', 'plugin_name_new_function' );
+	return plugin_name_new_function();
+}
+
+function plugin_name_new_function() {
+	// New implementation
+}
+```
+
+### Database Schema Updates
+
+**Version Database Schema**:
+
+```php
+function plugin_name_update_database() {
+	$current_version = get_option( 'plugin_name_db_version', '1.0' );
+
+	if ( version_compare( $current_version, '2.0', '<' ) ) {
+		plugin_name_upgrade_to_2_0();
+		update_option( 'plugin_name_db_version', '2.0' );
+	}
+}
+
+function plugin_name_upgrade_to_2_0() {
+	global $wpdb;
+
+	// Add new column
+	$wpdb->query( "ALTER TABLE {$wpdb->prefix}plugin_name_table ADD COLUMN new_column VARCHAR(255)" );
+}
+```
+
+### Backward Compatibility Checklist
+
+- [ ] Minimum WordPress version is specified
+- [ ] Minimum PHP version is specified
+- [ ] Version checks are in place
+- [ ] Deprecated functions use _deprecated_function()
+- [ ] Database schema updates are versioned
+- [ ] Settings migration is handled
+- [ ] Old hooks are maintained (with deprecation notices)
+- [ ] Breaking changes are documented
+- [ ] Upgrade path is tested
+
+## Internationalization (i18n)
+
+### Text Domain
+
+**Use Consistent Text Domain**:
+
+```php
+// In plugin header
+/*
+ * Text Domain: plugin-name
+ * Domain Path: /languages
+ */
+
+// In code
+__( 'Text', 'plugin-name' );
+_e( 'Text', 'plugin-name' );
+esc_html__( 'Text', 'plugin-name' );
+esc_html_e( 'Text', 'plugin-name' );
+```
+
+### Load Text Domain
+
+**Load Translations**:
+
+```php
+function plugin_name_load_textdomain() {
+	load_plugin_textdomain( 'plugin-name', false, dirname( plugin_basename( __FILE__ ) ) . '/languages' );
+}
+add_action( 'plugins_loaded', 'plugin_name_load_textdomain' );
+```
+
+### Translatable Strings
+
+**Make All User-Facing Strings Translatable**:
+
+```php
+// Simple string
+echo esc_html__( 'Hello World', 'plugin-name' );
+
+// String with context
+echo esc_html_x( 'Post', 'noun', 'plugin-name' );
+
+// Plural
+echo esc_html( sprintf(
+	_n( '%d item', '%d items', $count, 'plugin-name' ),
+	$count
+) );
+```
+
+## Documentation Standards
+
+### PHPDoc Comments
+
+**Document All Functions and Classes**:
+
+```php
+/**
+ * Process user data
+ *
+ * @since 1.0.0
+ * @param array $data The user data to process.
+ * @param bool  $validate Whether to validate the data.
+ * @return array|WP_Error Processed data or error.
+ */
+function plugin_name_process_data( $data, $validate = true ) {
+	// Implementation
+}
+```
+
+### Inline Comments
+
+**Add Explanatory Comments**:
+
+```php
+// Check if user has permission
+if ( ! current_user_can( 'manage_options' ) ) {
+	return;
+}
+
+// Process data in batches to avoid memory issues
+$batch_size = 100;
+for ( $i = 0; $i < count( $items ); $i += $batch_size ) {
+	$batch = array_slice( $items, $i, $batch_size );
+	process_batch( $batch );
+}
+```
+
+### README Documentation
+
+**Maintain Comprehensive README**:
+
+```markdown
+# Plugin Name
+
+## Description
+Brief description of what the plugin does.
+
+## Installation
+1. Upload plugin files
+2. Activate plugin
+3. Configure settings
+
+## Usage
+How to use the plugin.
+
+## Hooks
+List of available hooks and filters.
+
+## Changelog
+Version history with changes.
+```
+
+## Testing Best Practices
+
+### Write Tests First (TDD)
+
+```php
+// Write test first
+public function test_sanitizes_email() {
+	$input = 'test@EXAMPLE.com';
+	$expected = 'test@example.com';
+	$result = plugin_name_sanitize_email( $input );
+	$this->assertEquals( $expected, $result );
+}
+
+// Then implement function
+function plugin_name_sanitize_email( $email ) {
+	return sanitize_email( strtolower( $email ) );
+}
+```
+
+### Test Coverage
+
+**Aim for > 80% Code Coverage**:
+
+```bash
+vendor/bin/phpunit --coverage-html coverage/
+```
+
+### Test Different Scenarios
+
+```php
+public function test_handles_empty_input() {
+	$result = plugin_name_process( '' );
+	$this->assertWPError( $result );
+}
+
+public function test_handles_invalid_input() {
+	$result = plugin_name_process( 'invalid' );
+	$this->assertWPError( $result );
+}
+
+public function test_handles_valid_input() {
+	$result = plugin_name_process( 'valid' );
+	$this->assertNotWPError( $result );
+}
+```
+
+## Version Control Best Practices
+
+### Git Workflow
+
+**Use Feature Branches**:
+
+```bash
+git checkout -b feature/new-feature
+# Make changes
+git commit -m "feat: Add new feature"
+git push origin feature/new-feature
+```
+
+### Commit Messages
+
+**Use Conventional Commits**:
+
+```
+feat: Add new feature
+fix: Fix bug in data processing
+docs: Update README
+style: Format code
+refactor: Refactor data processing
+test: Add tests for new feature
+chore: Update dependencies
+```
+
+### .gitignore
+
+**Ignore Unnecessary Files**:
+
+```
+# .gitignore
+node_modules/
+vendor/
+.DS_Store
+*.log
+coverage/
+.phpunit.result.cache
+```
+
+## Release Checklist
+
+### Pre-Release
+
+- [ ] All tests pass
+- [ ] Code coverage > 80%
+- [ ] Security audit complete
+- [ ] WPCS compliance verified
+- [ ] Documentation updated
+- [ ] Changelog updated
+- [ ] Version number updated
+- [ ] Translation files generated
+
+### Release
+
+- [ ] Create git tag
+- [ ] Create release notes
+- [ ] Update WordPress.org SVN
+- [ ] Test in clean WordPress install
+- [ ] Monitor for issues
+
+### Post-Release
+
+- [ ] Monitor support forums
+- [ ] Respond to user feedback
+- [ ] Track bug reports
+- [ ] Plan next release
+
+## Resources
+
+- [WordPress Plugin Handbook](https://developer.wordpress.org/plugins/)
+- [WordPress Coding Standards](https://developer.wordpress.org/coding-standards/)
+- [WordPress Security Best Practices](https://developer.wordpress.org/plugins/security/)
+- [WCAG Guidelines](https://www.w3.org/WAI/WCAG21/quickref/)
+- [Semantic Versioning](https://semver.org/)
+
+## Related Workflows
+
+- `development-workflow.md` - Feature development cycle
+- `testing-workflow.md` - Testing setup and execution
+- `submission-workflow.md` - WordPress.org submission
+
+## Related Domain Rules
+
+- `domain-rules/wordpress-plugin/security-best-practices.md`
+- `domain-rules/wordpress-plugin/performance-optimization.md`
+- `domain-rules/wordpress-plugin/internationalization.md`
+