| [ Index ] |
PHP Cross Reference of WordPress |
[Summary view] [Print] [Text view]
1 <?php 2 /** 3 * Functions related to registering and parsing blocks. 4 * 5 * @package WordPress 6 * @subpackage Blocks 7 * @since 5.0.0 8 */ 9 10 /** 11 * Removes the block asset's path prefix if provided. 12 * 13 * @since 5.5.0 14 * 15 * @param string $asset_handle_or_path Asset handle or prefixed path. 16 * @return string Path without the prefix or the original value. 17 */ 18 function remove_block_asset_path_prefix( $asset_handle_or_path ) { 19 $path_prefix = 'file:'; 20 if ( 0 !== strpos( $asset_handle_or_path, $path_prefix ) ) { 21 return $asset_handle_or_path; 22 } 23 return substr( 24 $asset_handle_or_path, 25 strlen( $path_prefix ) 26 ); 27 } 28 29 /** 30 * Generates the name for an asset based on the name of the block 31 * and the field name provided. 32 * 33 * @since 5.5.0 34 * 35 * @param string $block_name Name of the block. 36 * @param string $field_name Name of the metadata field. 37 * @return string Generated asset name for the block's field. 38 */ 39 function generate_block_asset_handle( $block_name, $field_name ) { 40 if ( 0 === strpos( $block_name, 'core/' ) ) { 41 $asset_handle = str_replace( 'core/', 'wp-block-', $block_name ); 42 if ( 0 === strpos( $field_name, 'editor' ) ) { 43 $asset_handle .= '-editor'; 44 } 45 if ( 0 === strpos( $field_name, 'view' ) ) { 46 $asset_handle .= '-view'; 47 } 48 return $asset_handle; 49 } 50 51 $field_mappings = array( 52 'editorScript' => 'editor-script', 53 'script' => 'script', 54 'viewScript' => 'view-script', 55 'editorStyle' => 'editor-style', 56 'style' => 'style', 57 ); 58 return str_replace( '/', '-', $block_name ) . 59 '-' . $field_mappings[ $field_name ]; 60 } 61 62 /** 63 * Finds a script handle for the selected block metadata field. It detects 64 * when a path to file was provided and finds a corresponding asset file 65 * with details necessary to register the script under automatically 66 * generated handle name. It returns unprocessed script handle otherwise. 67 * 68 * @since 5.5.0 69 * 70 * @param array $metadata Block metadata. 71 * @param string $field_name Field name to pick from metadata. 72 * @return string|false Script handle provided directly or created through 73 * script's registration, or false on failure. 74 */ 75 function register_block_script_handle( $metadata, $field_name ) { 76 if ( empty( $metadata[ $field_name ] ) ) { 77 return false; 78 } 79 $script_handle = $metadata[ $field_name ]; 80 $script_path = remove_block_asset_path_prefix( $metadata[ $field_name ] ); 81 if ( $script_handle === $script_path ) { 82 return $script_handle; 83 } 84 85 $script_handle = generate_block_asset_handle( $metadata['name'], $field_name ); 86 $script_asset_path = wp_normalize_path( 87 realpath( 88 dirname( $metadata['file'] ) . '/' . 89 substr_replace( $script_path, '.asset.php', - strlen( '.js' ) ) 90 ) 91 ); 92 if ( ! file_exists( $script_asset_path ) ) { 93 _doing_it_wrong( 94 __FUNCTION__, 95 sprintf( 96 /* translators: 1: Field name, 2: Block name. */ 97 __( 'The asset file for the "%1$s" defined in "%2$s" block definition is missing.' ), 98 $field_name, 99 $metadata['name'] 100 ), 101 '5.5.0' 102 ); 103 return false; 104 } 105 // Path needs to be normalized to work in Windows env. 106 $wpinc_path_norm = wp_normalize_path( ABSPATH . WPINC ); 107 $script_path_norm = wp_normalize_path( realpath( dirname( $metadata['file'] ) . '/' . $script_path ) ); 108 $is_core_block = isset( $metadata['file'] ) && 0 === strpos( $metadata['file'], $wpinc_path_norm ); 109 110 $script_uri = $is_core_block ? 111 includes_url( str_replace( $wpinc_path_norm, '', $script_path_norm ) ) : 112 plugins_url( $script_path, $metadata['file'] ); 113 $script_asset = require $script_asset_path; 114 $script_dependencies = isset( $script_asset['dependencies'] ) ? $script_asset['dependencies'] : array(); 115 $result = wp_register_script( 116 $script_handle, 117 $script_uri, 118 $script_dependencies, 119 isset( $script_asset['version'] ) ? $script_asset['version'] : false 120 ); 121 if ( ! $result ) { 122 return false; 123 } 124 125 if ( ! empty( $metadata['textdomain'] ) && in_array( 'wp-i18n', $script_dependencies, true ) ) { 126 wp_set_script_translations( $script_handle, $metadata['textdomain'] ); 127 } 128 129 return $script_handle; 130 } 131 132 /** 133 * Finds a style handle for the block metadata field. It detects when a path 134 * to file was provided and registers the style under automatically 135 * generated handle name. It returns unprocessed style handle otherwise. 136 * 137 * @since 5.5.0 138 * 139 * @param array $metadata Block metadata. 140 * @param string $field_name Field name to pick from metadata. 141 * @return string|false Style handle provided directly or created through 142 * style's registration, or false on failure. 143 */ 144 function register_block_style_handle( $metadata, $field_name ) { 145 if ( empty( $metadata[ $field_name ] ) ) { 146 return false; 147 } 148 $wpinc_path_norm = wp_normalize_path( ABSPATH . WPINC ); 149 $is_core_block = isset( $metadata['file'] ) && 0 === strpos( $metadata['file'], $wpinc_path_norm ); 150 if ( $is_core_block && ! wp_should_load_separate_core_block_assets() ) { 151 return false; 152 } 153 154 // Check whether styles should have a ".min" suffix or not. 155 $suffix = SCRIPT_DEBUG ? '' : '.min'; 156 157 $style_handle = $metadata[ $field_name ]; 158 $style_path = remove_block_asset_path_prefix( $metadata[ $field_name ] ); 159 160 if ( $style_handle === $style_path && ! $is_core_block ) { 161 return $style_handle; 162 } 163 164 $style_uri = plugins_url( $style_path, $metadata['file'] ); 165 if ( $is_core_block ) { 166 $style_path = "style$suffix.css"; 167 $style_uri = includes_url( 'blocks/' . str_replace( 'core/', '', $metadata['name'] ) . "/style$suffix.css" ); 168 } 169 170 $style_handle = generate_block_asset_handle( $metadata['name'], $field_name ); 171 $block_dir = dirname( $metadata['file'] ); 172 $style_file = realpath( "$block_dir/$style_path" ); 173 $has_style_file = false !== $style_file; 174 $version = ! $is_core_block && isset( $metadata['version'] ) ? $metadata['version'] : false; 175 $style_uri = $has_style_file ? $style_uri : false; 176 $result = wp_register_style( 177 $style_handle, 178 $style_uri, 179 array(), 180 $version 181 ); 182 if ( file_exists( str_replace( '.css', '-rtl.css', $style_file ) ) ) { 183 wp_style_add_data( $style_handle, 'rtl', 'replace' ); 184 } 185 if ( $has_style_file ) { 186 wp_style_add_data( $style_handle, 'path', $style_file ); 187 } 188 189 $rtl_file = str_replace( "$suffix.css", "-rtl$suffix.css", $style_file ); 190 if ( is_rtl() && file_exists( $rtl_file ) ) { 191 wp_style_add_data( $style_handle, 'path', $rtl_file ); 192 } 193 194 return $result ? $style_handle : false; 195 } 196 197 /** 198 * Gets i18n schema for block's metadata read from `block.json` file. 199 * 200 * @since 5.9.0 201 * 202 * @return array The schema for block's metadata. 203 */ 204 function get_block_metadata_i18n_schema() { 205 static $i18n_block_schema; 206 207 if ( ! isset( $i18n_block_schema ) ) { 208 $i18n_block_schema = wp_json_file_decode( __DIR__ . '/block-i18n.json' ); 209 } 210 211 return $i18n_block_schema; 212 } 213 214 /** 215 * Registers a block type from the metadata stored in the `block.json` file. 216 * 217 * @since 5.5.0 218 * @since 5.7.0 Added support for `textdomain` field and i18n handling for all translatable fields. 219 * @since 5.9.0 Added support for `variations` and `viewScript` fields. 220 * 221 * @param string $file_or_folder Path to the JSON file with metadata definition for 222 * the block or path to the folder where the `block.json` file is located. 223 * If providing the path to a JSON file, the filename must end with `block.json`. 224 * @param array $args Optional. Array of block type arguments. Accepts any public property 225 * of `WP_Block_Type`. See WP_Block_Type::__construct() for information 226 * on accepted arguments. Default empty array. 227 * @return WP_Block_Type|false The registered block type on success, or false on failure. 228 */ 229 function register_block_type_from_metadata( $file_or_folder, $args = array() ) { 230 $filename = 'block.json'; 231 $metadata_file = ( substr( $file_or_folder, -strlen( $filename ) ) !== $filename ) ? 232 trailingslashit( $file_or_folder ) . $filename : 233 $file_or_folder; 234 if ( ! file_exists( $metadata_file ) ) { 235 return false; 236 } 237 238 $metadata = wp_json_file_decode( $metadata_file, array( 'associative' => true ) ); 239 if ( ! is_array( $metadata ) || empty( $metadata['name'] ) ) { 240 return false; 241 } 242 $metadata['file'] = wp_normalize_path( $metadata_file ); 243 244 /** 245 * Filters the metadata provided for registering a block type. 246 * 247 * @since 5.7.0 248 * 249 * @param array $metadata Metadata for registering a block type. 250 */ 251 $metadata = apply_filters( 'block_type_metadata', $metadata ); 252 253 // Add `style` and `editor_style` for core blocks if missing. 254 if ( ! empty( $metadata['name'] ) && 0 === strpos( $metadata['name'], 'core/' ) ) { 255 $block_name = str_replace( 'core/', '', $metadata['name'] ); 256 257 if ( ! isset( $metadata['style'] ) ) { 258 $metadata['style'] = "wp-block-$block_name"; 259 } 260 if ( ! isset( $metadata['editorStyle'] ) ) { 261 $metadata['editorStyle'] = "wp-block-{$block_name}-editor"; 262 } 263 } 264 265 $settings = array(); 266 $property_mappings = array( 267 'apiVersion' => 'api_version', 268 'title' => 'title', 269 'category' => 'category', 270 'parent' => 'parent', 271 'icon' => 'icon', 272 'description' => 'description', 273 'keywords' => 'keywords', 274 'attributes' => 'attributes', 275 'providesContext' => 'provides_context', 276 'usesContext' => 'uses_context', 277 'supports' => 'supports', 278 'styles' => 'styles', 279 'variations' => 'variations', 280 'example' => 'example', 281 ); 282 $textdomain = ! empty( $metadata['textdomain'] ) ? $metadata['textdomain'] : null; 283 $i18n_schema = get_block_metadata_i18n_schema(); 284 285 foreach ( $property_mappings as $key => $mapped_key ) { 286 if ( isset( $metadata[ $key ] ) ) { 287 $settings[ $mapped_key ] = $metadata[ $key ]; 288 if ( $textdomain && isset( $i18n_schema->$key ) ) { 289 $settings[ $mapped_key ] = translate_settings_using_i18n_schema( $i18n_schema->$key, $settings[ $key ], $textdomain ); 290 } 291 } 292 } 293 294 if ( ! empty( $metadata['editorScript'] ) ) { 295 $settings['editor_script'] = register_block_script_handle( 296 $metadata, 297 'editorScript' 298 ); 299 } 300 301 if ( ! empty( $metadata['script'] ) ) { 302 $settings['script'] = register_block_script_handle( 303 $metadata, 304 'script' 305 ); 306 } 307 308 if ( ! empty( $metadata['viewScript'] ) ) { 309 $settings['view_script'] = register_block_script_handle( 310 $metadata, 311 'viewScript' 312 ); 313 } 314 315 if ( ! empty( $metadata['editorStyle'] ) ) { 316 $settings['editor_style'] = register_block_style_handle( 317 $metadata, 318 'editorStyle' 319 ); 320 } 321 322 if ( ! empty( $metadata['style'] ) ) { 323 $settings['style'] = register_block_style_handle( 324 $metadata, 325 'style' 326 ); 327 } 328 329 /** 330 * Filters the settings determined from the block type metadata. 331 * 332 * @since 5.7.0 333 * 334 * @param array $settings Array of determined settings for registering a block type. 335 * @param array $metadata Metadata provided for registering a block type. 336 */ 337 $settings = apply_filters( 338 'block_type_metadata_settings', 339 array_merge( 340 $settings, 341 $args 342 ), 343 $metadata 344 ); 345 346 return WP_Block_Type_Registry::get_instance()->register( 347 $metadata['name'], 348 $settings 349 ); 350 } 351 352 /** 353 * Registers a block type. The recommended way is to register a block type using 354 * the metadata stored in the `block.json` file. 355 * 356 * @since 5.0.0 357 * @since 5.8.0 First parameter now accepts a path to the `block.json` file. 358 * 359 * @param string|WP_Block_Type $block_type Block type name including namespace, or alternatively 360 * a path to the JSON file with metadata definition for the block, 361 * or a path to the folder where the `block.json` file is located, 362 * or a complete WP_Block_Type instance. 363 * In case a WP_Block_Type is provided, the $args parameter will be ignored. 364 * @param array $args Optional. Array of block type arguments. Accepts any public property 365 * of `WP_Block_Type`. See WP_Block_Type::__construct() for information 366 * on accepted arguments. Default empty array. 367 * 368 * @return WP_Block_Type|false The registered block type on success, or false on failure. 369 */ 370 function register_block_type( $block_type, $args = array() ) { 371 if ( is_string( $block_type ) && file_exists( $block_type ) ) { 372 return register_block_type_from_metadata( $block_type, $args ); 373 } 374 375 return WP_Block_Type_Registry::get_instance()->register( $block_type, $args ); 376 } 377 378 /** 379 * Unregisters a block type. 380 * 381 * @since 5.0.0 382 * 383 * @param string|WP_Block_Type $name Block type name including namespace, or alternatively 384 * a complete WP_Block_Type instance. 385 * @return WP_Block_Type|false The unregistered block type on success, or false on failure. 386 */ 387 function unregister_block_type( $name ) { 388 return WP_Block_Type_Registry::get_instance()->unregister( $name ); 389 } 390 391 /** 392 * Determine whether a post or content string has blocks. 393 * 394 * This test optimizes for performance rather than strict accuracy, detecting 395 * the pattern of a block but not validating its structure. For strict accuracy, 396 * you should use the block parser on post content. 397 * 398 * @since 5.0.0 399 * 400 * @see parse_blocks() 401 * 402 * @param int|string|WP_Post|null $post Optional. Post content, post ID, or post object. 403 * Defaults to global $post. 404 * @return bool Whether the post has blocks. 405 */ 406 function has_blocks( $post = null ) { 407 if ( ! is_string( $post ) ) { 408 $wp_post = get_post( $post ); 409 if ( $wp_post instanceof WP_Post ) { 410 $post = $wp_post->post_content; 411 } 412 } 413 414 return false !== strpos( (string) $post, '<!-- wp:' ); 415 } 416 417 /** 418 * Determine whether a $post or a string contains a specific block type. 419 * 420 * This test optimizes for performance rather than strict accuracy, detecting 421 * whether the block type exists but not validating its structure and not checking 422 * reusable blocks. For strict accuracy, you should use the block parser on post content. 423 * 424 * @since 5.0.0 425 * 426 * @see parse_blocks() 427 * 428 * @param string $block_name Full block type to look for. 429 * @param int|string|WP_Post|null $post Optional. Post content, post ID, or post object. 430 * Defaults to global $post. 431 * @return bool Whether the post content contains the specified block. 432 */ 433 function has_block( $block_name, $post = null ) { 434 if ( ! has_blocks( $post ) ) { 435 return false; 436 } 437 438 if ( ! is_string( $post ) ) { 439 $wp_post = get_post( $post ); 440 if ( $wp_post instanceof WP_Post ) { 441 $post = $wp_post->post_content; 442 } 443 } 444 445 /* 446 * Normalize block name to include namespace, if provided as non-namespaced. 447 * This matches behavior for WordPress 5.0.0 - 5.3.0 in matching blocks by 448 * their serialized names. 449 */ 450 if ( false === strpos( $block_name, '/' ) ) { 451 $block_name = 'core/' . $block_name; 452 } 453 454 // Test for existence of block by its fully qualified name. 455 $has_block = false !== strpos( $post, '<!-- wp:' . $block_name . ' ' ); 456 457 if ( ! $has_block ) { 458 /* 459 * If the given block name would serialize to a different name, test for 460 * existence by the serialized form. 461 */ 462 $serialized_block_name = strip_core_block_namespace( $block_name ); 463 if ( $serialized_block_name !== $block_name ) { 464 $has_block = false !== strpos( $post, '<!-- wp:' . $serialized_block_name . ' ' ); 465 } 466 } 467 468 return $has_block; 469 } 470 471 /** 472 * Returns an array of the names of all registered dynamic block types. 473 * 474 * @since 5.0.0 475 * 476 * @return string[] Array of dynamic block names. 477 */ 478 function get_dynamic_block_names() { 479 $dynamic_block_names = array(); 480 481 $block_types = WP_Block_Type_Registry::get_instance()->get_all_registered(); 482 foreach ( $block_types as $block_type ) { 483 if ( $block_type->is_dynamic() ) { 484 $dynamic_block_names[] = $block_type->name; 485 } 486 } 487 488 return $dynamic_block_names; 489 } 490 491 /** 492 * Given an array of attributes, returns a string in the serialized attributes 493 * format prepared for post content. 494 * 495 * The serialized result is a JSON-encoded string, with unicode escape sequence 496 * substitution for characters which might otherwise interfere with embedding 497 * the result in an HTML comment. 498 * 499 * This function must produce output that remains in sync with the output of 500 * the serializeAttributes JavaScript function in the block editor in order 501 * to ensure consistent operation between PHP and JavaScript. 502 * 503 * @since 5.3.1 504 * 505 * @param array $block_attributes Attributes object. 506 * @return string Serialized attributes. 507 */ 508 function serialize_block_attributes( $block_attributes ) { 509 $encoded_attributes = wp_json_encode( $block_attributes, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE ); 510 $encoded_attributes = preg_replace( '/--/', '\\u002d\\u002d', $encoded_attributes ); 511 $encoded_attributes = preg_replace( '/</', '\\u003c', $encoded_attributes ); 512 $encoded_attributes = preg_replace( '/>/', '\\u003e', $encoded_attributes ); 513 $encoded_attributes = preg_replace( '/&/', '\\u0026', $encoded_attributes ); 514 // Regex: /\\"/ 515 $encoded_attributes = preg_replace( '/\\\\"/', '\\u0022', $encoded_attributes ); 516 517 return $encoded_attributes; 518 } 519 520 /** 521 * Returns the block name to use for serialization. This will remove the default 522 * "core/" namespace from a block name. 523 * 524 * @since 5.3.1 525 * 526 * @param string $block_name Original block name. 527 * @return string Block name to use for serialization. 528 */ 529 function strip_core_block_namespace( $block_name = null ) { 530 if ( is_string( $block_name ) && 0 === strpos( $block_name, 'core/' ) ) { 531 return substr( $block_name, 5 ); 532 } 533 534 return $block_name; 535 } 536 537 /** 538 * Returns the content of a block, including comment delimiters. 539 * 540 * @since 5.3.1 541 * 542 * @param string|null $block_name Block name. Null if the block name is unknown, 543 * e.g. Classic blocks have their name set to null. 544 * @param array $block_attributes Block attributes. 545 * @param string $block_content Block save content. 546 * @return string Comment-delimited block content. 547 */ 548 function get_comment_delimited_block_content( $block_name, $block_attributes, $block_content ) { 549 if ( is_null( $block_name ) ) { 550 return $block_content; 551 } 552 553 $serialized_block_name = strip_core_block_namespace( $block_name ); 554 $serialized_attributes = empty( $block_attributes ) ? '' : serialize_block_attributes( $block_attributes ) . ' '; 555 556 if ( empty( $block_content ) ) { 557 return sprintf( '<!-- wp:%s %s/-->', $serialized_block_name, $serialized_attributes ); 558 } 559 560 return sprintf( 561 '<!-- wp:%s %s-->%s<!-- /wp:%s -->', 562 $serialized_block_name, 563 $serialized_attributes, 564 $block_content, 565 $serialized_block_name 566 ); 567 } 568 569 /** 570 * Returns the content of a block, including comment delimiters, serializing all 571 * attributes from the given parsed block. 572 * 573 * This should be used when preparing a block to be saved to post content. 574 * Prefer `render_block` when preparing a block for display. Unlike 575 * `render_block`, this does not evaluate a block's `render_callback`, and will 576 * instead preserve the markup as parsed. 577 * 578 * @since 5.3.1 579 * 580 * @param WP_Block_Parser_Block $block A single parsed block object. 581 * @return string String of rendered HTML. 582 */ 583 function serialize_block( $block ) { 584 $block_content = ''; 585 586 $index = 0; 587 foreach ( $block['innerContent'] as $chunk ) { 588 $block_content .= is_string( $chunk ) ? $chunk : serialize_block( $block['innerBlocks'][ $index++ ] ); 589 } 590 591 if ( ! is_array( $block['attrs'] ) ) { 592 $block['attrs'] = array(); 593 } 594 595 return get_comment_delimited_block_content( 596 $block['blockName'], 597 $block['attrs'], 598 $block_content 599 ); 600 } 601 602 /** 603 * Returns a joined string of the aggregate serialization of the given parsed 604 * blocks. 605 * 606 * @since 5.3.1 607 * 608 * @param WP_Block_Parser_Block[] $blocks Parsed block objects. 609 * @return string String of rendered HTML. 610 */ 611 function serialize_blocks( $blocks ) { 612 return implode( '', array_map( 'serialize_block', $blocks ) ); 613 } 614 615 /** 616 * Filters and sanitizes block content to remove non-allowable HTML from 617 * parsed block attribute values. 618 * 619 * @since 5.3.1 620 * 621 * @param string $text Text that may contain block content. 622 * @param array[]|string $allowed_html An array of allowed HTML elements 623 * and attributes, or a context name 624 * such as 'post'. 625 * @param string[] $allowed_protocols Array of allowed URL protocols. 626 * @return string The filtered and sanitized content result. 627 */ 628 function filter_block_content( $text, $allowed_html = 'post', $allowed_protocols = array() ) { 629 $result = ''; 630 631 $blocks = parse_blocks( $text ); 632 foreach ( $blocks as $block ) { 633 $block = filter_block_kses( $block, $allowed_html, $allowed_protocols ); 634 $result .= serialize_block( $block ); 635 } 636 637 return $result; 638 } 639 640 /** 641 * Filters and sanitizes a parsed block to remove non-allowable HTML from block 642 * attribute values. 643 * 644 * @since 5.3.1 645 * 646 * @param WP_Block_Parser_Block $block The parsed block object. 647 * @param array[]|string $allowed_html An array of allowed HTML 648 * elements and attributes, or a 649 * context name such as 'post'. 650 * @param string[] $allowed_protocols Allowed URL protocols. 651 * @return array The filtered and sanitized block object result. 652 */ 653 function filter_block_kses( $block, $allowed_html, $allowed_protocols = array() ) { 654 $block['attrs'] = filter_block_kses_value( $block['attrs'], $allowed_html, $allowed_protocols ); 655 656 if ( is_array( $block['innerBlocks'] ) ) { 657 foreach ( $block['innerBlocks'] as $i => $inner_block ) { 658 $block['innerBlocks'][ $i ] = filter_block_kses( $inner_block, $allowed_html, $allowed_protocols ); 659 } 660 } 661 662 return $block; 663 } 664 665 /** 666 * Filters and sanitizes a parsed block attribute value to remove non-allowable 667 * HTML. 668 * 669 * @since 5.3.1 670 * 671 * @param string[]|string $value The attribute value to filter. 672 * @param array[]|string $allowed_html An array of allowed HTML elements 673 * and attributes, or a context name 674 * such as 'post'. 675 * @param string[] $allowed_protocols Array of allowed URL protocols. 676 * @return string[]|string The filtered and sanitized result. 677 */ 678 function filter_block_kses_value( $value, $allowed_html, $allowed_protocols = array() ) { 679 if ( is_array( $value ) ) { 680 foreach ( $value as $key => $inner_value ) { 681 $filtered_key = filter_block_kses_value( $key, $allowed_html, $allowed_protocols ); 682 $filtered_value = filter_block_kses_value( $inner_value, $allowed_html, $allowed_protocols ); 683 684 if ( $filtered_key !== $key ) { 685 unset( $value[ $key ] ); 686 } 687 688 $value[ $filtered_key ] = $filtered_value; 689 } 690 } elseif ( is_string( $value ) ) { 691 return wp_kses( $value, $allowed_html, $allowed_protocols ); 692 } 693 694 return $value; 695 } 696 697 /** 698 * Parses blocks out of a content string, and renders those appropriate for the excerpt. 699 * 700 * As the excerpt should be a small string of text relevant to the full post content, 701 * this function renders the blocks that are most likely to contain such text. 702 * 703 * @since 5.0.0 704 * 705 * @param string $content The content to parse. 706 * @return string The parsed and filtered content. 707 */ 708 function excerpt_remove_blocks( $content ) { 709 $allowed_inner_blocks = array( 710 // Classic blocks have their blockName set to null. 711 null, 712 'core/freeform', 713 'core/heading', 714 'core/html', 715 'core/list', 716 'core/media-text', 717 'core/paragraph', 718 'core/preformatted', 719 'core/pullquote', 720 'core/quote', 721 'core/table', 722 'core/verse', 723 ); 724 725 $allowed_wrapper_blocks = array( 726 'core/columns', 727 'core/column', 728 'core/group', 729 ); 730 731 /** 732 * Filters the list of blocks that can be used as wrapper blocks, allowing 733 * excerpts to be generated from the `innerBlocks` of these wrappers. 734 * 735 * @since 5.8.0 736 * 737 * @param string[] $allowed_wrapper_blocks The list of names of allowed wrapper blocks. 738 */ 739 $allowed_wrapper_blocks = apply_filters( 'excerpt_allowed_wrapper_blocks', $allowed_wrapper_blocks ); 740 741 $allowed_blocks = array_merge( $allowed_inner_blocks, $allowed_wrapper_blocks ); 742 743 /** 744 * Filters the list of blocks that can contribute to the excerpt. 745 * 746 * If a dynamic block is added to this list, it must not generate another 747 * excerpt, as this will cause an infinite loop to occur. 748 * 749 * @since 5.0.0 750 * 751 * @param string[] $allowed_blocks The list of names of allowed blocks. 752 */ 753 $allowed_blocks = apply_filters( 'excerpt_allowed_blocks', $allowed_blocks ); 754 $blocks = parse_blocks( $content ); 755 $output = ''; 756 757 foreach ( $blocks as $block ) { 758 if ( in_array( $block['blockName'], $allowed_blocks, true ) ) { 759 if ( ! empty( $block['innerBlocks'] ) ) { 760 if ( in_array( $block['blockName'], $allowed_wrapper_blocks, true ) ) { 761 $output .= _excerpt_render_inner_blocks( $block, $allowed_blocks ); 762 continue; 763 } 764 765 // Skip the block if it has disallowed or nested inner blocks. 766 foreach ( $block['innerBlocks'] as $inner_block ) { 767 if ( 768 ! in_array( $inner_block['blockName'], $allowed_inner_blocks, true ) || 769 ! empty( $inner_block['innerBlocks'] ) 770 ) { 771 continue 2; 772 } 773 } 774 } 775 776 $output .= render_block( $block ); 777 } 778 } 779 780 return $output; 781 } 782 783 /** 784 * Render inner blocks from the allowed wrapper blocks 785 * for generating an excerpt. 786 * 787 * @since 5.8.0 788 * @access private 789 * 790 * @param array $parsed_block The parsed block. 791 * @param array $allowed_blocks The list of allowed inner blocks. 792 * @return string The rendered inner blocks. 793 */ 794 function _excerpt_render_inner_blocks( $parsed_block, $allowed_blocks ) { 795 $output = ''; 796 797 foreach ( $parsed_block['innerBlocks'] as $inner_block ) { 798 if ( ! in_array( $inner_block['blockName'], $allowed_blocks, true ) ) { 799 continue; 800 } 801 802 if ( empty( $inner_block['innerBlocks'] ) ) { 803 $output .= render_block( $inner_block ); 804 } else { 805 $output .= _excerpt_render_inner_blocks( $inner_block, $allowed_blocks ); 806 } 807 } 808 809 return $output; 810 } 811 812 /** 813 * Renders a single block into a HTML string. 814 * 815 * @since 5.0.0 816 * 817 * @global WP_Post $post The post to edit. 818 * 819 * @param array $parsed_block A single parsed block object. 820 * @return string String of rendered HTML. 821 */ 822 function render_block( $parsed_block ) { 823 global $post; 824 $parent_block = null; 825 826 /** 827 * Allows render_block() to be short-circuited, by returning a non-null value. 828 * 829 * @since 5.1.0 830 * @since 5.9.0 The `$parent_block` parameter was added. 831 * 832 * @param string|null $pre_render The pre-rendered content. Default null. 833 * @param array $parsed_block The block being rendered. 834 * @param WP_Block|null $parent_block If this is a nested block, a reference to the parent block. 835 */ 836 $pre_render = apply_filters( 'pre_render_block', null, $parsed_block, $parent_block ); 837 if ( ! is_null( $pre_render ) ) { 838 return $pre_render; 839 } 840 841 $source_block = $parsed_block; 842 843 /** 844 * Filters the block being rendered in render_block(), before it's processed. 845 * 846 * @since 5.1.0 847 * @since 5.9.0 The `$parent_block` parameter was added. 848 * 849 * @param array $parsed_block The block being rendered. 850 * @param array $source_block An un-modified copy of $parsed_block, as it appeared in the source content. 851 * @param WP_Block|null $parent_block If this is a nested block, a reference to the parent block. 852 */ 853 $parsed_block = apply_filters( 'render_block_data', $parsed_block, $source_block, $parent_block ); 854 855 $context = array(); 856 857 if ( $post instanceof WP_Post ) { 858 $context['postId'] = $post->ID; 859 860 /* 861 * The `postType` context is largely unnecessary server-side, since the ID 862 * is usually sufficient on its own. That being said, since a block's 863 * manifest is expected to be shared between the server and the client, 864 * it should be included to consistently fulfill the expectation. 865 */ 866 $context['postType'] = $post->post_type; 867 } 868 869 /** 870 * Filters the default context provided to a rendered block. 871 * 872 * @since 5.5.0 873 * @since 5.9.0 The `$parent_block` parameter was added. 874 * 875 * @param array $context Default context. 876 * @param array $parsed_block Block being rendered, filtered by `render_block_data`. 877 * @param WP_Block|null $parent_block If this is a nested block, a reference to the parent block. 878 */ 879 $context = apply_filters( 'render_block_context', $context, $parsed_block, $parent_block ); 880 881 $block = new WP_Block( $parsed_block, $context ); 882 883 return $block->render(); 884 } 885 886 /** 887 * Parses blocks out of a content string. 888 * 889 * @since 5.0.0 890 * 891 * @param string $content Post content. 892 * @return array[] Array of parsed block objects. 893 */ 894 function parse_blocks( $content ) { 895 /** 896 * Filter to allow plugins to replace the server-side block parser 897 * 898 * @since 5.0.0 899 * 900 * @param string $parser_class Name of block parser class. 901 */ 902 $parser_class = apply_filters( 'block_parser_class', 'WP_Block_Parser' ); 903 904 $parser = new $parser_class(); 905 return $parser->parse( $content ); 906 } 907 908 /** 909 * Parses dynamic blocks out of `post_content` and re-renders them. 910 * 911 * @since 5.0.0 912 * 913 * @param string $content Post content. 914 * @return string Updated post content. 915 */ 916 function do_blocks( $content ) { 917 $blocks = parse_blocks( $content ); 918 $output = ''; 919 920 foreach ( $blocks as $block ) { 921 $output .= render_block( $block ); 922 } 923 924 // If there are blocks in this content, we shouldn't run wpautop() on it later. 925 $priority = has_filter( 'the_content', 'wpautop' ); 926 if ( false !== $priority && doing_filter( 'the_content' ) && has_blocks( $content ) ) { 927 remove_filter( 'the_content', 'wpautop', $priority ); 928 add_filter( 'the_content', '_restore_wpautop_hook', $priority + 1 ); 929 } 930 931 return $output; 932 } 933 934 /** 935 * If do_blocks() needs to remove wpautop() from the `the_content` filter, this re-adds it afterwards, 936 * for subsequent `the_content` usage. 937 * 938 * @access private 939 * 940 * @since 5.0.0 941 * 942 * @param string $content The post content running through this filter. 943 * @return string The unmodified content. 944 */ 945 function _restore_wpautop_hook( $content ) { 946 $current_priority = has_filter( 'the_content', '_restore_wpautop_hook' ); 947 948 add_filter( 'the_content', 'wpautop', $current_priority - 1 ); 949 remove_filter( 'the_content', '_restore_wpautop_hook', $current_priority ); 950 951 return $content; 952 } 953 954 /** 955 * Returns the current version of the block format that the content string is using. 956 * 957 * If the string doesn't contain blocks, it returns 0. 958 * 959 * @since 5.0.0 960 * 961 * @param string $content Content to test. 962 * @return int The block format version is 1 if the content contains one or more blocks, 0 otherwise. 963 */ 964 function block_version( $content ) { 965 return has_blocks( $content ) ? 1 : 0; 966 } 967 968 /** 969 * Registers a new block style. 970 * 971 * @since 5.3.0 972 * 973 * @param string $block_name Block type name including namespace. 974 * @param array $style_properties Array containing the properties of the style name, 975 * label, style (name of the stylesheet to be enqueued), 976 * inline_style (string containing the CSS to be added). 977 * @return bool True if the block style was registered with success and false otherwise. 978 */ 979 function register_block_style( $block_name, $style_properties ) { 980 return WP_Block_Styles_Registry::get_instance()->register( $block_name, $style_properties ); 981 } 982 983 /** 984 * Unregisters a block style. 985 * 986 * @since 5.3.0 987 * 988 * @param string $block_name Block type name including namespace. 989 * @param string $block_style_name Block style name. 990 * @return bool True if the block style was unregistered with success and false otherwise. 991 */ 992 function unregister_block_style( $block_name, $block_style_name ) { 993 return WP_Block_Styles_Registry::get_instance()->unregister( $block_name, $block_style_name ); 994 } 995 996 /** 997 * Checks whether the current block type supports the feature requested. 998 * 999 * @since 5.8.0 1000 * 1001 * @param WP_Block_Type $block_type Block type to check for support. 1002 * @param string $feature Name of the feature to check support for. 1003 * @param mixed $default Optional. Fallback value for feature support. Default false. 1004 * @return bool Whether the feature is supported. 1005 */ 1006 function block_has_support( $block_type, $feature, $default = false ) { 1007 $block_support = $default; 1008 if ( $block_type && property_exists( $block_type, 'supports' ) ) { 1009 $block_support = _wp_array_get( $block_type->supports, $feature, $default ); 1010 } 1011 1012 return true === $block_support || is_array( $block_support ); 1013 } 1014 1015 /** 1016 * Converts typography keys declared under `supports.*` to `supports.typography.*`. 1017 * 1018 * Displays a `_doing_it_wrong()` notice when a block using the older format is detected. 1019 * 1020 * @since 5.8.0 1021 * 1022 * @param array $metadata Metadata for registering a block type. 1023 * @return array Filtered metadata for registering a block type. 1024 */ 1025 function wp_migrate_old_typography_shape( $metadata ) { 1026 if ( ! isset( $metadata['supports'] ) ) { 1027 return $metadata; 1028 } 1029 1030 $typography_keys = array( 1031 '__experimentalFontFamily', 1032 '__experimentalFontStyle', 1033 '__experimentalFontWeight', 1034 '__experimentalLetterSpacing', 1035 '__experimentalTextDecoration', 1036 '__experimentalTextTransform', 1037 'fontSize', 1038 'lineHeight', 1039 ); 1040 1041 foreach ( $typography_keys as $typography_key ) { 1042 $support_for_key = _wp_array_get( $metadata['supports'], array( $typography_key ), null ); 1043 1044 if ( null !== $support_for_key ) { 1045 _doing_it_wrong( 1046 'register_block_type_from_metadata()', 1047 sprintf( 1048 /* translators: 1: Block type, 2: Typography supports key, e.g: fontSize, lineHeight, etc. 3: block.json, 4: Old metadata key, 5: New metadata key. */ 1049 __( 'Block "%1$s" is declaring %2$s support in %3$s file under %4$s. %2$s support is now declared under %5$s.' ), 1050 $metadata['name'], 1051 "<code>$typography_key</code>", 1052 '<code>block.json</code>', 1053 "<code>supports.$typography_key</code>", 1054 "<code>supports.typography.$typography_key</code>" 1055 ), 1056 '5.8.0' 1057 ); 1058 1059 _wp_array_set( $metadata['supports'], array( 'typography', $typography_key ), $support_for_key ); 1060 unset( $metadata['supports'][ $typography_key ] ); 1061 } 1062 } 1063 1064 return $metadata; 1065 } 1066 1067 /** 1068 * Helper function that constructs a WP_Query args array from 1069 * a `Query` block properties. 1070 * 1071 * It's used in Query Loop, Query Pagination Numbers and Query Pagination Next blocks. 1072 * 1073 * @since 5.8.0 1074 * 1075 * @param WP_Block $block Block instance. 1076 * @param int $page Current query's page. 1077 * 1078 * @return array Returns the constructed WP_Query arguments. 1079 */ 1080 function build_query_vars_from_query_block( $block, $page ) { 1081 $query = array( 1082 'post_type' => 'post', 1083 'order' => 'DESC', 1084 'orderby' => 'date', 1085 'post__not_in' => array(), 1086 ); 1087 1088 if ( isset( $block->context['query'] ) ) { 1089 if ( ! empty( $block->context['query']['postType'] ) ) { 1090 $post_type_param = $block->context['query']['postType']; 1091 if ( is_post_type_viewable( $post_type_param ) ) { 1092 $query['post_type'] = $post_type_param; 1093 } 1094 } 1095 if ( isset( $block->context['query']['sticky'] ) && ! empty( $block->context['query']['sticky'] ) ) { 1096 $sticky = get_option( 'sticky_posts' ); 1097 if ( 'only' === $block->context['query']['sticky'] ) { 1098 $query['post__in'] = $sticky; 1099 } else { 1100 $query['post__not_in'] = array_merge( $query['post__not_in'], $sticky ); 1101 } 1102 } 1103 if ( ! empty( $block->context['query']['exclude'] ) ) { 1104 $excluded_post_ids = array_map( 'intval', $block->context['query']['exclude'] ); 1105 $excluded_post_ids = array_filter( $excluded_post_ids ); 1106 $query['post__not_in'] = array_merge( $query['post__not_in'], $excluded_post_ids ); 1107 } 1108 if ( 1109 isset( $block->context['query']['perPage'] ) && 1110 is_numeric( $block->context['query']['perPage'] ) 1111 ) { 1112 $per_page = absint( $block->context['query']['perPage'] ); 1113 $offset = 0; 1114 1115 if ( 1116 isset( $block->context['query']['offset'] ) && 1117 is_numeric( $block->context['query']['offset'] ) 1118 ) { 1119 $offset = absint( $block->context['query']['offset'] ); 1120 } 1121 1122 $query['offset'] = ( $per_page * ( $page - 1 ) ) + $offset; 1123 $query['posts_per_page'] = $per_page; 1124 } 1125 if ( ! empty( $block->context['query']['categoryIds'] ) ) { 1126 $term_ids = array_map( 'intval', $block->context['query']['categoryIds'] ); 1127 $term_ids = array_filter( $term_ids ); 1128 $query['category__in'] = $term_ids; 1129 } 1130 if ( ! empty( $block->context['query']['tagIds'] ) ) { 1131 $term_ids = array_map( 'intval', $block->context['query']['tagIds'] ); 1132 $term_ids = array_filter( $term_ids ); 1133 $query['tag__in'] = $term_ids; 1134 } 1135 if ( 1136 isset( $block->context['query']['order'] ) && 1137 in_array( strtoupper( $block->context['query']['order'] ), array( 'ASC', 'DESC' ), true ) 1138 ) { 1139 $query['order'] = strtoupper( $block->context['query']['order'] ); 1140 } 1141 if ( isset( $block->context['query']['orderBy'] ) ) { 1142 $query['orderby'] = $block->context['query']['orderBy']; 1143 } 1144 if ( 1145 isset( $block->context['query']['author'] ) && 1146 (int) $block->context['query']['author'] > 0 1147 ) { 1148 $query['author'] = (int) $block->context['query']['author']; 1149 } 1150 if ( ! empty( $block->context['query']['search'] ) ) { 1151 $query['s'] = $block->context['query']['search']; 1152 } 1153 } 1154 return $query; 1155 } 1156 1157 /** 1158 * Helper function that returns the proper pagination arrow html for 1159 * `QueryPaginationNext` and `QueryPaginationPrevious` blocks based 1160 * on the provided `paginationArrow` from `QueryPagination` context. 1161 * 1162 * It's used in QueryPaginationNext and QueryPaginationPrevious blocks. 1163 * 1164 * @since 5.9.0 1165 * 1166 * @param WP_Block $block Block instance. 1167 * @param boolean $is_next Flag for handling `next/previous` blocks. 1168 * 1169 * @return string|null Returns the constructed WP_Query arguments. 1170 */ 1171 function get_query_pagination_arrow( $block, $is_next ) { 1172 $arrow_map = array( 1173 'none' => '', 1174 'arrow' => array( 1175 'next' => '→', 1176 'previous' => '←', 1177 ), 1178 'chevron' => array( 1179 'next' => '»', 1180 'previous' => '«', 1181 ), 1182 ); 1183 if ( ! empty( $block->context['paginationArrow'] ) && array_key_exists( $block->context['paginationArrow'], $arrow_map ) && ! empty( $arrow_map[ $block->context['paginationArrow'] ] ) ) { 1184 $pagination_type = $is_next ? 'next' : 'previous'; 1185 $arrow_attribute = $block->context['paginationArrow']; 1186 $arrow = $arrow_map[ $block->context['paginationArrow'] ][ $pagination_type ]; 1187 $arrow_classes = "wp-block-query-pagination-$pagination_type-arrow is-arrow-$arrow_attribute"; 1188 return "<span class='$arrow_classes'>$arrow</span>"; 1189 } 1190 return null; 1191 } 1192 1193 /** 1194 * Enqueues a stylesheet for a specific block. 1195 * 1196 * If the theme has opted-in to separate-styles loading, 1197 * then the stylesheet will be enqueued on-render, 1198 * otherwise when the block inits. 1199 * 1200 * @since 5.9.0 1201 * 1202 * @param string $block_name The block-name, including namespace. 1203 * @param array $args An array of arguments [handle,src,deps,ver,media]. 1204 * @return void 1205 */ 1206 function wp_enqueue_block_style( $block_name, $args ) { 1207 $args = wp_parse_args( 1208 $args, 1209 array( 1210 'handle' => '', 1211 'src' => '', 1212 'deps' => array(), 1213 'ver' => false, 1214 'media' => 'all', 1215 ) 1216 ); 1217 1218 /** 1219 * Callback function to register and enqueue styles. 1220 * 1221 * @param string $content When the callback is used for the render_block filter, 1222 * the content needs to be returned so the function parameter 1223 * is to ensure the content exists. 1224 * @return string Block content. 1225 */ 1226 $callback = static function( $content ) use ( $args ) { 1227 // Register the stylesheet. 1228 if ( ! empty( $args['src'] ) ) { 1229 wp_register_style( $args['handle'], $args['src'], $args['deps'], $args['ver'], $args['media'] ); 1230 } 1231 1232 // Add `path` data if provided. 1233 if ( isset( $args['path'] ) ) { 1234 wp_style_add_data( $args['handle'], 'path', $args['path'] ); 1235 1236 // Get the RTL file path. 1237 $rtl_file_path = str_replace( '.css', '-rtl.css', $args['path'] ); 1238 1239 // Add RTL stylesheet. 1240 if ( file_exists( $rtl_file_path ) ) { 1241 wp_style_add_data( $args['handle'], 'rtl', 'replace' ); 1242 1243 if ( is_rtl() ) { 1244 wp_style_add_data( $args['handle'], 'path', $rtl_file_path ); 1245 } 1246 } 1247 } 1248 1249 // Enqueue the stylesheet. 1250 wp_enqueue_style( $args['handle'] ); 1251 1252 return $content; 1253 }; 1254 1255 $hook = did_action( 'wp_enqueue_scripts' ) ? 'wp_footer' : 'wp_enqueue_scripts'; 1256 if ( wp_should_load_separate_core_block_assets() ) { 1257 /** 1258 * Callback function to register and enqueue styles. 1259 * 1260 * @param string $content The block content. 1261 * @param array $block The full block, including name and attributes. 1262 * @return string Block content. 1263 */ 1264 $callback_separate = static function( $content, $block ) use ( $block_name, $callback ) { 1265 if ( ! empty( $block['blockName'] ) && $block_name === $block['blockName'] ) { 1266 return $callback( $content ); 1267 } 1268 return $content; 1269 }; 1270 1271 /* 1272 * The filter's callback here is an anonymous function because 1273 * using a named function in this case is not possible. 1274 * 1275 * The function cannot be unhooked, however, users are still able 1276 * to dequeue the stylesheets registered/enqueued by the callback 1277 * which is why in this case, using an anonymous function 1278 * was deemed acceptable. 1279 */ 1280 add_filter( 'render_block', $callback_separate, 10, 2 ); 1281 return; 1282 } 1283 1284 /* 1285 * The filter's callback here is an anonymous function because 1286 * using a named function in this case is not possible. 1287 * 1288 * The function cannot be unhooked, however, users are still able 1289 * to dequeue the stylesheets registered/enqueued by the callback 1290 * which is why in this case, using an anonymous function 1291 * was deemed acceptable. 1292 */ 1293 add_filter( $hook, $callback ); 1294 1295 // Enqueue assets in the editor. 1296 add_action( 'enqueue_block_assets', $callback ); 1297 } 1298 1299 /** 1300 * Allow multiple block styles. 1301 * 1302 * @since 5.9.0 1303 * 1304 * @param array $metadata Metadata for registering a block type. 1305 * @return array Metadata for registering a block type. 1306 */ 1307 function _wp_multiple_block_styles( $metadata ) { 1308 foreach ( array( 'style', 'editorStyle' ) as $key ) { 1309 if ( ! empty( $metadata[ $key ] ) && is_array( $metadata[ $key ] ) ) { 1310 $default_style = array_shift( $metadata[ $key ] ); 1311 foreach ( $metadata[ $key ] as $handle ) { 1312 $args = array( 'handle' => $handle ); 1313 if ( 0 === strpos( $handle, 'file:' ) && isset( $metadata['file'] ) ) { 1314 $style_path = remove_block_asset_path_prefix( $handle ); 1315 $args = array( 1316 'handle' => sanitize_key( "{$metadata['name']}-{$style_path}" ), 1317 'src' => plugins_url( $style_path, $metadata['file'] ), 1318 ); 1319 } 1320 1321 wp_enqueue_block_style( $metadata['name'], $args ); 1322 } 1323 1324 // Only return the 1st item in the array. 1325 $metadata[ $key ] = $default_style; 1326 } 1327 } 1328 return $metadata; 1329 } 1330 add_filter( 'block_type_metadata', '_wp_multiple_block_styles' );
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated: Wed Jan 26 01:00:03 2022 | Cross-referenced by PHPXref 0.7.1 |