Merging upstream version 6.5+dfsg1.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 131 insertions, 0 deletions

diff --git a/wp-includes/block-bindings.php b/wp-includes/block-bindings.php
new file mode 100644
index 0000000..cee00e2
--- /dev/null
+++ b/wp-includes/block-bindings.php
@@ -0,0 +1,131 @@
+<?php
+/**
+ * Block Bindings API
+ *
+ * Contains functions for managing block bindings in WordPress.
+ *
+ * @package WordPress
+ * @subpackage Block Bindings
+ * @since 6.5.0
+ */
+
+/**
+ * Registers a new block bindings source.
+ *
+ * Registering a source consists of defining a **name** for that source and a callback function specifying
+ * how to get a value from that source and pass it to a block attribute.
+ *
+ * Once a source is registered, any block that supports the Block Bindings API can use a value
+ * from that source by setting its `metadata.bindings` attribute to a value that refers to the source.
+ *
+ * Note that `register_block_bindings_source()` should be called from a handler attached to the `init` hook.
+ *
+ *
+ * ## Example
+ *
+ * ### Registering a source
+ *
+ * First, you need to define a function that will be used to get the value from the source.
+ *
+ *     function my_plugin_get_custom_source_value( array $source_args, $block_instance, string $attribute_name ) {
+ *       // Your custom logic to get the value from the source.
+ *       // For example, you can use the `$source_args` to look up a value in a custom table or get it from an external API.
+ *       $value = $source_args['key'];
+ *
+ *       return "The value passed to the block is: $value"
+ *     }
+ *
+ * The `$source_args` will contain the arguments passed to the source in the block's
+ * `metadata.bindings` attribute. See the example in the "Usage in a block" section below.
+ *
+ *     function my_plugin_register_block_bindings_sources() {
+ *       register_block_bindings_source( 'my-plugin/my-custom-source', array(
+ *         'label'              => __( 'My Custom Source', 'my-plugin' ),
+ *         'get_value_callback' => 'my_plugin_get_custom_source_value',
+ *       ) );
+ *     }
+ *     add_action( 'init', 'my_plugin_register_block_bindings_sources' );
+ *
+ * ### Usage in a block
+ *
+ * In a block's `metadata.bindings` attribute, you can specify the source and
+ * its arguments. Such a block will use the source to override the block
+ * attribute's value. For example:
+ *
+ *     <!-- wp:paragraph {
+ *       "metadata": {
+ *         "bindings": {
+ *           "content": {
+ *             "source": "my-plugin/my-custom-source",
+ *             "args": {
+ *               "key": "you can pass any custom arguments here"
+ *             }
+ *           }
+ *         }
+ *       }
+ *     } -->
+ *     <p>Fallback text that gets replaced.</p>
+ *     <!-- /wp:paragraph -->
+ *
+ * @since 6.5.0
+ *
+ * @param string $source_name       The name of the source. It must be a string containing a namespace prefix, i.e.
+ *                                  `my-plugin/my-custom-source`. It must only contain lowercase alphanumeric
+ *                                  characters, the forward slash `/` and dashes.
+ * @param array  $source_properties {
+ *     The array of arguments that are used to register a source.
+ *
+ *     @type string   $label                   The label of the source.
+ *     @type callback $get_value_callback      A callback executed when the source is processed during block rendering.
+ *                                             The callback should have the following signature:
+ *
+ *                                             `function ($source_args, $block_instance,$attribute_name): mixed`
+ *                                                 - @param array    $source_args    Array containing source arguments
+ *                                                                                   used to look up the override value,
+ *                                                                                   i.e. {"key": "foo"}.
+ *                                                 - @param WP_Block $block_instance The block instance.
+ *                                                 - @param string   $attribute_name The name of an attribute .
+ *                                             The callback has a mixed return type; it may return a string to override
+ *                                             the block's original value, null, false to remove an attribute, etc.
+ *     @type array    $uses_context (optional) Array of values to add to block `uses_context` needed by the source.
+ * }
+ * @return WP_Block_Bindings_Source|false Source when the registration was successful, or `false` on failure.
+ */
+function register_block_bindings_source( string $source_name, array $source_properties ) {
+	return WP_Block_Bindings_Registry::get_instance()->register( $source_name, $source_properties );
+}
+
+/**
+ * Unregisters a block bindings source.
+ *
+ * @since 6.5.0
+ *
+ * @param string $source_name Block bindings source name including namespace.
+ * @return WP_Block_Bindings_Source|false The unregistered block bindings source on success and `false` otherwise.
+ */
+function unregister_block_bindings_source( string $source_name ) {
+	return WP_Block_Bindings_Registry::get_instance()->unregister( $source_name );
+}
+
+/**
+ * Retrieves the list of all registered block bindings sources.
+ *
+ * @since 6.5.0
+ *
+ * @return WP_Block_Bindings_Source[] The array of registered block bindings sources.
+ */
+function get_all_registered_block_bindings_sources() {
+	return WP_Block_Bindings_Registry::get_instance()->get_all_registered();
+}
+
+/**
+ * Retrieves a registered block bindings source.
+ *
+ * @since 6.5.0
+ *
+ * @param string $source_name The name of the source.
+ * @return WP_Block_Bindings_Source|null The registered block bindings source, or `null` if it is not registered.
+ */
+function get_block_bindings_source( string $source_name ) {
+	return WP_Block_Bindings_Registry::get_instance()->get_registered( $source_name );
+}