The new implementation starts by structurally parsing its input documents, meaning that logical choices are based on the meaning of the input text, not the text directly. Whereas the legacy wp_kses() implementation attempts to examine each token in an HTML input and make adjustments to that original document, the new implementation creates its output string as it proceeds by creating a fresh serialization of the parsed input.

This means that character references in text nodes will be fully un-escaped and deterministically re-escaped, tags will appear all-lowercase, attributes double-quoted, no ignored self-closing flags for void elements⁴, etc.

<!-- Input HTML -->
The <IMG class=bike class="bo&#x0061;t" src='vehicle.png' /> & the wheels&hellip;

<!-- Legacy behavior -->
The <IMG class="bike" src="vehicle.png" /> &amp; the wheels&hellip;

<!-- New behavior -->
The <img class="bike" src="vehicle.png"> &amp; the wheels…

The goal of these changes is to produce more predictable HTML so that other parsing code is more likely to successfully recognize the HTML it receives, even if that other code suffers the same problems characteristic with over-simplified HTML parsing. This is attempting to remove the edge cases that make handling HTML reliably so difficult.

This normalization also means that there are a number of places that content was erroneously removed before which will now be preserved. The legacy implementation took defensive measures against inputs it didn’t understand, often swallowing up content that appeared like a tag A directory in Subversion. WordPress uses tags to store a single snapshot of a version (3.6, 3.6.1, etc.), the common convention of tags in version control systems. (Not to be confused with post tags.). Since the HTML API An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. understands that structure, however, these situations are recognized and normalized to prevent this very kind of confusion.

<!-- Input HTML -->
It would have to be <$500 for me to be interested in buying it; it’s already >5yo and past its warranted life.

<!-- Legacy behavior -->
It would have to be 5yo and past its warranted life.

<!-- New behavior -->
It would have to be &lt;$500 for me to be interested in buying it; it’s already &gt;5yo and past its warranted life.

This one is a bit esoteric, but might appear when least expected: there’s a subtlety in how HTML parsers treat named character references which are missing their closing semicolon. Some character references may be recognized without a terminating semicolon, such as &copy, while others unconditionally require them, such as with ·. Things become ambiguous when there are successive characters after such a named reference which themselves do not form another character reference: e.g. &copypaste; It looks like there’s a name here, but there’s no character reference named copypaste.

Inside of text nodes, these semicolon-optional character references are decoded, sometimes surprisingly, but when found inside HTML attributes they aren’t, which is yet another surprise. In the &copypaste; example the rendered text would show ©paste;, but an attribute value would remain &copypaste;. The reason for this discrepancy is how URL A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org search parameters are frequently mis-encoded in src, href and other attributes. Consider a search link: <a href="/search?q=cat+pictures&not=cartoon">; it’s clear that the intent here was to add a search parameter named not to exclude search results, but if decoded strictly, would be interpreted as /search?q=cat+pictures¬=cartoon because the &not character reference doesn’t require its semicolon.

This exception was made to prevent breaking the existing web and remains today in all spec-compliant HTML parsers and browsers. Where this might turn up is when text nodes contain URLs containing query args or snippets of query args. Note that &sect substring has been replaced by the new implementation in the following snippet with the section sign §, just as a browser would.

<!-- Input HTML -->
Add <code>/?preview=true&section=grilling</code>.

<!-- Legacy behavior -->
Add <code>/?preview=true&amp;section=grilling</code>.

<!-- New behavior -->
Add <code>/?preview=true§ion=grilling</code>.

To avoid this situation, authors should always escape the ampersand character & when writing HTML, and always include the semicolon for character references. This is particularly true within URL query strings, as the unescaped ampersands can be easy to overlook; one must remember that the decoded value should be &, thus the attribute value must contain &.

The HTML API defines the concept of a “special atomic element.” These are essentially the elements whose content cannot contain other markup. That is, all of the bytes found inside of them are parsed as plaintext, sometimes un-escaping character references and other times not. Because of the unique rules applied to the content of each of these kinds of elements, the HTML API treats them as if they were a single unit — it provides the entire element or none at all.

In the legacy wp_kses() implementation, if a SCRIPT tag were not allowed (as is the case for the default “post” context), then the opening and closing tags would be removed but the content would stick around. This was safe behavior because the executable code was removed from its executable content, but it could leave large rendered spans of JavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com code on the final page.

