Dom\HTMLCollection — Klasse · PHP-Referenz

Signatur

class Dom\HTMLCollection extends Dom\NodeList

Beschreibung

Dom\HTMLCollection ist eine Read-only-Sammlung von DOM-Elementen, die typischerweise als Ergebnis von Methoden wie Dom\Element::getElementsByTagName() oder Dom\Element::getElementsByClassName() zurückgegeben wird. Sie ist Teil der modernen, namespaced DOM-API, die mit PHP 8.4 eingeführt wurde.

Im Gegensatz zu einem einfachen Array ist eine HTMLCollection live – das bedeutet, sie spiegelt Änderungen am DOM-Baum automatisch wider. Wenn Elemente hinzugefügt oder entfernt werden, aktualisiert sich die Sammlung entsprechend, ohne dass sie erneut abgefragt werden muss.

Die Elemente der Sammlung können sowohl über einen numerischen Index (z. B. $collection->item(0)) als auch direkt per Array-Syntax ($collection[0]) abgerufen werden. Die Eigenschaft length gibt die Anzahl der enthaltenen Elemente zurück. Eine Iteration per foreach ist ebenfalls möglich, da die Klasse Traversable implementiert.

Dom\HTMLCollection wird vor allem beim Arbeiten mit HTML-Dokumenten eingesetzt, die über Dom\HTMLDocument::loadHTML() geparst wurden. Sie bietet eine standardkonforme, webkompatible Schnittstelle, die der browser-seitigen HTMLCollection-API entspricht.

Beispiele

Elemente per getElementsByTagName abrufen

<?php
$html = <<<HTML
<!DOCTYPE html>
<html>
<body>
  <p class="intro">Erster Absatz</p>
  <p>Zweiter Absatz</p>
  <p class="intro">Dritter Absatz</p>
</body>
</html>
HTML;

$doc = Dom\HTMLDocument::createFromString($html);

/** @var Dom\HTMLCollection $paragraphs */
$paragraphs = $doc->body->getElementsByTagName('p');

echo 'Anzahl Absätze: ' . $paragraphs->length . PHP_EOL;

foreach ($paragraphs as $p) {
    echo $p->textContent . PHP_EOL;
}

Anzahl Absätze: 3 Erster Absatz Zweiter Absatz Dritter Absatz

Elemente per Klasse filtern und per Index abrufen

<?php
$html = <<<HTML
<!DOCTYPE html>
<html>
<body>
  <div class="card">Karte 1</div>
  <div class="card">Karte 2</div>
  <div class="other">Anderes Element</div>
</body>
</html>
HTML;

$doc = Dom\HTMLDocument::createFromString($html);

/** @var Dom\HTMLCollection $cards */
$cards = $doc->body->getElementsByClassName('card');

echo 'Erstes Element: ' . $cards->item(0)->textContent . PHP_EOL;
echo 'Zweites Element (Array-Syntax): ' . $cards[1]->textContent . PHP_EOL;
echo 'Gesamtanzahl: ' . $cards->length . PHP_EOL;

Erstes Element: Karte 1 Zweites Element (Array-Syntax): Karte 2 Gesamtanzahl: 2

// Wichtig · Fallstricke

Neu in PHP 8.4: Dom\HTMLCollection gehört zur neuen, vollständig namespaced DOM-API (Dom\), die parallel zur älteren DOMDocument-API existiert. Die alte API bleibt weiterhin verfügbar, wird aber langfristig durch die neue ersetzt.

Live-Charakter: Da HTMLCollection eine Live-Ansicht des DOMs darstellt, kann das Iterieren über eine Sammlung, während gleichzeitig Elemente eingefügt oder entfernt werden, zu unerwartetem Verhalten führen. Für solche Fälle empfiehlt es sich, die Sammlung vorher in ein reguläres Array zu konvertieren, z. B. mit iterator_to_array($collection).

Read-only: Die Sammlung selbst ist schreibgeschützt. Elemente können nicht direkt über die HTMLCollection hinzugefügt oder entfernt werden – Änderungen müssen am DOM-Knoten vorgenommen werden.

Siehe auch

Dom\NodeList Dom\HTMLDocument Dom\Element::getElementsByClassName Dom\Element::getElementsByTagName Dom\ParentNode::querySelectorAll