Add the Block Bindings API

src/wp-includes/block-bindings/block-bindings.php

@@ -0,0 +1,72 @@
+<?php
+/**
+ * Block Bindings API
+ *
+ * This file contains functions for managing block bindings in WordPress.
+ *
+ * @since 6.5.0
+ * @package WordPress
+ */
+
+/**
+ * Retrieves the singleton instance of WP_Block_Bindings.
+ *
+ * @since 6.5.0
+ *
+ * @return WP_Block_Bindings The WP_Block_Bindings instance.
+ */
+function wp_block_bindings() {
+	static $instance = null;
+	if ( is_null( $instance ) ) {
+		$instance = new WP_Block_Bindings();
+	}
+	return $instance;
+}
+
+
+/**
+ * Registers a new source for block bindings.
+ *
+ * @since 6.5.0
+ *
+ * @param string   $source_name The name of the source.
+ * @param string   $label The label of the source.
+ * @param callable $apply The callback executed when the source is processed during block rendering. The callable should have the following signature:
+ *                        function (object $source_attrs, object $block_instance, string $attribute_name): string
+ *                        - object $source_attrs: Object containing source ID used to look up the override value, i.e. {"value": "{ID}"}.
+ *                        - object $block_instance: The block instance.
+ *                        - string $attribute_name: The name of an attribute used to retrieve an override value from the block context.
+ *                        The callable should return a string that will be used to override the block's original value.
+ * @return void
+ */
+function wp_block_bindings_register_source( $source_name, $label, $apply ) {
+	wp_block_bindings()->register_source( $source_name, $label, $apply );
+}
+
+
+/**
+ * Retrieves the list of registered block sources.
+ *
+ * @since 6.5.0
+ *
+ * @return array The list of registered block sources.
+ */
+function wp_block_bindings_get_sources() {
+	return wp_block_bindings()->get_sources();
+}
+
+
+/**
+ * Replaces the HTML content of a block based on the provided source value.
+ *
+ * @since 6.5.0
+ *
+ * @param string $block_content Block content.
+ * @param string $block_name The name of the block to process.
+ * @param string $block_attr The attribute of the block we want to process.
+ * @param string $source_value The value used to replace the HTML.
+ * @return string The modified block content.
+ */
+function wp_block_bindings_replace_html( $block_content, $block_name, $block_attr, $source_value ) {
+	return wp_block_bindings()->replace_html( $block_content, $block_name, $block_attr, $source_value );
+}

src/wp-includes/block-bindings/class-wp-block-bindings.php

