[{"id":126106,"date":"2026-10-07T19:57:21","date_gmt":"2026-10-07T19:57:21","guid":{"rendered":"https:\/\/make.wordpress.org\/core\/?p=126106"},"modified":"2026-10-07T23:08:00","modified_gmt":"2026-10-07T23:08:00","slug":"progress-report-wp_kses","status":"publish","type":"post","link":"https:\/\/make.wordpress.org\/core\/2026\/10\/07\/progress-report-wp_kses\/","title":{"rendered":"Progress Report: wp_kses()<\/code>"},"content":{"rendered":"

Since its inception, WordPress has relied on the KSES1<\/a><\/sup> subsystem to sanitize HTMLHTML<\/span> HyperText Markup Language. The semantic scripting language primarily used for outputting content in web browsers.<\/span><\/span><\/span>. Its purpose has grown and changed over time, but primarily serves two purposes: correct aesthetic defects that are likely the result of typos or pasting errors; and remove security risks that might appear in untrusted inputs. The original kses<\/code> library was written before HTML5 fully-formalized HTML parsing and at a time when it was common to \u201chand type\u201d HTML. Today, however, there is no such thing as \u201cseriously malformed2<\/a><\/sup>\u201d HTML and most people author content through rich editors, such as WordPress\u2019 BlockBlock<\/span> Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience.<\/span><\/span><\/span> editor. This means that today, the primary purpose of wp_kses()<\/code> is to prune out risks from untrusted inputs, and it\u2019s time for it to get an overhaul.<\/p>\n\n\n\n

As part of #66208<\/a>, PR#13271<\/a> replaced the implementation of wp_kses()<\/code> with a new one based on the HTML API<\/a>. This update replaces a complicated chain of functions, string processing, PCRE regular expressions, and outdated logic to ensure that WordPress can perform its sanitization role reliably and comprehensibly.<\/p>\n\n\n\n\n\n\n\n

What changes might affect existing plugins, themes, or CoreCore<\/span> Core is the set of software required to run WordPress. The Core Development Team builds WordPress.<\/span><\/span><\/span> code?<\/h3>\n\n\n\n

Rebuilding wp_kses()<\/code> should not require any changes to plugins or themes; it\u2019s an in-place upgrade with no interface changes. However, as its mode of operation is being entirely overhauled, there may be significant impacts on inputs that were treated in particular ways by the legacy implementation.<\/p>\n\n\n\n

An opt-out filterFilter<\/span> Filters are one of the two types of Hooks https:\/\/codex.wordpress.org\/Plugin_API\/Hooks<\/a>. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output.<\/span><\/span><\/span> preserves existing behaviors.<\/h4>\n\n\n\n

For now, the original implementation is being kept around for compatibility reasons. A new filter gives site owners the opportunity to opt-out of running the replacement code. Reverting to the legacy mode is therefore as easy as adding the following line to your site. Before the full release of WordPress 7.2.0, any and all feedback on this new implementation will not only be greatly appreciated, but will help ensure a stable update for everyone.<\/p>\n\n\n\n

add_filter( 'wp_kses_force_legacy_parser', '__return_true' );<\/code><\/pre>\n\n\n\n
It\u2019s safe to run the new code, as the new internal parser is more robust, faster, and requires less memory to run, but in case some existing code depends on the idiosyncrasies of the legacy wp_kses()<\/code>, that implementation remains available for now<\/em>, but it will disappear in future releases or even in WordPress 7.2.03<\/a><\/sup>.<\/p>\n\n\n\n
What will change as a result of this refactor in the function\u2019s behavior?<\/h3>\n\n\n\n
The goal of the refactor is to preserve the intent of the safety and aesthetic checks in the legacy wp_kses()<\/code> function while ensuring that there will never be a mis-parse of HTML. To that extent, it is hard to quantify or completely qualify the kinds of changes this will bring to bear. There are a number of common scenarios, however, that are likely to present themselves.<\/p>\n\n\n\n
\n
Text nodes and all syntax tokens are normalized.<\/h4>\n\n\n\n
The new implementation starts by structurally parsing its input documents, meaning that logical choices are based on the meaning<\/em> of the input text, not the text directly. Whereas the legacy wp_kses()<\/code> 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.<\/p>\n\n\n\n
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 elements4<\/a><\/sup>, etc.<\/p>\n\n\n\n
<!-- Input HTML -->\nThe <IMG class=bike class=\"bo&#x0061;t\" src='vehicle.png' \/> & the wheels&hellip;\n\n<!-- Legacy behavior -->\nThe <IMG class=\"bike\" src=\"vehicle.png\" \/> &amp; the wheels&hellip;\n\n<!-- New behavior -->\nThe <img class=\"bike\" src=\"vehicle.png\"> &amp; the wheels\u2026<\/code><\/pre>\n\n\n\n
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.<\/p>\n\n\n\n
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\u2019t understand, often swallowing up content that appeared like a tagtag<\/span> 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.)<\/span><\/span><\/span>. Since the HTML APIAPI<\/span> 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.<\/span><\/span><\/span> understands that structure, however, these situations are recognized and normalized to prevent this very kind of confusion.<\/p>\n\n\n\n
<!-- Input HTML -->\nIt would have to be <$500 for me to be interested in buying it; it\u2019s already >5yo and past its warranted life.\n\n<!-- Legacy behavior -->\nIt would have to be 5yo and past its warranted life.\n\n<!-- New behavior -->\nIt would have to be &lt;$500 for me to be interested in buying it; it\u2019s already &gt;5yo and past its warranted life.<\/code><\/pre>\n<\/div>\n\n\n\n
\n
Ambiguous ampersands are resolved.<\/h4>\n\n\n\n
This one is a bit esoteric, but might appear when least expected: there\u2019s a subtlety in how HTML parsers treat named character references<\/em> which are missing their closing semicolon. Some character references may be recognized without a terminating semicolon, such as &copy<\/code>, while others unconditionally require them, such as with &middot;<\/code>. Things become ambiguous<\/em> when there are successive characters after such a named reference which themselves do not form another character reference: e.g. <\/em>&copypaste;<\/code> It looks like there\u2019s a name here, but there\u2019s no character reference named copypaste<\/code>.<\/p>\n\n\n\n
Inside of text nodes, these semicolon-optional character references are decoded, sometimes surprisingly, but when found inside HTML attributes they aren\u2019t, which is yet another surprise. In the &copypaste;<\/code> example<\/a> the rendered text would show \u00a9paste;<\/code>, but an attribute value would remain &copypaste;<\/code>. The reason for this discrepancy is how URLURL<\/span> A specific web address of a website or web page on the Internet, such as a website\u2019s URL www.wordpress.org<\/span><\/span><\/span> search parameters are frequently mis-encoded in src<\/code>, href<\/code> and other attributes. Consider a search link: <a href=\"\/search?q=cat+pictures&not=cartoon\"><\/code>; it\u2019s clear that the intent here was to add a search parameter named not<\/code> to exclude search results, but if decoded strictly, would be interpreted as \/search?q=cat+pictures\u00ac=cartoon<\/code> because the &not<\/code> character reference doesn\u2019t require its semicolon.<\/p>\n\n\n\n
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<\/em> contain URLs containing query args or snippets of query args. Note that &sect<\/code> substring has been replaced by the new implementation in the following snippet with the section sign \u00a7<\/code>, just as a browser would.<\/p>\n\n\n\n
<!-- Input HTML -->\nAdd <code>\/?preview=true&section=grilling<\/code>.\n\n<!-- Legacy behavior -->\nAdd <code>\/?preview=true&amp;section=grilling<\/code>.\n\n<!-- New behavior -->\nAdd <code>\/?preview=true\u00a7ion=grilling<\/code>.<\/code><\/pre>\n\n\n\n
To avoid this situation, authors should always escape the ampersand character &<\/code> 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 &<\/code>, thus the attribute value must contain &amp;<\/code>.<\/p>\n<\/div>\n\n\n\n
\n
The contents of SCRIPT and STYLE elements are removed with their corresponding tags.<\/h4>\n\n\n\n
The HTML API defines the concept of a \u201cspecial atomic element.\u201d 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<\/a>, 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 \u2014 it provides the entire element or none at all.<\/p>\n\n\n\n
In the legacy wp_kses()<\/code> implementation, if a SCRIPT<\/code> tag were not allowed (as is the case for the default \u201cpost\u201d context), then the opening and closing tags would be removed but the content would stick around. This was safe<\/em> behavior because the executable code was removed from its executable content, but it could leave large rendered spans of JavaScriptJavaScript<\/span> 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\u2019s browser.\nhttps:\/\/www.javascript.com<\/a><\/span><\/span><\/span> code on the final page.<\/p>\n\n\n\n
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<\/code> isn\u2019t passed in for the allowable HTML tags, then only the opening and closing <section><\/code> and <\/section><\/code> tags will be removed. The nature of the special atomic elements warrants the change.<\/p>\n\n\n\n
<!-- Input HTML -->\nClick on my <script>alert(1)<\/script>!\n\n<!-- Legacy behavior -->\nClick on my alert(1)!\n\n<!-- New behavior -->\nClick on my !<\/code><\/pre>\n\n\n\n
There\u2019s another side of this that could be surprising: there might be content inside of these special elements that looks like a tag but isn\u2019t. The updated code recognizes when things that look like tags but aren\u2019t, and then escapes that content where possible to prevent further confusion from downstream code.<\/p>\n\n\n\n
<!-- Input HTML -->\n<title>The <sneaky> tag is not allowed.<\/title>\n<div>The <sneaky> tag is removed.<\/div>\n\n<!-- Legacy behavior -->\n<title>The  tag is not allowed.<\/title>\n<div>The  tag is removed.<\/div>\n\n<!-- New behavior -->\n<title>The &lt;sneaky&gt; tag is not allowed.<\/title>\n<div>The  tag is removed.<\/div><\/code><\/pre>\n<\/div>\n\n\n\n
\n
Incomplete inputs are truncated before the start of the ambiguity.<\/h4>\n\n\n\n
While wp_kses()<\/code> is usually examining a snippet of HTML in isolation, its output is typically being rendered into a containing HTML document. Because of this, it\u2019s important to guard the end of the output to make sure that it can\u2019t 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<\/em> 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. <\/p>\n\n\n\n
<!-- Input -->\nClick on the <butto\n\n<!-- Legacy behavior -->\nClick on the &lt;butto\n\n<!-- New behavior -->\nClick on the <\/code><\/pre>\n\n\n\n
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()<\/code> 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<\/em> 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<\/em> in this context would mean a proper opening tag followed by a proper closing tag, including the contained content.<\/p>\n\n\n\n
<!-- Input -->\nUse the <title> tag to open a title.\n\n<!-- Legacy behavior (assuming that TITLE is allowed ) -->\nUse the <title> tag to open a title.\n\n<!-- New behavior -->\nUse the <\/code><\/pre>\n<\/div>\n\n\n\n
\n
SVG and MathML requiring more-complicated parsing is rejected.<\/h4>\n\n\n\n
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\u2019s draconian error policy5<\/a><\/sup> \u2014 a parser must<\/em> reject a document entirely if there is a single error or mistake in it \u2014 but when embedded into an HTML document they are a blend of HTML and XML6<\/a><\/sup>. When the markup behaves XML-like, it\u2019s 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.<\/p>\n\n\n\n
Because of this, the new implementation of wp_kses()<\/code> will parse as far into SVG and MathML content as it can with certainty. It\u2019s able to know when proceeding would require further complexity7<\/a><\/sup>, 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()<\/code>, but safeguards downstream code and parsers which also might be unaware of the more-substantial rules.<\/p>\n\n\n\n
<!-- Input -->\n<li>XML-like <math><mtext>MathML<\/mtext><\/math>\n<li>HTML-like <math><mtext><span>MathML<\/span><\/mtext><\/math>\n\n<!-- Legacy behavior -->\n<li>XML-like <math><mtext>MathML<\/mtext><\/math>\n<li>HTML-like <math><mtext><span>MathML<\/span><\/mtext><\/math>\n\n<!-- New behavior -->\n<li>XML-like <math><mtext>MathML<\/mtext><\/math>\n<li>HTML-like<\/code><\/pre>\n<\/div>\n\n\n\n
\n
Some inputs are never trusted.<\/h4>\n\n\n\n
The availability of an HTML parser brings capabilitiescapability<\/span> A\u00a0capability<\/strong>\u00a0is permission to perform one or more types of task. Checking if a user has a capability is performed by the current_user_can<\/code> function. Each user of a WordPress site might have some permissions but not others, depending on their\u00a0role. For example, users who have the Author role usually have permission to edit their own posts (the \u201cedit_posts\u201d capability), but not permission to edit other users\u2019 posts (the \u201cedit_others_posts\u201d capability).<\/span><\/span><\/span> that weren\u2019t previously possible, and in some cases, there are challenging decisions on what to allow based on those capabilities. The new implementation of wp_kses()<\/code> applies some hard-limits in situations where the legacy implementation didn\u2019t. This includes rejecting various kinds of malformed HTML comments, documents containing the NOSCRIPT<\/code> element, and various elements containing confusable content.<\/p>\n\n\n\n
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<\/code> sections and PLAINTEXT<\/code> element contents are transformed into normal escaped text.<\/p>\n<\/div>\n\n\n\n
What rationale is leading behavioral changes?<\/h3>\n\n\n\n
Preserve intentional behaviors.<\/h4>\n\n\n\n
There are some debatable historic decisions within wp_kses()<\/code>. One, for instance, is preserving so-called \u201cunbalanced tags\u201d in the input. One might expect wp_kses()<\/code> to add missing closing tags to its input, but plenty of existing code in the directory and in Core already passes \u201cunbalanced\u201d HTML intentionally through the function and expects it to remain unbalanced in the output. This is because people sometimes concatenate chunks of HTML which have been separately-sanitized. This may not be the ideal way to accomplish the task, but it\u2019s well-established.<\/p>\n\n\n\n
This is a situation where the existing behavior is preserved. Adding those missing tags was explored, but ultimately rejected for this reason.<\/p>\n\n\n\n
Allow already-broken behaviors to change.<\/h4>\n\n\n\n
It\u2019s also up for debate what \u201cbroken\u201d exactly means, but for the sake of this refactor, and all refactors with the HTML API, the qualification is whether a broken behavior was expected or not. For instance, wp_kses()<\/code> has generally not been aware of the special parsing rules inside an HTML TITLE<\/code> element. Consider its behavior when img<\/code> is<\/em> and isn\u2019t<\/em> allowed.<\/p>\n\n\n\n
<?php\n\necho wp_kses(\n    '<title><img><\/title>',\n    array( 'title' => true, 'img' => array( 'src' => array( 'required' => true ) ) ) \n);\n\/\/ <title><img><\/title>\n\necho wp_kses(\n    '<title><img \/><\/title>',\n    array( 'title' => true, 'img' => array( 'src' => array( 'required' => true ) ) )\n);\n\/\/ <title><\/title>\n\necho wp_kses( '<title><img><\/title>', array( 'title' => true ) );\n\/\/ <title><\/title><\/code><\/pre>\n\n\n\n
There is no real way to intuit the results of these calls because the parser was confused on the nature of the <img><\/code> and <img \/><\/code> byte sequences. Every one of the outputs of these calls is wrong because no IMG<\/code> element exists within the TITLE<\/code>.<\/p>\n\n\n\n
<?php\n\nadd_filter( 'wp_kses_force_legacy_parser', '__return_false' );\necho wp_kses(\n    '<title><img><\/title>',\n    array( 'title' => true, 'img' => array( 'src' => array( 'required' => true ) ) ) \n);\n\/\/ <title>&lt;img&gt;<\/title><\/code><\/pre>\n\n\n\n
The proper way to sanitize and normalize content within the TITLE<\/code> element is to escape it as text, after first decoding any character references inside it. This behavior was changed because there\u2019s no possible way to say that the existing behavior was correct without creating internal inconsistencies. It might have been \u201ccorrect\u201d in some cases for some people<\/a>, but an adjustment here only changes who is affected by the inconsistent state and it\u2019s not viable to attempt to evaluate whose broken flows are more or less important.<\/p>\n\n\n\n
So this change was adopted because it establishes clear expectations for everyone and fixes situations in which it was not previously possible for any consistent notion of \u201cit works.\u201d<\/p>\n\n\n\n
Conclusion<\/h2>\n\n\n\n
Please give the new implementation of wp_kses()<\/code> a try and share any feedback you have in the ticketticket<\/span> Created for both bug reports and feature development on the bug tracker.<\/span><\/span><\/span> (#66208<\/a>), or leave a comment below. Expect this to be part of WordPress 7.2 or 7.3 dependent on what this period of testing turns up. Thank you for your attention and participation!<\/p>\n\n\n\n
\n\n\n\n
Props to @<\/span>jonsurrell<\/a> and @<\/span>westonruter<\/a> who reviewed this post before publishing.<\/em><\/p>\n\n\n
  1. \u201cThe name kses comes from the terms XSS and access.\u201d \u2014 noted in the README of the 0.1.0 release<\/a> of the kses<\/code> library<\/a>. \u21a9\ufe0e<\/a><\/li>
  2. The HTML Living Specification<\/a> prescribes how to parse every kind of malformed input, meaning that every compliant parser should produce the same output for any given input. There is no point of giving up, and there is no leniency<\/a> in how a document is to be parsed. \u21a9\ufe0e<\/a><\/li>
  3. The speed with which the legacy wp_kses()<\/code> implementation will disappear is directly related to the severityseverity<\/span> The seriousness of the ticket in the eyes of the reporter. Generally, severity is a judgment of how bad a bug is, while priority<\/strong> is its relationship to other bugs.<\/span><\/span><\/span> of issues uncovered in testing. If all goes well, WordPress 7.2.0 could include a wholesale replacement of the legacy function without any transition support in the released version. \u21a9\ufe0e<\/a><\/li>
  4. There is a myth of XHTML-compatible HTML, but the sense of interoperability and security is superficial. It\u2019s not safe to deliver HTML as XHTML<\/a> and there is no general way to create a single document compatible under both systems. The mistaken self-closing flag on HTML elements appeared as a way to attempt to produce XHTML-safe HTML, but is non-normative and its presence continues a tradition of misunderstanding, because HTML has no self-closing elements. \u21a9\ufe0e<\/a><\/li>
  5. Also referred to as \u201cpenalize innocent end-users,\u201d XML\u2019s \u201cdraconian error handling\u201d<\/a> was chosen to keep XML parser implementations simple. \u21a9\ufe0e<\/a><\/li>
  6. When HTML5 was being standardized, one of the guiding rules was \u201cdon\u2019t break the Internet.\u201d Because a sufficient number of websites had already pasted SVG and MathML into HTML pages, with errors, and because the browsers at the time parsed and displayed that content anyway, the specification had to adapt to continue to allow these pages to render in spec-compliant browsers. In fact, this requirement for maximum backwards compatibility is the reason behind most of HTML\u2019s parsing complexity. \u21a9\ufe0e<\/a><\/li>
  7. The new wp_kses()<\/code> implementation relies on the Tag Processor, which can parse every tag, comment, text node, etc., but which isn\u2019t aware of the tree-structure of an HTML document. The HTML Processor, its more-powerful counterpart, is able to build that tree, but this process involves considerably more time and effort.  \u21a9\ufe0e<\/a><\/li>
  8. It\u2019s worth emphasizing that wp_kses()<\/code> is meant to sanitize untrusted inputs<\/em>. There is a certain blurriness in how specific inputs should be handled in order to neutralize potential dangers. Because of this, there are intentionally fewer behavioral guarantees and the logic will lean conservatively. That is, it will be safety to regretfully reject some safe inputs in order to ensure that more unsafe inputs are rejected. \u21a9\ufe0e<\/a><\/li><\/ol>\n\n\n
    <\/p>\n
    #<\/span>html-api<\/a>, #<\/span>html-api-progress-report<\/a>, #<\/span>progress-report<\/a><\/p>
It\u2019s easy to point out issues with wp_kses()<\/code>, but it\u2019s much harder to classify if those issues warrant change or not. There is essentially one value leading the decisions in these cases: don\u2019t make wp_kses()<\/code> worse<\/em> than it was. This manifests in a couple of ways: for normative runs it should reproduce the existing normative behaviors; but for cases where expectations are already broken, there is no need to retain those broken behaviors. These decisions are also made against the backdrop of the security-sensitive role that wp_kses()<\/code> plays \u2014 its purpose is to prevent misuse, so some changes will result from diligence in hardening despite a regretful change in behavior8<\/a><\/sup>.<\/p>\n\n\n\n