Edit File by line

<?php

[0] Fix | Delete

/**

[1] Fix | Delete

* Block Bindings API: WP_Block_Bindings_Registry class.

[2] Fix | Delete

[3] Fix | Delete

* Supports overriding content in blocks by connecting them to different sources.

[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

* Core class used for interacting with block bindings sources.

[12] Fix | Delete

[13] Fix | Delete

* @since 6.5.0

[14] Fix | Delete

[15] Fix | Delete

final class WP_Block_Bindings_Registry {

[16] Fix | Delete

[17] Fix | Delete

/**

[18] Fix | Delete

* Holds the registered block bindings sources, keyed by source identifier.

[19] Fix | Delete

[20] Fix | Delete

* @since 6.5.0

[21] Fix | Delete

* @var WP_Block_Bindings_Source[]

[22] Fix | Delete

[23] Fix | Delete

private $sources = array();

[24] Fix | Delete

[25] Fix | Delete

/**

[26] Fix | Delete

* Container for the main instance of the class.

[27] Fix | Delete

[28] Fix | Delete

* @since 6.5.0

[29] Fix | Delete

* @var WP_Block_Bindings_Registry|null

[30] Fix | Delete

[31] Fix | Delete

private static $instance = null;

[32] Fix | Delete

[33] Fix | Delete

/**

[34] Fix | Delete

* Supported source properties that can be passed to the registered source.

[35] Fix | Delete

[36] Fix | Delete

* @since 6.5.0

[37] Fix | Delete

* @var string[]

[38] Fix | Delete

[39] Fix | Delete

private $allowed_source_properties = array(

[40] Fix | Delete

'label',

[41] Fix | Delete

'get_value_callback',

[42] Fix | Delete

'uses_context',

[43] Fix | Delete

);

[44] Fix | Delete

[45] Fix | Delete

/**

[46] Fix | Delete

* Supported blocks that can use the block bindings API.

[47] Fix | Delete

[48] Fix | Delete

* @since 6.5.0

[49] Fix | Delete

* @var string[]

[50] Fix | Delete

[51] Fix | Delete

private $supported_blocks = array(

[52] Fix | Delete

'core/paragraph',

[53] Fix | Delete

'core/heading',

[54] Fix | Delete

'core/image',

[55] Fix | Delete

'core/button',

[56] Fix | Delete

);

[57] Fix | Delete

[58] Fix | Delete

/**

[59] Fix | Delete

* Registers a new block bindings source.

[60] Fix | Delete

[61] Fix | Delete

* This is a low-level method. For most use cases, it is recommended to use

[62] Fix | Delete

* the `register_block_bindings_source()` function instead.

[63] Fix | Delete

[64] Fix | Delete

* @see register_block_bindings_source()

[65] Fix | Delete

[66] Fix | Delete

* Sources are used to override block's original attributes with a value

[67] Fix | Delete

* coming from the source. Once a source is registered, it can be used by a

[68] Fix | Delete

* block by setting its `metadata.bindings` attribute to a value that refers

[69] Fix | Delete

* to the source.

[70] Fix | Delete

[71] Fix | Delete

* @since 6.5.0

[72] Fix | Delete

[73] Fix | Delete

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

[74] Fix | Delete

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

[75] Fix | Delete

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

[76] Fix | Delete

* @param array $source_properties {

[77] Fix | Delete

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

[78] Fix | Delete

[79] Fix | Delete

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

[80] Fix | Delete

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

[81] Fix | Delete

* The callback should have the following signature:

[82] Fix | Delete

[83] Fix | Delete

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

[84] Fix | Delete

* - @param array $source_args Array containing source arguments

[85] Fix | Delete

* used to look up the override value,

[86] Fix | Delete

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

[87] Fix | Delete

* - @param WP_Block $block_instance The block instance.

[88] Fix | Delete

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

[89] Fix | Delete

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

[90] Fix | Delete

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

[91] Fix | Delete

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

[92] Fix | Delete

* }

[93] Fix | Delete

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

[94] Fix | Delete

[95] Fix | Delete

public function register( string $source_name, array $source_properties ) {

[96] Fix | Delete

if ( ! is_string( $source_name ) ) {

[97] Fix | Delete

_doing_it_wrong(

[98] Fix | Delete

__METHOD__,

[99] Fix | Delete

__( 'Block bindings source name must be a string.' ),

[100] Fix | Delete

'6.5.0'

[101] Fix | Delete

);

[102] Fix | Delete

return false;

[103] Fix | Delete

}

[104] Fix | Delete

[105] Fix | Delete

if ( preg_match( '/[A-Z]+/', $source_name ) ) {

[106] Fix | Delete

_doing_it_wrong(

[107] Fix | Delete

__METHOD__,

[108] Fix | Delete

__( 'Block bindings source names must not contain uppercase characters.' ),

[109] Fix | Delete

'6.5.0'

[110] Fix | Delete

);

[111] Fix | Delete

return false;

[112] Fix | Delete

}

[113] Fix | Delete

[114] Fix | Delete

$name_matcher = '/^[a-z0-9-]+\/[a-z0-9-]+$/';

[115] Fix | Delete

if ( ! preg_match( $name_matcher, $source_name ) ) {

[116] Fix | Delete

_doing_it_wrong(

[117] Fix | Delete

__METHOD__,

[118] Fix | Delete

__( 'Block bindings source names must contain a namespace prefix. Example: my-plugin/my-custom-source' ),

[119] Fix | Delete

'6.5.0'

[120] Fix | Delete

);

[121] Fix | Delete

return false;

[122] Fix | Delete

}

[123] Fix | Delete

[124] Fix | Delete

if ( $this->is_registered( $source_name ) ) {

[125] Fix | Delete

_doing_it_wrong(

[126] Fix | Delete

__METHOD__,

[127] Fix | Delete

/* translators: %s: Block bindings source name. */