@@ -0,0 +1,169 @@
+<?php
+/**
+ * Block Bindings API: WP_Block_Bindings class.
+ *
+ * Support for overriding content in blocks by connecting them to different sources.
+ *
+ * @package WordPress
+ * @subpackage Block Bindings
+ */
+
+/**
+ * Core class used to define supported blocks, register sources, and populate HTML with content from those sources.
+ *
+ *  @since 6.5.0
+ */
+class WP_Block_Bindings {
+
+	/**
+	 * Holds the registered block bindings sources, keyed by source identifier.
+	 *
+	 * @since 6.5.0
+	 *
+	 * @var array
+	 */
+	private $sources = array();
+
+	/**
+	 * Function to register a new block binding source.
+	 *
+	 * Sources are used to override block's original attributes with a value
+	 * coming from the source. Once a source is registered, it can be used by a
+	 * block by setting its `metadata.bindings` attribute to a value that refers
+	 * to the source.
+	 *
+	 * @since 6.5.0
+	 *
+	 * @param string   $source_name The name of the source.
+	 * @param string   $label The label of the source.
+	 * @param callable $apply The callback executed when the source is processed during block rendering. The callable should have the following signature:
+	 *                        function (object $source_attrs, object $block_instance, string $attribute_name): string
+	 *                        - object $source_attrs: Object containing source ID used to look up the override value, i.e. {"value": "{ID}"}.
+	 *                        - object $block_instance: The block instance.
+	 *                        - string $attribute_name: The name of an attribute used to retrieve an override value from the block context.
+	 *                        The callable should return a string that will be used to override the block's original value.
+	 *
+	 * @return void
+	 */
+	public function register_source( $source_name, $label, $apply ) {
+		$this->sources[ $source_name ] = array(
+			'label' => $label,
+			'apply' => $apply,
+		);
+	}
+
+	/**
+	 * Depending on the block attributes, replace the HTML based on the value returned by the source.
+	 *
+	 * @since 6.5.0
+	 *
+	 * @param string $block_content Block content.
+	 * @param string $block_name The name of the block to process.
+	 * @param string $block_attr The attribute of the block we want to process.
+	 * @param string $source_value The value used to replace the HTML.
+	 */
+	public function replace_html( $block_content, $block_name, $block_attr, $source_value ) {
+		$block_type = WP_Block_Type_Registry::get_instance()->get_registered( $block_name );
+		if ( null === $block_type || ! isset( $block_type->attributes[ $block_attr ] ) ) {
+			return $block_content;
+		}
+
+		// Depending on the attribute source, the processing will be different.
+		switch ( $block_type->attributes[ $block_attr ]['source'] ) {
+			case 'html':
+			case 'rich-text':
+				$block_reader = new WP_HTML_Tag_Processor( $block_content );
+
+				// TODO: Support for CSS selectors whenever they are ready in the HTML API.
+				// In the meantime, support comma-separated selectors by exploding them into an array.
+				$selectors = explode( ',', $block_type->attributes[ $block_attr ]['selector'] );
+				// Add a bookmark to the first tag to be able to iterate over the selectors.
+				$block_reader->next_tag();
+				$block_reader->set_bookmark( 'iterate-selectors' );
+
+				// TODO: This shouldn't be needed when the `set_inner_html` function is ready.
+				// Store the parent tag and its attributes to be able to restore them later in the button.
+				// The button block has a wrapper while the paragraph and heading blocks don't.
+				if ( 'core/button' === $block_name ) {
+					$button_wrapper                 = $block_reader->get_tag();
+					$button_wrapper_attribute_names = $block_reader->get_attribute_names_with_prefix( '' );
+					$button_wrapper_attrs           = array();
+					foreach ( $button_wrapper_attribute_names as $name ) {
+						$button_wrapper_attrs[ $name ] = $block_reader->get_attribute( $name );
+					}
+				}
+
+				foreach ( $selectors as $selector ) {
+					// If the parent tag, or any of its children, matches the selector, replace the HTML.
+					if ( strcasecmp( $block_reader->get_tag( $selector ), $selector ) === 0 || $block_reader->next_tag(
+						array(
+							'tag_name' => $selector,
+						)
+					) ) {
+						$block_reader->release_bookmark( 'iterate-selectors' );
+
+						// TODO: Use `set_inner_html` method whenever it's ready in the HTML API.
+						// Until then, it is hardcoded for the paragraph, heading, and button blocks.
+						// Store the tag and its attributes to be able to restore them later.
+						$selector_attribute_names = $block_reader->get_attribute_names_with_prefix( '' );
+						$selector_attrs           = array();
+						foreach ( $selector_attribute_names as $name ) {
+							$selector_attrs[ $name ] = $block_reader->get_attribute( $name );
+						}
+						$selector_markup = "<$selector>" . esc_html( $source_value ) . "</$selector>";
+						$amended_content = new WP_HTML_Tag_Processor( $selector_markup );
+						$amended_content->next_tag();
+						foreach ( $selector_attrs as $attribute_key => $attribute_value ) {
+							$amended_content->set_attribute( $attribute_key, $attribute_value );
+						}
+						if ( 'core/paragraph' === $block_name || 'core/heading' === $block_name ) {
+							return $amended_content->get_updated_html();
+						}
+						if ( 'core/button' === $block_name ) {
+							$button_markup  = "<$button_wrapper>{$amended_content->get_updated_html()}</$button_wrapper>";
+							$amended_button = new WP_HTML_Tag_Processor( $button_markup );
+							$amended_button->next_tag();
+							foreach ( $button_wrapper_attrs as $attribute_key => $attribute_value ) {
+								$amended_button->set_attribute( $attribute_key, $attribute_value );
+							}
+							return $amended_button->get_updated_html();
+						}
+					} else {
+						$block_reader->seek( 'iterate-selectors' );
+					}
+				}
+				$block_reader->release_bookmark( 'iterate-selectors' );
+				return $block_content;
+
+			case 'attribute':
+				$amended_content = new WP_HTML_Tag_Processor( $block_content );
+				if ( ! $amended_content->next_tag(
+					array(
+						// TODO: build the query from CSS selector.
+						'tag_name' => $block_type->attributes[ $block_attr ]['selector'],
+					)
+				) ) {
+					return $block_content;
+				}
+				$amended_content->set_attribute( $block_type->attributes[ $block_attr ]['attribute'], esc_attr( $source_value ) );
+				return $amended_content->get_updated_html();
+				break;
+
+			default:
+				return $block_content;
+				break;
+		}
+		return;
+	}
+
+	/**
+	 * Retrieves the list of registered block sources.
+	 *
+	 * @since 6.5.0
+	 *
+	 * @return array The array of registered sources.
+	 */
+	public function get_sources() {
+		return $this->sources;
+	}
+}

src/wp-includes/block-bindings/sources/pattern.php

@@ -0,0 +1,21 @@
+<?php
+/**
+ * The "pattern" source for the Block Bindings API. This source is used by the
+ * Partially Synced Patterns.
+ *
+ * @since 6.5.0
+ * @package WordPress
+ */
+function pattern_source_callback( $source_attrs, $block_instance, $attribute_name ) {
+	if ( ! _wp_array_get( $block_instance->attributes, array( 'metadata', 'id' ), false ) ) {
+		return null;
+	}
+	$block_id = $block_instance->attributes['metadata']['id'];
+	return _wp_array_get( $block_instance->context, array( 'pattern/overrides', $block_id, $attribute_name ), null );
+}
+
+wp_block_bindings_register_source(
+	'pattern_attributes',
+	__( 'Pattern Attributes' ),
+	'pattern_source_callback'
+);

