<?php

[0] Fix | Delete

/**

[1] Fix | Delete

* Block Bindings API

[2] Fix | Delete

*

[3] Fix | Delete

* Contains functions for managing block bindings in WordPress.

[4] Fix | Delete

*

[5] Fix | Delete

* @package WordPress

[6] Fix | Delete

* @subpackage Block Bindings

[7] Fix | Delete

* @since 6.5.0

[8] Fix | Delete

*/

[9] Fix | Delete

[10] Fix | Delete

/**

[11] Fix | Delete

* Registers a new block bindings source.

[12] Fix | Delete

*

[13] Fix | Delete

* Registering a source consists of defining a **name** for that source and a callback function specifying

[14] Fix | Delete

* how to get a value from that source and pass it to a block attribute.

[15] Fix | Delete

*

[16] Fix | Delete

* Once a source is registered, any block that supports the Block Bindings API can use a value

[17] Fix | Delete

* from that source by setting its `metadata.bindings` attribute to a value that refers to the source.

[18] Fix | Delete

*

[19] Fix | Delete

* Note that `register_block_bindings_source()` should be called from a handler attached to the `init` hook.

[20] Fix | Delete

*

[21] Fix | Delete

*

[22] Fix | Delete

* ## Example

[23] Fix | Delete

*

[24] Fix | Delete

* ### Registering a source

[25] Fix | Delete

*

[26] Fix | Delete

* First, you need to define a function that will be used to get the value from the source.

[27] Fix | Delete

*

[28] Fix | Delete

* function my_plugin_get_custom_source_value( array $source_args, $block_instance, string $attribute_name ) {

[29] Fix | Delete

* // Your custom logic to get the value from the source.

[30] Fix | Delete

* // For example, you can use the `$source_args` to look up a value in a custom table or get it from an external API.

[31] Fix | Delete

* $value = $source_args['key'];

[32] Fix | Delete

*

[33] Fix | Delete

* return "The value passed to the block is: $value"

[34] Fix | Delete

* }

[35] Fix | Delete

*

[36] Fix | Delete

* The `$source_args` will contain the arguments passed to the source in the block's

[37] Fix | Delete

* `metadata.bindings` attribute. See the example in the "Usage in a block" section below.

[38] Fix | Delete

*

[39] Fix | Delete

* function my_plugin_register_block_bindings_sources() {

[40] Fix | Delete

* register_block_bindings_source( 'my-plugin/my-custom-source', array(

[41] Fix | Delete

* 'label' => __( 'My Custom Source', 'my-plugin' ),

[42] Fix | Delete

* 'get_value_callback' => 'my_plugin_get_custom_source_value',

[43] Fix | Delete

* ) );

[44] Fix | Delete

* }

[45] Fix | Delete

* add_action( 'init', 'my_plugin_register_block_bindings_sources' );

[46] Fix | Delete

*

[47] Fix | Delete

* ### Usage in a block

[48] Fix | Delete

*

[49] Fix | Delete

* In a block's `metadata.bindings` attribute, you can specify the source and

[50] Fix | Delete

* its arguments. Such a block will use the source to override the block

[51] Fix | Delete

* attribute's value. For example:

[52] Fix | Delete

*

[53] Fix | Delete

* <!-- wp:paragraph {

[54] Fix | Delete

* "metadata": {

[55] Fix | Delete

* "bindings": {

[56] Fix | Delete

* "content": {

[57] Fix | Delete

* "source": "my-plugin/my-custom-source",

[58] Fix | Delete

* "args": {

[59] Fix | Delete

* "key": "you can pass any custom arguments here"

[60] Fix | Delete

* }

[61] Fix | Delete

* }

[62] Fix | Delete

* }

[63] Fix | Delete

* }

[64] Fix | Delete

* } -->

[65] Fix | Delete

* <p>Fallback text that gets replaced.</p>

[66] Fix | Delete

* <!-- /wp:paragraph -->

[67] Fix | Delete

*

[68] Fix | Delete

* @since 6.5.0

[69] Fix | Delete

*

[70] Fix | Delete

* @param string $source_name The name of the source. It must be a string containing a namespace prefix, i.e.

[71] Fix | Delete

* `my-plugin/my-custom-source`. It must only contain lowercase alphanumeric

[72] Fix | Delete

* characters, the forward slash `/` and dashes.

[73] Fix | Delete

* @param array $source_properties {

[74] Fix | Delete

* The array of arguments that are used to register a source.

[75] Fix | Delete

*

[76] Fix | Delete

* @type string $label The label of the source.

[77] Fix | Delete

* @type callable $get_value_callback A callback executed when the source is processed during block rendering.

[78] Fix | Delete

* The callback should have the following signature:

[79] Fix | Delete

*

[80] Fix | Delete

* `function( $source_args, $block_instance, $attribute_name ): mixed`

[81] Fix | Delete

* - @param array $source_args Array containing source arguments

[82] Fix | Delete

* used to look up the override value,

[83] Fix | Delete

* i.e. {"key": "foo"}.

[84] Fix | Delete

* - @param WP_Block $block_instance The block instance.

[85] Fix | Delete

* - @param string $attribute_name The name of an attribute.

[86] Fix | Delete

* The callback has a mixed return type; it may return a string to override

[87] Fix | Delete

* the block's original value, null, false to remove an attribute, etc.

[88] Fix | Delete

* @type string[] $uses_context Optional. Array of values to add to block `uses_context` needed by the source.

[89] Fix | Delete

* }

[90] Fix | Delete

* @return WP_Block_Bindings_Source|false Source when the registration was successful, or `false` on failure.

[91] Fix | Delete

*/

