Sobald Benutzereingaben auf einer Webseite ausgegeben werden, besteht die Gefahr, dass eingeschleuster HTML- oder JavaScript-Code vom Browser ausgeführt wird. Die PHP-Funktion htmlentities() verhindert genau das: Sie wandelt alle Zeichen, für die eine benannte HTML-Entität existiert, in diese Entität um. Dadurch zeigt der Browser die Zeichen als Text an, statt sie als Code zu interpretieren. Das schützt vor Cross-Site-Scripting (XSS), einer der häufigsten Sicherheitslücken in Webanwendungen.
Syntax und Parameter
htmlentities() erwartet einen String und gibt ihn mit konvertierten Sonderzeichen zurück. Die vollständige Signatur sieht so aus:
htmlentities(
string $string,
int $flags = ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401,
?string $encoding = null,
bool $double_encode = true
): string
Die vier Parameter im Detail:
- $string: Der zu konvertierende Text. Alle Zeichen mit passender HTML-Entität werden umgewandelt.
- $flags: Steuert, wie Anführungszeichen und ungültige Zeichenfolgen behandelt werden. Standardmäßig werden seit PHP 8.1 sowohl einfache als auch doppelte Anführungszeichen konvertiert.
- $encoding: Der Zeichensatz des Eingabe-Strings. Seit PHP 5.4 ist
UTF-8 der Standard. Wer einen anderen Zeichensatz verwendet (z.B. ISO-8859-1), muss ihn hier explizit angeben. - $double_encode: Wenn
true (Standard), werden bereits vorhandene Entitäten erneut kodiert. Bei false bleiben bestehende Entitäten unverändert.
Welche Zeichen werden konvertiert?
Im Gegensatz zu htmlspecialchars(), das nur die fünf wichtigsten HTML-Sonderzeichen umwandelt (&, <, >, " und '), konvertiert htmlentities() jedes Zeichen, für das eine benannte HTML-Entität existiert. Dazu gehören Umlaute, das Copyright-Zeichen, Akzentbuchstaben und viele weitere.
<?php
$text = '© Müller & Partner – Café';
echo htmlspecialchars($text, ENT_QUOTES, 'UTF-8');
/* © Müller & Partner – Café
Nur & wird konvertiert */
echo htmlentities($text, ENT_QUOTES, 'UTF-8');
/* © Müller & Partner – Café
Alle Sonderzeichen werden konvertiert */
?>
In der Praxis bedeutet das: Wenn ein HTML-Dokument als UTF-8 ausgeliefert wird (was heute Standard ist), reicht htmlspecialchars() vollkommen aus. Die Umlaute und Sonderzeichen werden vom Browser korrekt dargestellt, auch ohne Entitäten. htmlentities() wird erst dann sinnvoll, wenn der erzeugte HTML-Code in Umgebungen funktionieren soll, die nicht mit UTF-8 arbeiten, oder wenn sämtliche Sonderzeichen explizit als Entitäten erscheinen sollen.
Verfügbare Flags und ihre Auswirkungen
Mit dem zweiten Parameter lässt sich das Verhalten der Funktion steuern. Die Flags werden mit dem Oder-Operator (|) kombiniert:
- ENT_QUOTES: Konvertiert sowohl doppelte (
") als auch einfache (') Anführungszeichen. Das ist für die sichere Ausgabe in HTML-Attributen unverzichtbar. - ENT_SUBSTITUTE: Ersetzt ungültige Code-Sequenzen durch das Unicode-Ersatzzeichen (
�), statt einen leeren String zurückzugeben. Verhindert, dass fehlerhafte Eingaben Teile der Ausgabe verschlucken. - ENT_HTML5: Verwendet die Entitäten gemäß HTML5-Standard. Damit stehen mehr benannte Entitäten zur Verfügung als im älteren HTML 4.01.
- ENT_NOQUOTES: Konvertiert keine Anführungszeichen. Sollte aus Sicherheitsgründen nie für Benutzereingaben verwendet werden, da ein Angreifer aus HTML-Attributen ausbrechen könnte.
<?php
$eingabe = "Er sagte: \"Das klappt 'bestimmt' nicht\"";
/* Nur doppelte Anführungszeichen */
echo htmlentities($eingabe, ENT_COMPAT, 'UTF-8');
/* Er sagte: "Das klappt 'bestimmt' nicht"
Einfache Anführungszeichen bleiben! */
/* Beide Arten konvertieren */
echo htmlentities($eingabe, ENT_QUOTES, 'UTF-8');
/* Er sagte: "Das klappt 'bestimmt' nicht"
Jetzt sind beide sicher */
?>
Standardwerte im Wandel der PHP-Versionen
Die Standardwerte von htmlentities() haben sich über die Jahre geändert. Wer Code für verschiedene PHP-Versionen schreibt, sollte die Unterschiede kennen:
- Vor PHP 5.4: Der Standard-Zeichensatz war
ISO-8859-1. UTF-8-Strings wurden falsch verarbeitet, wenn man den Zeichensatz nicht explizit angab. - Ab PHP 5.4: Der Standard-Zeichensatz ist
UTF-8. Das Standard-Flag war ENT_COMPAT, das nur doppelte Anführungszeichen konvertiert. - Ab PHP 8.1: Das Standard-Flag wurde auf
ENT_QUOTES | ENT_SUBSTITUTE geändert. Damit werden automatisch beide Arten von Anführungszeichen konvertiert und ungültige Sequenzen sicher behandelt.
Wer auf PHP 8.1 oder neuer arbeitet, erhält die sichersten Standardwerte automatisch. Für ältere Versionen sollte man ENT_QUOTES immer explizit angeben, um einfache Anführungszeichen nicht zu vergessen.
Doppelte Kodierung vermeiden
Wird htmlentities() auf einen String angewendet, der bereits Entitäten enthält, werden diese standardmäßig erneut kodiert. Aus & wird dann &amp;. Das passiert besonders häufig, wenn Inhalte aus einer Datenbank gelesen, bearbeitet und erneut gespeichert werden.
<?php
$text = 'Bereits kodiert: & und neu: &';
/* Standard: double_encode = true */
echo htmlentities($text, ENT_QUOTES, 'UTF-8');
/* Bereits kodiert: &amp; und neu: &
Die bestehende Entität wurde doppelt kodiert! */
/* Mit double_encode = false */
echo htmlentities($text, ENT_QUOTES, 'UTF-8', false);
/* Bereits kodiert: & und neu: &
Bestehende Entitäten bleiben unverändert */
?>
Gerade bei Content-Management-Systemen, in denen Texte mehrfach bearbeitet werden, ist double_encode = false wichtig. Ohne diesen Parameter wachsen die Entitäten mit jeder Speicherung weiter an.
Praxisbeispiel: Benutzereingaben sicher ausgeben
Ein typischer Anwendungsfall ist die Anzeige von Formulardaten. Der folgende Code zeigt, wie ein Name sicher in einem HTML-Attribut und im Seitentext ausgegeben wird:
<?php
$name = htmlentities(
$_POST['name'] ?? '',
ENT_QUOTES,
'UTF-8'
);
?>
<input type="text" value="<?= $name ?>">
<p>Willkommen, <?= $name ?></p>
Durch ENT_QUOTES werden auch einfache Anführungszeichen konvertiert. Ohne dieses Flag könnte ein Angreifer aus dem value-Attribut ausbrechen, wenn das Attribut mit einfachen Anführungszeichen umschlossen ist.
Ein konkretes Angriffsszenario: Gibt ein Benutzer den Wert ' onfocus='alert(document.cookie) in das Formular ein, entsteht ohne Escaping folgender HTML-Code:
<!-- Ohne Escaping: XSS-Lücke -->
<input type="text" value='' onfocus='alert(document.cookie)'>
<!-- Mit htmlentities(): sicher -->
<input type="text" value='' onfocus='alert(document.cookie)'>
Mit htmlentities() wird das Apostroph in ' umgewandelt. Der Browser interpretiert den Wert als harmlosen Text statt als Event-Handler.
html_entity_decode() als Gegenfunktion
Die Funktion html_entity_decode() macht die Konvertierung rückgängig. Sie wandelt HTML-Entitäten zurück in ihre entsprechenden Zeichen:
<?php
$kodiert = 'Müller & Partner';
$original = html_entity_decode(
$kodiert, ENT_QUOTES, 'UTF-8'
);
echo $original; // Müller & Partner
?>
Das ist nützlich, wenn HTML-kodierte Daten aus einer API oder Datenbank kommen und als Klartext weiterverarbeitet werden sollen, zum Beispiel für den Versand per E-Mail oder den Export als CSV-Datei.
Wann htmlentities() und wann htmlspecialchars()?
Beide Funktionen schützen vor XSS. Der Unterschied liegt im Umfang der Konvertierung:
- htmlspecialchars(): Konvertiert nur die fünf Zeichen
&, <, >, " und '. Das reicht für den XSS-Schutz in UTF-8-Dokumenten vollständig aus. - htmlentities(): Konvertiert zusätzlich Umlaute, Akzentbuchstaben, Copyright-Zeichen und alle weiteren Zeichen mit benannten Entitäten. Das erhöht die Dateigröße, bietet aber keinen zusätzlichen Sicherheitsgewinn.
Empfehlung: Für die meisten Projekte ist htmlspecialchars() die bessere Wahl. Es ist performanter, erzeugt kürzeren HTML-Code und bietet denselben XSS-Schutz. htmlentities() eignet sich für Sonderfälle: wenn der HTML-Code in Nicht-UTF-8-Umgebungen funktionieren muss, oder wenn Sonderzeichen in E-Mail-Templates als Entitäten erscheinen sollen.
Sicherheitshinweise und Best Practices
Beim Einsatz von htmlentities() gelten folgende Grundregeln:
- Escaping gehört zur Ausgabe, nicht zur Speicherung. Daten sollten unverändert in der Datenbank landen und erst bei der HTML-Ausgabe durch
htmlentities() oder htmlspecialchars() geschützt werden. So bleiben die Rohdaten für andere Ausgabeformate (JSON, CSV, E-Mail) nutzbar. - Zeichensatz immer explizit angeben. Auch wenn UTF-8 seit PHP 5.4 der Standard ist, macht eine explizite Angabe den Code klarer und verhindert Probleme bei Konfigurationswechseln.
- ENT_QUOTES verwenden. Ohne dieses Flag bleiben einfache Anführungszeichen unkonvertiert, was in bestimmten HTML-Kontexten eine Sicherheitslücke eröffnet.
- Für JavaScript-Kontexte reicht htmlentities() nicht. Wer Werte in
<script>-Blöcke einbettet, braucht json_encode() mit dem Flag JSON_HEX_TAG statt HTML-Escaping.
Zusammenfassung
htmlentities() konvertiert alle Zeichen mit benannten HTML-Entitäten und ist damit umfassender als htmlspecialchars(). Für die Ausgabe von Benutzereingaben im HTML-Kontext genügt in den meisten Fällen htmlspecialchars() mit ENT_QUOTES und UTF-8. Wer sämtliche Sonderzeichen als Entitäten darstellen muss, greift zu htmlentities(). In beiden Fällen gilt: Immer bei der Ausgabe escapen, den Zeichensatz explizit angeben und Anführungszeichen mitkonvertieren.