src/wp-includes/block-bindings/sources/post-meta.php

@@ -0,0 +1,24 @@
+<?php
+/**
+ * Add the post_meta source to the Block Bindings API.
+ *
+ * @since 6.5.0
+ * @package WordPress
+ */
+function post_meta_source_callback( $source_attrs ) {
+	// Use the postId attribute if available
+	if ( isset( $source_attrs['postId'] ) ) {
+		$post_id = $source_attrs['postId'];
+	} else {
+		// $block_instance->context['postId'] is not available in the Image block.
+		$post_id = get_the_ID();
+	}
+
+	return get_post_meta( $post_id, $source_attrs['value'], true );
+}
+
+wp_block_bindings_register_source(
+	'post_meta',
+	__( 'Post Meta' ),
+	'post_meta_source_callback'
+);

src/wp-includes/blocks.php

@@ -2083,3 +2083,98 @@ function _wp_footnotes_force_filtered_html_on_import_filter( $arg ) {
 	}
 	return $arg;
 }
+
+
+/**
+ * Processes the block bindings in block's attributes.
+ *
+ * A block might contain bindings in its attributes. Bindings are mappings
+ * between an attribute of the block and a source. A "source" is a function
+ * registered with `wp_block_bindings_register_source()` that defines how to
+ * retrieve a value from outside the block, e.g. from post meta.
+ *
+ * This function will process those bindings and replace the HTML with the value of the binding.
+ * The value is retrieved from the source of the binding.
+ *
+ * ### Example
+ *
+ * The "bindings" property for an Image block might look like this:
+ *
+ * ```json
+ * {
+ *   "metadata": {
+ *     "bindings": {
+ *       "title": {
+ *         "source": {
+ *           "name": "post_meta",
+ *           "attributes": { "value": "text_custom_field" }
+ *         }
+ *       },
+ *       "url": {
+ *         "source": {
+ *           "name": "post_meta",
+ *           "attributes": { "value": "url_custom_field" }
+ *         }
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * The above example will replace the `title` and `url` attributes of the Image
+ * block with the values of the `text_custom_field` and `url_custom_field` post meta.
+ *
+ * @access private
+ * @since 6.5.0
+ *
+ * @param string   $block_content Block content.
+ * @param array    $block The full block, including name and attributes.
+ * @param WP_Block $block_instance The block instance.
+ */
+function _process_block_bindings( $block_content, $block, $block_instance ) {
+
+	// Allowed blocks that support block bindings.
+	// TODO: Look for a mechanism to opt-in for this. Maybe adding a property to block attributes?
+	$allowed_blocks = array(
+		'core/paragraph' => array( 'content' ),
+		'core/heading'   => array( 'content' ),
+		'core/image'     => array( 'url', 'title', 'alt' ),
+		'core/button'    => array( 'url', 'text' ),
+	);
+
+	// If the block doesn't have the bindings property or isn't one of the allowed block types, return.
+	if ( ! isset( $block['attrs']['metadata']['bindings'] ) || ! isset( $allowed_blocks[ $block_instance->name ] ) ) {
+		return $block_content;
+	}
+
+	$block_bindings_sources = wp_block_bindings_get_sources();
+	$modified_block_content = $block_content;
+	foreach ( $block['attrs']['metadata']['bindings'] as $binding_attribute => $binding_source ) {
+
+		// If the attribute is not in the list, process next attribute.
+		if ( ! in_array( $binding_attribute, $allowed_blocks[ $block_instance->name ], true ) ) {
+			continue;
+		}
+		// If no source is provided, or that source is not registered, process next attribute.
+		if ( ! isset( $binding_source['source'] ) || ! isset( $binding_source['source']['name'] ) || ! isset( $block_bindings_sources[ $binding_source['source']['name'] ] ) ) {
+			continue;
+		}
+
+		$source_callback = $block_bindings_sources[ $binding_source['source']['name'] ]['apply'];
+		// Get the value based on the source.
+		if ( ! isset( $binding_source['source']['attributes'] ) ) {
+			$source_args = array();
+		} else {
+			$source_args = $binding_source['source']['attributes'];
+		}
+		$source_value = $source_callback( $source_args, $block_instance, $binding_attribute );
+		// If the value is null, process next attribute.
+		if ( is_null( $source_value ) ) {
+			continue;
+		}
+
+		// Process the HTML based on the block and the attribute.
+		$modified_block_content = wp_block_bindings_replace_html( $modified_block_content, $block_instance->name, $binding_attribute, $source_value );
+	}
+	return $modified_block_content;
+}

src/wp-includes/class-wp-block.php

@@ -280,6 +280,10 @@ public function render( $options = array() ) {
 			}
 		}
 
+		// Process the block bindings for this block, if any are registered. This
+		// will replace the block content with the value from a registered binding source.
+		$block_content = _process_block_bindings( $block_content, $this->parsed_block, $this );
+
 		/**
 		 * Filters the content of a single block.
 		 *