HTML API: Update Processing Instruction handling by sirreal · Pull Request #12424 · WordPress/wordpress-develop

sirreal · 2026-07-06T16:47:55Z

Handle Processing Instructions in the HTML API.

Processing instruction parsing has been updated in the HTML standard. <?processing instructions ?> were transformed into comments, but are now preserved.

See the processing instruction states in the standard.

Some doubts about parsing PI in some insertions modes came up while implementing this change. I've raised them with the standards:

Handle processing instruction tokens in head-noscript, template whatwg/html#12653
Add tests for processing instructions in templates and head noscript web-platform-tests/wpt#61120

~~See #12423 (merged here) for the test addition.~~ (landed in r62655)

Trac ticket: https://core.trac.wordpress.org/ticket/65582

Use of AI Tools

AI assistance: Yes
Tool(s): Claude
Model(s): Fable 5
Used for: Initial implementation.

This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See GitHub Pull Requests for Code Review in the Core Handbook for more details.

…essing-instruction-parse

Claude-Session: https://claude.ai/code/session_019T4FGdVaBpVbMRcBbQPehd

…oken fixtures Claude-Session: https://claude.ai/code/session_019T4FGdVaBpVbMRcBbQPehd

Claude-Session: https://claude.ai/code/session_019T4FGdVaBpVbMRcBbQPehd

…essing-instruction-parse

web-platform-tests/wpt@a315c38

The HTML standard has added Processing Instruction parsing. The HTML API needs updates to handle PI.

…essing-instruction-parse

github-actions · 2026-07-06T16:52:26Z

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

All changes will be lost when closing a tab with a Playground instance.
All changes will be lost when refreshing the page.
A fresh instance is created each time the link below is clicked.
Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

sirreal · 2026-07-06T18:00:37Z

 			case '#comment':
 			case '#funky-comment':
 			case '#presumptuous-tag':
+			case '#processing-instruction':


We'll assume this is the intention. This entire insertion mode is gone from the current version of the spec: #9298

sirreal · 2026-07-06T18:16:30Z

This adds PI handling to all the relevant insertion modes. PI handling is notably missing from two places:

This change currently follows the spec for in head noscript but inserts the token in template.

It's unclear whether these are an oversight or not. I've asked and will follow-up.

PI nodes exist and are parsed. Bogus comments are just bugos comments.

sirreal · 2026-07-07T15:57:27Z

+			/**
+			 * Processing instructions are serialized as `<?target data>`, not `<?target data?>`.
+			 * Both forms are parsed equivalently.
+			 *
+			 * @see https://html.spec.whatwg.org/multipage/parsing.html#serialising-html-fragments
+			 */
+			case '#processing-instruction':
+				/**
+				 * A final `?` is ignored when parsing a processing instruction. If the data ends
+				 * with `?`, it must be doubled to ensure its recognized as part of the data and
+				 * not the closing `?>` sequence.
+				 */
+				$data = $this->get_modifiable_text();
+				if ( str_ends_with( $data, '?' ) ) {
+					$data .= '?';
+				}
+				$html .= "<?{$this->get_tag()} {$data}>";
+				break;


whatwg/html#12654

github-actions · 2026-07-07T16:01:06Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Core Committers: Use this line as a base for the props when committing in SVN:

Props jonsurrell, dmsnell.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

dmsnell

@SInCE tag in HTML Processor

dmsnell · 2026-07-07T19:04:29Z

