1<?php
  2/**
  3 * Block Bindings API: WP_Block_Bindings_Source class.
  4 *
  5 * @package WordPress
  6 * @subpackage Block Bindings
  7 * @since 6.5.0
  8 */
  9
 10/**
 11 * Class representing block bindings source.
 12 *
 13 * This class is designed for internal use by the Block Bindings registry.
 14 *
 15 * @since 6.5.0
 16 * @access private
 17 *
 18 * @see WP_Block_Bindings_Registry
 19 */
 20final class WP_Block_Bindings_Source {
 21
 22	/**
 23	 * The name of the source.
 24	 *
 25	 * @since 6.5.0
 26	 * @var string
 27	 */
 28	public $name;
 29
 30	/**
 31	 * The label of the source.
 32	 *
 33	 * @since 6.5.0
 34	 * @var string
 35	 */
 36	public $label;
 37
 38	/**
 39	 * The function used to get the value from the source.
 40	 *
 41	 * @since 6.5.0
 42	 * @var callable
 43	 */
 44	private $get_value_callback;
 45
 46	/**
 47	 * The context added to the blocks needed by the source.
 48	 *
 49	 * @since 6.5.0
 50	 * @var string[]|null
 51	 */
 52	public $uses_context = null;
 53
 54	/**
 55	 * Constructor.
 56	 *
 57	 * Do not use this constructor directly. Instead, use the
 58	 * `WP_Block_Bindings_Registry::register` method or the `register_block_bindings_source` function.
 59	 *
 60	 * @since 6.5.0
 61	 *
 62	 * @param string $name              The name of the source.
 63	 * @param array  $source_properties The properties of the source.
 64	 */
 65	public function __construct( string $name, array $source_properties ) {
 66		$this->name = $name;
 67		foreach ( $source_properties as $property_name => $property_value ) {
 68			$this->$property_name = $property_value;
 69		}
 70	}
 71
 72	/**
 73	 * Calls the callback function specified in the `$get_value_callback` property
 74	 * with the given arguments and returns the result. It can be modified with
 75	 * `block_bindings_source_value` filter.
 76	 *
 77	 * @since 6.5.0
 78	 * @since 6.7.0 `block_bindings_source_value` filter was added.
 79	 *
 80	 * @param array    $source_args    Array containing source arguments used to look up the override value, i.e. {"key": "foo"}.
 81	 * @param WP_Block $block_instance The block instance.
 82	 * @param string   $attribute_name The name of the target attribute.
 83	 * @return mixed The value of the source.
 84	 */
 85	public function get_value( array $source_args, $block_instance, string $attribute_name ) {
 86		$value = call_user_func_array( $this->get_value_callback, array( $source_args, $block_instance, $attribute_name ) );
 87		/**
 88		 * Filters the output of a block bindings source.
 89		 *
 90		 * @since 6.7.0
 91		 *
 92		 * @param mixed    $value          The computed value for the source.
 93		 * @param string   $name           The name of the source.
 94		 * @param array    $source_args    Array containing source arguments used to look up the override value, i.e. { "key": "foo" }.
 95		 * @param WP_Block $block_instance The block instance.
 96		 * @param string   $attribute_name The name of an attribute.
 97		 */
 98		return apply_filters( 'block_bindings_source_value', $value, $this->name, $source_args, $block_instance, $attribute_name );
 99	}
100
101	/**
102	 * Wakeup magic method.
103	 *
104	 * @since 6.5.0
105	 */
106	public function __wakeup() {
107		throw new \LogicException( __CLASS__ . ' should never be unserialized' );
108	}
109}
110