| author | ymh <ymh.work@gmail.com> |
| Fri, 05 Sep 2025 18:40:08 +0200 | |
| changeset 21 | 48c4eec2b7e6 |
| parent 19 | 3d72ae0968f4 |
| child 22 | 8c2e4d02f4ef |
| permissions | -rw-r--r-- |
| 16 | 1 |
<?php |
2 |
/** |
|
3 |
* Blocks API: WP_Block_Styles_Registry class |
|
4 |
* |
|
5 |
* @package WordPress |
|
6 |
* @subpackage Blocks |
|
7 |
* @since 5.3.0 |
|
8 |
*/ |
|
9 |
||
10 |
/** |
|
11 |
* Class used for interacting with block styles. |
|
12 |
* |
|
13 |
* @since 5.3.0 |
|
14 |
*/ |
|
|
21
48c4eec2b7e6
Add CLAUDE.md documentation and sync WordPress core files
ymh <ymh.work@gmail.com>
parents:
19
diff
changeset
|
15 |
#[AllowDynamicProperties] |
| 16 | 16 |
final class WP_Block_Styles_Registry { |
17 |
/** |
|
18 |
* Registered block styles, as `$block_name => $block_style_name => $block_style_properties` multidimensional arrays. |
|
19 |
* |
|
20 |
* @since 5.3.0 |
|
| 19 | 21 |
* |
22 |
* @var array[] |
|
| 16 | 23 |
*/ |
24 |
private $registered_block_styles = array(); |
|
25 |
||
26 |
/** |
|
27 |
* Container for the main instance of the class. |
|
28 |
* |
|
29 |
* @since 5.3.0 |
|
| 19 | 30 |
* |
| 16 | 31 |
* @var WP_Block_Styles_Registry|null |
32 |
*/ |
|
33 |
private static $instance = null; |
|
34 |
||
35 |
/** |
|
| 19 | 36 |
* Registers a block style for the given block type. |
| 16 | 37 |
* |
|
21
48c4eec2b7e6
Add CLAUDE.md documentation and sync WordPress core files
ymh <ymh.work@gmail.com>
parents:
19
diff
changeset
|
38 |
* If the block styles are present in a standalone stylesheet, register it and pass |
|
48c4eec2b7e6
Add CLAUDE.md documentation and sync WordPress core files
ymh <ymh.work@gmail.com>
parents:
19
diff
changeset
|
39 |
* its handle as the `style_handle` argument. If the block styles should be inline, |
|
48c4eec2b7e6
Add CLAUDE.md documentation and sync WordPress core files
ymh <ymh.work@gmail.com>
parents:
19
diff
changeset
|
40 |
* use the `inline_style` argument. Usually, one of them would be used to pass CSS |
|
48c4eec2b7e6
Add CLAUDE.md documentation and sync WordPress core files
ymh <ymh.work@gmail.com>
parents:
19
diff
changeset
|
41 |
* styles. However, you could also skip them and provide CSS styles in any stylesheet |
|
48c4eec2b7e6
Add CLAUDE.md documentation and sync WordPress core files
ymh <ymh.work@gmail.com>
parents:
19
diff
changeset
|
42 |
* or with an inline tag. |
|
48c4eec2b7e6
Add CLAUDE.md documentation and sync WordPress core files
ymh <ymh.work@gmail.com>
parents:
19
diff
changeset
|
43 |
* |
| 16 | 44 |
* @since 5.3.0 |
|
21
48c4eec2b7e6
Add CLAUDE.md documentation and sync WordPress core files
ymh <ymh.work@gmail.com>
parents:
19
diff
changeset
|
45 |
* @since 6.6.0 Added ability to register style across multiple block types along with theme.json-like style data. |
|
48c4eec2b7e6
Add CLAUDE.md documentation and sync WordPress core files
ymh <ymh.work@gmail.com>
parents:
19
diff
changeset
|
46 |
* |
|
48c4eec2b7e6
Add CLAUDE.md documentation and sync WordPress core files
ymh <ymh.work@gmail.com>
parents:
19
diff
changeset
|
47 |
* @link https://developer.wordpress.org/block-editor/reference-guides/block-api/block-styles/ |
| 16 | 48 |
* |
|
21
48c4eec2b7e6
Add CLAUDE.md documentation and sync WordPress core files
ymh <ymh.work@gmail.com>
parents:
19
diff
changeset
|
49 |
* @param string|string[] $block_name Block type name including namespace or array of namespaced block type names. |
|
48c4eec2b7e6
Add CLAUDE.md documentation and sync WordPress core files
ymh <ymh.work@gmail.com>
parents:
19
diff
changeset
|
50 |
* @param array $style_properties { |
|
48c4eec2b7e6
Add CLAUDE.md documentation and sync WordPress core files
ymh <ymh.work@gmail.com>
parents:
19
diff
changeset
|
51 |
* Array containing the properties of the style. |
|
48c4eec2b7e6
Add CLAUDE.md documentation and sync WordPress core files
ymh <ymh.work@gmail.com>
parents:
19
diff
changeset
|
52 |
* |
|
48c4eec2b7e6
Add CLAUDE.md documentation and sync WordPress core files
ymh <ymh.work@gmail.com>
parents:
19
diff
changeset
|
53 |
* @type string $name The identifier of the style used to compute a CSS class. |
|
48c4eec2b7e6
Add CLAUDE.md documentation and sync WordPress core files
ymh <ymh.work@gmail.com>
parents:
19
diff
changeset
|
54 |
* @type string $label A human-readable label for the style. |
|
48c4eec2b7e6
Add CLAUDE.md documentation and sync WordPress core files
ymh <ymh.work@gmail.com>
parents:
19
diff
changeset
|
55 |
* @type string $inline_style Inline CSS code that registers the CSS class required |
|
48c4eec2b7e6
Add CLAUDE.md documentation and sync WordPress core files
ymh <ymh.work@gmail.com>
parents:
19
diff
changeset
|
56 |
* for the style. |
|
48c4eec2b7e6
Add CLAUDE.md documentation and sync WordPress core files
ymh <ymh.work@gmail.com>
parents:
19
diff
changeset
|
57 |
* @type string $style_handle The handle to an already registered style that should be |
|
48c4eec2b7e6
Add CLAUDE.md documentation and sync WordPress core files
ymh <ymh.work@gmail.com>
parents:
19
diff
changeset
|
58 |
* enqueued in places where block styles are needed. |
|
48c4eec2b7e6
Add CLAUDE.md documentation and sync WordPress core files
ymh <ymh.work@gmail.com>
parents:
19
diff
changeset
|
59 |
* @type bool $is_default Whether this is the default style for the block type. |
|
48c4eec2b7e6
Add CLAUDE.md documentation and sync WordPress core files
ymh <ymh.work@gmail.com>
parents:
19
diff
changeset
|
60 |
* @type array $style_data Theme.json-like object to generate CSS from. |
|
48c4eec2b7e6
Add CLAUDE.md documentation and sync WordPress core files
ymh <ymh.work@gmail.com>
parents:
19
diff
changeset
|
61 |
* } |
| 18 | 62 |
* @return bool True if the block style was registered with success and false otherwise. |
| 16 | 63 |
*/ |
64 |
public function register( $block_name, $style_properties ) { |
|
65 |
||
|
21
48c4eec2b7e6
Add CLAUDE.md documentation and sync WordPress core files
ymh <ymh.work@gmail.com>
parents:
19
diff
changeset
|
66 |
if ( ! is_string( $block_name ) && ! is_array( $block_name ) ) { |
| 18 | 67 |
_doing_it_wrong( |
68 |
__METHOD__, |
|
|
21
48c4eec2b7e6
Add CLAUDE.md documentation and sync WordPress core files
ymh <ymh.work@gmail.com>
parents:
19
diff
changeset
|
69 |
__( 'Block name must be a string or array.' ), |
|
48c4eec2b7e6
Add CLAUDE.md documentation and sync WordPress core files
ymh <ymh.work@gmail.com>
parents:
19
diff
changeset
|
70 |
'6.6.0' |
| 18 | 71 |
); |
| 16 | 72 |
return false; |
73 |
} |
|
74 |
||
75 |
if ( ! isset( $style_properties['name'] ) || ! is_string( $style_properties['name'] ) ) { |
|
| 18 | 76 |
_doing_it_wrong( |
77 |
__METHOD__, |
|
78 |
__( 'Block style name must be a string.' ), |
|
79 |
'5.3.0' |
|
80 |
); |
|
| 16 | 81 |
return false; |
82 |
} |
|
83 |
||
| 19 | 84 |
if ( str_contains( $style_properties['name'], ' ' ) ) { |
85 |
_doing_it_wrong( |
|
86 |
__METHOD__, |
|
87 |
__( 'Block style name must not contain any spaces.' ), |
|
88 |
'5.9.0' |
|
89 |
); |
|
90 |
return false; |
|
91 |
} |
|
92 |
||
| 16 | 93 |
$block_style_name = $style_properties['name']; |
|
21
48c4eec2b7e6
Add CLAUDE.md documentation and sync WordPress core files
ymh <ymh.work@gmail.com>
parents:
19
diff
changeset
|
94 |
$block_names = is_string( $block_name ) ? array( $block_name ) : $block_name; |
| 16 | 95 |
|
|
21
48c4eec2b7e6
Add CLAUDE.md documentation and sync WordPress core files
ymh <ymh.work@gmail.com>
parents:
19
diff
changeset
|
96 |
foreach ( $block_names as $name ) { |
|
48c4eec2b7e6
Add CLAUDE.md documentation and sync WordPress core files
ymh <ymh.work@gmail.com>
parents:
19
diff
changeset
|
97 |
if ( ! isset( $this->registered_block_styles[ $name ] ) ) { |
|
48c4eec2b7e6
Add CLAUDE.md documentation and sync WordPress core files
ymh <ymh.work@gmail.com>
parents:
19
diff
changeset
|
98 |
$this->registered_block_styles[ $name ] = array(); |
|
48c4eec2b7e6
Add CLAUDE.md documentation and sync WordPress core files
ymh <ymh.work@gmail.com>
parents:
19
diff
changeset
|
99 |
} |
|
48c4eec2b7e6
Add CLAUDE.md documentation and sync WordPress core files
ymh <ymh.work@gmail.com>
parents:
19
diff
changeset
|
100 |
$this->registered_block_styles[ $name ][ $block_style_name ] = $style_properties; |
| 16 | 101 |
} |
102 |
||
103 |
return true; |
|
104 |
} |
|
105 |
||
106 |
/** |
|
| 19 | 107 |
* Unregisters a block style of the given block type. |
108 |
* |
|
109 |
* @since 5.3.0 |
|
| 16 | 110 |
* |
111 |
* @param string $block_name Block type name including namespace. |
|
112 |
* @param string $block_style_name Block style name. |
|
| 18 | 113 |
* @return bool True if the block style was unregistered with success and false otherwise. |
| 16 | 114 |
*/ |
115 |
public function unregister( $block_name, $block_style_name ) { |
|
116 |
if ( ! $this->is_registered( $block_name, $block_style_name ) ) { |
|
| 18 | 117 |
_doing_it_wrong( |
118 |
__METHOD__, |
|
119 |
/* translators: 1: Block name, 2: Block style name. */ |
|
120 |
sprintf( __( 'Block "%1$s" does not contain a style named "%2$s".' ), $block_name, $block_style_name ), |
|
121 |
'5.3.0' |
|
122 |
); |
|
| 16 | 123 |
return false; |
124 |
} |
|
125 |
||
126 |
unset( $this->registered_block_styles[ $block_name ][ $block_style_name ] ); |
|
127 |
||
128 |
return true; |
|
129 |
} |
|
130 |
||
131 |
/** |
|
| 19 | 132 |
* Retrieves the properties of a registered block style for the given block type. |
| 16 | 133 |
* |
134 |
* @since 5.3.0 |
|
135 |
* |
|
136 |
* @param string $block_name Block type name including namespace. |
|
137 |
* @param string $block_style_name Block style name. |
|
138 |
* @return array Registered block style properties. |
|
139 |
*/ |
|
140 |
public function get_registered( $block_name, $block_style_name ) { |
|
141 |
if ( ! $this->is_registered( $block_name, $block_style_name ) ) { |
|
142 |
return null; |
|
143 |
} |
|
144 |
||
145 |
return $this->registered_block_styles[ $block_name ][ $block_style_name ]; |
|
146 |
} |
|
147 |
||
148 |
/** |
|
149 |
* Retrieves all registered block styles. |
|
150 |
* |
|
151 |
* @since 5.3.0 |
|
152 |
* |
|
| 19 | 153 |
* @return array[] Array of arrays containing the registered block styles properties grouped by block type. |
| 16 | 154 |
*/ |
155 |
public function get_all_registered() { |
|
156 |
return $this->registered_block_styles; |
|
157 |
} |
|
158 |
||
159 |
/** |
|
| 19 | 160 |
* Retrieves registered block styles for a specific block type. |
| 16 | 161 |
* |
162 |
* @since 5.3.0 |
|
163 |
* |
|
164 |
* @param string $block_name Block type name including namespace. |
|
| 19 | 165 |
* @return array[] Array whose keys are block style names and whose values are block style properties. |
| 16 | 166 |
*/ |
167 |
public function get_registered_styles_for_block( $block_name ) { |
|
168 |
if ( isset( $this->registered_block_styles[ $block_name ] ) ) { |
|
169 |
return $this->registered_block_styles[ $block_name ]; |
|
170 |
} |
|
171 |
return array(); |
|
172 |
} |
|
173 |
||
174 |
/** |
|
| 19 | 175 |
* Checks if a block style is registered for the given block type. |
| 16 | 176 |
* |
177 |
* @since 5.3.0 |
|
178 |
* |
|
179 |
* @param string $block_name Block type name including namespace. |
|
180 |
* @param string $block_style_name Block style name. |
|
181 |
* @return bool True if the block style is registered, false otherwise. |
|
182 |
*/ |
|
183 |
public function is_registered( $block_name, $block_style_name ) { |
|
184 |
return isset( $this->registered_block_styles[ $block_name ][ $block_style_name ] ); |
|
185 |
} |
|
186 |
||
187 |
/** |
|
188 |
* Utility method to retrieve the main instance of the class. |
|
189 |
* |
|
190 |
* The instance will be created if it does not exist yet. |
|
191 |
* |
|
192 |
* @since 5.3.0 |
|
193 |
* |
|
194 |
* @return WP_Block_Styles_Registry The main instance. |
|
195 |
*/ |
|
196 |
public static function get_instance() { |
|
197 |
if ( null === self::$instance ) { |
|
198 |
self::$instance = new self(); |
|
199 |
} |
|
200 |
||
201 |
return self::$instance; |
|
202 |
} |
|
203 |
} |