wp-plugin-performance

Documentación de origen, no instrucciones para este sitio. Revisa los permisos antes de ejecutar comandos.

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