mensbeam / html-sanitizer

1.0.0 2026-10-19 23:15 UTC

Requires

• php: >=8.0
• ext-dom: *
• mensbeam/html-parser: ^1.4
• mensbeam/intl: >=0.9.4
• mensbeam/mimesniff: >=0.4
• mensbeam/uri: ^1.0

Requires (Dev)

• bamarni/composer-bin-plugin: ^1.3

MIT

• J. King

• HTML5
• html
• dom
• sanitizer
• WHATWG

Published on Packagist.org on 2026-10-20 03:25 UTC

README

This is an implementation of the HTML insertion methods and the accompanying Sanitizer interface. All features of the Sanitizer interface are supported, and all insertion methods are supported as well. However, there are some limitations to the insertion methods:

• HTML fragments are first parsed then filtered. This has subtle interactions with invalid documents which trigger the adoption agency algorithm or foster parenting. Valid documents are unaffected
• If using Dom\Document or an instance of Dom\Element as a context, processing instructions will be converted into comments as of PHP 8.5.11
• if using DOMDocument or an instance of DOMElement as a context, parsing will be relatively slow; however it will be accurate, including the retention of processing instructions

With default options the sanitizer will perform the following modifications to the input:

• Remove unsafe elements such as <script>, <iframe>, <embed>, and <object>, among others
• Remove event handler attributes (such as onload or onclick)
• Remove URL attributes whose value uses the javascript: scheme
• Remove most other attributes, those considered non-essential
• Remove unknown elements
• Remove any processing instructions

Usage

namespace MensBeam\HTML;

abstract class SanitizerApi {
    public static function setHTML(\DOMElement|\Dom\Element $element, string $html, array $options = []): void;
    public static function setHTMLUnsafe(\DOMElement|\Dom\Element $element, string $html, array $options = []): void;
    public static function appendHTML(\DOMElement|\Dom\Element $element, string $html, array $options = []): void;
    public static function appendHTMLUnsafe(\DOMElement|\Dom\Element $element, string $html, array $options = []): void;
    public static function prependHTML(\DOMElement|\Dom\Element $element, string $html, array $options = []): void;
    public static function prependHTMLUnsafe(\DOMElement|\Dom\Element $element, string $html, array $options = []): void;
    public static function beforeHTML(\DOMElement|\DOMCharacterData|\Dom\Element|\Dom\CharacterData $node, string $html, array $options = []): void;
    public static function beforeHTMLUnsafe(\DOMElement|\DOMCharacterData|\Dom\Element|\Dom\CharacterData $node, string $html, array $options = []): void;
    public static function afterHTML(\DOMElement|\DOMCharacterData|\Dom\Element|\Dom\CharacterData $node, string $html, array $options = []): void;
    public static function afterHTMLUnsafe(\DOMElement|\DOMCharacterData|\Dom\Element|\Dom\CharacterData $node, string $html, array $options = []): void;
    public static function replaceWithHTML(\DOMElement|\DOMCharacterData|\Dom\Element|\Dom\CharacterData $node, string $html, array $options = []): void;
    public static function replaceWithHTMLUnsafe(\DOMElement|\DOMCharacterData|\Dom\Element|\Dom\CharacterData $node, string $html, array $options = []): void;
    public static function parseHTML(string $documentClass, string $html, array $options = []): \DOMDocument|\Dom\HTMLDocument;
    public static function parseHTMLUnsafe(string $documentClass, string $html, array $options = []): \DOMDocument|\Dom\HTMLDocument;
    ...
}

The MensBeam\HTML\SanitizerApi abstract class implements all of the standard HTML insertion methods. Those methods which would normally be instance methods of DOM nodes take as their first argument such a DOM node; those methods which would normally be static methods of the Dcoument object take a class name as their first argument, such as "DOMDocument" or "Dom\HTMLDocument" or any extended class thereof, an instance of which will be output.

The second argument is the input markup. With the exception of input to the parseHTML and parseHTMLUnsafe methods, this input must be encoded as UTF-8 text. For parseHTML and parseHTMLUnsafe, the encoding may be specified in the $options array as described in the following paragraph. If no encoding is provided and no encoding can be detected from the document, UTF-8 will be assumed.

The third argument is an array of options consistent with the SetHTMLOptions dictionary. Its sanitizer member, if any, should be either an instance of the MensBeam\HTML\Sanitizer class, the string "default", or an array consistent with the SanitizerConfig dictionary. When using the parseHTML or parseHTMLUnsafe methods an encoding member may also be specified, which may be either an encoding name or label or a MIME type with a charset parameter. This is an extension to the API to deal with the needs of the PHP environment. Finally, as no HTML parser for PHP is known to execute scripts, any runScripts member is ignored.

Extension methods

namespace MensBeam\HTML;

abstract class SanitizerApi {
    ...
    public static function setHTMLStr(string $html, array $options = []): string;
    public static function setHTMLUnsafeStr(string $html, array $options = []): string;
    public static function parseHTMLStr(string $html, array $options = []): string;
    public static function parseHTMLUnsafeStr(string $html, array $options = []): string;
}

The MensBeam\HTML\SanitizerApi abstract class also implements a few non-standard convenience methods. All these methods parse their input, sanitize it, and finally serialize the sanitized result back into a string. Except for their output and taking only two arguments (an input string and an array of options), they function identically to their standard counterparts.

Further reading

MDN features a fairly extensive article on how to use the Sanitizer class, with links to the similar documentation for some of the HTML insertion methods.