Registers a new block bindings source.

Description

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

See also

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

Parameters

$source_namestringrequired

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_propertiesarrayrequired

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

• label string
  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.

Return

Source

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;
}

View all references View on Trac View on GitHub

Changelog