| [ Index ] |
PHP Cross Reference of WordPress Trunk (Updated Daily) |
[Summary view] [Print] [Text view]
1 <?php 2 /** 3 * Interactivity API: WP_Interactivity_API class. 4 * 5 * @package WordPress 6 * @subpackage Interactivity API 7 * @since 6.5.0 8 */ 9 10 /** 11 * Class used to process the Interactivity API on the server. 12 * 13 * @since 6.5.0 14 */ 15 final class WP_Interactivity_API { 16 /** 17 * Holds the mapping of directive attribute names to their processor methods. 18 * 19 * @since 6.5.0 20 * @var array 21 */ 22 private static $directive_processors = array( 23 'data-wp-interactive' => 'data_wp_interactive_processor', 24 'data-wp-router-region' => 'data_wp_router_region_processor', 25 'data-wp-context' => 'data_wp_context_processor', 26 'data-wp-bind' => 'data_wp_bind_processor', 27 'data-wp-class' => 'data_wp_class_processor', 28 'data-wp-style' => 'data_wp_style_processor', 29 'data-wp-text' => 'data_wp_text_processor', 30 /* 31 * `data-wp-each` needs to be processed in the last place because it moves 32 * the cursor to the end of the processed items to prevent them to be 33 * processed twice. 34 */ 35 'data-wp-each' => 'data_wp_each_processor', 36 ); 37 38 /** 39 * Holds the initial state of the different Interactivity API stores. 40 * 41 * This state is used during the server directive processing. Then, it is 42 * serialized and sent to the client as part of the interactivity data to be 43 * recovered during the hydration of the client interactivity stores. 44 * 45 * @since 6.5.0 46 * @var array 47 */ 48 private $state_data = array(); 49 50 /** 51 * Holds the configuration required by the different Interactivity API stores. 52 * 53 * This configuration is serialized and sent to the client as part of the 54 * interactivity data and can be accessed by the client interactivity stores. 55 * 56 * @since 6.5.0 57 * @var array 58 */ 59 private $config_data = array(); 60 61 /** 62 * Flag that indicates whether the `data-wp-router-region` directive has 63 * been found in the HTML and processed. 64 * 65 * The value is saved in a private property of the WP_Interactivity_API 66 * instance instead of using a static variable inside the processor 67 * function, which would hold the same value for all instances 68 * independently of whether they have processed any 69 * `data-wp-router-region` directive or not. 70 * 71 * @since 6.5.0 72 * @var bool 73 */ 74 private $has_processed_router_region = false; 75 76 /** 77 * Stack of namespaces defined by `data-wp-interactive` directives, in 78 * the order they are processed. 79 * 80 * This is only available during directive processing, otherwise it is `null`. 81 * 82 * @since 6.6.0 83 * @var array<string>|null 84 */ 85 private $namespace_stack = null; 86 87 /** 88 * Stack of contexts defined by `data-wp-context` directives, in 89 * the order they are processed. 90 * 91 * This is only available during directive processing, otherwise it is `null`. 92 * 93 * @since 6.6.0 94 * @var array<array<mixed>>|null 95 */ 96 private $context_stack = null; 97 98 /** 99 * Representation in array format of the element currently being processed. 100 * 101 * This is only available during directive processing, otherwise it is `null`. 102 * 103 * @since 6.7.0 104 * @var array{attributes: array<string, string|bool>}|null 105 */ 106 private $current_element = null; 107 108 /** 109 * Gets and/or sets the initial state of an Interactivity API store for a 110 * given namespace. 111 * 112 * If state for that store namespace already exists, it merges the new 113 * provided state with the existing one. 114 * 115 * When no namespace is specified, it returns the state defined for the 116 * current value in the internal namespace stack during a `process_directives` call. 117 * 118 * @since 6.5.0 119 * @since 6.6.0 The `$store_namespace` param is optional. 120 * 121 * @param string $store_namespace Optional. The unique store namespace identifier. 122 * @param array $state Optional. The array that will be merged with the existing state for the specified 123 * store namespace. 124 * @return array The current state for the specified store namespace. This will be the updated state if a $state 125 * argument was provided. 126 */ 127 public function state( ?string $store_namespace = null, ?array $state = null ): array { 128 if ( ! $store_namespace ) { 129 if ( $state ) { 130 _doing_it_wrong( 131 __METHOD__, 132 __( 'The namespace is required when state data is passed.' ), 133 '6.6.0' 134 ); 135 return array(); 136 } 137 if ( null !== $store_namespace ) { 138 _doing_it_wrong( 139 __METHOD__, 140 __( 'The namespace should be a non-empty string.' ), 141 '6.6.0' 142 ); 143 return array(); 144 } 145 if ( null === $this->namespace_stack ) { 146 _doing_it_wrong( 147 __METHOD__, 148 __( 'The namespace can only be omitted during directive processing.' ), 149 '6.6.0' 150 ); 151 return array(); 152 } 153 154 $store_namespace = end( $this->namespace_stack ); 155 } 156 if ( ! isset( $this->state_data[ $store_namespace ] ) ) { 157 $this->state_data[ $store_namespace ] = array(); 158 } 159 if ( is_array( $state ) ) { 160 $this->state_data[ $store_namespace ] = array_replace_recursive( 161 $this->state_data[ $store_namespace ], 162 $state 163 ); 164 } 165 return $this->state_data[ $store_namespace ]; 166 } 167 168 /** 169 * Gets and/or sets the configuration of the Interactivity API for a given 170 * store namespace. 171 * 172 * If configuration for that store namespace exists, it merges the new 173 * provided configuration with the existing one. 174 * 175 * @since 6.5.0 176 * 177 * @param string $store_namespace The unique store namespace identifier. 178 * @param array $config Optional. The array that will be merged with the existing configuration for the 179 * specified store namespace. 180 * @return array The configuration for the specified store namespace. This will be the updated configuration if a 181 * $config argument was provided. 182 */ 183 public function config( string $store_namespace, array $config = array() ): array { 184 if ( ! isset( $this->config_data[ $store_namespace ] ) ) { 185 $this->config_data[ $store_namespace ] = array(); 186 } 187 if ( is_array( $config ) ) { 188 $this->config_data[ $store_namespace ] = array_replace_recursive( 189 $this->config_data[ $store_namespace ], 190 $config 191 ); 192 } 193 return $this->config_data[ $store_namespace ]; 194 } 195 196 /** 197 * Prints the serialized client-side interactivity data. 198 * 199 * Encodes the config and initial state into JSON and prints them inside a 200 * script tag of type "application/json". Once in the browser, the state will 201 * be parsed and used to hydrate the client-side interactivity stores and the 202 * configuration will be available using a `getConfig` utility. 203 * 204 * @since 6.5.0 205 * 206 * @deprecated 6.7.0 Client data passing is handled by the {@see "script_module_data_{$module_id}"} filter. 207 */ 208 public function print_client_interactivity_data() { 209 _deprecated_function( __METHOD__, '6.7.0' ); 210 } 211 212 /** 213 * Set client-side interactivity-router data. 214 * 215 * Once in the browser, the state will be parsed and used to hydrate the client-side 216 * interactivity stores and the configuration will be available using a `getConfig` utility. 217 * 218 * @since 6.7.0 219 * 220 * @param array $data Data to filter. 221 * @return array Data for the Interactivity Router script module. 222 */ 223 public function filter_script_module_interactivity_router_data( array $data ): array { 224 if ( ! isset( $data['i18n'] ) ) { 225 $data['i18n'] = array(); 226 } 227 $data['i18n']['loading'] = __( 'Loading page, please wait.' ); 228 $data['i18n']['loaded'] = __( 'Page Loaded.' ); 229 return $data; 230 } 231 232 /** 233 * Set client-side interactivity data. 234 * 235 * Once in the browser, the state will be parsed and used to hydrate the client-side 236 * interactivity stores and the configuration will be available using a `getConfig` utility. 237 * 238 * @since 6.7.0 239 * 240 * @param array $data Data to filter. 241 * @return array Data for the Interactivity API script module. 242 */ 243 public function filter_script_module_interactivity_data( array $data ): array { 244 if ( empty( $this->state_data ) && empty( $this->config_data ) ) { 245 return $data; 246 } 247 248 $config = array(); 249 foreach ( $this->config_data as $key => $value ) { 250 if ( ! empty( $value ) ) { 251 $config[ $key ] = $value; 252 } 253 } 254 if ( ! empty( $config ) ) { 255 $data['config'] = $config; 256 } 257 258 $state = array(); 259 foreach ( $this->state_data as $key => $value ) { 260 if ( ! empty( $value ) ) { 261 $state[ $key ] = $value; 262 } 263 } 264 if ( ! empty( $state ) ) { 265 $data['state'] = $state; 266 } 267 268 return $data; 269 } 270 271 /** 272 * Returns the latest value on the context stack with the passed namespace. 273 * 274 * When the namespace is omitted, it uses the current namespace on the 275 * namespace stack during a `process_directives` call. 276 * 277 * @since 6.6.0 278 * 279 * @param string $store_namespace Optional. The unique store namespace identifier. 280 */ 281 public function get_context( ?string $store_namespace = null ): array { 282 if ( null === $this->context_stack ) { 283 _doing_it_wrong( 284 __METHOD__, 285 __( 'The context can only be read during directive processing.' ), 286 '6.6.0' 287 ); 288 return array(); 289 } 290 291 if ( ! $store_namespace ) { 292 if ( null !== $store_namespace ) { 293 _doing_it_wrong( 294 __METHOD__, 295 __( 'The namespace should be a non-empty string.' ), 296 '6.6.0' 297 ); 298 return array(); 299 } 300 301 $store_namespace = end( $this->namespace_stack ); 302 } 303 304 $context = end( $this->context_stack ); 305 306 return ( $store_namespace && $context && isset( $context[ $store_namespace ] ) ) 307 ? $context[ $store_namespace ] 308 : array(); 309 } 310 311 /** 312 * Returns an array representation of the current element being processed. 313 * 314 * The returned array contains a copy of the element attributes. 315 * 316 * @since 6.7.0 317 * 318 * @return array{attributes: array<string, string|bool>}|null Current element. 319 */ 320 public function get_element(): ?array { 321 if ( null === $this->current_element ) { 322 _doing_it_wrong( 323 __METHOD__, 324 __( 'The element can only be read during directive processing.' ), 325 '6.7.0' 326 ); 327 } 328 329 return $this->current_element; 330 } 331 332 /** 333 * Registers the `@wordpress/interactivity` script modules. 334 * 335 * @deprecated 6.7.0 Script Modules registration is handled by {@see wp_default_script_modules()}. 336 * 337 * @since 6.5.0 338 */ 339 public function register_script_modules() { 340 _deprecated_function( __METHOD__, '6.7.0', 'wp_default_script_modules' ); 341 } 342 343 /** 344 * Adds the necessary hooks for the Interactivity API. 345 * 346 * @since 6.5.0 347 */ 348 public function add_hooks() { 349 add_filter( 'script_module_data_@wordpress/interactivity', array( $this, 'filter_script_module_interactivity_data' ) ); 350 add_filter( 'script_module_data_@wordpress/interactivity-router', array( $this, 'filter_script_module_interactivity_router_data' ) ); 351 } 352 353 /** 354 * Processes the interactivity directives contained within the HTML content 355 * and updates the markup accordingly. 356 * 357 * @since 6.5.0 358 * 359 * @param string $html The HTML content to process. 360 * @return string The processed HTML content. It returns the original content when the HTML contains unbalanced tags. 361 */ 362 public function process_directives( string $html ): string { 363 if ( ! str_contains( $html, 'data-wp-' ) ) { 364 return $html; 365 } 366 367 $this->namespace_stack = array(); 368 $this->context_stack = array(); 369 370 $result = $this->_process_directives( $html ); 371 372 $this->namespace_stack = null; 373 $this->context_stack = null; 374 375 return null === $result ? $html : $result; 376 } 377 378 /** 379 * Processes the interactivity directives contained within the HTML content 380 * and updates the markup accordingly. 381 * 382 * It uses the WP_Interactivity_API instance's context and namespace stacks, 383 * which are shared between all calls. 384 * 385 * This method returns null if the HTML contains unbalanced tags. 386 * 387 * @since 6.6.0 388 * 389 * @param string $html The HTML content to process. 390 * @return string|null The processed HTML content. It returns null when the HTML contains unbalanced tags. 391 */ 392 private function _process_directives( string $html ) { 393 $p = new WP_Interactivity_API_Directives_Processor( $html ); 394 $tag_stack = array(); 395 $unbalanced = false; 396 397 $directive_processor_prefixes = array_keys( self::$directive_processors ); 398 $directive_processor_prefixes_reversed = array_reverse( $directive_processor_prefixes ); 399 400 /* 401 * Save the current size for each stack to restore them in case 402 * the processing finds unbalanced tags. 403 */ 404 $namespace_stack_size = count( $this->namespace_stack ); 405 $context_stack_size = count( $this->context_stack ); 406 407 while ( $p->next_tag( array( 'tag_closers' => 'visit' ) ) ) { 408 $tag_name = $p->get_tag(); 409 410 /* 411 * Directives inside SVG and MATH tags are not processed, 412 * as they are not compatible with the Tag Processor yet. 413 * We still process the rest of the HTML. 414 */ 415 if ( 'SVG' === $tag_name || 'MATH' === $tag_name ) { 416 if ( $p->get_attribute_names_with_prefix( 'data-wp-' ) ) { 417 /* translators: 1: SVG or MATH HTML tag, 2: Namespace of the interactive block. */ 418 $message = sprintf( __( 'Interactivity directives were detected on an incompatible %1$s tag when processing "%2$s". These directives will be ignored in the server side render.' ), $tag_name, end( $this->namespace_stack ) ); 419 _doing_it_wrong( __METHOD__, $message, '6.6.0' ); 420 } 421 $p->skip_to_tag_closer(); 422 continue; 423 } 424 425 if ( $p->is_tag_closer() ) { 426 list( $opening_tag_name, $directives_prefixes ) = end( $tag_stack ); 427 428 if ( 0 === count( $tag_stack ) || $opening_tag_name !== $tag_name ) { 429 430 /* 431 * If the tag stack is empty or the matching opening tag is not the 432 * same than the closing tag, it means the HTML is unbalanced and it 433 * stops processing it. 434 */ 435 $unbalanced = true; 436 break; 437 } else { 438 // Remove the last tag from the stack. 439 array_pop( $tag_stack ); 440 } 441 } else { 442 if ( 0 !== count( $p->get_attribute_names_with_prefix( 'data-wp-each-child' ) ) ) { 443 /* 444 * If the tag has a `data-wp-each-child` directive, jump to its closer 445 * tag because those tags have already been processed. 446 */ 447 $p->next_balanced_tag_closer_tag(); 448 continue; 449 } else { 450 $directives_prefixes = array(); 451 452 // Checks if there is a server directive processor registered for each directive. 453 foreach ( $p->get_attribute_names_with_prefix( 'data-wp-' ) as $attribute_name ) { 454 if ( ! preg_match( 455 /* 456 * This must align with the client-side regex used by the interactivity API. 457 * @see https://github.com/WordPress/gutenberg/blob/ca616014255efbb61f34c10917d52a2d86c1c660/packages/interactivity/src/vdom.ts#L20-L32 458 */ 459 '/' . 460 '^data-wp-' . 461 // Match alphanumeric characters including hyphen-separated 462 // segments. It excludes underscore intentionally to prevent confusion. 463 // E.g., "custom-directive". 464 '([a-z0-9]+(?:-[a-z0-9]+)*)' . 465 // (Optional) Match '--' followed by any alphanumeric charachters. It 466 // excludes underscore intentionally to prevent confusion, but it can 467 // contain multiple hyphens. E.g., "--custom-prefix--with-more-info". 468 '(?:--([a-z0-9_-]+))?$' . 469 '/i', 470 $attribute_name 471 ) ) { 472 continue; 473 } 474 list( $directive_prefix ) = $this->extract_prefix_and_suffix( $attribute_name ); 475 if ( array_key_exists( $directive_prefix, self::$directive_processors ) ) { 476 $directives_prefixes[] = $directive_prefix; 477 } 478 } 479 480 /* 481 * If this tag will visit its closer tag, it adds it to the tag stack 482 * so it can process its closing tag and check for unbalanced tags. 483 */ 484 if ( $p->has_and_visits_its_closer_tag() ) { 485 $tag_stack[] = array( $tag_name, $directives_prefixes ); 486 } 487 } 488 } 489 /* 490 * If the matching opener tag didn't have any directives, it can skip the 491 * processing. 492 */ 493 if ( 0 === count( $directives_prefixes ) ) { 494 continue; 495 } 496 497 // Directive processing might be different depending on if it is entering the tag or exiting it. 498 $modes = array( 499 'enter' => ! $p->is_tag_closer(), 500 'exit' => $p->is_tag_closer() || ! $p->has_and_visits_its_closer_tag(), 501 ); 502 503 // Get the element attributes to include them in the element representation. 504 $element_attrs = array(); 505 $attr_names = $p->get_attribute_names_with_prefix( '' ) ?? array(); 506 507 foreach ( $attr_names as $name ) { 508 $element_attrs[ $name ] = $p->get_attribute( $name ); 509 } 510 511 // Assign the current element right before running its directive processors. 512 $this->current_element = array( 513 'attributes' => $element_attrs, 514 ); 515 516 foreach ( $modes as $mode => $should_run ) { 517 if ( ! $should_run ) { 518 continue; 519 } 520 521 /* 522 * Sorts the attributes by the order of the `directives_processor` array 523 * and checks what directives are present in this element. 524 */ 525 $existing_directives_prefixes = array_intersect( 526 'enter' === $mode ? $directive_processor_prefixes : $directive_processor_prefixes_reversed, 527 $directives_prefixes 528 ); 529 foreach ( $existing_directives_prefixes as $directive_prefix ) { 530 $func = is_array( self::$directive_processors[ $directive_prefix ] ) 531 ? self::$directive_processors[ $directive_prefix ] 532 : array( $this, self::$directive_processors[ $directive_prefix ] ); 533 534 call_user_func_array( $func, array( $p, $mode, &$tag_stack ) ); 535 } 536 } 537 538 // Clear the current element. 539 $this->current_element = null; 540 } 541 542 if ( $unbalanced ) { 543 // Reset the namespace and context stacks to their previous values. 544 array_splice( $this->namespace_stack, $namespace_stack_size ); 545 array_splice( $this->context_stack, $context_stack_size ); 546 } 547 548 /* 549 * It returns null if the HTML is unbalanced because unbalanced HTML is 550 * not safe to process. In that case, the Interactivity API runtime will 551 * update the HTML on the client side during the hydration. It will also 552 * display a notice to the developer to inform them about the issue. 553 */ 554 if ( $unbalanced || 0 < count( $tag_stack ) ) { 555 $tag_errored = 0 < count( $tag_stack ) ? end( $tag_stack )[0] : $tag_name; 556 /* translators: %1s: Namespace processed, %2s: The tag that caused the error; could be any HTML tag. */ 557 $message = sprintf( __( 'Interactivity directives failed to process in "%1$s" due to a missing "%2$s" end tag.' ), end( $this->namespace_stack ), $tag_errored ); 558 _doing_it_wrong( __METHOD__, $message, '6.6.0' ); 559 return null; 560 } 561 562 return $p->get_updated_html(); 563 } 564 565 /** 566 * Evaluates the reference path passed to a directive based on the current 567 * store namespace, state and context. 568 * 569 * @since 6.5.0 570 * @since 6.6.0 The function now adds a warning when the namespace is null, falsy, or the directive value is empty. 571 * @since 6.6.0 Removed `default_namespace` and `context` arguments. 572 * @since 6.6.0 Add support for derived state. 573 * 574 * @param string|true $directive_value The directive attribute value string or `true` when it's a boolean attribute. 575 * @return mixed|null The result of the evaluation. Null if the reference path doesn't exist or the namespace is falsy. 576 */ 577 private function evaluate( $directive_value ) { 578 $default_namespace = end( $this->namespace_stack ); 579 $context = end( $this->context_stack ); 580 581 list( $ns, $path ) = $this->extract_directive_value( $directive_value, $default_namespace ); 582 if ( ! $ns || ! $path ) { 583 /* translators: %s: The directive value referenced. */ 584 $message = sprintf( __( 'Namespace or reference path cannot be empty. Directive value referenced: %s' ), $directive_value ); 585 _doing_it_wrong( __METHOD__, $message, '6.6.0' ); 586 return null; 587 } 588 589 $store = array( 590 'state' => $this->state_data[ $ns ] ?? array(), 591 'context' => $context[ $ns ] ?? array(), 592 ); 593 594 // Checks if the reference path is preceded by a negation operator (!). 595 $should_negate_value = '!' === $path[0]; 596 $path = $should_negate_value ? substr( $path, 1 ) : $path; 597 598 // Extracts the value from the store using the reference path. 599 $path_segments = explode( '.', $path ); 600 $current = $store; 601 foreach ( $path_segments as $path_segment ) { 602 /* 603 * Special case for numeric arrays and strings. Add length 604 * property mimicking JavaScript behavior. 605 * 606 * @since 6.8.0 607 */ 608 if ( 'length' === $path_segment ) { 609 if ( is_array( $current ) && array_is_list( $current ) ) { 610 $current = count( $current ); 611 break; 612 } 613 614 if ( is_string( $current ) ) { 615 /* 616 * Differences in encoding between PHP strings and 617 * JavaScript mean that it's complicated to calculate 618 * the string length JavaScript would see from PHP. 619 * `strlen` is a reasonable approximation. 620 * 621 * Users that desire a more precise length likely have 622 * more precise needs than "bytelength" and should 623 * implement their own length calculation in derived 624 * state taking into account encoding and their desired 625 * output (codepoints, graphemes, bytes, etc.). 626 */ 627 $current = strlen( $current ); 628 break; 629 } 630 } 631 632 if ( ( is_array( $current ) || $current instanceof ArrayAccess ) && isset( $current[ $path_segment ] ) ) { 633 $current = $current[ $path_segment ]; 634 } elseif ( is_object( $current ) && isset( $current->$path_segment ) ) { 635 $current = $current->$path_segment; 636 } else { 637 $current = null; 638 break; 639 } 640 641 if ( $current instanceof Closure ) { 642 /* 643 * This state getter's namespace is added to the stack so that 644 * `state()` or `get_config()` read that namespace when called 645 * without specifying one. 646 */ 647 array_push( $this->namespace_stack, $ns ); 648 try { 649 $current = $current(); 650 } catch ( Throwable $e ) { 651 _doing_it_wrong( 652 __METHOD__, 653 sprintf( 654 /* translators: 1: Path pointing to an Interactivity API state property, 2: Namespace for an Interactivity API store. */ 655 __( 'Uncaught error executing a derived state callback with path "%1$s" and namespace "%2$s".' ), 656 $path, 657 $ns 658 ), 659 '6.6.0' 660 ); 661 return null; 662 } finally { 663 // Remove the property's namespace from the stack. 664 array_pop( $this->namespace_stack ); 665 } 666 } 667 } 668 669 // Returns the opposite if it contains a negation operator (!). 670 return $should_negate_value ? ! $current : $current; 671 } 672 673 /** 674 * Extracts the directive attribute name to separate and return the directive 675 * prefix and an optional suffix. 676 * 677 * The suffix is the string after the first double hyphen and the prefix is 678 * everything that comes before the suffix. 679 * 680 * Example: 681 * 682 * extract_prefix_and_suffix( 'data-wp-interactive' ) => array( 'data-wp-interactive', null ) 683 * extract_prefix_and_suffix( 'data-wp-bind--src' ) => array( 'data-wp-bind', 'src' ) 684 * extract_prefix_and_suffix( 'data-wp-foo--and--bar' ) => array( 'data-wp-foo', 'and--bar' ) 685 * 686 * @since 6.5.0 687 * 688 * @param string $directive_name The directive attribute name. 689 * @return array An array containing the directive prefix and optional suffix. 690 */ 691 private function extract_prefix_and_suffix( string $directive_name ): array { 692 return explode( '--', $directive_name, 2 ); 693 } 694 695 /** 696 * Parses and extracts the namespace and reference path from the given 697 * directive attribute value. 698 * 699 * If the value doesn't contain an explicit namespace, it returns the 700 * default one. If the value contains a JSON object instead of a reference 701 * path, the function tries to parse it and return the resulting array. If 702 * the value contains strings that represent booleans ("true" and "false"), 703 * numbers ("1" and "1.2") or "null", the function also transform them to 704 * regular booleans, numbers and `null`. 705 * 706 * Example: 707 * 708 * extract_directive_value( 'actions.foo', 'myPlugin' ) => array( 'myPlugin', 'actions.foo' ) 709 * extract_directive_value( 'otherPlugin::actions.foo', 'myPlugin' ) => array( 'otherPlugin', 'actions.foo' ) 710 * extract_directive_value( '{ "isOpen": false }', 'myPlugin' ) => array( 'myPlugin', array( 'isOpen' => false ) ) 711 * extract_directive_value( 'otherPlugin::{ "isOpen": false }', 'myPlugin' ) => array( 'otherPlugin', array( 'isOpen' => false ) ) 712 * 713 * @since 6.5.0 714 * 715 * @param string|true $directive_value The directive attribute value. It can be `true` when it's a boolean 716 * attribute. 717 * @param string|null $default_namespace Optional. The default namespace if none is explicitly defined. 718 * @return array An array containing the namespace in the first item and the JSON, the reference path, or null on the 719 * second item. 720 */ 721 private function extract_directive_value( $directive_value, $default_namespace = null ): array { 722 if ( empty( $directive_value ) || is_bool( $directive_value ) ) { 723 return array( $default_namespace, null ); 724 } 725 726 // Replaces the value and namespace if there is a namespace in the value. 727 if ( 1 === preg_match( '/^([\w\-_\/]+)::./', $directive_value ) ) { 728 list($default_namespace, $directive_value) = explode( '::', $directive_value, 2 ); 729 } 730 731 /* 732 * Tries to decode the value as a JSON object. If it fails and the value 733 * isn't `null`, it returns the value as it is. Otherwise, it returns the 734 * decoded JSON or null for the string `null`. 735 */ 736 $decoded_json = json_decode( $directive_value, true ); 737 if ( null !== $decoded_json || 'null' === $directive_value ) { 738 $directive_value = $decoded_json; 739 } 740 741 return array( $default_namespace, $directive_value ); 742 } 743 744 /** 745 * Transforms a kebab-case string to camelCase. 746 * 747 * @param string $str The kebab-case string to transform to camelCase. 748 * @return string The transformed camelCase string. 749 */ 750 private function kebab_to_camel_case( string $str ): string { 751 return lcfirst( 752 preg_replace_callback( 753 '/(-)([a-z])/', 754 function ( $matches ) { 755 return strtoupper( $matches[2] ); 756 }, 757 strtolower( rtrim( $str, '-' ) ) 758 ) 759 ); 760 } 761 762 /** 763 * Processes the `data-wp-interactive` directive. 764 * 765 * It adds the default store namespace defined in the directive value to the 766 * stack so that it's available for the nested interactivity elements. 767 * 768 * @since 6.5.0 769 * 770 * @param WP_Interactivity_API_Directives_Processor $p The directives processor instance. 771 * @param string $mode Whether the processing is entering or exiting the tag. 772 */ 773 private function data_wp_interactive_processor( WP_Interactivity_API_Directives_Processor $p, string $mode ) { 774 // When exiting tags, it removes the last namespace from the stack. 775 if ( 'exit' === $mode ) { 776 array_pop( $this->namespace_stack ); 777 return; 778 } 779 780 // Tries to decode the `data-wp-interactive` attribute value. 781 $attribute_value = $p->get_attribute( 'data-wp-interactive' ); 782 783 /* 784 * Pushes the newly defined namespace or the current one if the 785 * `data-wp-interactive` definition was invalid or does not contain a 786 * namespace. It does so because the function pops out the current namespace 787 * from the stack whenever it finds a `data-wp-interactive`'s closing tag, 788 * independently of whether the previous `data-wp-interactive` definition 789 * contained a valid namespace. 790 */ 791 $new_namespace = null; 792 if ( is_string( $attribute_value ) && ! empty( $attribute_value ) ) { 793 $decoded_json = json_decode( $attribute_value, true ); 794 if ( is_array( $decoded_json ) ) { 795 $new_namespace = $decoded_json['namespace'] ?? null; 796 } else { 797 $new_namespace = $attribute_value; 798 } 799 } 800 $this->namespace_stack[] = ( $new_namespace && 1 === preg_match( '/^([\w\-_\/]+)/', $new_namespace ) ) 801 ? $new_namespace 802 : end( $this->namespace_stack ); 803 } 804 805 /** 806 * Processes the `data-wp-context` directive. 807 * 808 * It adds the context defined in the directive value to the stack so that 809 * it's available for the nested interactivity elements. 810 * 811 * @since 6.5.0 812 * 813 * @param WP_Interactivity_API_Directives_Processor $p The directives processor instance. 814 * @param string $mode Whether the processing is entering or exiting the tag. 815 */ 816 private function data_wp_context_processor( WP_Interactivity_API_Directives_Processor $p, string $mode ) { 817 // When exiting tags, it removes the last context from the stack. 818 if ( 'exit' === $mode ) { 819 array_pop( $this->context_stack ); 820 return; 821 } 822 823 $attribute_value = $p->get_attribute( 'data-wp-context' ); 824 $namespace_value = end( $this->namespace_stack ); 825 826 // Separates the namespace from the context JSON object. 827 list( $namespace_value, $decoded_json ) = is_string( $attribute_value ) && ! empty( $attribute_value ) 828 ? $this->extract_directive_value( $attribute_value, $namespace_value ) 829 : array( $namespace_value, null ); 830 831 /* 832 * If there is a namespace, it adds a new context to the stack merging the 833 * previous context with the new one. 834 */ 835 if ( is_string( $namespace_value ) ) { 836 $this->context_stack[] = array_replace_recursive( 837 end( $this->context_stack ) !== false ? end( $this->context_stack ) : array(), 838 array( $namespace_value => is_array( $decoded_json ) ? $decoded_json : array() ) 839 ); 840 } else { 841 /* 842 * If there is no namespace, it pushes the current context to the stack. 843 * It needs to do so because the function pops out the current context 844 * from the stack whenever it finds a `data-wp-context`'s closing tag. 845 */ 846 $this->context_stack[] = end( $this->context_stack ); 847 } 848 } 849 850 /** 851 * Processes the `data-wp-bind` directive. 852 * 853 * It updates or removes the bound attributes based on the evaluation of its 854 * associated reference. 855 * 856 * @since 6.5.0 857 * 858 * @param WP_Interactivity_API_Directives_Processor $p The directives processor instance. 859 * @param string $mode Whether the processing is entering or exiting the tag. 860 */ 861 private function data_wp_bind_processor( WP_Interactivity_API_Directives_Processor $p, string $mode ) { 862 if ( 'enter' === $mode ) { 863 $all_bind_directives = $p->get_attribute_names_with_prefix( 'data-wp-bind--' ); 864 865 foreach ( $all_bind_directives as $attribute_name ) { 866 list( , $bound_attribute ) = $this->extract_prefix_and_suffix( $attribute_name ); 867 if ( empty( $bound_attribute ) ) { 868 return; 869 } 870 871 $attribute_value = $p->get_attribute( $attribute_name ); 872 $result = $this->evaluate( $attribute_value ); 873 874 if ( 875 null !== $result && 876 ( 877 false !== $result || 878 ( strlen( $bound_attribute ) > 5 && '-' === $bound_attribute[4] ) 879 ) 880 ) { 881 /* 882 * If the result of the evaluation is a boolean and the attribute is 883 * `aria-` or `data-, convert it to a string "true" or "false". It 884 * follows the exact same logic as Preact because it needs to 885 * replicate what Preact will later do in the client: 886 * https://github.com/preactjs/preact/blob/ea49f7a0f9d1ff2c98c0bdd66aa0cbc583055246/src/diff/props.js#L131C24-L136 887 */ 888 if ( 889 is_bool( $result ) && 890 ( strlen( $bound_attribute ) > 5 && '-' === $bound_attribute[4] ) 891 ) { 892 $result = $result ? 'true' : 'false'; 893 } 894 $p->set_attribute( $bound_attribute, $result ); 895 } else { 896 $p->remove_attribute( $bound_attribute ); 897 } 898 } 899 } 900 } 901 902 /** 903 * Processes the `data-wp-class` directive. 904 * 905 * It adds or removes CSS classes in the current HTML element based on the 906 * evaluation of its associated references. 907 * 908 * @since 6.5.0 909 * 910 * @param WP_Interactivity_API_Directives_Processor $p The directives processor instance. 911 * @param string $mode Whether the processing is entering or exiting the tag. 912 */ 913 private function data_wp_class_processor( WP_Interactivity_API_Directives_Processor $p, string $mode ) { 914 if ( 'enter' === $mode ) { 915 $all_class_directives = $p->get_attribute_names_with_prefix( 'data-wp-class--' ); 916 917 foreach ( $all_class_directives as $attribute_name ) { 918 list( , $class_name ) = $this->extract_prefix_and_suffix( $attribute_name ); 919 if ( empty( $class_name ) ) { 920 return; 921 } 922 923 $attribute_value = $p->get_attribute( $attribute_name ); 924 $result = $this->evaluate( $attribute_value ); 925 926 if ( $result ) { 927 $p->add_class( $class_name ); 928 } else { 929 $p->remove_class( $class_name ); 930 } 931 } 932 } 933 } 934 935 /** 936 * Processes the `data-wp-style` directive. 937 * 938 * It updates the style attribute value of the current HTML element based on 939 * the evaluation of its associated references. 940 * 941 * @since 6.5.0 942 * 943 * @param WP_Interactivity_API_Directives_Processor $p The directives processor instance. 944 * @param string $mode Whether the processing is entering or exiting the tag. 945 */ 946 private function data_wp_style_processor( WP_Interactivity_API_Directives_Processor $p, string $mode ) { 947 if ( 'enter' === $mode ) { 948 $all_style_attributes = $p->get_attribute_names_with_prefix( 'data-wp-style--' ); 949 950 foreach ( $all_style_attributes as $attribute_name ) { 951 list( , $style_property ) = $this->extract_prefix_and_suffix( $attribute_name ); 952 if ( empty( $style_property ) ) { 953 continue; 954 } 955 956 $directive_attribute_value = $p->get_attribute( $attribute_name ); 957 $style_property_value = $this->evaluate( $directive_attribute_value ); 958 $style_attribute_value = $p->get_attribute( 'style' ); 959 $style_attribute_value = ( $style_attribute_value && ! is_bool( $style_attribute_value ) ) ? $style_attribute_value : ''; 960 961 /* 962 * Checks first if the style property is not falsy and the style 963 * attribute value is not empty because if it is, it doesn't need to 964 * update the attribute value. 965 */ 966 if ( $style_property_value || $style_attribute_value ) { 967 $style_attribute_value = $this->merge_style_property( $style_attribute_value, $style_property, $style_property_value ); 968 /* 969 * If the style attribute value is not empty, it sets it. Otherwise, 970 * it removes it. 971 */ 972 if ( ! empty( $style_attribute_value ) ) { 973 $p->set_attribute( 'style', $style_attribute_value ); 974 } else { 975 $p->remove_attribute( 'style' ); 976 } 977 } 978 } 979 } 980 } 981 982 /** 983 * Merges an individual style property in the `style` attribute of an HTML 984 * element, updating or removing the property when necessary. 985 * 986 * If a property is modified, the old one is removed and the new one is added 987 * at the end of the list. 988 * 989 * @since 6.5.0 990 * 991 * Example: 992 * 993 * merge_style_property( 'color:green;', 'color', 'red' ) => 'color:red;' 994 * merge_style_property( 'background:green;', 'color', 'red' ) => 'background:green;color:red;' 995 * merge_style_property( 'color:green;', 'color', null ) => '' 996 * 997 * @param string $style_attribute_value The current style attribute value. 998 * @param string $style_property_name The style property name to set. 999 * @param string|false|null $style_property_value The value to set for the style property. With false, null or an 1000 * empty string, it removes the style property. 1001 * @return string The new style attribute value after the specified property has been added, updated or removed. 1002 */ 1003 private function merge_style_property( string $style_attribute_value, string $style_property_name, $style_property_value ): string { 1004 $style_assignments = explode( ';', $style_attribute_value ); 1005 $result = array(); 1006 $style_property_value = ! empty( $style_property_value ) ? rtrim( trim( $style_property_value ), ';' ) : null; 1007 $new_style_property = $style_property_value ? $style_property_name . ':' . $style_property_value . ';' : ''; 1008 1009 // Generates an array with all the properties but the modified one. 1010 foreach ( $style_assignments as $style_assignment ) { 1011 if ( empty( trim( $style_assignment ) ) ) { 1012 continue; 1013 } 1014 list( $name, $value ) = explode( ':', $style_assignment ); 1015 if ( trim( $name ) !== $style_property_name ) { 1016 $result[] = trim( $name ) . ':' . trim( $value ) . ';'; 1017 } 1018 } 1019 1020 // Adds the new/modified property at the end of the list. 1021 $result[] = $new_style_property; 1022 1023 return implode( '', $result ); 1024 } 1025 1026 /** 1027 * Processes the `data-wp-text` directive. 1028 * 1029 * It updates the inner content of the current HTML element based on the 1030 * evaluation of its associated reference. 1031 * 1032 * @since 6.5.0 1033 * 1034 * @param WP_Interactivity_API_Directives_Processor $p The directives processor instance. 1035 * @param string $mode Whether the processing is entering or exiting the tag. 1036 */ 1037 private function data_wp_text_processor( WP_Interactivity_API_Directives_Processor $p, string $mode ) { 1038 if ( 'enter' === $mode ) { 1039 $attribute_value = $p->get_attribute( 'data-wp-text' ); 1040 $result = $this->evaluate( $attribute_value ); 1041 1042 /* 1043 * Follows the same logic as Preact in the client and only changes the 1044 * content if the value is a string or a number. Otherwise, it removes the 1045 * content. 1046 */ 1047 if ( is_string( $result ) || is_numeric( $result ) ) { 1048 $p->set_content_between_balanced_tags( esc_html( $result ) ); 1049 } else { 1050 $p->set_content_between_balanced_tags( '' ); 1051 } 1052 } 1053 } 1054 1055 /** 1056 * Returns the CSS styles for animating the top loading bar in the router. 1057 * 1058 * @since 6.5.0 1059 * 1060 * @return string The CSS styles for the router's top loading bar animation. 1061 */ 1062 private function get_router_animation_styles(): string { 1063 return <<<CSS 1064 .wp-interactivity-router-loading-bar { 1065 position: fixed; 1066 top: 0; 1067 left: 0; 1068 margin: 0; 1069 padding: 0; 1070 width: 100vw; 1071 max-width: 100vw !important; 1072 height: 4px; 1073 background-color: #000; 1074 opacity: 0 1075 } 1076 .wp-interactivity-router-loading-bar.start-animation { 1077 animation: wp-interactivity-router-loading-bar-start-animation 30s cubic-bezier(0.03, 0.5, 0, 1) forwards 1078 } 1079 .wp-interactivity-router-loading-bar.finish-animation { 1080 animation: wp-interactivity-router-loading-bar-finish-animation 300ms ease-in 1081 } 1082 @keyframes wp-interactivity-router-loading-bar-start-animation { 1083 0% { transform: scaleX(0); transform-origin: 0 0; opacity: 1 } 1084 100% { transform: scaleX(1); transform-origin: 0 0; opacity: 1 } 1085 } 1086 @keyframes wp-interactivity-router-loading-bar-finish-animation { 1087 0% { opacity: 1 } 1088 50% { opacity: 1 } 1089 100% { opacity: 0 } 1090 } 1091 CSS; 1092 } 1093 1094 /** 1095 * Deprecated. 1096 * 1097 * @since 6.5.0 1098 * @deprecated 6.7.0 Use {@see WP_Interactivity_API::print_router_markup} instead. 1099 */ 1100 public function print_router_loading_and_screen_reader_markup() { 1101 _deprecated_function( __METHOD__, '6.7.0', 'WP_Interactivity_API::print_router_markup' ); 1102 1103 // Call the new method. 1104 $this->print_router_markup(); 1105 } 1106 1107 /** 1108 * Outputs markup for the @wordpress/interactivity-router script module. 1109 * 1110 * This method prints a div element representing a loading bar visible during 1111 * navigation. 1112 * 1113 * @since 6.7.0 1114 */ 1115 public function print_router_markup() { 1116 echo <<<HTML 1117 <div 1118 class="wp-interactivity-router-loading-bar" 1119 data-wp-interactive="core/router" 1120 data-wp-class--start-animation="state.navigation.hasStarted" 1121 data-wp-class--finish-animation="state.navigation.hasFinished" 1122 ></div> 1123 HTML; 1124 } 1125 1126 /** 1127 * Processes the `data-wp-router-region` directive. 1128 * 1129 * It renders in the footer a set of HTML elements to notify users about 1130 * client-side navigations. More concretely, the elements added are 1) a 1131 * top loading bar to visually inform that a navigation is in progress 1132 * and 2) an `aria-live` region for accessible navigation announcements. 1133 * 1134 * @since 6.5.0 1135 * 1136 * @param WP_Interactivity_API_Directives_Processor $p The directives processor instance. 1137 * @param string $mode Whether the processing is entering or exiting the tag. 1138 */ 1139 private function data_wp_router_region_processor( WP_Interactivity_API_Directives_Processor $p, string $mode ) { 1140 if ( 'enter' === $mode && ! $this->has_processed_router_region ) { 1141 $this->has_processed_router_region = true; 1142 1143 // Enqueues as an inline style. 1144 wp_register_style( 'wp-interactivity-router-animations', false ); 1145 wp_add_inline_style( 'wp-interactivity-router-animations', $this->get_router_animation_styles() ); 1146 wp_enqueue_style( 'wp-interactivity-router-animations' ); 1147 1148 // Adds the necessary markup to the footer. 1149 add_action( 'wp_footer', array( $this, 'print_router_markup' ) ); 1150 } 1151 } 1152 1153 /** 1154 * Processes the `data-wp-each` directive. 1155 * 1156 * This directive gets an array passed as reference and iterates over it 1157 * generating new content for each item based on the inner markup of the 1158 * `template` tag. 1159 * 1160 * @since 6.5.0 1161 * 1162 * @param WP_Interactivity_API_Directives_Processor $p The directives processor instance. 1163 * @param string $mode Whether the processing is entering or exiting the tag. 1164 * @param array $tag_stack The reference to the tag stack. 1165 */ 1166 private function data_wp_each_processor( WP_Interactivity_API_Directives_Processor $p, string $mode, array &$tag_stack ) { 1167 if ( 'enter' === $mode && 'TEMPLATE' === $p->get_tag() ) { 1168 $attribute_name = $p->get_attribute_names_with_prefix( 'data-wp-each' )[0]; 1169 $extracted_suffix = $this->extract_prefix_and_suffix( $attribute_name ); 1170 $item_name = isset( $extracted_suffix[1] ) ? $this->kebab_to_camel_case( $extracted_suffix[1] ) : 'item'; 1171 $attribute_value = $p->get_attribute( $attribute_name ); 1172 $result = $this->evaluate( $attribute_value ); 1173 1174 // Gets the content between the template tags and leaves the cursor in the closer tag. 1175 $inner_content = $p->get_content_between_balanced_template_tags(); 1176 1177 // Checks if there is a manual server-side directive processing. 1178 $template_end = 'data-wp-each: template end'; 1179 $p->set_bookmark( $template_end ); 1180 $p->next_tag(); 1181 $manual_sdp = $p->get_attribute( 'data-wp-each-child' ); 1182 $p->seek( $template_end ); // Rewinds to the template closer tag. 1183 $p->release_bookmark( $template_end ); 1184 1185 /* 1186 * It doesn't process in these situations: 1187 * - Manual server-side directive processing. 1188 * - Empty or non-array values. 1189 * - Associative arrays because those are deserialized as objects in JS. 1190 * - Templates that contain top-level texts because those texts can't be 1191 * identified and removed in the client. 1192 */ 1193 if ( 1194 $manual_sdp || 1195 empty( $result ) || 1196 ! is_array( $result ) || 1197 ! array_is_list( $result ) || 1198 ! str_starts_with( trim( $inner_content ), '<' ) || 1199 ! str_ends_with( trim( $inner_content ), '>' ) 1200 ) { 1201 array_pop( $tag_stack ); 1202 return; 1203 } 1204 1205 // Extracts the namespace from the directive attribute value. 1206 $namespace_value = end( $this->namespace_stack ); 1207 list( $namespace_value ) = is_string( $attribute_value ) && ! empty( $attribute_value ) 1208 ? $this->extract_directive_value( $attribute_value, $namespace_value ) 1209 : array( $namespace_value, null ); 1210 1211 // Processes the inner content for each item of the array. 1212 $processed_content = ''; 1213 foreach ( $result as $item ) { 1214 // Creates a new context that includes the current item of the array. 1215 $this->context_stack[] = array_replace_recursive( 1216 end( $this->context_stack ) !== false ? end( $this->context_stack ) : array(), 1217 array( $namespace_value => array( $item_name => $item ) ) 1218 ); 1219 1220 // Processes the inner content with the new context. 1221 $processed_item = $this->_process_directives( $inner_content ); 1222 1223 if ( null === $processed_item ) { 1224 // If the HTML is unbalanced, stop processing it. 1225 array_pop( $this->context_stack ); 1226 return; 1227 } 1228 1229 // Adds the `data-wp-each-child` to each top-level tag. 1230 $i = new WP_Interactivity_API_Directives_Processor( $processed_item ); 1231 while ( $i->next_tag() ) { 1232 $i->set_attribute( 'data-wp-each-child', true ); 1233 $i->next_balanced_tag_closer_tag(); 1234 } 1235 $processed_content .= $i->get_updated_html(); 1236 1237 // Removes the current context from the stack. 1238 array_pop( $this->context_stack ); 1239 } 1240 1241 // Appends the processed content after the tag closer of the template. 1242 $p->append_content_after_template_tag_closer( $processed_content ); 1243 1244 // Pops the last tag because it skipped the closing tag of the template tag. 1245 array_pop( $tag_stack ); 1246 } 1247 } 1248 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated : Thu Apr 3 08:20:01 2025 | Cross-referenced by PHPXref |