htmlspecialchars()

Die Funktion htmlspecialchars() wandelt die wenigen Zeichen, die in HTML eine besondere Bedeutung haben, in ihre entsprechenden HTML-Entitäten um. Ihre Hauptaufgabe ist die Sicherheit: Wenn Sie vom Benutzer stammende Daten in eine Webseite ausgeben, verhindert die vorherige Übergabe durch htmlspecialchars(), dass diese Daten als Markup oder Script interpretiert werden — die Standard-Abwehr gegen Cross-Site-Scripting (XSS)-Angriffe.

Diese Seite behandelt die Syntax der Funktion, jeden ihrer Parameter mit ausführbaren Beispielen, die fünf betroffenen Zeichen, wie sie sich von verwandten Funktionen unterscheidet und wie man sie sicher umkehrt.

Syntax

htmlspecialchars(
    string $string,
    int $flags = ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401,
    ?string $encoding = null,
    bool $double_encode = true
): string

Die Funktion nimmt einen erforderlichen Parameter entgegen, $string — den umzuwandelnden String — und drei optionale Parameter: $flags, $encoding und $double_encode. Sie gibt den umgewandelten String zurück.

Hinweis zum Standard-Flag. Ab PHP 8.1 ist der Standardwert von $flags gleich ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401, was sowohl einfache als auch doppelte Anführungszeichen kodiert. In PHP 8.0 und früher war der Standard ENT_COMPAT, der einfache Anführungszeichen unberührt ließ. Wenn Sie ältere Versionen unterstützen, übergeben Sie immer explizit ENT_QUOTES, damit das Verhalten vorhersehbar ist.

Welche Zeichen werden umgewandelt

Nur fünf Zeichen sind betroffen. Alles andere wird unverändert durchgereicht:

Wenn Sie auch Buchstaben mit Akzenten, Symbole und andere Nicht-ASCII-Zeichen kodieren müssen, verwenden Sie stattdessen htmlentities().

Einfaches Beispiel

Ausgabe:

Hello <strong>World</strong>!

Die <strong>-Tags wurden in <strong> und </strong> umgewandelt. Wenn dieser String an einen Browser gesendet wird, zeigt er nun den Literaltext <strong>World</strong> an, anstatt fettes Markup darzustellen.

Der $flags-Parameter: Umgang mit Anführungszeichen

Der zweite Parameter, $flags, legt fest, wie Anführungszeichen behandelt und welcher Dokumenttyp verwendet werden soll. Die häufigste Wahl ist ENT_QUOTES, das sowohl einfache (') als auch doppelte (") Anführungszeichen umwandelt. Das ist wichtig, wenn Sie einen Wert in einem HTML-Attribut platzieren, da ein nicht maskiertes Anführungszeichen das Attribut vorzeitig schließen und neue einfügen könnte.

Ausgabe:

I'm a paragraph

Das einfache Anführungszeichen wurde in ' umgewandelt. Die gängigen Flag-Werte sind:

• ENT_QUOTES — wandelt sowohl doppelte als auch einfache Anführungszeichen um (empfohlen).
• ENT_COMPAT — wandelt doppelte Anführungszeichen um, lässt einfache unberührt.
• ENT_NOQUOTES — lässt beide Arten von Anführungszeichen unverändert.
• ENT_SUBSTITUTE — ersetzt ungültige Code-Unit-Sequenzen durch � anstatt einen leeren String zurückzugeben.

Der $encoding-Parameter

Der dritte Parameter, $encoding, gibt die Zeichenkodierung des Eingabe-Strings an. Er verwendet standardmäßig den Wert der INI-Einstellung default_charset (UTF-8 bei modernen Installationen). Das explizite Setzen vermeidet Überraschungen, wenn Ihre Eingabe eine andere Kodierung hat.

Ausgabe:

Tom & Jerry

Hier wird das kaufmännische Und als & kodiert, während PHP die Eingabe als UTF-8 interpretiert. Wenn die Kodierung nicht mit den tatsächlichen Bytes von $string übereinstimmt, kann die Funktion einen leeren String zurückgeben (oder ein Ersatzzeichen, wenn ENT_SUBSTITUTE gesetzt ist).

Der $double_encode-Parameter

Der vierte Parameter, $double_encode, steuert, ob bereits vorhandene Entitäten erneut kodiert werden. Standardmäßig ist er true, sodass ein String, der bereits < enthält, zu < wird. Setzen Sie ihn auf false, um bereits kodierte Entitäten unberührt zu lassen — nützlich, wenn die Eingabe bereits teilweise maskiert wurde.

Ausgabe:

Hello <strong>World</strong>!

Die vorhandenen <- und >-Entitäten bleiben unverändert, da $double_encode den Wert false hat. Mit dem Standard true hätte dieselbe Eingabe Hello <strong>... ergeben.

XSS in der Praxis verhindern

Die wichtigste Verwendung von htmlspecialchars() ist das Maskieren von Daten, die Sie nicht vollständig kontrollieren — Formulareingaben, Query-String-Werte, Datenbankeinträge, die von Benutzern stammen — bevor Sie sie in eine Seite ausgeben:

<?php
$comment = $_GET['comment'] ?? '';   // e.g. "<script>alert('xss')</script>"
echo "<p>" . htmlspecialchars($comment, ENT_QUOTES, "UTF-8") . "</p>";
?>

Der <script>-Tag wird zu <script>...</script> neutralisiert, sodass der Browser den Text anzeigt, anstatt ihn auszuführen. Wenden Sie die Maskierung zum Zeitpunkt der Ausgabe an, nicht beim Speichern der Daten, damit der Rohwert für andere Kontexte erhalten bleibt.

Die Umwandlung umkehren

Um die Entitäten wieder in ihre ursprünglichen Zeichen zurückzuwandeln, verwenden Sie htmlspecialchars_decode(). Übergeben Sie dieselben Flags, die Sie beim Kodieren verwendet haben, damit Anführungszeichen symmetrisch behandelt werden.

Verwandte Funktionen

• htmlentities() — wie htmlspecialchars(), wandelt aber alle Zeichen um, die HTML-Entitätsäquivalente haben, nicht nur die fünf Sonderzeichen.
• htmlspecialchars_decode() — die Umkehrfunktion dieser Funktion.
• strip_tags() — entfernt HTML- und PHP-Tags vollständig, anstatt sie zu maskieren.
• nl2br() — fügt <br> vor Zeilenumbrüchen ein, wird häufig nach der Maskierung von Klartext verwendet.

Zusammenfassung

Verwenden Sie htmlspecialchars(), immer wenn Sie nicht vertrauenswürdigen Text in HTML ausgeben. Übergeben Sie ENT_QUOTES und eine explizite UTF-8-Kodierung für vorhersehbare, sichere Ergebnisse über PHP-Versionen hinweg, maskieren Sie zum Ausgabezeitpunkt und greifen Sie auf htmlentities() nur dann zurück, wenn Sie jede Entität kodieren müssen, nicht nur die fünf Sonderzeichen.

Übung