wp-plugin-performance

Source documentation, not instructions for this website. Review permissions before running any commands.

Query only what you need
Cache expensive operations
Load assets conditionally
Avoid work on every request

// CORRECT: Optimized query for displaying 10 posts
$query = new WP_Query( array(
    'post_type'              => 'post',
    'posts_per_page'         => 10,
    'no_found_rows'          => true, // Skip SQL_CALC_FOUND_ROWS if not paginating
    'update_post_meta_cache' => false, // Skip if not using meta
    'update_post_term_cache' => false, // Skip if not using terms
) );

// CORRECT: Get only post IDs for a lightweight lookup
$post_ids = get_posts( array(
    'post_type'      => 'product',
    'posts_per_page' => 100,
    'fields'         => 'ids',
    'no_found_rows'  => true,
) );

// WRONG: Unbounded query - will crash on large sites
$all_posts = get_posts( array(
    'post_type'      => 'post',
    'posts_per_page' => -1, // Never do this in production!
) );

// CORRECT: With pagination - need found_rows for page links
$paged = get_query_var( 'paged' ) ? get_query_var( 'paged' ) : 1;

$query = new WP_Query( array(
    'post_type'      => 'post',
    'posts_per_page' => 10,
    'paged'          => $paged,
    // no_found_rows defaults to false - we need the count
) );

// Display pagination
echo paginate_links( array(
    'total' => $query->max_num_pages,
) );

// WRONG: Never use query_posts() - breaks main query and pagination
query_posts( 'cat=5' );

// CORRECT: Use pre_get_posts filter to modify main query
add_action( 'pre_get_posts', 'ayudawp_modify_main_query' );
function ayudawp_modify_main_query( $query ) {
    if ( ! is_admin() && $query->is_main_query() && $query->is_home() ) {
        $query->set( 'cat', 5 );
    }
}

// CORRECT: Use WP_Query for secondary queries
$custom_query = new WP_Query( array( 'cat' => 5 ) );

// WRONG: Complex meta query on every page load
$query = new WP_Query( array(
    'meta_query' => array(
        'relation' => 'AND',
        array(
            'key'     => 'color',
            'value'   => 'red',
            'compare' => '=',
        ),
        array(
            'key'     => 'size',
            'value'   => array( 'S', 'M', 'L' ),
            'compare' => 'IN',
        ),
    ),
) );

// CORRECT: Use taxonomy for filterable attributes
register_taxonomy( 'product_color', 'product', array( /* ... */ ) );
register_taxonomy( 'product_size', 'product', array( /* ... */ ) );

$query = new WP_Query( array(
    'tax_query' => array(
        'relation' => 'AND',
        array(
            'taxonomy' => 'product_color',
            'field'    => 'slug',
            'terms'    => 'red',
        ),
        array(
            'taxonomy' => 'product_size',
            'field'    => 'slug',
            'terms'    => array( 's', 'm', 'l' ),
        ),
    ),
) );

$query = new WP_Query( array(
    'post_type'  => 'ayudawp_withdrawal',
    'meta_query' => array( // phpcs:ignore WordPress.DB.SlowDBQuery.slow_db_query_meta_query -- Privacy API exporter contract requires lookup by stored customer email.
        array(
            'key'   => '_ayudawp_email',
            'value' => $email,
        ),
    ),
) );

// WRONG: post__not_in on a query that can grow
$query = new WP_Query( array(
    'post__not_in'   => $hundreds_of_ids,
    'posts_per_page' => 20,
) );

// CORRECT: fetch more, filter, cap.
$candidates = get_posts( array(
    'posts_per_page' => 60, // 3x desired so the filter rarely empties the list
    'fields'         => 'ids',
    'no_found_rows'  => true,
) );

$results = array();
foreach ( $candidates as $id ) {
    if ( in_array( $id, $excluded_ids, true ) ) {
        continue;
    }
    $results[] = $id;
    if ( count( $results ) >= 20 ) {
        break;
    }
}

// WRONG: exclude param on get_terms()
$terms = get_terms( array(
    'taxonomy'   => 'product_cat',
    'number'     => 20,
    'exclude'    => $excluded_ids,
) );

