PHP DOMDocument errors/warnings on html5-tags

PHP DOMDocument errors/warnings on html5-tags

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

PHP DOMDocument errors/warnings on html5-tags

When working with legacy PHP environments like version 5.3, you might encounter a specific limitation when trying to parse HTML5 markup using the built-in DOMDocument class. A common scenario involves attempting to load modern semantic tags such as <nav>, <section>, or <article>. If you run code similar to the example below in PHP 5.3, you will see warnings indicating that these tags are invalid:

<?php
$dom = new DOMDocument();
// Using @ to suppress errors hides them, but doesn't solve the issue
@$dom->loadHTML("<!DOCTYPE HTML>
<html><head><title>test</title></head>
<body>
<nav>
  <ul>
    <li>first</li>
    <li>second</li>
  </ul>
</nav>
<section>
  ...
</section>
</body>
</html>");

The resulting warnings, such as DOMDocument::loadHTML(): Tag nav invalid in Entity, stem from the fact that DOMDocument is an XML parser. While HTML5 is technically a subset of XML (when served with application/xhtml+xml), standard HTML parsing requires handling specific quirks like loose nesting and case-insensitivity that strict XML parsers reject.

In PHP 5.3, the underlying C library used by DOMDocument defaults to expecting well-formed XML unless explicitly told otherwise. When you pass a string starting with <!DOCTYPE html> (lowercase), it signals HTML5, but the parser still throws errors because it doesn't recognize these new semantic tags as part of its internal DTD (Document Type Definition). This is not a bug in your PHP installation; it is a fundamental difference between XML and HTML parsing.

The Correct Approach: Internal Subset

To resolve this without upgrading your PHP version or switching libraries, you must explicitly instruct DOMDocument to use an internal subset that supports HTML5 tags. This involves setting the HTML_ENTITIES flag and ensuring the parser treats the input as HTML rather than XML.

However, even with the correct flags, PHP 5.3's DOMDocument was notoriously strict about unknown tags in certain configurations. The most reliable fix within this version is to ensure you are not triggering the strict XML validation path. You can do this by explicitly setting the error handling mode and passing the string as a parameter that triggers the HTML parser:

<?php
$dom = new DOMDocument();

// Suppress notices for malformed input initially, then fix them later
libxml_use_internal_errors(true);

// Load the HTML string. 
// In PHP 5.3, simply loading the DOCTYPE often isn't enough if the DTD is missing.
// The parser needs to know to accept unknown tags as valid elements.
$dom->loadHTML("<!DOCTYPE html>
<html lang='en'>
<head><title>Test</title></head>
<body>
<nav>
  <ul>
    <li>first</li>
    <li>second</li>
  </ul>
</nav>
<section class='content'>
  This is a section.
</section>
</body>
</html>", LIBXML_NOERROR | LIBXML_NOWARNING);

// Check for any remaining errors that weren't suppressed internally
$errors = libxml_get_errors();
if ($errors) {
    foreach ($errors as $error) {
        echo "Error: " . $error->message . "\n";
    }
} else {
    echo "DOM loaded successfully.\n";
}

// Now you can manipulate the DOM normally
$nav = $dom->getElementsByTagName('nav')->item(0);
if ($nav) {
    echo "Found <nav> tag\n";
}

Why This Works and When It Fails

The key here is libxml_use_internal_errors(true) combined with LIBXML_NOERROR or LIBXML_NOWARNING. By default, DOMDocument attempts to validate against a built-in DTD. For HTML5 tags introduced in 2014 (like <nav>), older XML parsers often lacked the definition for these elements in their internal schema.

By suppressing the warnings during load and checking via libxml_get_errors(), you can proceed with DOM manipulation even if the initial validation was imperfect. Once loaded, accessing $dom->getElementsByTagName('nav') will return the element nodes correctly, allowing you to modify attributes or innerHTML.

Modern Alternatives

If you are starting a new project and have control over the PHP version, relying on DOMDocument for HTML5 parsing is generally discouraged due to these historical quirks. Modern versions of PHP (7.x and 8.x) have improved their handling of HTML, but even then, the HtmlParser library or using DOMXpath with modern flags is often preferred for complex HTML5 documents.

In a Laravel application, for instance, you would typically rely on the framework's built-in capabilities or switch to a dedicated parser like dompdf (for rendering) or tidy (for cleaning). However, if you are stuck on PHP 5.3 within an existing MVC structure, the method of suppressing internal errors and validating manually remains the standard workaround.

For developers maintaining older codebases where upgrading PHP is not immediately feasible, understanding that DOMDocument is fundamentally an XML parser trying to act as an HTML parser is crucial. The warnings you see are simply the parser rejecting tags it doesn't recognize in its strict XML mode. Explicitly telling it to relax its validation rules allows you to access and manipulate those modern semantic elements anyway.

Our network