[128] Fix | Delete

sprintf( __( 'Block bindings source "%s" already registered.' ), $source_name ),

[129] Fix | Delete

'6.5.0'

[130] Fix | Delete

);

[131] Fix | Delete

return false;

[132] Fix | Delete

}

[133] Fix | Delete

[134] Fix | Delete

// Validates that the source properties contain the label.

[135] Fix | Delete

if ( ! isset( $source_properties['label'] ) ) {

[136] Fix | Delete

_doing_it_wrong(

[137] Fix | Delete

__METHOD__,

[138] Fix | Delete

__( 'The $source_properties must contain a "label".' ),

[139] Fix | Delete

'6.5.0'

[140] Fix | Delete

);

[141] Fix | Delete

return false;

[142] Fix | Delete

}

[143] Fix | Delete

[144] Fix | Delete

// Validates that the source properties contain the get_value_callback.

[145] Fix | Delete

if ( ! isset( $source_properties['get_value_callback'] ) ) {

[146] Fix | Delete

_doing_it_wrong(

[147] Fix | Delete

__METHOD__,

[148] Fix | Delete

__( 'The $source_properties must contain a "get_value_callback".' ),

[149] Fix | Delete

'6.5.0'

[150] Fix | Delete

);

[151] Fix | Delete

return false;

[152] Fix | Delete

}

[153] Fix | Delete

[154] Fix | Delete

// Validates that the get_value_callback is a valid callback.

[155] Fix | Delete

if ( ! is_callable( $source_properties['get_value_callback'] ) ) {

[156] Fix | Delete

_doing_it_wrong(

[157] Fix | Delete

__METHOD__,

[158] Fix | Delete

__( 'The "get_value_callback" parameter must be a valid callback.' ),

[159] Fix | Delete

'6.5.0'

[160] Fix | Delete

);

[161] Fix | Delete

return false;

[162] Fix | Delete

}

[163] Fix | Delete

[164] Fix | Delete

// Validates that the uses_context parameter is an array.

[165] Fix | Delete

if ( isset( $source_properties['uses_context'] ) && ! is_array( $source_properties['uses_context'] ) ) {

[166] Fix | Delete

_doing_it_wrong(

[167] Fix | Delete

__METHOD__,

[168] Fix | Delete

__( 'The "uses_context" parameter must be an array.' ),

[169] Fix | Delete

'6.5.0'

[170] Fix | Delete

);

[171] Fix | Delete

return false;

[172] Fix | Delete

}

[173] Fix | Delete

[174] Fix | Delete

if ( ! empty( array_diff( array_keys( $source_properties ), $this->allowed_source_properties ) ) ) {

[175] Fix | Delete

_doing_it_wrong(

[176] Fix | Delete

__METHOD__,

[177] Fix | Delete

__( 'The $source_properties array contains invalid properties.' ),

[178] Fix | Delete

'6.5.0'

[179] Fix | Delete

);

[180] Fix | Delete

return false;

[181] Fix | Delete

}

[182] Fix | Delete

[183] Fix | Delete

$source = new WP_Block_Bindings_Source(

[184] Fix | Delete

$source_name,

[185] Fix | Delete

$source_properties

[186] Fix | Delete

);

[187] Fix | Delete

[188] Fix | Delete

$this->sources[ $source_name ] = $source;

[189] Fix | Delete

[190] Fix | Delete

// Adds `uses_context` defined by block bindings sources.

[191] Fix | Delete

add_filter(

[192] Fix | Delete

'get_block_type_uses_context',

[193] Fix | Delete

function ( $uses_context, $block_type ) use ( $source ) {

[194] Fix | Delete

if ( ! in_array( $block_type->name, $this->supported_blocks, true ) || empty( $source->uses_context ) ) {

[195] Fix | Delete

return $uses_context;

[196] Fix | Delete

}

[197] Fix | Delete

// Use array_values to reset the array keys.

[198] Fix | Delete

return array_values( array_unique( array_merge( $uses_context, $source->uses_context ) ) );

[199] Fix | Delete

[200] Fix | Delete

10,

[201] Fix | Delete

[202] Fix | Delete

);

[203] Fix | Delete

[204] Fix | Delete

return $source;

[205] Fix | Delete

}

