WP_Block_Bindings_Registry::register() │ public │ WP 6.5.0

Registers a new block bindings source.

This is a low-level method. For most use cases, it is recommended to use the register_block_bindings_source() instead.

Метод класса: WP_Block_Bindings_Registry{}

Хуков нет.

Возвращает

WP_Block_Bindings_Source|false. Source when the registration was successful, or false on failure.

Использование

$WP_Block_Bindings_Registry = new WP_Block_Bindings_Registry();
$WP_Block_Bindings_Registry->register( $source_name, $source_properties );

$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.

$source_properties(массив) (обязательный)

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

• label(строка)
  The label of the source.

• get_value_callback(callable)
  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 the target 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.
• uses_context(string[])
  Optional. Array of values to add to block uses_context needed by the source.

Заметки

• Смотрите: register_block_bindings_source()

Sources are used to override block's original attributes with a value
coming from the source. Once a source is registered, it can be used by a
block by setting its metadata.bindings attribute to a value that refers
to the source.

Список изменений

Код WP_Block_Bindings_Registry::register() WP Block Bindings Registry::register ^{WP 6.7.1}

public function register( string $source_name, array $source_properties ) {
	if ( ! is_string( $source_name ) ) {
		_doing_it_wrong(
			__METHOD__,
			__( 'Block bindings source name must be a string.' ),
			'6.5.0'
		);
		return false;
	}

	if ( preg_match( '/[A-Z]+/', $source_name ) ) {
		_doing_it_wrong(
			__METHOD__,
			__( 'Block bindings source names must not contain uppercase characters.' ),
			'6.5.0'
		);
		return false;
	}

	$name_matcher = '/^[a-z0-9-]+\/[a-z0-9-]+$/';
	if ( ! preg_match( $name_matcher, $source_name ) ) {
		_doing_it_wrong(
			__METHOD__,
			__( 'Block bindings source names must contain a namespace prefix. Example: my-plugin/my-custom-source' ),
			'6.5.0'
		);
		return false;
	}

	if ( $this->is_registered( $source_name ) ) {
		_doing_it_wrong(
			__METHOD__,
			/* translators: %s: Block bindings source name. */
			sprintf( __( 'Block bindings source "%s" already registered.' ), $source_name ),
			'6.5.0'
		);
		return false;
	}

	// Validates that the source properties contain the label.
	if ( ! isset( $source_properties['label'] ) ) {
		_doing_it_wrong(
			__METHOD__,
			__( 'The $source_properties must contain a "label".' ),
			'6.5.0'
		);
		return false;
	}

	// Validates that the source properties contain the get_value_callback.
	if ( ! isset( $source_properties['get_value_callback'] ) ) {
		_doing_it_wrong(
			__METHOD__,
			__( 'The $source_properties must contain a "get_value_callback".' ),
			'6.5.0'
		);
		return false;
	}

	// Validates that the get_value_callback is a valid callback.
	if ( ! is_callable( $source_properties['get_value_callback'] ) ) {
		_doing_it_wrong(
			__METHOD__,
			__( 'The "get_value_callback" parameter must be a valid callback.' ),
			'6.5.0'
		);
		return false;
	}

	// Validates that the uses_context parameter is an array.
	if ( isset( $source_properties['uses_context'] ) && ! is_array( $source_properties['uses_context'] ) ) {
		_doing_it_wrong(
			__METHOD__,
			__( 'The "uses_context" parameter must be an array.' ),
			'6.5.0'
		);
		return false;
	}

	if ( ! empty( array_diff( array_keys( $source_properties ), $this->allowed_source_properties ) ) ) {
		_doing_it_wrong(
			__METHOD__,
			__( 'The $source_properties array contains invalid properties.' ),
			'6.5.0'
		);
		return false;
	}

	$source = new WP_Block_Bindings_Source(
		$source_name,
		$source_properties
	);

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

	return $source;
}