WP-CLI: Advanced Techniques for Real-World WordPress Development — Part 2

and**

This command cleans up expired transients and optimizes database tables. It includes a --dry-run flag and progress tracking for large datasets.

<?php
// File: inc/cli-commands/db-vacuum.php

use WP_CLI;
use WP_CLI\Utils;

if ( ! defined( 'WP_CLI' ) || ! WP_CLI ) {
    return;
}

WP_CLI::add_command( 'db vacuum', function( $args, $assoc ) {
    $dry_run = Utils\get_flag_value( $assoc, 'dry-run', false );
    $tables  = $args ?: Utils\wp_get_table_names( [] );

    WP_CLI::log( sprintf( 'Starting vacuum on %d tables.', count( $tables ) ) );
    if ( $dry_run ) {
        WP_CLI::log( '[DRY RUN] No changes will be applied.' );
    }

    $progress = Utils\make_progress_bar( 'Processing tables', count( $tables ) );

    foreach ( $tables as $table ) {
        if ( $dry_run ) {
            WP_CLI::log( sprintf( 'Would optimize: %s', $table ) );
        } else {
            global $wpdb;
            $result = $wpdb->query( $wpdb->prepare( 'OPTIMIZE TABLE %i', $table ) );
            if ( false === $result ) {
                WP_CLI::warning( sprintf( 'Failed to optimize: %s', $table ) );
            }
        }
        $progress->tick();
    }

    $progress->finish();

    // Clean expired transients
    $deleted = delete_expired_transients( $dry_run );
    WP_CLI::success( sprintf( 'Vacuum complete. Removed %d expired transients.', $deleted ) );
}, [
    'shortdesc' => 'Optimize tables and clean expired transients.',
    'synopsis'  => [
        [
            'type'        => 'positional',
            'name'        => 'tables',
            'description' => 'Specific tables to optimize. Defaults to all.',
            'optional'    => true,
            'repeating'   => true,
        ],
        [
            'type'        => 'flag',
            'name'        => 'dry-run',
            'description' => 'Preview changes without applying them.',
        ],
    ],
]);

function delete_expired_transients( $dry_run = false ) {
    global $wpdb;
    $query = "DELETE FROM {$wpdb->options} WHERE option_name LIKE '_transient_%' AND option_value < UNIX_TIMESTAMP()";
    
    if ( $dry_run ) {
        $count = $wpdb->get_var( "SELECT COUNT(*) FROM {$wpdb->options} WHERE option_name LIKE '_transient_%' AND option_value < UNIX_TIMESTAMP()" );
        return (int) $count;
    }

    $deleted = $wpdb->query( $query );
    return (int) $deleted;
}

Rationale:

• Synopsis Definition: Explicitly defines arguments and flags, enabling auto-generated help text and validation.
• Progress Bar: Provides visual feedback for long-running operations, essential for large databases.
• Dry-Run Support: Allows operators to preview impact before committing changes, mitigating risk.
• Utility Functions: Uses WP_CLI\Utils for consistent output formatting and table name resolution.

2. CI/CD Pipeline Integration

WP-CLI commands should be embedded in deployment pipelines to ensure environment consistency. Post-deploy tasks must be idempotent, meaning they can be safely re-run without side effects.

Example: GitHub Actions Deployment Workflow

This workflow demonstrates a secure deployment process that includes database backups, core updates, and cache management.

# .github/workflows/deploy-production.yml
name: Deploy to Production

on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v4

      - name: Setup SSH Key
        uses: webfactory/ssh-agent@v0.8.0
        with:
          ssh-private-key: ${{ secrets.PRODUCTION_SSH_KEY }}

      - name: Execute Deployment Tasks
        run: |
          ssh -o StrictHostKeyChecking=no deployer@production.example.com << 'REMOTE'
            set -e
            cd /var/www/html

            # Pre-deploy backup
            wp db export backup-$(date +%Y%m%d%H%M%S).sql --porcelain
            echo "✅ Database backup created."

            # Pull latest code
            git pull origin main
            composer install --no-dev --optimize-autoloader
            echo "✅ Code deployed."

            # Run database migrations
            wp core update-db --network
            echo "✅ Database updated."

            # Flush caches and rewrite rules
            wp cache flush
            wp rewrite flush
            echo "✅ Caches flushed."

            # Verify integrity
            wp core verify-checksums
            echo "✅ Integrity verified."

            echo "🚀 Deployment complete."
          REMOTE

Rationale:

• Idempotency: Commands like wp core update-db and wp cache flush are safe to re-run.
• Safety: Database export precedes any modifications, providing a rollback point.
• Verification: wp core verify-checksums ensures no unauthorized file modifications occurred.
• Error Handling: set -e ensures the script halts on any command failure, preventing partial deployments.

