Rinominare uno Shortcode via Codice

Capita cambiare idea. Ma quando per qualche ragione cambiamo idea sul nome di uno shortcode diventato quasi onnipresente tra i nostri Articoli, Pagine e Post Personalizzati, l'unico modo ragionevole di rinominarne tutte le occorrenze è programmaticamente — sviluppare script a cui delegare tutto il lavoro ripetitivo è un'abitudine che, credimi, ripaga a lungo termine.

Il frammento di codice che segue è una generalizzazione di uno script più semplice che ho sviluppato per la migrazione dei dati da SiteTree a The Permalinks Cascade, sostanzialmente è un'implementazione dell'operazione 'ricerca e sostituisci' iterata su tutti i post che presentano una traccia dello shortcode da rinominare. Il più della magia è condensata nelle espressioni regolari, usate per individuare le occorrenze dello shortcode che non includano una sequenza di escape, ovvero doppie parentesi quadre. Per fare ciò, le due regex usano un lookaround negativo, un'asserzione di larghezza zero di cui puoi apprendere tutto sul sito Regular-Expressions.info.

$old_shortcode_name = 'my-shortcode';
$new_shortcode_name = 'my-new-shortcode';

// Facciamo una prima cernita dei post usando la funzionalità
// di ricerca integrata nella classe WP_Query, così da
// recuperare dal database solo i post che potrebbero contenere
// lo shortcode da rinominare.
$arguments = array(
    'posts_per_page' => -1,
    'post_type'      => 'any',
    's'              => "[{$old_shortcode_name}"
);

$query = new WP_Query( $arguments );

// Il look-behind e look-ahead negativi nelle espressioni 
// regolari assicurano che gli shortcode inclusivi della 
// sequenza di escade (doppie parentesi quadre) vengano scartati.
// Inoltre, il gruppo di acquisizione nella prima regex viene
// usato per catturare la lista di attributi che potrebbero
// essere inclusi nello shortcode.
$patterns = array(
    "#(?<!\[)\[{$old_shortcode_name}( [^\]]+)?\]#",
    "#\[/{$old_shortcode_name}\](?!\])#"
);

// La variabile '$1' verrà sostituita con una stringa vuota
// oppure con la lista di attributi inclusa nello shortcode.
$replacements = array(
    "[{$new_shortcode_name}\$1]",
    "[/{$new_shortcode_name}]"
);

while ( $query->have_posts() ) {
    $query->the_post();

    $the_content = get_the_content();

    // Se $the_content non contiene occorrenze dello shortcode 
    // prive della sequenza di escape, passiamo semplicemente ad
    // analizzare il post successivo.
    if (! preg_match( $patterns[0], $the_content ) ) {
        continue;
    }
    
    // Richiediamo il post corrente in forma di array associativo.
    $the_post = get_post( null, ARRAY_A );

    if (! $the_post ) {
        continue;
    }

    $the_post['post_content'] = preg_replace( $patterns,
                                              $replacements,
                                              $the_content );

    // Lasciamo che WordPress aggiorni automaticamente la data di
    // modifica del post.
    unset( $the_post['post_modified'], $the_post['post_modified_gmt'] );

    // L'ultimo parametro impedisce che WordPress esegua
    // gli hook di "after-insert".
    wp_update_post( $the_post, false, false );
}

// Obbligatorio quando si creano loop secondari con WP_Query.
wp_reset_postdata();

Il Caso Limite

La presenza di shortcode nidificati in uno o più dei tuoi post non è certamente un'improbabilità tale da doverla etichettare come caso limite, ma uno shortcode con sequenza di escape che racchiuda proprio un'occorrenza dello shortcode da rinominare è senza dubbio un caso limite. Quindi, se da qualche parte nel tuo sito hai scritto qualcosa del genere...

[[my-outer-shortcode]
    [my-shortcode arg="value"]
[/my-outer-shortcode]]

...sarebbe meglio escludere preventivamente dalla query i post contenenti pseudo-codice di questo tipo. Devi giusto passare al costruttore di WP_Query una lista di ID quale valore dell'argomento post__not_in.

Eseguire il Codice: Dove e Quando

Considerato un contesto generico, puoi semplicemente mettere il codice nel file functions.php del tema attivo, e cancellarlo una volta che lo shortcode sia stato rinominato. Come precauzione però, ti suggerisco di lasciare che WordPress lo esegua in corrispondenza dell'hook init, in questo modo:

function rename_my_shortcode() {
    // Lo snippet va qui.
}
add_action( 'init', 'rename_my_shortcode' );

Eseguire il Codice: Una Nota Finale

Eseguire lo snippet una sola volta è più che sufficiente, però, nell'eventualità in cui lasci lo snippet in esecuzione più volte, non devi preoccuparti, perché le istruzioni condizionali di cui è provvisto agiranno da deterrente a risultati inattesi.