unserialize()

Einführung

Die Funktion unserialize() ist eine eingebaute PHP-Funktion, die einen von serialize() erzeugten String zurück in den ursprünglichen PHP-Wert umwandelt – ein Array, Objekt, string, eine Zahl oder einen boolean.

Serialisierung ist der Mechanismus, mit dem PHP einen Wert im Arbeitsspeicher in einen flachen, speicherbaren String umwandelt. Typischerweise wird ein Wert mit serialize() gespeichert – in eine Datei, eine Datenbankspalte oder einen Cache – und später mit unserialize() wieder als lebendiger Wert zurückgeholt. Diese Seite behandelt die Syntax, funktionierende Beispiele, die sichere Wiederherstellung von Objekten, die Fehlerbehandlung und einen wichtigen Sicherheitshinweis bei nicht vertrauenswürdigen Eingaben.

Syntax

mixed unserialize(string $data, array $options = [])

Rückgabewert: der wiederhergestellte PHP-Wert. Bei einem Fehler wird false zurückgegeben und (seit PHP 8.0) eine E_WARNING ausgelöst. Da ein gültiges serialisiertes false dem String "b:0;" entspricht, ist der Vergleich mit diesem String die einzige zuverlässige Methode, ein echtes false von einem Fehler zu unterscheiden.

Beispiel: ein Array wiederherstellen

Der folgende serialisierte String beschreibt ein Array mit drei Strings. unserialize() stellt es wieder her, und print_r() zeigt das Ergebnis an.

Ausgabe:

Array
(
    [0] => apple
    [1] => banana
    [2] => cherry
)

Das serialisierte Format verstehen

Jedes Token im String ist ein Typ-Tag: a:3 steht für ein Array mit 3 Paaren, i:0 ist der Integer-Schlüssel 0, und s:5:"apple" ist ein 5-Byte-String. Dieses Format wird selten von Hand geschrieben – serialize() erzeugt es –, aber die Kenntnis der Struktur hilft beim Debuggen beschädigter Daten.

Hin- und Rückumwandlung mit serialize()

In der Praxis wird beim Speichern serialisiert und beim Lesen deserialisiert. Der wiederhergestellte Wert ist identisch mit dem ursprünglichen:

<?php
$user = ['name' => 'Ada', 'roles' => ['admin', 'editor']];

$stored  = serialize($user);          // save this string somewhere
$restored = unserialize($stored);     // read it back later

var_dump($restored === $user);
?>

Ausgabe:

bool(true)

Objekte wiederherstellen

unserialize() kann nicht nur Arrays, sondern auch Objekte wiederherstellen. Die Klasse muss zum Zeitpunkt der Deserialisierung geladen (oder per Autoloading verfügbar) sein; andernfalls erstellt PHP einen __PHP_Incomplete_Class-Platzhalter, der nicht verwendet werden kann.

<?php
class Point {
    public function __construct(public int $x, public int $y) {}
}

$data    = serialize(new Point(3, 4));
$point   = unserialize($data);

echo $point->x + $point->y;
?>

Ausgabe:

7

Objekte sicher wiederherstellen

Das Deserialisieren von Daten, die ein Angreifer kontrolliert, ist gefährlich: Es können beliebige Klassen instanziiert und ihre magischen Methoden __wakeup() oder __destruct() ausgelöst werden (ein „PHP Object Injection"-Angriff). Das Schlüssel-Argument allowed_classes im $options-Parameter schränkt ein, welche Klassen erstellt werden dürfen:

<?php
// Refuse all objects — any object becomes __PHP_Incomplete_Class
$safe = unserialize($input, ['allowed_classes' => false]);

// Allow only specific classes
$safe = unserialize($input, ['allowed_classes' => [Point::class]]);
?>

Faustregel: Rufe unserialize() niemals auf benutzerseitig gelieferten Eingaben ohne allowed_classes auf. Wenn nur einfache Daten mit nicht vertrauenswürdigen Quellen ausgetauscht werden sollen, ist json_decode() vorzuziehen, da es keine PHP-Objekte instanziieren kann.

Fehlerbehandlung

Wenn der String fehlerhaft ist, gibt unserialize() false zurück und gibt eine Warnung aus. Prüfe den Rückgabewert, bevor du ihn verwendest:

<?php
$result = unserialize('not-valid-data');

if ($result === false) {
    echo "Could not unserialize the data";
} else {
    print_r($result);
}
?>

Ausgabe:

Could not unserialize the data

Da ein tatsächlich gespeichertes false zu "b:0;" serialisiert wird, muss bei false als legitimem Wert entsprechend geprüft werden:

<?php
$data   = serialize(false);   // "b:0;"
$result = unserialize($data);

if ($result === false && $data !== 'b:0;') {
    echo "Failure";
} else {
    echo "Restored a real false value";
}
?>

Ausgabe:

Restored a real false value

Fazit

unserialize() kehrt serialize() um und wandelt einen gespeicherten String zurück in einen lebendigen PHP-Wert wie ein Array oder Objekt. Zwei Dinge sind dabei zu beachten: den Rückgabewert prüfen (Vergleich mit "b:0;", um ein echtes false von einem Fehler zu unterscheiden) und stets allowed_classes übergeben – oder auf json_decode() wechseln –, wenn die Eingabe nicht vollständig vertrauenswürdig ist.

Übungen