1<?php
  2/**
  3 * Block Bindings API
  4 *
  5 * Contains functions for managing block bindings in WordPress.
  6 *
  7 * @package WordPress
  8 * @subpackage Block Bindings
  9 * @since 6.5.0
 10 */
 11
 12/**
 13 * Registers a new block bindings source.
 14 *
 15 * Registering a source consists of defining a **name** for that source and a callback function specifying
 16 * how to get a value from that source and pass it to a block attribute.
 17 *
 18 * Once a source is registered, any block that supports the Block Bindings API can use a value
 19 * from that source by setting its `metadata.bindings` attribute to a value that refers to the source.
 20 *
 21 * Note that `register_block_bindings_source()` should be called from a handler attached to the `init` hook.
 22 *
 23 *
 24 * ## Example
 25 *
 26 * ### Registering a source
 27 *
 28 * First, you need to define a function that will be used to get the value from the source.
 29 *
 30 *     function my_plugin_get_custom_source_value( array $source_args, $block_instance, string $attribute_name ) {
 31 *       // Your custom logic to get the value from the source.
 32 *       // For example, you can use the `$source_args` to look up a value in a custom table or get it from an external API.
 33 *       $value = $source_args['key'];
 34 *
 35 *       return "The value passed to the block is: $value"
 36 *     }
 37 *
 38 * The `$source_args` will contain the arguments passed to the source in the block's
 39 * `metadata.bindings` attribute. See the example in the "Usage in a block" section below.
 40 *
 41 *     function my_plugin_register_block_bindings_sources() {
 42 *       register_block_bindings_source( 'my-plugin/my-custom-source', array(
 43 *         'label'              => __( 'My Custom Source', 'my-plugin' ),
 44 *         'get_value_callback' => 'my_plugin_get_custom_source_value',
 45 *       ) );
 46 *     }
 47 *     add_action( 'init', 'my_plugin_register_block_bindings_sources' );
 48 *
 49 * ### Usage in a block
 50 *
 51 * In a block's `metadata.bindings` attribute, you can specify the source and
 52 * its arguments. Such a block will use the source to override the block
 53 * attribute's value. For example:
 54 *
 55 *     <!-- wp:paragraph {
 56 *       "metadata": {
 57 *         "bindings": {
 58 *           "content": {
 59 *             "source": "my-plugin/my-custom-source",
 60 *             "args": {
 61 *               "key": "you can pass any custom arguments here"
 62 *             }
 63 *           }
 64 *         }
 65 *       }
 66 *     } -->
 67 *     <p>Fallback text that gets replaced.</p>
 68 *     <!-- /wp:paragraph -->
 69 *
 70 * @since 6.5.0
 71 *
 72 * @param string $source_name       The name of the source. It must be a string containing a namespace prefix, i.e.
 73 *                                  `my-plugin/my-custom-source`. It must only contain lowercase alphanumeric
 74 *                                  characters, the forward slash `/` and dashes.
 75 * @param array  $source_properties {
 76 *     The array of arguments that are used to register a source.
 77 *
 78 *     @type string   $label              The label of the source.
 79 *     @type callable $get_value_callback A callback executed when the source is processed during block rendering.
 80 *                                        The callback should have the following signature:
 81 *
 82 *                                        `function( $source_args, $block_instance, $attribute_name ): mixed`
 83 *                                            - @param array    $source_args    Array containing source arguments
 84 *                                                                              used to look up the override value,
 85 *                                                                              i.e. {"key": "foo"}.
 86 *                                            - @param WP_Block $block_instance The block instance.
 87 *                                            - @param string   $attribute_name The name of an attribute.
 88 *                                        The callback has a mixed return type; it may return a string to override
 89 *                                        the block's original value, null, false to remove an attribute, etc.
 90 *     @type string[] $uses_context       Optional. Array of values to add to block `uses_context` needed by the source.
 91 * }
 92 * @return WP_Block_Bindings_Source|false Source when the registration was successful, or `false` on failure.
 93 */
 94function register_block_bindings_source( string $source_name, array $source_properties ) {
 95	return WP_Block_Bindings_Registry::get_instance()->register( $source_name, $source_properties );
 96}
 97
 98/**
 99 * Unregisters a block bindings source.
100 *
101 * @since 6.5.0
102 *
103 * @param string $source_name Block bindings source name including namespace.
104 * @return WP_Block_Bindings_Source|false The unregistered block bindings source on success and `false` otherwise.
105 */
106function unregister_block_bindings_source( string $source_name ) {
107	return WP_Block_Bindings_Registry::get_instance()->unregister( $source_name );
108}
109
110/**
111 * Retrieves the list of all registered block bindings sources.
112 *
113 * @since 6.5.0
114 *
115 * @return WP_Block_Bindings_Source[] The array of registered block bindings sources.
116 */
117function get_all_registered_block_bindings_sources() {
118	return WP_Block_Bindings_Registry::get_instance()->get_all_registered();
119}
120
121/**
122 * Retrieves a registered block bindings source.
123 *
124 * @since 6.5.0
125 *
126 * @param string $source_name The name of the source.
127 * @return WP_Block_Bindings_Source|null The registered block bindings source, or `null` if it is not registered.
128 */
129function get_block_bindings_source( string $source_name ) {
130	return WP_Block_Bindings_Registry::get_instance()->get_registered( $source_name );
131}
132
133/**
134 * Retrieves the list of block attributes supported by block bindings.
135 *
136 * @since 6.9.0
137 *
138 * @param string $block_type The block type whose supported attributes are being retrieved.
139 * @return array The list of block attributes that are supported by block bindings.
140 */
141function get_block_bindings_supported_attributes( $block_type ) {
142	$block_bindings_supported_attributes = array(
143		'core/paragraph'          => array( 'content' ),
144		'core/heading'            => array( 'content' ),
145		'core/image'              => array( 'id', 'url', 'title', 'alt', 'caption' ),
146		'core/button'             => array( 'url', 'text', 'linkTarget', 'rel' ),
147		'core/post-date'          => array( 'datetime' ),
148		'core/navigation-link'    => array( 'url' ),
149		'core/navigation-submenu' => array( 'url' ),
150	);
151
152	$supported_block_attributes =
153		isset( $block_type, $block_bindings_supported_attributes[ $block_type ] ) ?
154			$block_bindings_supported_attributes[ $block_type ] :
155			array();
156
157	/**
158	 * Filters the supported block attributes for block bindings.
159	 *
160	 * @since 6.9.0
161	 *
162	 * @param string[] $supported_block_attributes The block's attributes that are supported by block bindings.
163	 * @param string   $block_type                 The block type whose attributes are being filtered.
164	 */
165	$supported_block_attributes = apply_filters(
166		'block_bindings_supported_attributes',
167		$supported_block_attributes,
168		$block_type
169	);
170
171	/**
172	 * Filters the supported block attributes for block bindings.
173	 *
174	 * The dynamic portion of the hook name, `$block_type`, refers to the block type
175	 * whose attributes are being filtered.
176	 *
177	 * @since 6.9.0
178	 *
179	 * @param string[] $supported_block_attributes The block's attributes that are supported by block bindings.
180	 */
181	$supported_block_attributes = apply_filters(
182		"block_bindings_supported_attributes_{$block_type}",
183		$supported_block_attributes
184	);
185
186	return $supported_block_attributes;
187}
188