--- name: wordpress-plugin-core description: | Build secure WordPress plugins with core patterns for hooks, database interactions, Settings API, custom post types, REST API, and AJAX. Covers three architecture patterns (Simple, OOP, PSR-4) and the Security Trinity. Use when creating plugins, implementing nonces/sanitization/escaping, working with $wpdb prepared statements, or troubleshooting SQL injection, XSS, CSRF vulnerabilities, or plugin activation errors. license: MIT --- # WordPress Plugin Development (Core) **Status**: Production Ready **Last Updated**: 2025-11-06 **Dependencies**: None (WordPress 5.9+, PHP 7.4+) **Latest Versions**: WordPress 6.7+, PHP 8.0+ recommended --- ## Quick Start (10 Minutes) ### 1. Choose Your Plugin Structure WordPress plugins can use three architecture patterns: - **Simple** (functions only) - For small plugins with <5 functions - **OOP** (Object-Oriented) - For medium plugins with related functionality - **PSR-4** (Namespaced + Composer autoload) - For large/modern plugins **Why this matters:** - Simple plugins are easiest to start but don't scale well - OOP provides organization without modern PHP features - PSR-4 is the modern standard (2025) and most maintainable ### 2. Create Plugin Header Every plugin MUST have a header comment in the main file: ```php " /> // 4. Sanitize Input, Escape Output $clean = sanitize_text_field( $_POST['input'] ); echo esc_html( $output ); // 5. Prepared Statements for Database global $wpdb; $results = $wpdb->get_results( $wpdb->prepare( "SELECT * FROM {$wpdb->prefix}table WHERE id = %d", $id ) ); ``` --- ## The 5-Step Security Foundation WordPress plugin security has THREE components that must ALL be present: ### Step 1: Use Unique Prefix for Everything **Why**: Prevents naming conflicts with other plugins and WordPress core. **Rules**: - 4-5 characters minimum - Apply to: functions, classes, constants, options, transients, meta keys, global variables - Avoid: `wp_`, `__`, `_`, "WordPress" ```php // GOOD function mypl_function_name() {} class MyPL_Class_Name {} define( 'MYPL_CONSTANT', 'value' ); add_option( 'mypl_option', 'value' ); set_transient( 'mypl_cache', $data, HOUR_IN_SECONDS ); // BAD function function_name() {} // No prefix, will conflict class Settings {} // Too generic ``` ### Step 2: Check Capabilities, Not Just Admin Status **ERROR**: Using `is_admin()` for permission checks ```php // WRONG - Anyone can access admin area URLs if ( is_admin() ) { // Delete user data - SECURITY HOLE } // CORRECT - Check user capability if ( current_user_can( 'manage_options' ) ) { // Delete user data - Now secure } ``` **Common Capabilities**: - `manage_options` - Administrator - `edit_posts` - Editor/Author - `publish_posts` - Author - `edit_pages` - Editor - `read` - Subscriber ### Step 3: The Security Trinity **Input → Processing → Output** each require different functions: ```php // SANITIZATION (Input) - Clean user data $name = sanitize_text_field( $_POST['name'] ); $email = sanitize_email( $_POST['email'] ); $url = esc_url_raw( $_POST['url'] ); $html = wp_kses_post( $_POST['content'] ); // Allow safe HTML $key = sanitize_key( $_POST['option'] ); $ids = array_map( 'absint', $_POST['ids'] ); // Array of integers // VALIDATION (Logic) - Verify it meets requirements if ( ! is_email( $email ) ) { wp_die( 'Invalid email' ); } // ESCAPING (Output) - Make safe for display echo esc_html( $name ); echo ''; echo '

