Skip to content

secondsky/claude-skills / plugins/wordpress-plugin-core/skills/wordpress-plugin-core

wordpress-plugin-core

Flagged

WordPress plugin development with hooks, security, REST API, custom post types. Use for plugin creation, $wpdb queries, Settings API, or encountering SQL injection, XSS, CSRF, nonce errors.

FileKindSize
SKILL.mdskill md17.9 KB
assets/example-template.txtmarkdown416 B
examples/github-updater.phpscript15.3 KB
references/advanced-topics.mdmarkdown16.6 KB
references/common-hooks.mdmarkdown2.7 KB
references/common-patterns.mdmarkdown13.1 KB
references/error-catalog.mdmarkdown16.3 KB
references/example-reference.mdmarkdown760 B
references/github-auto-updates.mdmarkdown30.3 KB
references/plugin-architectures.mdmarkdown21.0 KB
references/security-checklist.mdmarkdown11.7 KB
scripts/example-script.shexecutablescript302 B
scripts/scaffold-plugin.shexecutablescript9.0 KB
templates/examples/ajax-handler.phpscript8.0 KB
templates/examples/custom-post-type.phpscript9.5 KB
templates/examples/meta-box.phpscript6.3 KB
templates/examples/rest-endpoint.phpscript8.7 KB
templates/examples/settings-page.phpscript7.9 KB
templates/plugin-oop/README.mdmarkdown7.4 KB
templates/plugin-oop/my-oop-plugin.phpscript12.5 KB
templates/plugin-oop/uninstall.phpscript929 B
templates/plugin-oop/views/admin-settings.phpscript2.1 KB
templates/plugin-psr4/README.mdmarkdown9.7 KB
templates/plugin-psr4/composer.jsonconfig706 B
templates/plugin-psr4/my-psr4-plugin.phpscript1.7 KB
templates/plugin-psr4/src/API/BookEndpoints.phpscript5.3 KB
templates/plugin-psr4/src/Admin/Settings.phpscript5.1 KB
templates/plugin-psr4/src/Frontend/Assets.phpscript2.0 KB
templates/plugin-psr4/src/Plugin.phpscript2.4 KB
templates/plugin-psr4/src/PostTypes/Book.phpscript4.9 KB
templates/plugin-psr4/src/Taxonomies/Genre.phpscript1.9 KB
templates/plugin-psr4/uninstall.phpscript929 B
templates/plugin-simple/README.mdmarkdown4.6 KB
templates/plugin-simple/my-simple-plugin.phpscript7.4 KB
templates/plugin-simple/uninstall.phpscript1.3 KB

references/common-patterns.md

View on GitHub
# WordPress Plugin Common Patterns

**Purpose**: Production-ready implementation patterns for common WordPress plugin features.

**Last Updated**: 2025-11-27

**Use this reference when**: Implementing specific features like custom post types, taxonomies, meta boxes, Settings API, REST API, AJAX, custom database tables, or caching with transients.

---

## Pattern 1: Custom Post Types

```php
function mypl_register_cpt() {
    register_post_type( 'book', array(
        'labels' => array(
            'name'          => 'Books',
            'singular_name' => 'Book',
            'add_new_item'  => 'Add New Book',
        ),
        'public'       => true,
        'has_archive'  => true,
        'show_in_rest' => true,  // Gutenberg support
        'supports'     => array( 'title', 'editor', 'thumbnail', 'excerpt' ),
        'rewrite'      => array( 'slug' => 'books' ),
        'menu_icon'    => 'dashicons-book',
    ) );
}
add_action( 'init', 'mypl_register_cpt' );

// CRITICAL: Flush rewrite rules on activation
function mypl_activate() {
    mypl_register_cpt();
    flush_rewrite_rules();
}
register_activation_hook( __FILE__, 'mypl_activate' );

function mypl_deactivate() {
    flush_rewrite_rules();
}
register_deactivation_hook( __FILE__, 'mypl_deactivate' );
```

**Key Points**:
- Always include `'show_in_rest' => true` for Gutenberg support
- MUST flush rewrite rules on activation/deactivation
- Use `dashicons-*` for menu icons
- Define `supports` array to enable specific features

---