// CORRECT: ask for more, filter in PHP, cap.
$candidates = get_terms( array(
    'taxonomy'   => 'product_cat',
    'hide_empty' => false,
    'number'     => 40,
) );

$results = array();
foreach ( $candidates as $term ) {
    if ( in_array( (int) $term->term_id, $excluded_ids, true ) ) {
        continue;
    }
    $results[] = $term;
    if ( count( $results ) >= 20 ) {
        break;
    }
}

// CORRECT: Use $wpdb->prepare() with proper placeholders
global $wpdb;

$results = $wpdb->get_results(
    $wpdb->prepare(
        "SELECT ID, post_title FROM {$wpdb->posts} 
         WHERE post_type = %s AND post_status = %s 
         LIMIT %d",
        'product',
        'publish',
        100
    )
);

// WRONG: LIKE with leading wildcard - full table scan
$wpdb->get_results(
    $wpdb->prepare(
        "SELECT * FROM {$wpdb->posts} WHERE post_title LIKE %s",
        '%' . $wpdb->esc_like( $search ) . '%' // Leading % = slow
    )
);

// CORRECT: Trailing wildcard only when possible
$wpdb->get_results(
    $wpdb->prepare(
        "SELECT * FROM {$wpdb->posts} WHERE post_title LIKE %s",
        $wpdb->esc_like( $search ) . '%' // Trailing % = can use index
    )
);

// WRONG: Query with potentially falsy ID
$post_id = get_some_id(); // Might return false, null, or 0
$query = new WP_Query( array( 'p' => intval( $post_id ) ) ); // p=0 returns posts!

// CORRECT: Validate before querying
$post_id = get_some_id();
if ( ! empty( $post_id ) && is_numeric( $post_id ) ) {
    $query = new WP_Query( array( 'p' => absint( $post_id ) ) );
}

// CORRECT: Small settings - autoload is fine (default)
add_option( 'ayudawp_settings', array(
    'enabled' => true,
    'limit'   => 10,
) );

// CORRECT: Large data - disable autoload
add_option( 'ayudawp_large_data', $large_array, '', 'no' );

// CORRECT: Update existing option's autoload status
global $wpdb;
$wpdb->update(
    $wpdb->options,
    array( 'autoload' => 'no' ),
    array( 'option_name' => 'ayudawp_large_data' )
);

// Check total autoloaded size (for debugging)
$autoload_size = $wpdb->get_var(
    "SELECT SUM(LENGTH(option_value)) FROM {$wpdb->options} WHERE autoload = 'yes'"
);
// Target: under 800KB total

// WRONG: Writing options on every page view
add_action( 'wp_head', 'ayudawp_bad_tracking' );
function ayudawp_bad_tracking() {
    $count = get_option( 'page_views', 0 );
    update_option( 'page_views', $count + 1 ); // DB write every request!
}

// CORRECT: Buffer in object cache, flush periodically
add_action( 'shutdown', 'ayudawp_buffer_tracking' );
function ayudawp_buffer_tracking() {
    wp_cache_incr( 'page_views_buffer', 1, 'ayudawp_stats' );
}

// Flush buffer via cron (hourly)
add_action( 'ayudawp_flush_stats', 'ayudawp_flush_view_buffer' );
function ayudawp_flush_view_buffer() {
    $buffered = wp_cache_get( 'page_views_buffer', 'ayudawp_stats' );
    if ( $buffered ) {
        $current = get_option( 'page_views', 0 );
        update_option( 'page_views', $current + $buffered );
        wp_cache_delete( 'page_views_buffer', 'ayudawp_stats' );
    }
}

