WP_HTML_Tag_Processor: Inject dynamic data to block HTML markup in PHP (#42485)

Introduce WP_HTML_Tag_Processor for reliably modifying HTML attributes.

Dynamic blocks often need to inject a CSS class name or set <img src /> in the rendered block HTML markup but lack the means to do so. WP_HTML_Tag_Processor solves this problem.

It scans through an HTML document to find specific tags, then transforms those tags by adding, removing, or updating the values of the HTML attributes within that tag (opener).

Importantly, it does not fully parse HTML or _recurse_ into the HTML structure. Instead WP_HTML_Tag_Processor scans linearly through a document and only parses the HTML tag openers.

Example:

```
$p = new WP_HTML_Tag_Processor('<div id="first"><img /></div>');
$p->next_tag('img')->set_attribute('src', '/wp-content/logo.png');
echo $p;
// <div id="first"><img src="/wp-content/logo.png" /></div>
```

For more details and context, see the original GitHub Pull Request at #42485 and the overview issue at #44410.

Co-authored-by: Adam Zieliński <[email protected]>
Co-authored-by: Dennis Snell <[email protected]>
Co-authored-by: Grzegorz Ziółkowski <[email protected]>
Co-authored-by: Sören Wrede <[email protected]>
Co-authored-by: Colin Stewart <[email protected]>

Author: 5 people

lib/experimental/html/class-wp-html-attribute-token.php

@@ -0,0 +1,89 @@
+<?php
+/**
+ * HTML Tag Processor: Attribute token structure class.
+ *
+ * @package WordPress
+ * @subpackage HTML
+ * @since 6.1.0
+ */
+
+/**
+ * Data structure for the attribute token that allows to drastically improve performance.
+ *
+ * This class is for internal usage of the WP_HTML_Tag_Processor class.
+ *
+ * @access private
+ * @since 6.1.0
+ *
+ * @see WP_HTML_Tag_Processor
+ */
+class WP_HTML_Attribute_Token {
+	/**
+	 * Attribute name.
+	 *
+	 * @since 6.1.0
+	 * @var string
+	 */
+	public $name;
+
+	/**
+	 * Attribute value.
+	 *
+	 * @since 6.1.0
+	 * @var int
+	 */
+	public $value_starts_at;
+
+	/**
+	 * How many bytes the value occupies in the input HTML.
+	 *
+	 * @since 6.1.0
+	 * @var int
+	 */
+	public $value_length;
+
+	/**
+	 * The string offset where the attribute name starts.
+	 *
+	 * @since 6.1.0
+	 * @var int
+	 */
+	public $start;
+
+	/**
+	 * The string offset after the attribute value or its name.
+	 *
+	 * @since 6.1.0
+	 * @var int
+	 */
+	public $end;
+
+	/**
+	 * Whether the attribute is a boolean attribute with value `true`.
+	 *
+	 * @since 6.1.0
+	 * @var bool
+	 */
+	public $is_true;
+
+	/**
+	 * Constructor.
+	 *
+	 * @since 6.1.0
+	 *
+	 * @param string $name         Attribute name.
+	 * @param int    $value_start  Attribute value.
+	 * @param int    $value_length Number of bytes attribute value spans.
+	 * @param int    $start        The string offset where the attribute name starts.
+	 * @param int    $end          The string offset after the attribute value or its name.
+	 * @param bool   $is_true      Whether the attribute is a boolean attribute with true value.
+	 */
+	public function __construct( $name, $value_start, $value_length, $start, $end, $is_true ) {
+		$this->name            = $name;
+		$this->value_starts_at = $value_start;
+		$this->value_length    = $value_length;
+		$this->start           = $start;
+		$this->end             = $end;
+		$this->is_true         = $is_true;
+	}
+}