+			 * parsing: data with leading whitespace cannot be represented.
+			 */
+			if ( 0 !== strspn( $plaintext_content, " \t\f\r\n" ) ) {
+				return false;


Q? would it be pragmatic to trim this and call _doing_it_wrong()?

dmsnell · 2026-07-07T19:15:25Z

+				? '?>'
+				: '>';
+
+			$this->lexical_updates['modifiable text closer'] = new WP_HTML_Text_Replacement( $token_end, 0, $closer );


how about just a single update, the existing modifiable_text, and update get_modifiable_text() accordingly?

dmsnell · 2026-07-07T19:15:54Z

+	 * Processing instructions with an allowable target are parsed
+	 * into processing instruction nodes. The reserved `xml` and
+	 * `xml-stylesheet` targets, and targets with characters outside
+	 * an ASCII-representable subset, are turned into bogus comments.


this is another case for preserving PI_NODE_LOOKALIKE

dmsnell · 2026-07-07T19:16:39Z

+	 * `COMMENT_AS_INVALID_HTML`.
 	 *
 	 * @since 6.5.0
+	 * @deprecated 7.1.0 Use `COMMENT_AS_INVALID_HTML` instead.


why not preserve the extra lexical info that PI_NODE_LOOKALIKE provided? many a DSL are formed from these

…ocessing-instruction-parse

Replace the three coordinated replacements (separator, data, closer) with one replacement spanning from the start of the data through the end of the token, holding the raw syntax for that region. This removes the dependency on update ordering at shared offsets and the named-key lifecycle for the auxiliary replacements. The enqueued text is raw syntax rather than the data itself, so get_modifiable_text() now finds the data within a pending update by applying the same rules used when parsing the document. Claude-Session: https://claude.ai/code/session_01NKkom28VKTXSqDTDq5g3yS

Bogus comments of the form `<?target ... ?>` whose targets are not allowed in HTML processing instructions - the reserved `xml` and `xml-stylesheet` names and XML-valid names with characters like `:` and `.` - are again classified as COMMENT_AS_PI_NODE_LOOKALIKE, with the target exposed through get_tag() and the browser-visible text through get_full_comment_text(). Removes the deprecation of COMMENT_AS_PI_NODE_LOOKALIKE: valid processing instructions produce their own token type, but PI-like bogus comments remain distinguishable from other invalid HTML. Claude-Session: https://claude.ai/code/session_01NKkom28VKTXSqDTDq5g3yS

Serialization and modifiable text updates now always terminate a processing instruction with the explicit `?>` closer instead of preserving or emitting the bare `>` form. The closer's `?` is dropped when parsing, so this single form represents any data unambiguously - data ending in `?` no longer needs special doubling logic in the serializer, and the modifiable text setter no longer chooses between closer forms. The HTML fragment serialization algorithm specifies the `<?target data>` form, which cannot represent data ending in `?`. Claude-Session: https://claude.ai/code/session_01NKkom28VKTXSqDTDq5g3yS

The HTML Standard is being updated to serialize processing instructions with the `?>` closer, matching this serializer. Claude-Session: https://claude.ai/code/session_01NKkom28VKTXSqDTDq5g3yS

sirreal added 18 commits July 3, 2026 14:55

Tests: Update html5lib test data from WPT

2482ea1

Tests: Rename HTML API external suite to WPT

082b840

Tests: Update WPT workflow group name

f3c7b3e

Merge branch 'html-api-update-html5lib-wpt' into html-api/update-proc…

5646973

…essing-instruction-parse

Remove PI test skips

81d528c

Update and rename test structure

f51e56d

Update WPT dir

0faa100

Tag Processor: parse processing instructions per the HTML Standard

c2f47c8

Claude-Session: https://claude.ai/code/session_019T4FGdVaBpVbMRcBbQPehd

HTML Processor: handle and serialize processing instruction tokens

e3f60f6

Claude-Session: https://claude.ai/code/session_019T4FGdVaBpVbMRcBbQPehd

WPT harness: serialize processing instructions in tree dumps, skip br…

134041e

…oken fixtures Claude-Session: https://claude.ai/code/session_019T4FGdVaBpVbMRcBbQPehd

HTML Processor: only rewrite IMAGE to IMG for tag tokens

c4cd77d

Claude-Session: https://claude.ai/code/session_019T4FGdVaBpVbMRcBbQPehd

Merge branch 'html-api-update-html5lib-wpt' into html-api/update-proc…

d7e0898

…essing-instruction-parse

Update to latest version a315c382eac

5db5f4b

web-platform-tests/wpt@a315c38

Merge branch 'trunk' into html-api-update-html5lib-wpt

c20858c

Add necessary PI skips

f102e61

The HTML standard has added Processing Instruction parsing. The HTML API needs updates to handle PI.

Revert documentation change

f134e89

Remove unused JS files

45e1452

Merge branch 'html-api-update-html5lib-wpt' into html-api/update-proc…

f5ad313

…essing-instruction-parse

sirreal added 2 commits July 6, 2026 18:56

Simplify PI normalization comment

aaf76c2

Ensure PI data ending in ? is serialized correctly

0c7db12

sirreal commented Jul 6, 2026

View reviewed changes

sirreal added 7 commits July 6, 2026 20:18

Update PI state docs

ca3d849

Use "processing instruction" state

4fa13c8

Update PI example

d655770

Drop PI lookalike comments

24eecae

PI nodes exist and are parsed. Bogus comments are just bugos comments.

Add phpstan-return to get_token_type

d94eca0

Support set_modifiable_text on PI

b87ea5b

Add and improve test method types

860a887

sirreal added 4 commits July 7, 2026 14:58

Merge branch 'trunk' into html-api/update-processing-instruction-parse

cc427f0

Update tree output for updated WPT

0721a4b

Merge branch 'trunk' into html-api/update-processing-instruction-parse

a66d0d4

Use 2-start comments for better ide formatting

2c74364

sirreal commented Jul 7, 2026

View reviewed changes

sirreal marked this pull request as ready for review July 7, 2026 16:00

sirreal marked this pull request as draft July 7, 2026 16:01

Handle PI in build_visual_html_tree/assertEqualHTML

cb61c12

dmsnell reviewed Jul 7, 2026

View reviewed changes

sirreal added 6 commits July 8, 2026 18:57

Add visual tree tests

754a7dc

Merge remote-tracking branch 'upstream/trunk' into html-api/update-pr…

c344e29

…ocessing-instruction-parse

Remove stale claim about the spec PI serialization form

4eee7ed

The HTML Standard is being updated to serialize processing instructions with the `?>` closer, matching this serializer. Claude-Session: https://claude.ai/code/session_01NKkom28VKTXSqDTDq5g3yS

sirreal commented Jul 8, 2026

View reviewed changes

Comment thread src/wp-includes/html-api/class-wp-html-processor.php Outdated

Clarify why PI support was added

a2fbcb6

sirreal commented Jul 8, 2026

View reviewed changes

Comment thread tests/phpunit/tests/build-visual-html-tree.php Outdated

sirreal commented Jul 8, 2026

View reviewed changes

Comment thread tests/phpunit/includes/build-visual-html-tree.php Outdated

sirreal added 5 commits July 8, 2026 21:42

Add/update PI bogus comment tests

b8eaaa3

Add pi lookalike token test

1f6e2b4

Fix build_visual_html PI handling, improve test

71724f2

Update XML pi-lookalike comment

7b4bd4b

Merge branch 'trunk' into html-api/update-processing-instruction-parse

692cbd1

sirreal marked this pull request as ready for review July 8, 2026 20:02

Simplify serialize PI explanation.

7bab900

sirreal requested a review from dmsnell July 8, 2026 20:03

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

HTML API: Update Processing Instruction handling#12424

HTML API: Update Processing Instruction handling#12424
sirreal wants to merge 45 commits into
WordPress:trunkfrom
sirreal:html-api/update-processing-instruction-parse

sirreal commented Jul 6, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jul 6, 2026

Uh oh!

sirreal Jul 6, 2026 •

edited

Loading

Uh oh!

sirreal commented Jul 6, 2026

Uh oh!

sirreal Jul 7, 2026

Uh oh!

github-actions Bot commented Jul 7, 2026 •

edited

Loading

Uh oh!

dmsnell left a comment

Uh oh!

Uh oh!

dmsnell Jul 7, 2026

Uh oh!

dmsnell Jul 7, 2026

Uh oh!

dmsnell Jul 7, 2026

Uh oh!

dmsnell Jul 7, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

sirreal commented Jul 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Use of AI Tools

Uh oh!

github-actions Bot commented Jul 6, 2026

Test using WordPress Playground

Some things to be aware of

Uh oh!

sirreal Jul 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sirreal commented Jul 6, 2026

Uh oh!

sirreal Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dmsnell left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

dmsnell Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

dmsnell Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

dmsnell Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

dmsnell Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

sirreal commented Jul 6, 2026 •

edited

Loading

sirreal Jul 6, 2026 •

edited

Loading

github-actions Bot commented Jul 7, 2026 •

edited

Loading