## Pattern 2: Custom Taxonomies

```php
function mypl_register_taxonomy() {
    register_taxonomy( 'genre', 'book', array(
        'labels' => array(
            'name'          => 'Genres',
            'singular_name' => 'Genre',
        ),
        'hierarchical' => true,  // Like categories
        'show_in_rest' => true,
        'rewrite'      => array( 'slug' => 'genre' ),
    ) );
}
add_action( 'init', 'mypl_register_taxonomy' );
```

**Key Points**:
- `hierarchical => true` for category-like (parent/child)
- `hierarchical => false` for tag-like (flat)
- Second parameter associates with post type (e.g., 'book')
- Register taxonomies AFTER custom post types

---

## Pattern 3: Meta Boxes

```php
function mypl_add_meta_box() {
    add_meta_box(
        'book_details',
        'Book Details',
        'mypl_meta_box_html',
        'book',
        'normal',
        'high'
    );
}
add_action( 'add_meta_boxes', 'mypl_add_meta_box' );

function mypl_meta_box_html( $post ) {
    $isbn = get_post_meta( $post->ID, '_book_isbn', true );

    wp_nonce_field( 'mypl_save_meta', 'mypl_meta_nonce' );
    ?>
    <label for="book_isbn">ISBN:</label>
    <input type="text" id="book_isbn" name="book_isbn" value="<?php echo esc_attr( $isbn ); ?>" />
    <?php
}

function mypl_save_meta( $post_id ) {
    // Security checks
    if ( ! isset( $_POST['mypl_meta_nonce'] )
         || ! wp_verify_nonce( $_POST['mypl_meta_nonce'], 'mypl_save_meta' ) ) {
        return;
    }

    if ( defined( 'DOING_AUTOSAVE' ) && DOING_AUTOSAVE ) {
        return;
    }

    if ( ! current_user_can( 'edit_post', $post_id ) ) {
        return;
    }

    // Save data
    if ( isset( $_POST['book_isbn'] ) ) {
        update_post_meta(
            $post_id,
            '_book_isbn',
            sanitize_text_field( $_POST['book_isbn'] )
        );
    }
}
add_action( 'save_post_book', 'mypl_save_meta' );
```

**Security Requirements**:
1. ALWAYS include nonce verification
2. Check for autosave
3. Verify user capabilities
4. Sanitize ALL input before saving

**Key Points**:
- Use `save_post_{post_type}` for specific post types
- Prefix meta keys with `_` to hide from custom fields UI
- Use `get_post_meta()` third parameter `true` for single values

---

## Pattern 4: Settings API

```php
function mypl_add_menu() {
    add_options_page(
        'My Plugin Settings',
        'My Plugin',
        'manage_options',
        'my-plugin',
        'mypl_settings_page'
    );
}
add_action( 'admin_menu', 'mypl_add_menu' );

function mypl_register_settings() {
    register_setting( 'mypl_options', 'mypl_api_key', array(
        'type'              => 'string',
        'sanitize_callback' => 'sanitize_text_field',
        'default'           => '',
    ) );

    add_settings_section(
        'mypl_section',
        'API Settings',
        'mypl_section_callback',
        'my-plugin'
    );

    add_settings_field(
        'mypl_api_key',
        'API Key',
        'mypl_field_callback',
        'my-plugin',
        'mypl_section'
    );
}
add_action( 'admin_init', 'mypl_register_settings' );

function mypl_section_callback() {
    echo '<p>Configure your API settings.</p>';
}

function mypl_field_callback() {
    $value = get_option( 'mypl_api_key' );
    ?>
    <input type="text" name="mypl_api_key" value="<?php echo esc_attr( $value ); ?>" />
    <?php
}

function mypl_settings_page() {
    if ( ! current_user_can( 'manage_options' ) ) {
        return;
    }
    ?>
    <div class="wrap">
        <h1><?php echo esc_html( get_admin_page_title() ); ?></h1>
        <form method="post" action="options.php">
            <?php
            settings_fields( 'mypl_options' );
            do_settings_sections( 'my-plugin' );
            submit_button();
            ?>
        </form>
    </div>
    <?php
}
```

