Get WordPress

WordPress Developer Resources

WP_Block_Bindings_Registry::register()

WP_Block_Bindings_Registry::register( string $source_name, array $source_properties ): WP_Block_Bindings_Source|false

In this article

Back to top

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

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

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;

	// Adds `uses_context` defined by block bindings sources.
	add_filter(
		'get_block_type_uses_context',
		function ( $uses_context, $block_type ) use ( $source ) {
			if ( ! in_array( $block_type->name, $this->supported_blocks, true ) || empty( $source->uses_context ) ) {
				return $uses_context;
			}
			// Use array_values to reset the array keys.
			return array_values( array_unique( array_merge( $uses_context, $source->uses_context ) ) );
		},
		10,
		2
	);

	return $source;
}

View all references View on Trac View on GitHub

UsesDescription
WP_Block_Bindings_Registry::is_registered()wp-includes/class-wp-block-bindings-registry.php

Checks if a block bindings source is registered.

WP_Block_Bindings_Source::__construct()wp-includes/class-wp-block-bindings-source.php

Constructor.

__()wp-includes/l10n.php

Retrieves the translation of $text.

_doing_it_wrong()wp-includes/functions.php

Marks something as being incorrectly called.

add_filter()wp-includes/plugin.php

Adds a callback function to a filter hook.

Show 3 moreShow less

Changelog

VersionDescription
6.5.0Introduced.

User Contributed Notes

You must log in before being able to contribute a note or feedback.