[92] Fix | Delete

function register_block_bindings_source( string $source_name, array $source_properties ) {

[93] Fix | Delete

return WP_Block_Bindings_Registry::get_instance()->register( $source_name, $source_properties );

[94] Fix | Delete

}

[95] Fix | Delete

[96] Fix | Delete

/**

[97] Fix | Delete

* Unregisters a block bindings source.

[98] Fix | Delete

*

[99] Fix | Delete

* @since 6.5.0

[100] Fix | Delete

*

[101] Fix | Delete

* @param string $source_name Block bindings source name including namespace.

[102] Fix | Delete

* @return WP_Block_Bindings_Source|false The unregistered block bindings source on success and `false` otherwise.

[103] Fix | Delete

*/

[104] Fix | Delete

function unregister_block_bindings_source( string $source_name ) {

[105] Fix | Delete

return WP_Block_Bindings_Registry::get_instance()->unregister( $source_name );

[106] Fix | Delete

}

[107] Fix | Delete

[108] Fix | Delete

/**

[109] Fix | Delete

* Retrieves the list of all registered block bindings sources.

[110] Fix | Delete

*

[111] Fix | Delete

* @since 6.5.0

[112] Fix | Delete

*

[113] Fix | Delete

* @return WP_Block_Bindings_Source[] The array of registered block bindings sources.

[114] Fix | Delete

*/

[115] Fix | Delete

function get_all_registered_block_bindings_sources() {

[116] Fix | Delete

return WP_Block_Bindings_Registry::get_instance()->get_all_registered();

[117] Fix | Delete

}

[118] Fix | Delete

[119] Fix | Delete

/**

[120] Fix | Delete

* Retrieves a registered block bindings source.

[121] Fix | Delete

*

[122] Fix | Delete

* @since 6.5.0

[123] Fix | Delete

*

[124] Fix | Delete

* @param string $source_name The name of the source.

[125] Fix | Delete

* @return WP_Block_Bindings_Source|null The registered block bindings source, or `null` if it is not registered.

[126] Fix | Delete

*/

[127] Fix | Delete

function get_block_bindings_source( string $source_name ) {

[128] Fix | Delete

return WP_Block_Bindings_Registry::get_instance()->get_registered( $source_name );

[129] Fix | Delete

}

[130] Fix | Delete

[131] Fix | Delete