// CORRECT: Cache expensive function results
function ayudawp_get_complex_data( $user_id ) {
    $cache_key = 'complex_data_' . $user_id;
    $cache_group = 'ayudawp_data';
    
    $data = wp_cache_get( $cache_key, $cache_group );
    
    if ( false === $data ) {
        // Expensive operation

name: wp-plugin-performance
description: "Performance guidelines for WordPress plugin development: database optimization, object caching, conditional asset loading, efficient hooks, HTTP requests, WP-Cron, AJAX/REST optimization, and common anti-patterns. Based on official WordPress Developer Resources and WP VIP documentation."
compatibility: "WordPress 6.0+ / PHP 7.4+. Applies to plugins and custom code."
license: GPL-2.0-or-later
metadata:
  author: fernando-tellado
  version: "1.1"

---
name: wp-plugin-performance
description: "Performance guidelines for WordPress plugin development: database optimization, object caching, conditional asset loading, efficient hooks, HTTP requests, WP-Cron, AJAX/REST optimization, and common anti-patterns. Based on official WordPress Developer Resources and WP VIP documentation."
compatibility: "WordPress 6.0+ / PHP 7.4+. Applies to plugins and custom code."
license: GPL-2.0-or-later
metadata:
  author: fernando-tellado
  version: "1.1"
---

# WordPress plugin performance

## When to use

Use this skill when:

- Developing new WordPress plugins
- Optimizing existing plugin code for better performance
- Working with database queries (WP_Query, $wpdb, options)
- Implementing caching strategies (object cache, transients)
- Loading assets (scripts, styles) efficiently
- Creating AJAX handlers or REST API endpoints
- Scheduling background tasks with WP-Cron
- Making external HTTP requests from plugins
- Reviewing code before deployment to high-traffic sites

## Core performance principles

### The performance mantra

```
Query only what you need
Cache expensive operations
Load assets conditionally
Avoid work on every request
```

### Key concepts

1. **Bounded queries**: Always limit results with `posts_per_page` or similar
2. **Object caching**: Store expensive computations for reuse across requests
3. **Conditional loading**: Enqueue scripts/styles only where needed
4. **Context awareness**: Check `is_admin()`, page conditions before heavy operations
5. **Async processing**: Move slow tasks to WP-Cron or background processes

## Database queries

Efficient database queries are the foundation of plugin performance.

### WP_Query optimization

| Parameter | Purpose |
|-----------|---------|
| `posts_per_page` | Limit results (never use -1 in production) |
| `no_found_rows` | Skip counting total rows when not paginating |
| `update_post_meta_cache` | Set false if not using post meta |
| `update_post_term_cache` | Set false if not using taxonomies |
| `fields` | Request only 'ids' or 'id=>parent' when full objects not needed |
| `cache_results` | Keep true unless intentionally bypassing cache |

### WP_Query examples

```php
// CORRECT: Optimized query for displaying 10 posts
$query = new WP_Query( array(
    'post_type'              => 'post',
    'posts_per_page'         => 10,
    'no_found_rows'          => true, // Skip SQL_CALC_FOUND_ROWS if not paginating
    'update_post_meta_cache' => false, // Skip if not using meta
    'update_post_term_cache' => false, // Skip if not using terms
) );

// CORRECT: Get only post IDs for a lightweight lookup
$post_ids = get_posts( array(
    'post_type'      => 'product',
    'posts_per_page' => 100,
    'fields'         => 'ids',
    'no_found_rows'  => true,
) );

// WRONG: Unbounded query - will crash on large sites
$all_posts = get_posts( array(
    'post_type'      => 'post',
    'posts_per_page' => -1, // Never do this in production!
) );
```

### When pagination is needed

```php
// CORRECT: With pagination - need found_rows for page links
$paged = get_query_var( 'paged' ) ? get_query_var( 'paged' ) : 1;

$query = new WP_Query( array(
    'post_type'      => 'post',
    'posts_per_page' => 10,
    'paged'          => $paged,
    // no_found_rows defaults to false - we need the count
) );

// Display pagination
echo paginate_links( array(
    'total' => $query->max_num_pages,
) );
```

### Avoid query_posts()

```php
// WRONG: Never use query_posts() - breaks main query and pagination
query_posts( 'cat=5' );

// CORRECT: Use pre_get_posts filter to modify main query
add_action( 'pre_get_posts', 'ayudawp_modify_main_query' );
function ayudawp_modify_main_query( $query ) {
    if ( ! is_admin() && $query->is_main_query() && $query->is_home() ) {
        $query->set( 'cat', 5 );
    }
}

// CORRECT: Use WP_Query for secondary queries
$custom_query = new WP_Query( array( 'cat' => 5 ) );
```

### Meta queries optimization

Meta queries scan unindexed columns. Use them sparingly.

```php
// WRONG: Complex meta query on every page load
$query = new WP_Query( array(
    'meta_query' => array(
        'relation' => 'AND',
        array(
            'key'     => 'color',
            'value'   => 'red',
            'compare' => '=',
        ),
        array(
            'key'     => 'size',
            'value'   => array( 'S', 'M', 'L' ),
            'compare' => 'IN',
        ),
    ),
) );

// CORRECT: Use taxonomy for filterable attributes
register_taxonomy( 'product_color', 'product', array( /* ... */ ) );
register_taxonomy( 'product_size', 'product', array( /* ... */ ) );

$query = new WP_Query( array(
    'tax_query' => array(
        'relation' => 'AND',
        array(
            'taxonomy' => 'product_color',
            'field'    => 'slug',
            'terms'    => 'red',
        ),
        array(
            'taxonomy' => 'product_size',
            'field'    => 'slug',
            'terms'    => array( 's', 'm', 'l' ),
        ),
    ),
) );
```

### Legitimate `meta_query` uses

Some lookups are unavoidably keyed by post meta because that is where the data lives (Privacy API exporters/erasers keyed by customer email, WooCommerce order number resolvers that respect plugins like Sequential Order Numbers, etc.). For these, the `WordPress.DB.SlowDBQuery.slow_db_query_meta_query` warning is informational, not a security issue, and the manual reviewer accepts it with a short justification:

```php
$query = new WP_Query( array(
    'post_type'  => 'ayudawp_withdrawal',
    'meta_query' => array( // phpcs:ignore WordPress.DB.SlowDBQuery.slow_db_query_meta_query -- Privacy API exporter contract requires lookup by stored customer email.
        array(
            'key'   => '_ayudawp_email',
            'value' => $email,
        ),
    ),
) );
```

The justification text matters: state *why* the meta_query is the right tool here (a contract from another API, a third-party numbering scheme, etc.). A bare `phpcs:ignore` without comment looks lazy and triggers extra scrutiny.

### Post and term exclusion patterns

Plugin Check (and PHPCS WPVIP rules) flag every exclusionary argument: `post__not_in`, `exclude`, `category__not_in`, `tag__not_in`, `author__not_in`. The wp.org review pipeline surfaces the warning even when the input set is tiny. Refactor to "fetch a slightly larger window, filter in PHP, cap at the desired count":

```php
// WRONG: post__not_in on a query that can grow
$query = new WP_Query( array(
    'post__not_in'   => $hundreds_of_ids,
    'posts_per_page' => 20,
) );

// CORRECT: fetch more, filter, cap.
$candidates = get_posts( array(
    'posts_per_page' => 60, // 3x desired so the filter rarely empties the list
    'fields'         => 'ids',
    'no_found_rows'  => true,
) );

$results = array();
foreach ( $candidates as $id ) {
    if ( in_array( $id, $excluded_ids, true ) ) {
        continue;
    }
    $results[] = $id;
    if ( count( $results ) >= 20 ) {
        break;
    }
}
```

Same pattern applies to `get_terms()` with `exclude`:

```php
// WRONG: exclude param on get_terms()
$terms = get_terms( array(
    'taxonomy'   => 'product_cat',
    'number'     => 20,
    'exclude'    => $excluded_ids,
) );

// CORRECT: ask for more, filter in PHP, cap.
$candidates = get_terms( array(
    'taxonomy'   => 'product_cat',
    'hide_empty' => false,
    'number'     => 40,
) );

$results = array();
foreach ( $candidates as $term ) {
    if ( in_array( (int) $term->term_id, $excluded_ids, true ) ) {
        continue;
    }
    $results[] = $term;
    if ( count( $results ) >= 20 ) {
        break;
    }
}
```

The PHP loop is cheap (small bounded window) and the SQL query no longer carries a `NOT IN (...)` clause that scales linearly with the exclusion list.

### Direct database queries

```php
// CORRECT: Use $wpdb->prepare() with proper placeholders
global $wpdb;

$results = $wpdb->get_results(
    $wpdb->prepare(
        "SELECT ID, post_title FROM {$wpdb->posts} 
         WHERE post_type = %s AND post_status = %s 
         LIMIT %d",
        'product',
        'publish',
        100
    )
);

// WRONG: LIKE with leading wildcard - full table scan
$wpdb->get_results(
    $wpdb->prepare(
        "SELECT * FROM {$wpdb->posts} WHERE post_title LIKE %s",
        '%' . $wpdb->esc_like( $search ) . '%' // Leading % = slow
    )
);

// CORRECT: Trailing wildcard only when possible
$wpdb->get_results(
    $wpdb->prepare(
        "SELECT * FROM {$wpdb->posts} WHERE post_title LIKE %s",
        $wpdb->esc_like( $search ) . '%' // Trailing % = can use index
    )
);
```

### Validate before querying

```php
// WRONG: Query with potentially falsy ID
$post_id = get_some_id(); // Might return false, null, or 0
$query = new WP_Query( array( 'p' => intval( $post_id ) ) ); // p=0 returns posts!

// CORRECT: Validate before querying
$post_id = get_some_id();
if ( ! empty( $post_id ) && is_numeric( $post_id ) ) {
    $query = new WP_Query( array( 'p' => absint( $post_id ) ) );
}
```

## Options and autoload

WordPress loads all autoloaded options on every page request.

### Autoload guidelines

| Data type | Autoload | Reason |
|-----------|----------|--------|
| Plugin settings (small) | Yes | Needed on most requests |
| Feature flags | Yes | Checked frequently |
| Large serialized data | No | Bloats memory on every request |
| Rarely used data | No | Only load when needed |
| Cached API responses | No | Use transients instead |

### Managing autoload

```php
// CORRECT: Small settings - autoload is fine (default)
add_option( 'ayudawp_settings', array(
    'enabled' => true,
    'limit'   => 10,
) );

// CORRECT: Large data - disable autoload
add_option( 'ayudawp_large_data', $large_array, '', 'no' );

// CORRECT: Update existing option's autoload status
global $wpdb;
$wpdb->update(
    $wpdb->options,
    array( 'autoload' => 'no' ),
    array( 'option_name' => 'ayudawp_large_data' )
);

// Check total autoloaded size (for debugging)
$autoload_size = $wpdb->get_var(
    "SELECT SUM(LENGTH(option_value)) FROM {$wpdb->options} WHERE autoload = 'yes'"
);
// Target: under 800KB total
```

### Avoid frequent option writes

```php
// WRONG: Writing options on every page view
add_action( 'wp_head', 'ayudawp_bad_tracking' );
function ayudawp_bad_tracking() {
    $count = get_option( 'page_views', 0 );
    update_option( 'page_views', $count + 1 ); // DB write every request!
}

// CORRECT: Buffer in object cache, flush periodically
add_action( 'shutdown', 'ayudawp_buffer_tracking' );
function ayudawp_buffer_tracking() {
    wp_cache_incr( 'page_views_buffer', 1, 'ayudawp_stats' );
}

// Flush buffer via cron (hourly)
add_action( 'ayudawp_flush_stats', 'ayudawp_flush_view_buffer' );
function ayudawp_flush_view_buffer() {
    $buffered = wp_cache_get( 'page_views_buffer', 'ayudawp_stats' );
    if ( $buffered ) {
        $current = get_option( 'page_views', 0 );
        update_option( 'page_views', $current + $buffered );
        wp_cache_delete( 'page_views_buffer', 'ayudawp_stats' );
    }
}
```

## Object cache

Object cache stores data in memory for the duration of a request (or persistently with Redis/Memcached).

### Object cache functions

| Function | Purpose |
|----------|---------|
| `wp_cache_get()` | Retrieve cached value |
| `wp_cache_set()` | Store value in cache |
| `wp_cache_add()` | Store only if key doesn't exist |
| `wp_cache_delete()` | Remove cached value |
| `wp_cache_incr()` | Increment numeric value |
| `wp_cache_get_multiple()` | Batch retrieve (WP 5.5+) |
| `wp_using_ext_object_cache()` | Check if persistent cache available |

### Caching expensive operations

```php
// CORRECT: Cache expensive function results
function ayudawp_get_complex_data( $user_id ) {
    $cache_key = 'complex_data_' . $user_id;
    $cache_group = 'ayudawp_data';
    
    $data = wp_cache_get( $cache_key, $cache_group );
    
    if ( false === $data ) {
        // Expensive operation