**Settings API Hierarchy**:
1. `register_setting()` - Register the option
2. `add_settings_section()` - Create a section
3. `add_settings_field()` - Add fields to sections
4. `settings_fields()` + `do_settings_sections()` - Display in page

**Key Points**:
- ALWAYS use `sanitize_callback` in `register_setting()`
- Check `manage_options` capability
- Use `settings_fields()` for nonce/referer protection
- Use `esc_attr()` when outputting values

---

## Pattern 5: REST API Endpoints

```php
add_action( 'rest_api_init', function() {
    register_rest_route( 'myplugin/v1', '/data', array(
        'methods'             => WP_REST_Server::READABLE,
        'callback'            => 'mypl_rest_callback',
        'permission_callback' => function() {
            return current_user_can( 'edit_posts' );
        },
        'args'                => array(
            'id' => array(
                'required'          => true,
                'validate_callback' => function( $param ) {
                    return is_numeric( $param );
                },
                'sanitize_callback' => 'absint',
            ),
        ),
    ) );
} );

function mypl_rest_callback( $request ) {
    $id = $request->get_param( 'id' );

    // Process...

    return new WP_REST_Response( array(
        'success' => true,
        'data'    => $data,
    ), 200 );
}
```

**Security Requirements**:
1. ALWAYS include `permission_callback` (even if public: `__return_true`)
2. Validate ALL parameters with `validate_callback`
3. Sanitize ALL parameters with `sanitize_callback`

**Key Points**:
- Use `WP_REST_Server::READABLE` (GET), `CREATABLE` (POST), `EDITABLE` (PUT/PATCH), `DELETABLE` (DELETE)
- Return `WP_REST_Response` object with HTTP status code
- Use `$request->get_param()` to retrieve parameters
- Version your API namespace (e.g., `/myplugin/v1/`)

---

## Pattern 6: AJAX Handlers (Legacy)

```php
// Enqueue script with localized data
function mypl_enqueue_ajax_script() {
    wp_enqueue_script( 'mypl-ajax', plugins_url( 'js/ajax.js', __FILE__ ), array( 'jquery' ), '1.0', true );

    wp_localize_script( 'mypl-ajax', 'mypl_ajax_object', array(
        'ajaxurl' => admin_url( 'admin-ajax.php' ),
        'nonce'   => wp_create_nonce( 'mypl-ajax-nonce' ),
    ) );
}
add_action( 'wp_enqueue_scripts', 'mypl_enqueue_ajax_script' );

// AJAX handler (logged-in users)
function mypl_ajax_handler() {
    check_ajax_referer( 'mypl-ajax-nonce', 'nonce' );

    $data = sanitize_text_field( $_POST['data'] );

    // Process...

    wp_send_json_success( array( 'message' => 'Success' ) );
}
add_action( 'wp_ajax_mypl_action', 'mypl_ajax_handler' );

// AJAX handler (logged-out users)
add_action( 'wp_ajax_nopriv_mypl_action', 'mypl_ajax_handler' );
```

**JavaScript (js/ajax.js)**:
```javascript
jQuery(document).ready(function($) {
    $('#my-button').on('click', function() {
        $.ajax({
            url: mypl_ajax_object.ajaxurl,
            type: 'POST',
            data: {
                action: 'mypl_action',
                nonce: mypl_ajax_object.nonce,
                data: 'value'
            },
            success: function(response) {
                console.log(response.data.message);
            }
        });
    });
});
```

**Security Requirements**:
1. ALWAYS use `check_ajax_referer()` in PHP handler
2. Create nonce with `wp_create_nonce()` and pass via `wp_localize_script()`
3. Sanitize ALL input data

**Key Points**:
- Use `wp_ajax_{action}` for logged-in users
- Use `wp_ajax_nopriv_{action}` for logged-out users
- Use `wp_send_json_success()` / `wp_send_json_error()` for responses
- For modern apps, prefer REST API (Pattern 5) over AJAX

---

## Pattern 7: Custom Database Tables

