Serialisierte Plugin-Daten beim Domainwechsel korrigieren

Ein Domainwechsel kann Bild-URLs in Plugin-Daten zurücklassen, obwohl home, siteurl und wp search-replace bereits aktualisiert wurden. Ein WP-CLI-Skript dekodiert die gespeicherten Werte, ersetzt die Domain und speichert die Datenstruktur wieder korrekt in WordPress.

3 Min. von Erhard Sigrist

Nach einem Domainwechsel waren home und siteurl korrekt gesetzt, und wp search-replace hatte die üblichen URLs erfolgreich ersetzt. Eine Fotogalerie verwendete dennoch weiterhin Bild-URLs der früheren Domain.

Die Ursache lag in der Datenstruktur von Responsive Photo Gallery Pro. Das Plugin speichert die Bildinformationen in einem Base64-kodierten Postmeta-Wert. Für die Korrektur haben wir diesen Wert mit WP-CLI dekodiert, die enthaltenen URLs ersetzt und die Daten anschliessend wieder über die WordPress-API gespeichert.

Bild-URLs im Postmeta-Feld finden

Die betroffene Galerie wird über folgenden Shortcode eingebunden:

[RPG id=1224]

Responsive Photo Gallery Pro speichert die Bildinformationen im Postmeta-Feld rpgp_all_photos_details. Der Wert enthält mehrere Ebenen:

  1. einen Base64-kodierten String,
  2. darin ein serialisiertes PHP-Array,
  3. darin die absoluten URLs der Galeriebilder.

Ein gekürzter Wert sieht beispielsweise so aus:

YToyOntpOjA7YToyOntzOjE0OiJycGdwX2ltYWdlX3VybCI7czo2MToiaHR0cHM6Ly9jYW1pbm8u...

Die Datenbank enthält an dieser Stelle einen kodierten Wert. Die Bild-URL liegt darin nicht als Klartext vor und wird deshalb von einem gewöhnlichen Such- und Ersetzungsvorgang nicht erreicht.

Weshalb wp search-replace die URLs hier nicht verarbeitet

wp search-replace verarbeitet normale serialisierte PHP-Daten und erhält dabei ihre Struktur. Die WP-CLI-Dokumentation zu wp search-replace beschreibt diesen Ablauf.

Die zusätzliche Base64-Kodierung umschliesst die serialisierten Daten jedoch als Zeichenfolge. Die enthaltenen URLs werden dadurch erst nach dem Dekodieren zugänglich.

Serialisierte PHP-Arrays enthalten Längenangaben für ihre Zeichenketten. Die Verarbeitung über unserialize() und serialize() berechnet diese Angaben passend zur neuen URL. update_post_meta() speichert den neu erzeugten Wert wieder im zugehörigen Postmeta-Feld.

Der Postmeta-Wert wird dekodiert, die Domain in den Bild-URLs ersetzt und die Plugin-Daten werden wieder strukturgerecht gespeichert.
Der Postmeta-Wert wird dekodiert, die Domain in den Bild-URLs ersetzt und die Plugin-Daten werden wieder strukturgerecht gespeichert.

Kodierte Plugin-Daten mit WP-CLI verarbeiten

Vor der Ausführung wird ein Datenbank-Backup erstellt. Das Skript verarbeitet anschliessend alle betroffenen Postmeta-Einträge in derselben Reihenfolge:

  1. Postmeta-Einträge auslesen,
  2. Base64-Inhalt dekodieren,
  3. PHP-Array unserialisieren,
  4. Domain in allen enthaltenen Zeichenketten ersetzen,
  5. Array erneut serialisieren und Base64-kodieren,
  6. Wert über update_post_meta() speichern.
wp eval 'global $wpdb;

$from = "https://domain.ulrich.digital";
$to   = "https://domain.ch";
$key  = "rpgp_all_photos_details";

$metas = $wpdb->get_results(
    $wpdb->prepare(
        "SELECT post_id, meta_value
        FROM {$wpdb->postmeta}
        WHERE meta_key = %s",
        $key
    )
);

$checked = 0;
$updated = 0;

foreach ($metas as $row) {
    $checked++;

    $decoded = base64_decode($row->meta_value, true);

    if ($decoded === false) {
        continue;
    }

    $data = @unserialize($decoded, ["allowed_classes" => false]);

    if ($data === false && $decoded !== "b:0;") {
        continue;
    }

    $changed = false;

    $replace = function (&$value) use (&$replace, $from, $to, &$changed) {
        if (is_array($value)) {
            foreach ($value as &$item) {
                $replace($item);
            }

            return;
        }

        if (is_string($value) && str_contains($value, $from)) {
            $value   = str_replace($from, $to, $value);
            $changed = true;
        }
    };

    $replace($data);

    if ($changed) {
        $value = base64_encode(serialize($data));
        update_post_meta((int) $row->post_id, $key, $value);
        $updated++;
    }
}

echo "Checked: {$checked}\n";
echo "Updated: {$updated}\n";'

In diesem Fall prüfte das Skript 20 Einträge und aktualisierte 19 davon:

Checked: 20
Updated: 19

Domainwechsel mit WP-CLI vorbereiten

Für normale serialisierte Daten eignet sich wp search-replace. Plugin-Daten mit zusätzlicher Kodierung oder einer eigenen Datenstruktur werden anschliessend separat geprüft und verarbeitet.

Ein strukturierter Ablauf verbindet die einzelnen Schritte:

  1. Datenbank sichern.
  2. wp search-replace zuerst mit --dry-run ausführen.
  3. Verbliebene frühere URLs mit wp db search suchen.
  4. Auffällige Plugin-Daten auf ihre Speicherstruktur prüfen.
  5. Kodierte Werte mit WP-CLI und der WordPress-API aktualisieren.
  6. Frontend und Mediendateien kontrollieren.

Ergebnis

Bild-URLs in kodierten Plugin-Daten korrigieren

Die Bild-URLs der Galerie bleiben auch bei zusätzlicher Base64-Kodierung zugänglich. WP-CLI und die WordPress-API verarbeiten die gespeicherte Struktur nachvollziehbar und übertragen die neue Domain in alle enthaltenen Bildpfade.

Datenstruktur verstehen

Die Galerie speichert Bild-URLs als Base64-kodierten String mit einem serialisierten PHP-Array im Postmeta-Feld.

URLs sicher ersetzen

Das WP-CLI-Skript dekodiert den Wert, ersetzt die Domain in allen Zeichenketten und speichert das Array über die WordPress-API.

Domainwechsel prüfen

Backup, Dry Run und die Prüfung verbliebener URLs strukturieren den Ablauf. Ein Frontend-Test bestätigt die aktualisierten Bildpfade.