[ Index ] |
PHP Cross Reference of WordPress Trunk (Updated Daily) |
[Summary view] [Print] [Text view]
1 <?php 2 /** 3 * Blocks API: WP_Block_Patterns_Registry class 4 * 5 * @package WordPress 6 * @subpackage Blocks 7 * @since 5.5.0 8 */ 9 10 /** 11 * Class used for interacting with block patterns. 12 * 13 * @since 5.5.0 14 */ 15 #[AllowDynamicProperties] 16 final class WP_Block_Patterns_Registry { 17 /** 18 * Registered block patterns array. 19 * 20 * @since 5.5.0 21 * @var array[] 22 */ 23 private $registered_patterns = array(); 24 25 /** 26 * Patterns registered outside the `init` action. 27 * 28 * @since 6.0.0 29 * @var array[] 30 */ 31 private $registered_patterns_outside_init = array(); 32 33 /** 34 * Container for the main instance of the class. 35 * 36 * @since 5.5.0 37 * @var WP_Block_Patterns_Registry|null 38 */ 39 private static $instance = null; 40 41 /** 42 * Registers a block pattern. 43 * 44 * @since 5.5.0 45 * @since 5.8.0 Added support for the `blockTypes` property. 46 * @since 6.1.0 Added support for the `postTypes` property. 47 * @since 6.2.0 Added support for the `templateTypes` property. 48 * @since 6.5.0 Added support for the `filePath` property. 49 * 50 * @param string $pattern_name Block pattern name including namespace. 51 * @param array $pattern_properties { 52 * List of properties for the block pattern. 53 * 54 * @type string $title Required. A human-readable title for the pattern. 55 * @type string $content Optional. Block HTML markup for the pattern. 56 * If not provided, the content will be retrieved from the `filePath` if set. 57 * If both `content` and `filePath` are not set, the pattern will not be registered. 58 * @type string $description Optional. Visually hidden text used to describe the pattern 59 * in the inserter. A description is optional, but is strongly 60 * encouraged when the title does not fully describe what the 61 * pattern does. The description will help users discover the 62 * pattern while searching. 63 * @type int $viewportWidth Optional. The intended width of the pattern to allow for a scaled 64 * preview within the pattern inserter. 65 * @type bool $inserter Optional. Determines whether the pattern is visible in inserter. 66 * To hide a pattern so that it can only be inserted programmatically, 67 * set this to false. Default true. 68 * @type string[] $categories Optional. A list of registered pattern categories used to group 69 * block patterns. Block patterns can be shown on multiple categories. 70 * A category must be registered separately in order to be used here. 71 * @type string[] $keywords Optional. A list of aliases or keywords that help users discover 72 * the pattern while searching. 73 * @type string[] $blockTypes Optional. A list of block names including namespace that could use 74 * the block pattern in certain contexts (placeholder, transforms). 75 * The block pattern is available in the block editor inserter 76 * regardless of this list of block names. 77 * Certain blocks support further specificity besides the block name 78 * (e.g. for `core/template-part` you can specify areas 79 * like `core/template-part/header` or `core/template-part/footer`). 80 * @type string[] $postTypes Optional. An array of post types that the pattern is restricted 81 * to be used with. The pattern will only be available when editing one 82 * of the post types passed on the array. For all the other post types 83 * not part of the array the pattern is not available at all. 84 * @type string[] $templateTypes Optional. An array of template types where the pattern fits. 85 * @type string $filePath Optional. The full path to the file containing the block pattern content. 86 * } 87 * @return bool True if the pattern was registered with success and false otherwise. 88 */ 89 public function register( $pattern_name, $pattern_properties ) { 90 if ( ! isset( $pattern_name ) || ! is_string( $pattern_name ) ) { 91 _doing_it_wrong( 92 __METHOD__, 93 __( 'Pattern name must be a string.' ), 94 '5.5.0' 95 ); 96 return false; 97 } 98 99 if ( ! isset( $pattern_properties['title'] ) || ! is_string( $pattern_properties['title'] ) ) { 100 _doing_it_wrong( 101 __METHOD__, 102 __( 'Pattern title must be a string.' ), 103 '5.5.0' 104 ); 105 return false; 106 } 107 108 if ( ! isset( $pattern_properties['filePath'] ) ) { 109 if ( ! isset( $pattern_properties['content'] ) || ! is_string( $pattern_properties['content'] ) ) { 110 _doing_it_wrong( 111 __METHOD__, 112 __( 'Pattern content must be a string.' ), 113 '5.5.0' 114 ); 115 return false; 116 } 117 } 118 119 $pattern = array_merge( 120 $pattern_properties, 121 array( 'name' => $pattern_name ) 122 ); 123 124 $this->registered_patterns[ $pattern_name ] = $pattern; 125 126 // If the pattern is registered inside an action other than `init`, store it 127 // also to a dedicated array. Used to detect deprecated registrations inside 128 // `admin_init` or `current_screen`. 129 if ( current_action() && 'init' !== current_action() ) { 130 $this->registered_patterns_outside_init[ $pattern_name ] = $pattern; 131 } 132 133 return true; 134 } 135 136 /** 137 * Unregisters a block pattern. 138 * 139 * @since 5.5.0 140 * 141 * @param string $pattern_name Block pattern name including namespace. 142 * @return bool True if the pattern was unregistered with success and false otherwise. 143 */ 144 public function unregister( $pattern_name ) { 145 if ( ! $this->is_registered( $pattern_name ) ) { 146 _doing_it_wrong( 147 __METHOD__, 148 /* translators: %s: Pattern name. */ 149 sprintf( __( 'Pattern "%s" not found.' ), $pattern_name ), 150 '5.5.0' 151 ); 152 return false; 153 } 154 155 unset( $this->registered_patterns[ $pattern_name ] ); 156 unset( $this->registered_patterns_outside_init[ $pattern_name ] ); 157 158 return true; 159 } 160 161 /** 162 * Retrieves the content of a registered block pattern. 163 * 164 * @since 6.5.0 165 * 166 * @param string $pattern_name Block pattern name including namespace. 167 * @param bool $outside_init_only Optional. Return only patterns registered outside the `init` action. Default false. 168 * @return string The content of the block pattern. 169 */ 170 private function get_content( $pattern_name, $outside_init_only = false ) { 171 if ( $outside_init_only ) { 172 $patterns = &$this->registered_patterns_outside_init; 173 } else { 174 $patterns = &$this->registered_patterns; 175 } 176 if ( ! isset( $patterns[ $pattern_name ]['content'] ) && isset( $patterns[ $pattern_name ]['filePath'] ) ) { 177 ob_start(); 178 include $patterns[ $pattern_name ]['filePath']; 179 $patterns[ $pattern_name ]['content'] = ob_get_clean(); 180 unset( $patterns[ $pattern_name ]['filePath'] ); 181 } 182 return $patterns[ $pattern_name ]['content']; 183 } 184 185 /** 186 * Retrieves an array containing the properties of a registered block pattern. 187 * 188 * @since 5.5.0 189 * 190 * @param string $pattern_name Block pattern name including namespace. 191 * @return array Registered pattern properties. 192 */ 193 public function get_registered( $pattern_name ) { 194 if ( ! $this->is_registered( $pattern_name ) ) { 195 return null; 196 } 197 198 $pattern = $this->registered_patterns[ $pattern_name ]; 199 $content = $this->get_content( $pattern_name ); 200 $pattern['content'] = apply_block_hooks_to_content( 201 $content, 202 $pattern, 203 'insert_hooked_blocks_and_set_ignored_hooked_blocks_metadata' 204 ); 205 206 return $pattern; 207 } 208 209 /** 210 * Retrieves all registered block patterns. 211 * 212 * @since 5.5.0 213 * 214 * @param bool $outside_init_only Return only patterns registered outside the `init` action. 215 * @return array[] Array of arrays containing the registered block patterns properties, 216 * and per style. 217 */ 218 public function get_all_registered( $outside_init_only = false ) { 219 $patterns = $outside_init_only 220 ? $this->registered_patterns_outside_init 221 : $this->registered_patterns; 222 $hooked_blocks = get_hooked_blocks(); 223 224 foreach ( $patterns as $index => $pattern ) { 225 $content = $this->get_content( $pattern['name'], $outside_init_only ); 226 $patterns[ $index ]['content'] = apply_block_hooks_to_content( 227 $content, 228 $pattern, 229 'insert_hooked_blocks_and_set_ignored_hooked_blocks_metadata' 230 ); 231 } 232 233 return array_values( $patterns ); 234 } 235 236 /** 237 * Checks if a block pattern is registered. 238 * 239 * @since 5.5.0 240 * 241 * @param string $pattern_name Block pattern name including namespace. 242 * @return bool True if the pattern is registered, false otherwise. 243 */ 244 public function is_registered( $pattern_name ) { 245 return isset( $this->registered_patterns[ $pattern_name ] ); 246 } 247 248 public function __wakeup() { 249 if ( ! $this->registered_patterns ) { 250 return; 251 } 252 if ( ! is_array( $this->registered_patterns ) ) { 253 throw new UnexpectedValueException(); 254 } 255 foreach ( $this->registered_patterns as $value ) { 256 if ( ! is_array( $value ) ) { 257 throw new UnexpectedValueException(); 258 } 259 } 260 $this->registered_patterns_outside_init = array(); 261 } 262 263 /** 264 * Utility method to retrieve the main instance of the class. 265 * 266 * The instance will be created if it does not exist yet. 267 * 268 * @since 5.5.0 269 * 270 * @return WP_Block_Patterns_Registry The main instance. 271 */ 272 public static function get_instance() { 273 if ( null === self::$instance ) { 274 self::$instance = new self(); 275 } 276 277 return self::$instance; 278 } 279 } 280 281 /** 282 * Registers a new block pattern. 283 * 284 * @since 5.5.0 285 * 286 * @param string $pattern_name Block pattern name including namespace. 287 * @param array $pattern_properties List of properties for the block pattern. 288 * See WP_Block_Patterns_Registry::register() for accepted arguments. 289 * @return bool True if the pattern was registered with success and false otherwise. 290 */ 291 function register_block_pattern( $pattern_name, $pattern_properties ) { 292 return WP_Block_Patterns_Registry::get_instance()->register( $pattern_name, $pattern_properties ); 293 } 294 295 /** 296 * Unregisters a block pattern. 297 * 298 * @since 5.5.0 299 * 300 * @param string $pattern_name Block pattern name including namespace. 301 * @return bool True if the pattern was unregistered with success and false otherwise. 302 */ 303 function unregister_block_pattern( $pattern_name ) { 304 return WP_Block_Patterns_Registry::get_instance()->unregister( $pattern_name ); 305 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
Generated : Wed Dec 4 08:20:01 2024 | Cross-referenced by PHPXref |