Signatur
Beschreibung
Dom\AdjacentPosition ist ein String-Backed-Enum, das die vier Standard-Einfügepositionen repräsentiert, die aus der Web-API insertAdjacentHTML/insertAdjacentElement bekannt sind. Es wird in der modernen DOM-Erweiterung (Dom\-Namespace, eingeführt in PHP 8.4) verwendet und ersetzt fehleranfällige Zeichenketten-Konstanten durch typsichere Enum-Werte.
Die vier Positionen beziehen sich stets auf ein Referenz-Element: BeforeBegin fügt unmittelbar vor dem öffnenden Tag ein, AfterBegin direkt nach dem öffnenden Tag (erstes Kind), BeforeEnd kurz vor dem schließenden Tag (letztes Kind) und AfterEnd unmittelbar nach dem schließenden Tag.
Der Einsatz des Enums verbessert die Lesbarkeit und verhindert Tippfehler, da PHP den übergebenen Wert gegen die definierten Cases validiert. Besonders praktisch ist er bei der programmatischen Manipulation von XML- oder HTML-Dokumenten, wenn Inhalte relativ zu einem bekannten Ankerelement positioniert werden sollen.
Beispiele
Knoten vor und nach einem Element einfügen
<?php
$dom = Dom\HTMLDocument::createFromString('<div id="main"><p>Inhalt</p></div>');
$main = $dom->getElementById('main');
$before = $dom->createElement('header');
$before->textContent = 'Kopfbereich';
$main->insertAdjacentElement(Dom\AdjacentPosition::BeforeBegin, $before);
$after = $dom->createElement('footer');
$after->textContent = 'Fußbereich';
$main->insertAdjacentElement(Dom\AdjacentPosition::AfterEnd, $after);
echo $dom->body->innerHTML;Kindelemente am Anfang und Ende eines Containers einfügen
<?php
$dom = Dom\HTMLDocument::createFromString('<ul id="liste"><li>Mitte</li></ul>');
$liste = $dom->getElementById('liste');
$first = $dom->createElement('li');
$first->textContent = 'Erstes Element';
$liste->insertAdjacentElement(Dom\AdjacentPosition::AfterBegin, $first);
$last = $dom->createElement('li');
$last->textContent = 'Letztes Element';
$liste->insertAdjacentElement(Dom\AdjacentPosition::BeforeEnd, $last);
echo $dom->getElementById('liste')->innerHTML;Enum-Cases und ihre Rohwerte ausgeben
<?php
foreach (Dom\AdjacentPosition::cases() as $case) {
echo $case->name . ' => ' . $case->value . PHP_EOL;
}// Wichtig · Fallstricke
Nur im neuen Dom\-Namespace verfügbar: Dieses Enum gehört zur überarbeiteten DOM-Erweiterung, die in PHP 8.4 eingeführt wurde. Die ältere DOMDocument-Klasse (ohne Namespace) kennt dieses Enum nicht.
Die Rohwerte (value) des Enums entsprechen den lowercase-Strings der gleichnamigen Web-API (beforebegin, afterbegin, beforeend, afterend), was die Interoperabilität mit JavaScript-Code erleichtert.
Hinweis zu BeforeBegin und AfterEnd: Diese Positionen setzen voraus, dass das Referenz-Element einen Elternknoten besitzt. Wird ein wurzelloses Element übergeben, kann eine Exception geworfen werden.