Add placeholder compilation skeleton to WP_HTML_Template

Add $compiled property and get_placeholders() accessor. The compile()
method is stubbed and will be implemented to extract placeholder
positions, lengths, and contexts from the template.

Author: sirreal

src/wp-includes/html-api/class-wp-html-template.php

@@ -19,6 +19,44 @@ class WP_HTML_Template {
 
 	private array $replacements = array();
 
+	/**
+	 * Compiled placeholder metadata.
+	 *
+	 * Array of placeholder_name => array with keys:
+	 * - 'offsets': array of [start, length] pairs for each occurrence
+	 * - 'context': 'text' or 'attribute' (attribute takes precedence)
+	 *
+	 * @since 7.0.0
+	 * @var array|null
+	 */
+	private ?array $compiled = null;
+
+	/**
+	 * Returns the compiled placeholder metadata.
+	 *
+	 * Triggers compilation if not already done.
+	 *
+	 * @since 7.0.0
+	 *
+	 * @return array Associative array of placeholder_name => metadata.
+	 */
+	public function get_placeholders(): array {
+		$this->compile();
+		return $this->compiled;
+	}
+
+	/**
+	 * Compiles the template to extract placeholder metadata.
+	 *
+	 * @since 7.0.0
+	 */
+	private function compile(): void {
+		if ( null !== $this->compiled ) {
+			return;
+		}
+		$this->compiled = array();
+	}
+
 	private function __construct( string $template_string, array $replacements ) {
 		$this->template_string = $template_string;
 		$this->replacements    = $replacements;

tests/phpunit/tests/html-api/wpHtmlTemplate.php

@@ -754,4 +754,22 @@ public static function data_pre_element_leading_newline() {
 			),
 		);
 	}
+
+	/**
+	 * Verifies that get_placeholders returns placeholder metadata.
+	 *
+	 * @ticket 60229
+	 *
+	 * @covers ::get_placeholders
+	 */
+	public function test_get_placeholders_returns_metadata() {
+		$template = T::from( '<p class="</%class>"></%content></p>' );
+
+		$placeholders = $template->get_placeholders();
+
+		$this->assertArrayHasKey( 'class', $placeholders );
+		$this->assertArrayHasKey( 'content', $placeholders );
+		$this->assertSame( 'attribute', $placeholders['class']['context'] );
+		$this->assertSame( 'text', $placeholders['content']['context'] );
+	}
 }