```php
function mypl_create_tables() {
    global $wpdb;

    $table_name = $wpdb->prefix . 'mypl_data';
    $charset_collate = $wpdb->get_charset_collate();

    $sql = "CREATE TABLE $table_name (
        id bigint(20) NOT NULL AUTO_INCREMENT,
        user_id bigint(20) NOT NULL,
        data text NOT NULL,
        created datetime DEFAULT CURRENT_TIMESTAMP NOT NULL,
        PRIMARY KEY  (id),
        KEY user_id (user_id)
    ) $charset_collate;";

    require_once ABSPATH . 'wp-admin/includes/upgrade.php';
    dbDelta( $sql );

    add_option( 'mypl_db_version', '1.0' );
}

// Create tables on activation
register_activation_hook( __FILE__, 'mypl_create_tables' );
```

**Critical Requirements**:
1. ALWAYS use `dbDelta()` (not direct SQL) for table creation
2. Use `$wpdb->prefix` for multisite compatibility
3. Include `$charset_collate` for proper character encoding
4. Version your database schema with options

**Key Points**:
- Two spaces after PRIMARY KEY (dbDelta requirement)
- Include indexes for frequently queried columns
- Use `bigint(20)` for IDs to match WordPress core
- Create tables on plugin activation, not on every load

---

## Pattern 8: Transients for Caching

```php
function mypl_get_expensive_data() {
    // Try to get cached data
    $data = get_transient( 'mypl_expensive_data' );

    if ( false === $data ) {
        // Not cached - regenerate
        $data = perform_expensive_operation();

        // Cache for 12 hours
        set_transient( 'mypl_expensive_data', $data, 12 * HOUR_IN_SECONDS );
    }

    return $data;
}

// Clear cache when data changes
function mypl_clear_cache() {
    delete_transient( 'mypl_expensive_data' );
}
add_action( 'save_post', 'mypl_clear_cache' );
```

**When to Use Transients**:
- External API calls (cache for minutes/hours)
- Complex database queries (cache for hours/days)
- Heavy computations (cache for days/weeks)
- Non-user-specific data only (use user meta for per-user caching)

**Key Points**:
- Transients can expire or be cleared at any time (not guaranteed)
- Use `HOUR_IN_SECONDS`, `DAY_IN_SECONDS`, `WEEK_IN_SECONDS` constants
- Always include cache invalidation logic
- Maximum transient name length: 172 characters (WordPress limit)

**Transient vs. Options**:
- Transients: Temporary, can expire, can be cleared
- Options: Permanent, never expire unless explicitly deleted
- Use transients for cache, options for settings

---

## Best Practices Summary

### Naming Conventions
- Prefix ALL functions, classes, constants, database tables with unique prefix
- Use lowercase with underscores for function names: `mypl_function_name()`
- Use uppercase with underscores for constants: `MYPL_CONSTANT_NAME`
- Start private meta keys with underscore: `_mypl_meta_key`

### Security
- Always verify nonces for form submissions
- Always check user capabilities
- Always sanitize input, escape output
- Always use prepared statements for database queries

### Performance
- Cache expensive operations with transients
- Enqueue scripts/styles only where needed
- Use `wp_enqueue_script()` in footer (5th parameter `true`)
- Minimize database queries (use `get_posts()` vs multiple `get_post()` calls)

### WordPress Coding Standards
- Use tabs for indentation (not spaces)
- Follow WordPress PHP coding standards
- Use Yoda conditions: `if ( 5 === $value )` not `if ( $value === 5 )`
- Always use braces for control structures, even single-line

---

## Common Mistakes to Avoid

1. **Not flushing rewrite rules** after registering custom post types/taxonomies
2. **Flushing rewrite rules on every page load** (huge performance hit)
3. **Direct database queries without `$wpdb->prepare()`** (SQL injection)
4. **Not checking nonces** in form/AJAX handlers (CSRF vulnerability)
5. **Not sanitizing input** or escaping output (XSS vulnerability)
6. **Hardcoding table prefixes** instead of using `$wpdb->prefix`
7. **Using `$_GET`/`$_POST` directly** without sanitization
8. **Not checking user capabilities** before privileged operations
9. **Enqueueing scripts everywhere** instead of specific pages
10. **Creating tables on every page load** instead of activation hook

---

**Reference Updated**: 2025-11-27
**Related**: See `error-catalog.md` for detailed error solutions, `security-checklist.md` for security audit
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 469kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 469kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 469kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall