<?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 callable $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 string[] $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 );

}