[Summary view] [Print] [Text view]

   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   *
  94   * @phpstan-param lowercase-string&non-falsy-string $source_name
  95   */
  96  function register_block_bindings_source( string $source_name, array $source_properties ) {
  97      return WP_Block_Bindings_Registry::get_instance()->register( $source_name, $source_properties );
  98  }
  99  
 100  /**
 101   * Unregisters a block bindings source.
 102   *
 103   * @since 6.5.0
 104   *
 105   * @param string $source_name Block bindings source name including namespace.
 106   * @return WP_Block_Bindings_Source|false The unregistered block bindings source on success and `false` otherwise.
 107   */
 108  function unregister_block_bindings_source( string $source_name ) {
 109      return WP_Block_Bindings_Registry::get_instance()->unregister( $source_name );
 110  }
 111  
 112  /**
 113   * Retrieves the list of all registered block bindings sources.
 114   *
 115   * @since 6.5.0
 116   *
 117   * @return WP_Block_Bindings_Source[] The array of registered block bindings sources.
 118   */
 119  function get_all_registered_block_bindings_sources() {
 120      return WP_Block_Bindings_Registry::get_instance()->get_all_registered();
 121  }
 122  
 123  /**
 124   * Retrieves a registered block bindings source.
 125   *
 126   * @since 6.5.0
 127   *
 128   * @param string $source_name The name of the source.
 129   * @return WP_Block_Bindings_Source|null The registered block bindings source, or `null` if it is not registered.
 130   */
 131  function get_block_bindings_source( string $source_name ) {
 132      return WP_Block_Bindings_Registry::get_instance()->get_registered( $source_name );
 133  }
 134  
 135  /**
 136   * Retrieves the list of block attributes supported by block bindings.
 137   *
 138   * @since 6.9.0
 139   * @since 7.1.0 Added support for the List Item block.
 140   * @since 7.2.0 Added support for the Icon block.
 141   *
 142   * @param string $block_type The block type whose supported attributes are being retrieved.
 143   * @return array The list of block attributes that are supported by block bindings.
 144   */
 145  function get_block_bindings_supported_attributes( $block_type ) {
 146      $block_bindings_supported_attributes = array(
 147          'core/paragraph'          => array( 'content' ),
 148          'core/heading'            => array( 'content' ),
 149          'core/list-item'          => array( 'content' ),
 150          'core/image'              => array( 'id', 'url', 'title', 'alt', 'caption' ),
 151          'core/button'             => array( 'url', 'text', 'linkTarget', 'rel' ),
 152          'core/post-date'          => array( 'datetime' ),
 153          'core/navigation-link'    => array( 'url' ),
 154          'core/navigation-submenu' => array( 'url' ),
 155          'core/icon'               => array( 'icon' ),
 156      );
 157  
 158      $supported_block_attributes =
 159          isset( $block_type, $block_bindings_supported_attributes[ $block_type ] ) ?
 160              $block_bindings_supported_attributes[ $block_type ] :
 161              array();
 162  
 163      /**
 164       * Filters the supported block attributes for block bindings.
 165       *
 166       * @since 6.9.0
 167       *
 168       * @param string[] $supported_block_attributes The block's attributes that are supported by block bindings.
 169       * @param string   $block_type                 The block type whose attributes are being filtered.
 170       */
 171      $supported_block_attributes = apply_filters(
 172          'block_bindings_supported_attributes',
 173          $supported_block_attributes,
 174          $block_type
 175      );
 176  
 177      /**
 178       * Filters the supported block attributes for block bindings.
 179       *
 180       * The dynamic portion of the hook name, `$block_type`, refers to the block type
 181       * whose attributes are being filtered.
 182       *
 183       * @since 6.9.0
 184       *
 185       * @param string[] $supported_block_attributes The block's attributes that are supported by block bindings.
 186       */
 187      $supported_block_attributes = apply_filters(
 188          "block_bindings_supported_attributes_{$block_type}",
 189          $supported_block_attributes
 190      );
 191  
 192      return $supported_block_attributes;
 193  }