[206] Fix | Delete

[207] Fix | Delete

/**

[208] Fix | Delete

* Unregisters a block bindings source.

[209] Fix | Delete

[210] Fix | Delete

* @since 6.5.0

[211] Fix | Delete

[212] Fix | Delete

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

[213] Fix | Delete

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

[214] Fix | Delete

[215] Fix | Delete

public function unregister( string $source_name ) {

[216] Fix | Delete

if ( ! $this->is_registered( $source_name ) ) {

[217] Fix | Delete

_doing_it_wrong(

[218] Fix | Delete

__METHOD__,

[219] Fix | Delete

/* translators: %s: Block bindings source name. */

[220] Fix | Delete

sprintf( __( 'Block binding "%s" not found.' ), $source_name ),

[221] Fix | Delete

'6.5.0'

[222] Fix | Delete

);

[223] Fix | Delete

return false;

[224] Fix | Delete

}

[225] Fix | Delete

[226] Fix | Delete

$unregistered_source = $this->sources[ $source_name ];

[227] Fix | Delete

unset( $this->sources[ $source_name ] );

[228] Fix | Delete

[229] Fix | Delete

return $unregistered_source;

[230] Fix | Delete

}

[231] Fix | Delete

[232] Fix | Delete

/**

[233] Fix | Delete

* Retrieves the list of all registered block bindings sources.

[234] Fix | Delete

[235] Fix | Delete

* @since 6.5.0

[236] Fix | Delete

[237] Fix | Delete

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

[238] Fix | Delete

[239] Fix | Delete

public function get_all_registered() {

[240] Fix | Delete

return $this->sources;

[241] Fix | Delete

}

[242] Fix | Delete

[243] Fix | Delete

/**

[244] Fix | Delete

* Retrieves a registered block bindings source.

[245] Fix | Delete

[246] Fix | Delete

* @since 6.5.0

[247] Fix | Delete

[248] Fix | Delete

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

[249] Fix | Delete

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

[250] Fix | Delete

[251] Fix | Delete

public function get_registered( string $source_name ) {

[252] Fix | Delete

if ( ! $this->is_registered( $source_name ) ) {

[253] Fix | Delete

return null;

[254] Fix | Delete

}

[255] Fix | Delete

[256] Fix | Delete

return $this->sources[ $source_name ];

[257] Fix | Delete

}

[258] Fix | Delete

[259] Fix | Delete

/**

[260] Fix | Delete

* Checks if a block bindings source is registered.

[261] Fix | Delete

[262] Fix | Delete

* @since 6.5.0

[263] Fix | Delete

[264] Fix | Delete

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

[265] Fix | Delete

* @return bool `true` if the block bindings source is registered, `false` otherwise.

[266] Fix | Delete

[267] Fix | Delete

public function is_registered( $source_name ) {

[268] Fix | Delete

return isset( $this->sources[ $source_name ] );

[269] Fix | Delete

}

[270] Fix | Delete

[271] Fix | Delete

/**

[272] Fix | Delete

* Wakeup magic method.

[273] Fix | Delete

[274] Fix | Delete

* @since 6.5.0

[275] Fix | Delete

[276] Fix | Delete

public function __wakeup() {

[277] Fix | Delete

if ( ! $this->sources ) {

[278] Fix | Delete

return;

[279] Fix | Delete

}

[280] Fix | Delete

if ( ! is_array( $this->sources ) ) {

[281] Fix | Delete

throw new UnexpectedValueException();

[282] Fix | Delete

}

[283] Fix | Delete

foreach ( $this->sources as $value ) {

[284] Fix | Delete

if ( ! $value instanceof WP_Block_Bindings_Source ) {

[285] Fix | Delete

throw new UnexpectedValueException();

[286] Fix | Delete

}

[287] Fix | Delete

}

[288] Fix | Delete

}

[289] Fix | Delete

[290] Fix | Delete

/**

[291] Fix | Delete

* Utility method to retrieve the main instance of the class.

[292] Fix | Delete

[293] Fix | Delete

* The instance will be created if it does not exist yet.

[294] Fix | Delete

[295] Fix | Delete

* @since 6.5.0

[296] Fix | Delete

[297] Fix | Delete

* @return WP_Block_Bindings_Registry The main instance.

[298] Fix | Delete

[299] Fix | Delete

public static function get_instance() {

[300] Fix | Delete

if ( null === self::$instance ) {

[301] Fix | Delete

self::$instance = new self();

[302] Fix | Delete

}

[303] Fix | Delete

[304] Fix | Delete

return self::$instance;

[305] Fix | Delete

}

[306] Fix | Delete

}

[307] Fix | Delete

[308] Fix | Delete