'; echo ''; ``` **Critical Rule**: Sanitize on INPUT, escape on OUTPUT. Never trust user data. ### Step 4: Nonces (CSRF Protection) **What**: One-time tokens that prove requests came from your site. **Form Pattern**: ```php // Generate nonce in form // Verify nonce in handler if ( ! isset( $_POST['mypl_nonce'] ) || ! wp_verify_nonce( $_POST['mypl_nonce'], 'mypl_action' ) ) { wp_die( 'Security check failed' ); } // Now safe to proceed $data = sanitize_text_field( $_POST['data'] ); ``` **AJAX Pattern**: ```javascript // JavaScript jQuery.ajax({ url: ajaxurl, data: { action: 'mypl_ajax_action', nonce: mypl_ajax_object.nonce, data: formData } }); ``` ```php // PHP Handler function mypl_ajax_handler() { check_ajax_referer( 'mypl-ajax-nonce', 'nonce' ); // Safe to proceed wp_send_json_success( array( 'message' => 'Success' ) ); } add_action( 'wp_ajax_mypl_ajax_action', 'mypl_ajax_handler' ); // Localize script with nonce wp_localize_script( 'mypl-script', 'mypl_ajax_object', array( 'ajaxurl' => admin_url( 'admin-ajax.php' ), 'nonce' => wp_create_nonce( 'mypl-ajax-nonce' ), ) ); ``` ### Step 5: Prepared Statements for Database **CRITICAL**: Always use `$wpdb->prepare()` for queries with user input. ```php global $wpdb; // WRONG - SQL Injection vulnerability $results = $wpdb->get_results( "SELECT * FROM {$wpdb->prefix}table WHERE id = {$_GET['id']}" ); // CORRECT - Prepared statement $results = $wpdb->get_results( $wpdb->prepare( "SELECT * FROM {$wpdb->prefix}table WHERE id = %d", $_GET['id'] ) ); ``` **Placeholders**: - `%s` - String - `%d` - Integer - `%f` - Float **LIKE Queries** (Special Case): ```php $search = '%' . $wpdb->esc_like( $term ) . '%'; $results = $wpdb->get_results( $wpdb->prepare( "SELECT * FROM {$wpdb->prefix}posts WHERE post_title LIKE %s", $search ) ); ``` --- ## Critical Rules ### Always Do ✅ **Use unique prefix** (4-5 chars) for all global code (functions, classes, options, transients) ✅ **Add ABSPATH check** to every PHP file: `if ( ! defined( 'ABSPATH' ) ) exit;` ✅ **Check capabilities** (`current_user_can()`) not just `is_admin()` ✅ **Verify nonces** for all forms and AJAX requests ✅ **Use $wpdb->prepare()** for all database queries with user input ✅ **Sanitize input** with `sanitize_*()` functions before saving ✅ **Escape output** with `esc_*()` functions before displaying ✅ **Flush rewrite rules** on activation when registering custom post types ✅ **Use uninstall.php** for permanent cleanup (not deactivation hook) ✅ **Follow WordPress Coding Standards** (tabs for indentation, Yoda conditions) ### Never Do ❌ **Never use extract()** - Creates security vulnerabilities ❌ **Never trust $_POST/$_GET** without sanitization ❌ **Never concatenate user input into SQL** - Always use prepare() ❌ **Never use `is_admin()` alone** for permission checks ❌ **Never output unsanitized data** - Always escape ❌ **Never use generic function/class names** - Always prefix ❌ **Never use short PHP tags** `prepare()` with placeholders ```php // VULNERABLE $wpdb->query( "DELETE FROM {$wpdb->prefix}table WHERE id = {$_GET['id']}" ); // SECURE $wpdb->query( $wpdb->prepare( "DELETE FROM {$wpdb->prefix}table WHERE id = %d", $_GET['id'] ) ); ``` ### Issue #2: XSS (Cross-Site Scripting) **Error**: Malicious JavaScript executed in user browsers **Source**: https://patchstack.com (35% of all vulnerabilities) **Why It Happens**: Outputting unsanitized user data to HTML **Prevention**: Always escape output with context-appropriate function ```php // VULNERABLE echo $_POST['name']; echo '

'; // SECURE echo esc_html( $_POST['name'] ); echo '

My Plugin requires WooCommerce.

'; } ); return; } // Initialize plugin } ); ``` ### Issue #19: Autosave Triggering Meta Save **Error**: Meta saved multiple times, performance issues **Source**: WordPress Post Meta **Why It Happens**: No autosave check in save_post hook **Prevention**: Check for DOING_AUTOSAVE constant ```php add_action( 'save_post', function( $post_id ) { if ( defined( 'DOING_AUTOSAVE' ) && DOING_AUTOSAVE ) { return; } // Safe to save meta } ); ``` ### Issue #20: admin-ajax.php Performance **Error**: Slow AJAX responses **Source**: https://deliciousbrains.com/comparing-wordpress-rest-api-performance-admin-ajax-php/ **Why It Happens**: admin-ajax.php loads entire WordPress core **Prevention**: Use REST API for new projects (10x faster) ```php // OLD: admin-ajax.php (still works but slower) add_action( 'wp_ajax_mypl_action', 'mypl_ajax_handler' ); // NEW: REST API (10x faster, recommended) add_action( 'rest_api_init', function() { register_rest_route( 'myplugin/v1', '/endpoint', array( 'methods' => 'POST', 'callback' => 'mypl_rest_handler', 'permission_callback' => function() { return current_user_can( 'edit_posts' ); }, ) ); } ); ``` --- ## Plugin Architecture Patterns ### Pattern 1: Simple Plugin (Functions Only) **When to use**: Small plugins with <5 functions, no complex state ```php