Modificare stringhe nel database di Wordpress con WP-CLI

Attenzione: i comandi mostrati in questo articolo possono causare problemi se non usati correttamente. Raccomando la massima prudenza, di provare prima i comandi in un ambiente di test e, in ogni caso, di fare prima un backup del sito. Non mi assumo responsabilità per eventuali danni provocati dalle informazioni riportate.

Dopo l’introduzione del post precedente, passiamo ad uno dei pezzi forti di WP-CLI: il comando search-replace.

Come si può intuire dal nome, serve a cercare tutte le occorrenze di una determinata stringa nel database di WordPress e a sostituirle con un’altra.

Seppure possa sembrare una cosa piuttosto banale, bisogna considerare che alcuni campi contengono dati serializzati. Non possiamo usare una normale query SQL e una eventuale modifica manuale, oltre che piuttosto scomoda, rischia di compromettere il funzionamento dell’intero sito. WP-CLI è in grado di identificare le informazioni serializzate e trattarle correttamente.

Sintassi di base

Nella sua forma più semplice, la sintassi del comando è questa:

wp search-replace <old-string> <new-string>

In sostanza bisogna indicare la stringa da cercare (old-string) e quella con cui sostituirla (new-string).

Per sicurezza, consiglio di racchiudere le due stringhe tra apici, anche se non contengono spazi.

Al termine dell’esecuzione, il comando mostra una lista delle tabelle analizzate, il numero di sostituzioni per ogni tabella/campo e le sostituzioni totali. Nell’esempio un frammento di output:

+-------------------+-----------------------+--------------+------+
| Table             | Column                | Replacements | Type |
+-------------------+-----------------------+--------------+------+
| voc_commentmeta   | meta_key              | 0            | SQL  |
| voc_commentmeta   | meta_value            | 0            | SQL  |
| voc_comments      | comment_author        | 0            | SQL  |
| voc_comments      | comment_author_email  | 0            | SQL  |


| voc_users         | user_email            | 1            | SQL  |
| voc_users         | user_url              | 0            | SQL  |
| voc_users         | user_activation_key   | 0            | SQL  |
| voc_users         | display_name          | 0            | SQL  |
+-------------------+-----------------------+--------------+------+
Success: Made 27 replacements.

Opzioni

Questo comando ha molte opzioni. Per una lista completa ti rimando alla documentazione ufficiale. Qui di seguito ti mostro quelle che uso più spesso.

wp search-replace <old-string> <new-string> --dry-run

Questa è importantissima e andrebbe tatuata sul dorso di una mano per vederla mentre digitiamo sulla tastiera. Consente di eseguire una “simulazione” del comando, quindi di avere un’anteprima del risultato effettivo. La utilizzo sempre per testare la prima esecuzione di una sostituzione. Se il risultato previsto non mi sembra corretto, posso modificare il comando e riprovare.

Inoltre, consente di effettuare una semplice ricerca per sapere se una stringa è presente nel database. In questo caso il valore di new-string è indifferente (può anche essere nullo).

Ribadisco: fondamentale.

wp search-replace <old-string> <new-string> --all-tables-with-prefix

Il comando search-replace cerca di default in tutte le tabelle registrate nell’oggetto $wpdb, quello che fornisce i metodi di accesso al database (documentazione). Con questa opzione la ricerca viene estesa anche alle tabelle non registrate ma che hanno il table prefix configurato nel sito. Utile nel caso in cui vi accorgiate che la ricerca ignora ad esempio le tabelle di qualche plugin.

wp search-replace <old-string> <new-string> --all-tables

Simile alla precedente nell’intento di allargare il raggio d’azione, in questo caso estende la ricerca a tutte le tabelle del database, senza alcuna distinzione. Può essere utile in presenza di tabelle utilizzate da codice custom e che non riportano il table prefix nel nome.

wp search-replace <old-string> <new-string> --verbose

Mostra l’attività svolta in modo più dettagliato. Può essere utile abbinarla a --dry-run per avere un quadro più approfondito del risultato finale.

Casi d’uso

Ho usato il comando search-replace soprattutto in due situazioni.

Migrazione di un sito WordPress da un dominio ad un altro: ad esempio il cassico stage -> production. In questo caso, se non si ha la possibilità di usare un plugin dedicato allo scopo, si riesce rapidamente a modificare tutte le occorrenze dell’indirizzo del sito.

Modifica del table prefix: se si ha necessità di cambiare questo parametro, non si può fare a meno di questo comando.

Hai usato search-replace in altre situazioni? Fammelo sapere nei commenti.