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