A common use for Dom\Element::insertAdjacentHTML is processing data without rebuilding the operation manually. Inserts parsed HTML before, after or inside the current element at the requested position.
What Is Dom\Element::insertAdjacentHTML in PHP?
Inserts parsed HTML before, after or inside the current element at the requested position.
Syntax:
Dom\Element::insertAdjacentHTML($position, $data)
Parameters and Return Value
$position— The location relative to the element, such as beforeend.$data— The input text or XML content.
Check the returned value, including false when applicable, or handle exceptions for invalid input. The required XML/DOM extension must be installed.
Example 1: Basic Usage
This example demonstrates the main operation with a small, controlled input.
<?php
$htmlDocument = Dom\HTMLDocument::createFromString("<!doctype html><html><body><p class=\"notice\">Hello</p></body></html>");
$paragraph = $htmlDocument->querySelector("p");
$paragraph->insertAdjacentHTML("beforeend", "<strong> world</strong>");
echo $htmlDocument->saveHtml();
The result depends on the supplied data and the documented operation. Output is not shown as a fixed value when files, locales or runtime configuration can change it.
Example 2: Another Input
This example changes the input or surrounding setup to illustrate another behavior.
<?php
$htmlDocument = Dom\HTMLDocument::createFromString("<!doctype html><html><body><p class=\"notice\">Hello</p></body></html>");
$paragraph = $htmlDocument->querySelector("p");
$paragraph->insertAdjacentHTML("beforeend", "<strong> world</strong>");
echo $htmlDocument->saveHtml();
// Validate the result in a condition appropriate to this operation.
if (function_exists("json_encode")) { echo "Operation demonstrated"; }
The result depends on the supplied data and the documented operation. Output is not shown as a fixed value when files, locales or runtime configuration can change it.
Practical Example
This application-style example shows a self-contained usage pattern and checks its result.
<?php
$htmlDocument = Dom\HTMLDocument::createFromString("<!doctype html><html><body><p class=\"notice\">Hello</p></body></html>");
$paragraph = $htmlDocument->querySelector("p");
$paragraph->insertAdjacentHTML("beforeend", "<strong> world</strong>");
echo $htmlDocument->saveHtml();
// Inspect the surrounding runtime requirements before adapting this example.
echo PHP_VERSION;
The result depends on the supplied data and the documented operation. Output is not shown as a fixed value when files, locales or runtime configuration can change it.
Important Behavior and Edge Cases
- Do not enable external entity loading for untrusted XML. The legacy DOMDocument HTML parser and the modern PHP 8.4 HTML parser follow different HTML parsing rules.
- Use the intended input type and handle empty or malformed values explicitly.
- Where this API requires an extension, version, or file, document that dependency before using it in a real application.
Comparison With Related Functions
| Function or Method | When to Use It |
|---|---|
Dom\Element::insertAdjacentHTML | Inserts parsed HTML before, after or inside the current element at the requested position. |
DOMDocument::loadHTML | Parses HTML markup into the legacy DOMDocument tree. |
Common Beginner Mistakes
| Mistake | Correct Approach |
|---|---|
| Using this API without checking the required input or extension | Do not enable external entity loading for untrusted XML. The legacy DOMDocument HTML parser and the modern PHP 8.4 HTML parser follow different HTML parsing rules. |
| Confusing a detached node with one in the document | Append or import nodes into the intended owner document before querying the tree. |
| Loading untrusted XML with external entities enabled | Disable network entity loading and impose limits on input size. |
Key Takeaways
- Inserts parsed HTML before, after or inside the current element at the requested position.
- Do not enable external entity loading for untrusted XML. The legacy DOMDocument HTML parser and the modern PHP 8.4 HTML parser follow different HTML parsing rules.
- Test both the expected case and at least one failure or empty-input case before deployment.
Inserts parsed HTML before, after or inside the current element at the requested position. Use it when the operation fits your input, output and validation requirements.