Add validation warnings to bind()

Trigger _doing_it_wrong() for:
- Missing replacement keys (placeholder without value)
- Unused replacement keys (value without placeholder)
- Template values in attribute context

Share compiled data between original and bound template instances
for efficiency.

Author: sirreal

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

@@ -183,13 +183,98 @@ public static function from( string $template ): static {
 	/**
 	 * Returns a new immutable instance with replacements bound.
 	 *
+	 * Triggers compilation if not already done. Validates replacements:
+	 * - Warns if a placeholder has no corresponding replacement
+	 * - Warns if a replacement key has no corresponding placeholder
+	 * - Warns if a template is used in attribute context
+	 *
 	 * @since 7.0.0
 	 *
 	 * @param array $replacements The replacement values.
 	 * @return static A new template instance with the replacements bound.
 	 */
 	public function bind( array $replacements ): static {
-		return new static( $this->template_string, $replacements );
+		$this->compile();
+
+		// Build a lookup of placeholder keys from compiled data.
+		$placeholder_keys = array();
+		foreach ( $this->compiled as $placeholder => $info ) {
+			$placeholder = (string) $placeholder;
+			$placeholder_keys[ $placeholder ] = true;
+			if ( ctype_digit( $placeholder ) ) {
+				$placeholder_keys[ (int) $placeholder ] = true;
+			}
+		}
+
+		// Build a lookup of replacement keys.
+		$replacement_keys = array();
+		foreach ( $replacements as $key => $value ) {
+			$replacement_keys[ (string) $key ] = true;
+			if ( is_int( $key ) ) {
+				$replacement_keys[ $key ] = true;
+			}
+		}
+
+		// Check for missing keys (placeholder without replacement).
+		foreach ( $this->compiled as $placeholder => $info ) {
+			$placeholder = (string) $placeholder;
+			$found       = isset( $replacement_keys[ $placeholder ] );
+			if ( ! $found && ctype_digit( $placeholder ) ) {
+				$found = isset( $replacement_keys[ (int) $placeholder ] ) || array_key_exists( (int) $placeholder, $replacements );
+			}
+			if ( ! $found ) {
+				_doing_it_wrong(
+					__METHOD__,
+					sprintf(
+						'Missing replacement for placeholder: %s',
+						$placeholder
+					),
+					'7.0.0'
+				);
+			}
+		}
+
+		// Check for unused keys (replacement without placeholder).
+		foreach ( $replacements as $key => $value ) {
+			$str_key = (string) $key;
+			$found   = isset( $placeholder_keys[ $key ] ) || isset( $placeholder_keys[ $str_key ] );
+			if ( ! $found ) {
+				_doing_it_wrong(
+					__METHOD__,
+					sprintf(
+						'Unused replacement key: %s',
+						$key
+					),
+					'7.0.0'
+				);
+			}
+		}
+
+		// Check for templates in attribute context.
+		foreach ( $this->compiled as $placeholder => $info ) {
+			$placeholder = (string) $placeholder;
+			if ( 'attribute' !== $info['context'] ) {
+				continue;
+			}
+
+			$key   = ctype_digit( $placeholder ) ? (int) $placeholder : $placeholder;
+			$value = $replacements[ $key ] ?? $replacements[ $placeholder ] ?? null;
+
+			if ( $value instanceof self ) {
+				_doing_it_wrong(
+					__METHOD__,
+					sprintf(
+						'Template cannot be used in attribute context: %s',
+						$placeholder
+					),
+					'7.0.0'
+				);
+			}
+		}
+
+		$new = new static( $this->template_string, $replacements );
+		$new->compiled = $this->compiled;
+		return $new;
 	}
 
 	/**

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

@@ -135,6 +135,8 @@ public function test_escapes_ampersand_to_prevent_character_reference_injection(
 	 * @covers ::from
 	 * @covers ::bind
 	 * @covers ::render
+	 *
+	 * @expectedIncorrectUsage WP_HTML_Template::bind
 	 */
 	public function test_rejects_nested_template_in_attribute_value() {
 		$template_string = '<meta name="not-allowed" description="</%html>">';
@@ -755,6 +757,48 @@ public static function data_pre_element_leading_newline() {
 		);
 	}
 
+	/**
+	 * Verifies bind() warns on missing replacement key.
+	 *
+	 * @ticket 60229
+	 *
+	 * @covers ::bind
+	 *
+	 * @expectedIncorrectUsage WP_HTML_Template::bind
+	 */
+	public function test_bind_warns_on_missing_key() {
+		$template = T::from( '<p></%name> </%age></p>' );
+		$template->bind( array( 'name' => 'Alice' ) );
+	}
+
+	/**
+	 * Verifies bind() warns on unused replacement key.
+	 *
+	 * @ticket 60229
+	 *
+	 * @covers ::bind
+	 *
+	 * @expectedIncorrectUsage WP_HTML_Template::bind
+	 */
+	public function test_bind_warns_on_unused_key() {
+		$template = T::from( '<p></%name></p>' );
+		$template->bind( array( 'name' => 'Alice', 'extra' => 'ignored' ) );
+	}
+
+	/**
+	 * Verifies bind() warns when template used in attribute context.
+	 *
+	 * @ticket 60229
+	 *
+	 * @covers ::bind
+	 *
+	 * @expectedIncorrectUsage WP_HTML_Template::bind
+	 */
+	public function test_bind_warns_on_template_in_attribute_context() {
+		$template = T::from( '<meta content="</%html>">' );
+		$template->bind( array( 'html' => T::from( '<b>nested</b>' ) ) );
+	}
+
 	/**
 	 * Verifies that get_placeholders returns placeholder metadata.
 	 *