3. Remote Management via Aliases

Managing multiple environments requires a centralized configuration for remote access. WP-CLI supports SSH aliases defined in wp-cli.yml, enabling seamless execution against remote instances.

Configuration:

# wp-cli.yml
@staging:
  ssh: deployer@staging.example.com/var/www/html

@production:
  ssh: deployer@production.example.com/var/www/html
  url: https://production.example.com

require:
  - inc/cli-commands/db-vacuum.php

Usage:

# Run vacuum on staging with dry-run
wp @staging db vacuum --dry-run

# Execute security audit on production
wp @production security roles --role=administrator --inactive-days=90

# Sync options across environments
wp @staging option get siteurl | xargs -I {} wp @production option update siteurl {}

Rationale:

• Centralized Config: Aliases abstract connection details, reducing command complexity.
• Context Awareness: The url parameter ensures multisite and domain-specific commands target the correct site.
• Command Loading: The require directive automatically loads custom commands, ensuring consistency across environments.

Pitfall Guide

Pitfall	Explanation	Fix
Missing Context Guard	Custom commands execute during web requests if not guarded, causing errors or security issues.	Always wrap command registration in if ( defined( 'WP_CLI' ) && WP_CLI ).
Non-Idempotent Deploys	Pipeline commands that fail on subsequent runs (e.g., creating a user that already exists) break automation.	Use flags like --skip-if-exists or check state before executing.
Hardcoded Secrets	Storing database credentials or API keys in wp-cli.yml exposes sensitive data in version control.	Use environment variables or secret management tools; reference them via ${ENV_VAR}.
Ignoring Multisite Context	Running commands without --url on a multisite network may affect the wrong site or the network admin.	Always specify --url or use aliases with the url parameter defined.
Blocking Operations	Long-running commands without progress feedback cause timeouts and poor UX.	Implement WP_CLI\Utils\make_progress_bar for operations processing large datasets.
No Dry-Run Validation	Executing destructive commands (e.g., search-replace, delete) without previewing impact.	Always test with --dry-run first; implement dry-run support in custom commands.
Web Request Interference	Custom commands loading heavy dependencies or triggering hooks intended for web requests.	Isolate command logic; avoid loading themes or plugins unless necessary using --skip-plugins.

Production Bundle

Action Checklist

• Guard Context: Ensure all custom commands are wrapped in WP_CLI context checks.
• Define Synopsis: Document arguments and flags in command registration for auto-generated help.
• Implement Dry-Run: Add --dry-run support to all commands that modify data.
• Use Progress Bars: Integrate progress tracking for operations processing more than 100 items.
• Configure Aliases: Set up wp-cli.yml with environment aliases and required command files.
• Backup Strategy: Include database exports in CI/CD pipelines before executing mutations.
• Verify Idempotency: Test deployment commands multiple times to ensure safe re-execution.
• Audit Output: Use WP_CLI::success, ::warning, and ::error for structured, parseable output.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
One-off cleanup	Shell script with WP-CLI calls	Quick execution, no code maintenance required.	Low
Reusable bulk operation	Custom WP-CLI command	Encapsulated logic, validation, progress tracking, distributed via packages.	Medium (Dev time)
Environment sync	CI/CD pipeline integration	Automated, auditable, consistent across environments.	Low (Ops efficiency)
Remote management	SSH aliases in wp-cli.yml	Centralized config, secure, reduces command complexity.	Low
Destructive operation	Custom command with --dry-run	Safety net, preview impact, prevents data loss.	Medium (Safety value)

Configuration Template

# wp-cli.yml
# Global configuration for WP-CLI projects

# Environment Aliases
@local:
  path: ./public
  url: http://localhost:8080

@staging:
  ssh: deployer@staging.example.com/var/www/html
  url: https://staging.example.com

@production:
  ssh: deployer@production.example.com/var/www/html
  url: https://production.example.com

# Auto-load custom commands
require:
  - inc/cli-commands/db-vacuum.php
  - inc/cli-commands/security-audit.php

# Default flags
core:
  download:
    locale: en_US

plugin:
  install:
    force: false
    activate: true

Quick Start Guide

1. Install WP-CLI: Download the Phar file and make it executable. Verify with wp --info.
2. Create Configuration: Add a wp-cli.yml file to your project root with environment aliases and required command paths.
3. Write First Command: Create a PHP file in inc/cli-commands/ with a simple command using WP_CLI::add_command().
4. Test Locally: Run wp db vacuum --dry-run to verify command registration and output.
5. Integrate Pipeline: Add WP-CLI steps to your CI/CD workflow for post-deploy tasks, ensuring backups and verification are included.