The new behavior is that when one of these tags is not allowed, it will be removed with all of its content too, automatically. This is not the case for other tags generally. For example, if section isn’t passed in for the allowable HTML tags, then only the opening and closing <section> and </section> tags will be removed. The nature of the special atomic elements warrants the change.

<!-- Input HTML -->
Click on my <script>alert(1)</script>!

<!-- Legacy behavior -->
Click on my alert(1)!

<!-- New behavior -->
Click on my !

There’s another side of this that could be surprising: there might be content inside of these special elements that looks like a tag but isn’t. The updated code recognizes when things that look like tags but aren’t, and then escapes that content where possible to prevent further confusion from downstream code.

<!-- Input HTML -->
<title>The <sneaky> tag is not allowed.</title>
<div>The <sneaky> tag is removed.</div>

<!-- Legacy behavior -->
<title>The  tag is not allowed.</title>
<div>The  tag is removed.</div>

<!-- New behavior -->
<title>The &lt;sneaky&gt; tag is not allowed.</title>
<div>The  tag is removed.</div>

While wp_kses() is usually examining a snippet of HTML in isolation, its output is typically being rendered into a containing HTML document. Because of this, it’s important to guard the end of the output to make sure that it can’t form a tag when joined with other strings. The legacy implementation handles this by treating anything which fails to fully parse as plaintext and escape it, which produces safe but often corrupt outputs. The HTML API pauses when it finds text that looks like it could have been truncated, meaning that it might be the start of a tag or comment or other syntax element. Therefore the refactor avoids treating these tail-ends as if they were text and simply discards them instead.

<!-- Input -->
Click on the <butto

<!-- Legacy behavior -->
Click on the &lt;butto

<!-- New behavior -->
Click on the 

For most situations the new behavior will result in less-clobbered text on the rendered page. However, there are a few points to be aware of regarding the special atomic elements. wp_kses() was built in a way that allows for un-matched tags at the start and end of the input, and plenty of code sends these kinds of incomplete fragments. For the most part, this has been preserved, but the special atomic elements are unique in that the parser changes modes inside of the elements. Therefore, if any of these elements appears incompletely, then the entire element will be removed. Complete in this context would mean a proper opening tag followed by a proper closing tag, including the contained content.

<!-- Input -->
Use the <title> tag to open a title.

<!-- Legacy behavior (assuming that TITLE is allowed ) -->
Use the <title> tag to open a title.

<!-- New behavior -->
Use the 

When SVG or MathML content is directly embedded in HTML it presents a complicated situation. SVG and MathML are normatively XML applications and adhere to XML’s draconian error policy⁵ — a parser must reject a document entirely if there is a single error or mistake in it — but when embedded into an HTML document they are a blend of HTML and XML⁶. When the markup behaves XML-like, it’s relatively straightforward to parse, but when it toggles into the HTML-like syntax then it becomes harder to know when to switch back or when the content ends.

Because of this, the new implementation of wp_kses() will parse as far into SVG and MathML content as it can with certainty. It’s able to know when proceeding would require further complexity⁷, and when it would, then it aborts entirely and returns the input up until that SVG or MathML content begins. This is important not only for wp_kses(), but safeguards downstream code and parsers which also might be unaware of the more-substantial rules.

<!-- Input -->
<li>XML-like <math><mtext>MathML</mtext></math>
<li>HTML-like <math><mtext><span>MathML</span></mtext></math>

<!-- Legacy behavior -->
<li>XML-like <math><mtext>MathML</mtext></math>
<li>HTML-like <math><mtext><span>MathML</span></mtext></math>

<!-- New behavior -->
<li>XML-like <math><mtext>MathML</mtext></math>
<li>HTML-like

The availability of an HTML parser brings capabilities A capability is permission to perform one or more types of task. Checking if a user has a capability is performed by the current_user_can function. Each user of a WordPress site might have some permissions but not others, depending on their role. For example, users who have the Author role usually have permission to edit their own posts (the “edit_posts” capability), but not permission to edit other users’ posts (the “edit_others_posts” capability). that weren’t previously possible, and in some cases, there are challenging decisions on what to allow based on those capabilities. The new implementation of wp_kses() applies some hard-limits in situations where the legacy implementation didn’t. This includes rejecting various kinds of malformed HTML comments, documents containing the NOSCRIPT element, and various elements containing confusable content.

In certain risky situations, whereby the risk is high that downstream parsers might get confused, or where the major browsers currently disagree on how to interpret the specification, elements may be rewritten in another form. For example, CDATA sections and PLAINTEXT element contents are transformed into normal escaped text.