Créer ses propres commandes WP-CLI pour automatiser les tâches récurrentes

Passé un certain nombre de scripts de maintenance — nettoyage de transients, réindexation d’un moteur de recherche interne, régénération de miniatures pour certaines catégories seulement — on finit toujours par vouloir les rendre accessibles comme de vraies commandes WP-CLI, avec leur propre aide, leurs propres arguments et leur propre validation. C’est exactement ce que permet l’extension de WP-CLI via WP_CLI_Command.

Voici comment on structure nos commandes personnalisées, du script isolé jusqu’au petit plugin de commandes réutilisable d’un projet à l’autre.

La structure minimale d’une commande

Une commande WP-CLI personnalisée est une classe PHP qui étend WP_CLI_Command, enregistrée via WP_CLI::add_command(). On la place généralement dans un mu-plugin ou dans un plugin dédié, chargé uniquement dans le contexte WP-CLI :

<?php
/**
 * Plugin Name: Commandes maison
 */

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

class Agence_Maintenance_Command extends WP_CLI_Command {

    /**
     * Nettoie les transients expirés et les révisions anciennes.
     *
     * ## OPTIONS
     *
     * [--dry-run]
     * : N'affiche que ce qui serait supprimé, sans rien exécuter.
     *
     * ## EXAMPLES
     *
     *     wp agence nettoyer --dry-run
     *
     * @when after_wp_load
     */
    public function nettoyer( $args, $assoc_args ) {
        $dry_run = WP_CLI\Utils\get_flag_value( $assoc_args, 'dry-run', false );

        $revisions = get_posts( [
            'post_type'      => 'revision',
            'posts_per_page' => -1,
            'fields'         => 'ids',
        ] );

        WP_CLI::log( sprintf( '%d révisions trouvées.', count( $revisions ) ) );

        if ( $dry_run ) {
            WP_CLI::success( 'Simulation terminée, aucune suppression effectuée.' );
            return;
        }

        foreach ( $revisions as $id ) {
            wp_delete_post_revision( $id );
        }

        WP_CLI::success( sprintf( '%d révisions supprimées.', count( $revisions ) ) );
    }
}

WP_CLI::add_command( 'agence', 'Agence_Maintenance_Command' );

Cette commande devient alors utilisable exactement comme n’importe quelle commande native : wp agence nettoyer --dry-run. Le bloc de documentation en commentaire n’est pas décoratif : WP-CLI l’utilise pour générer l’aide accessible via wp agence nettoyer --help.

Les bonnes pratiques qu’on applique systématiquement

• Toujours proposer une option --dry-run sur les commandes qui modifient des données, sans exception
• Utiliser WP_CLI::log(), WP_CLI::success() et WP_CLI::error() plutôt que echo, pour un affichage cohérent avec le reste de WP-CLI
• Ajouter @when after_wp_load quand la commande a besoin que WordPress soit entièrement chargé, notamment pour utiliser les fonctions du cœur
• Utiliser WP_CLI\Utils\make_progress_bar() pour les opérations longues sur de gros volumes de contenu

Un exemple avec barre de progression

public function regenerer_miniatures( $args, $assoc_args ) {
    $categorie = WP_CLI\Utils\get_flag_value( $assoc_args, 'categorie', '' );

    $query = new WP_Query( [
        'post_type'      => 'post',
        'category_name'  => $categorie,
        'posts_per_page' => -1,
    ] );

    $progress = WP_CLI\Utils\make_progress_bar( 'Régénération', $query->post_count );

    foreach ( $query->posts as $post ) {
        $thumbnail_id = get_post_thumbnail_id( $post->ID );
        if ( $thumbnail_id ) {
            wp_update_attachment_metadata(
                $thumbnail_id,
                wp_generate_attachment_metadata( $thumbnail_id, get_attached_file( $thumbnail_id ) )
            );
        }
        $progress->tick();
    }

    $progress->finish();
    WP_CLI::success( 'Miniatures régénérées.' );
}

Aller plus loin : un package WP-CLI distribuable

Pour des commandes réutilisées sur plusieurs projets, on préfère les distribuer comme un package Composer indépendant plutôt que de les dupliquer dans chaque mu-plugin. La commande wp scaffold package génère la structure de base :

wp scaffold package agence/wp-cli-maintenance --require=wp-cli/wp-cli:^2
composer config repositories.wp-cli-maintenance vcs https://github.com/agence/wp-cli-maintenance
composer require agence/wp-cli-maintenance

Cette approche a un avantage concret : on met à jour la commande une seule fois, dans son propre dépôt, et tous les projets qui la consomment en bénéficient à la prochaine mise à jour Composer.

Une commande WP-CLI personnalisée bien pensée finit toujours par remplacer un script bash fragile plein de ssh et de grep. Le gain n’est pas seulement esthétique : elle bénéficie de la validation d’arguments, de l’aide intégrée et d’un comportement cohérent avec le reste de l’écosystème.

En résumé

Dès qu’un script de maintenance revient plus de deux ou trois fois, ça vaut le coup de l’encapsuler dans une vraie commande WP-CLI. C’est peu de code supplémentaire — une classe, une méthode, un enregistrement — pour un gain réel en fiabilité, en documentation et en réutilisabilité entre projets.