WordPress stocke des URL absolues dans des dizaines de tables de la base de données : un changement de domaine ou un passage au SSL laisse donc d'anciennes adresses éparpillées dans les articles, les options et les réglages des extensions. Un rechercher-remplacer est le moyen de les nettoyer en toute sécurité. Ce guide présente les deux méthodes prises en charge pour le faire dans KPanel, explique pourquoi une troisième méthode courante corrompt les données, et indique comment vérifier le résultat.
Quand vous en avez besoin
- Pour passer de
http://àhttps://après l'activation du SSL. - Pour changer de domaine, par exemple de
old-brand.co.nzànew-brand.co.nz. - Après avoir poussé la préproduction en production, lorsque le nom d'hôte de préproduction est encore inscrit dans la base de données.
- Pour retirer un ancien hôte de ressources et rediriger toutes les URL d'images en une seule fois.
- Pour corriger en masse une faute de frappe dans de nombreux articles, comme un ancien numéro de téléphone ou le nom d'un produit abandonné.
Un rechercher-remplacer réécrit des lignes dans toutes les tables à la fois, et il n'existe aucune annulation ligne par ligne. Effectuez une sauvegarde avant de commencer, à chaque fois, même pour une modification qui semble anodine. KPanel en crée une automatiquement lorsque vous utilisez les outils intégrés décrits ci-dessous, mais si vous exécutez la commande vous-même, cette sauvegarde est de votre responsabilité. Consultez Effectuer une sauvegarde.
Pourquoi vous ne pouvez pas simplement exécuter un REPLACE SQL
C'est l'erreur la plus destructrice qui soit lorsqu'on travaille sur une base de données WordPress : il vaut donc la peine de la comprendre avant de choisir une méthode.
WordPress stocke les réglages des extensions, les options des thèmes et les données des widgets sous forme de chaînes PHP sérialisées. Une chaîne sérialisée enregistre la longueur de chaque valeur qu'elle contient, comme ceci :
a:1:{s:3:"url";s:26:"http://old-domain.co.nz/x";}
Ce s:26 indique que l'URL compte 26 caractères. Remplacez http:// par https:// avec un simple REPLACE() SQL et le texte passe à 27 caractères, alors que la longueur stockée indique toujours 26. PHP refuse alors de désérialiser l'option entière, et le réglage redevient vide sans le moindre message. Les réglages de personnalisation du thème disparaissent, les diaporamas perdent leurs diapositives, les licences d'extensions se désenregistrent d'elles-mêmes.
Le search-replace de WP-CLI qu'exécute KPanel désérialise chaque valeur, effectue le remplacement à l'intérieur, puis la resérialise avec les longueurs corrigées. C'est pourquoi c'est la seule méthode documentée ici.
N'exécutez jamais UPDATE wp_options SET option_value = REPLACE(...) ni son équivalent dans phpMyAdmin sur une base de données WordPress. Tout semble avoir fonctionné, le nombre de lignes affectées s'affiche, et pourtant chaque réglage sérialisé touché est détruit sans bruit. Il n'existe aucune réparation possible, à part la restauration d'une sauvegarde.
Méthode 1 : la carte Rechercher et remplacer
C'est le bon choix pour presque tout le monde. Elle est disponible avec toutes les offres WordPress.
- Connectez-vous à KPanel et cliquez sur Sites web dans la barre latérale gauche.
- Cliquez sur le site.
- Ouvrez l'onglet WordPress, puis la section Actions rapides.
- Repérez la carte Rechercher et remplacer et cliquez sur Configurer.
- Saisissez le texte existant dans Rechercher (ancienne valeur).
- Saisissez le nouveau texte dans Remplacer par.
- Laissez Simulation (aperçu uniquement, aucune modification) cochée et cliquez sur Aperçu.
La simulation indique combien de remplacements seraient effectués et détaille ce nombre par table et par colonne, afin que vous puissiez voir exactement où la modification s'appliquerait avant de la valider.
Lorsque l'aperçu vous semble correct :
- Décochez Simulation.
- Cliquez sur Exécuter.
- Confirmez la boîte de dialogue.
Une sauvegarde complète est effectuée automatiquement avant le début du remplacement, et l'opération couvre toutes les tables, y compris celles créées par les extensions.
Recherchez la chaîne la plus précise possible. Remplacer old-domain.co.nz réécrit aussi mail.old-domain.co.nz et staging.old-domain.co.nz, ce qui est rarement ce que vous souhaitez. Inclure le schéma, comme dans https://old-domain.co.nz, permet de garder une correspondance stricte.
Méthode 2 : WP-CLI depuis la console
La console vous offre le même moteur avec davantage de contrôle sur les options. C'est l'une des sections qui apparaissent avec les offres gérées ; avec les autres offres, la barre d'onglets affiche à la place un lien +8 sur Managed.
Ouvrez le site, puis WordPress, puis Console. L'invite commence déjà par wp : saisissez donc uniquement le reste de la commande.
Commencez par un aperçu :
search-replace 'http://old-domain.co.nz' 'https://old-domain.co.nz' --all-tables --dry-run
Puis exécutez-la pour de bon :
search-replace 'http://old-domain.co.nz' 'https://old-domain.co.nz' --all-tables
La console n'effectue pas de sauvegarde à votre place. La sauvegarde automatique préalable n'a lieu que lorsque vous utilisez la carte Rechercher et remplacer de la méthode 1. Si vous exécutez la commande ici, effectuez d'abord vous-même une sauvegarde depuis la page Sauvegardes du site.
Options utiles :
| Option | Ce qu'elle fait |
|---|---|
--all-tables | Inclut les tables personnalisées créées par les extensions, et pas seulement les tables principales de WordPress |
--dry-run | Indique ce qui changerait sans rien écrire |
--precise | Utilise PHP plutôt que SQL pour le remplacement. Plus lent, mais gère les structures sérialisées délicates |
--skip-columns=guid | Laisse intacts les GUID des articles (voir ci-dessous) |
--report-changed-only | Limite la sortie aux tables qui ont réellement changé |
Remarque sur les GUID
Chaque article WordPress possède une colonne guid. Bien qu'elle ressemble à une URL, il s'agit d'un identifiant et non d'un lien, et les lecteurs de flux l'utilisent pour savoir s'ils ont déjà vu un élément. La réécrire peut faire réapparaître chaque article de votre flux comme s'il était nouveau.
Réécrivez les GUID lorsque vous changez définitivement de domaine et repartez de zéro. Ignorez-les avec --skip-columns=guid lorsque vous passez seulement de HTTP à HTTPS sur le même domaine.
Changer de domaine : utilisez plutôt la carte URL du site
Si le seul objectif est de déplacer le site vers un nouveau domaine, ne commencez pas par un rechercher-remplacer. La carte Modifier l'URL du site, dans la même section Actions rapides, met à jour les options siteurl et home et effectue le remplacement dans toutes les tables en une seule opération, dans le bon ordre. Procéder dans l'autre sens peut empêcher WordPress de charger sa propre administration.
Après le remplacement
Parcourez cette liste avant de considérer le travail comme terminé.
- Videz le cache. Dans la section Actions rapides, lancez Vider le cache. Si le site utilise le cache de pages complet, purgez-le depuis WordPress, puis Mise en cache.
- Videz les règles de réécriture. Lancez Vider les réécritures dans la même section, ou ouvrez Réglages, puis Permaliens dans wp-admin et cliquez sur Enregistrer les modifications sans rien changer.
- Purgez le CDN si le site l'utilise, depuis Performances, puis Kapsule CDN. Consultez Vider le cache de Kapsule CDN.
- Chargez le site dans une fenêtre de navigation privée afin que le cache de votre navigateur ne puisse pas vous induire en erreur.
- Vérifiez le cadenas. Un cadenas absent ou accompagné d'un avertissement après un passage au SSL signifie que des URL ont été oubliées : Corriger les avertissements de contenu mixte.
- Parcourez les pages délicates. Les diaporamas de la page d'accueil, le logo de l'en-tête, toute page créée avec un constructeur de pages, et le paiement sur une boutique. Ce sont elles qui contiennent les URL stockées dans les options sérialisées.
- Videz le cache de toute extension de mise en cache depuis son propre écran de réglages.
Dépannage
La simulation indique zéro remplacement. La chaîne ne figure pas sous cette forme exacte dans la base de données. Vérifiez la présence d'une barre oblique finale, d'un préfixe www. ou du schéma. Essayez d'abord de rechercher uniquement le nom d'hôte seul pour confirmer qu'il est bien présent.
Les images sont cassées après un changement de domaine. Les URL des médias se trouvent dans wp_posts et wp_postmeta et sont prises en compte par --all-tables, mais un CDN ou une extension d'optimisation d'images peut mettre en cache ses propres copies réécrites. Purgez le CDN et le cache de l'extension, puis rechargez la page.
Des réglages ont disparu après le remplacement. C'est le problème de sérialisation, et cela signifie que la modification a été effectuée en SQL brut plutôt qu'avec les outils présentés ici. Restaurez la sauvegarde effectuée avant l'opération : Restaurer à partir d'une sauvegarde.
Les URL de préproduction reviennent sans cesse. Quelque chose les réintroduit, généralement un envoi planifié ou une option en cache. Vérifiez le flux de travail dans Utiliser la préproduction : pousser et récupérer et assurez-vous que Réécrire les URL est cochée lorsque vous poussez.