WordPress.org
Get WordPress

Make WordPress Core

Changeset 58769


Ignore:
Timestamp:
07/19/2024 11:42:14 PM (5 months ago)
Author:
dmsnell
Message:

HTML API: Add PHP type annotations.

This patch adds type annotations to internal and private methods of the HTML
API and the supporting WP_Token_Map. Annotations have not been added to the
public interfaces where it would likely crash a site if called wrong.

These annotations should help avoid unnecessary type-related bugs (as have
been uncovered in earlier work adding such annotations) and provide additional
guidance to developers when interacting with these classes in an IDE.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/6753
Discussed in https://core.trac.wordpress.org/ticket/61399

Props dmsnell, jonsurrell.
See #61399.

Location:
trunk/src/wp-includes
Files:
11 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/wp-includes/class-wp-token-map.php

    r58742 r58769  
    281281     * @return WP_Token_Map|null Token map, unless unable to create it.
    282282     */
    283     public static function from_array( $mappings, $key_length = 2 ) {
     283    public static function from_array( array $mappings, int $key_length = 2 ): ?WP_Token_Map {
    284284        $map             = new WP_Token_Map();
    285285        $map->key_length = $key_length;
    … …  
    329329            usort(
    330330                $groups[ $group_key ],
    331                 static function ( $a, $b ) {
     331                static function ( array $a, array $b ): int {
    332332                    return self::longest_first_then_alphabetical( $a[0], $b[0] );
    333333                }
    … …  
    386386     * @return WP_Token_Map Map with precomputed data loaded.
    387387     */
    388     public static function from_precomputed_table( $state ) {
     388    public static function from_precomputed_table( $state ): ?WP_Token_Map {
    389389        $has_necessary_state = isset(
    390390            $state['storage_version'],
    … …  
    440440     * @return bool Whether there's an entry for the given word in the map.
    441441     */
    442     public function contains( $word, $case_sensitivity = 'case-sensitive' ) {
     442    public function contains( string $word, string $case_sensitivity = 'case-sensitive' ): bool {
    443443        $ignore_case = 'ascii-case-insensitive' === $case_sensitivity;
    444444
    … …  
    528528     * @return string|null Mapped value of lookup key if found, otherwise `null`.
    529529     */
    530     public function read_token( $text, $offset = 0, &$matched_token_byte_length = null, $case_sensitivity = 'case-sensitive' ) {
     530    public function read_token( string $text, int $offset = 0, &$matched_token_byte_length = null, $case_sensitivity = 'case-sensitive' ): ?string {
    531531        $ignore_case = 'ascii-case-insensitive' === $case_sensitivity;
    532532        $text_length = strlen( $text );
    … …  
    572572     * Finds a match for a short word at the index.
    573573     *
    574      * @since 6.6.0.
    575      *
    576      * @param string $text                       String in which to search for a lookup key.
    577      * @param int    $offset                     Optional. How many bytes into the string where the lookup key ought to start. Default 0.
    578      * @param ?int   &$matched_token_byte_length Optional. Holds byte-length of found lookup key if matched, otherwise not set. Default null.
    579      * @param string $case_sensitivity           Optional. Pass 'ascii-case-insensitive' to ignore ASCII case when matching. Default 'case-sensitive'.
     574     * @since 6.6.0
     575     *
     576     * @param string   $text                       String in which to search for a lookup key.
     577     * @param int      $offset                     Optional. How many bytes into the string where the lookup key ought to start. Default 0.
     578     * @param int|null &$matched_token_byte_length Optional. Holds byte-length of found lookup key if matched, otherwise not set. Default null.
     579     * @param string   $case_sensitivity           Optional. Pass 'ascii-case-insensitive' to ignore ASCII case when matching. Default 'case-sensitive'.
     580     *
    580581     * @return string|null Mapped value of lookup key if found, otherwise `null`.
    581582     */
    582     private function read_small_token( $text, $offset, &$matched_token_byte_length, $case_sensitivity = 'case-sensitive' ) {
     583    private function read_small_token( string $text, int $offset = 0, &$matched_token_byte_length = null, $case_sensitivity = 'case-sensitive' ): ?string {
    583584        $ignore_case  = 'ascii-case-insensitive' === $case_sensitivity;
    584585        $small_length = strlen( $this->small_words );
    … …  
    635636     * @return array The lookup key/substitution values as an associate array.
    636637     */
    637     public function to_array() {
     638    public function to_array(): array {
    638639        $tokens = array();
    639640
    … …  
    697698     * @return string Value which can be pasted into a PHP source file for quick loading of table.
    698699     */
    699     public function precomputed_php_source_table( $indent = "\t" ) {
     700    public function precomputed_php_source_table( string $indent = "\t" ): string {
    700701        $i1 = $indent;
    701702        $i2 = $i1 . $indent;
    … …  
    802803     * @return int -1 or lower if `$a` is less than `$b`; 1 or greater if `$a` is greater than `$b`, and 0 if they are equal.
    803804     */
    804     private static function longest_first_then_alphabetical( $a, $b ) {
     805    private static function longest_first_then_alphabetical( string $a, string $b ): int {
    805806        if ( $a === $b ) {
    806807            return 0;

  • trunk/src/wp-includes/html-api/class-wp-html-active-formatting-elements.php

    r57209 r58769  
    5252     * @return bool Whether the referenced node is in the stack of active formatting elements.
    5353     */
    54     public function contains_node( $token ) {
     54    public function contains_node( WP_HTML_Token $token ) {
    5555        foreach ( $this->walk_up() as $item ) {
    5656            if ( $token->bookmark_name === $item->bookmark_name ) {
    … …  
    9696     * @param WP_HTML_Token $token Push this node onto the stack.
    9797     */
    98     public function push( $token ) {
     98    public function push( WP_HTML_Token $token ) {
    9999        /*
    100100         * > If there are already three elements in the list of active formatting elements after the last marker,
    … …  
    120120     * @return bool Whether the node was found and removed from the stack of active formatting elements.
    121121     */
    122     public function remove_node( $token ) {
     122    public function remove_node( WP_HTML_Token $token ) {
    123123        foreach ( $this->walk_up() as $position_from_end => $item ) {
    124124            if ( $token->bookmark_name !== $item->bookmark_name ) {

  • trunk/src/wp-includes/html-api/class-wp-html-decoder.php

    r58613 r58769  
    3232     * @return bool Whether the attribute value starts with the given string.
    3333     */
    34     public static function attribute_starts_with( $haystack, $search_text, $case_sensitivity = 'case-sensitive' ) {
     34    public static function attribute_starts_with( $haystack, $search_text, $case_sensitivity = 'case-sensitive' ): bool {
    3535        $search_length = strlen( $search_text );
    3636        $loose_case    = 'ascii-case-insensitive' === $case_sensitivity;
    … …  
    9191     * @return string Decoded UTF-8 value of given text node.
    9292     */
    93     public static function decode_text_node( $text ) {
     93    public static function decode_text_node( $text ): string {
    9494        return static::decode( 'data', $text );
    9595    }
    … …  
    111111     * @return string Decoded UTF-8 value of given attribute value.
    112112     */
    113     public static function decode_attribute( $text ) {
     113    public static function decode_attribute( $text ): string {
    114114        return static::decode( 'attribute', $text );
    115115    }
    … …  
    134134     * @return string Decoded UTF-8 string.
    135135     */
    136     public static function decode( $context, $text ) {
     136    public static function decode( $context, $text ): string {
    137137        $decoded = '';
    138138        $end     = strlen( $text );
    … …  
    422422     * @return string Converted code point, or `�` if invalid.
    423423     */
    424     public static function code_point_to_utf8_bytes( $code_point ) {
     424    public static function code_point_to_utf8_bytes( $code_point ): string {
    425425        // Pre-check to ensure a valid code point.
    426426        if (

  • trunk/src/wp-includes/html-api/class-wp-html-open-elements.php

    r58742 r58769  
    5959     * @since 6.6.0
    6060     *
    61      * @var Closure
     61     * @var Closure|null
    6262     */
    6363    private $pop_handler = null;
    … …  
    7070     * @since 6.6.0
    7171     *
    72      * @var Closure
     72     * @var Closure|null
    7373     */
    7474    private $push_handler = null;
    … …  
    8484     * @param Closure $handler The handler function.
    8585     */
    86     public function set_pop_handler( Closure $handler ) {
     86    public function set_pop_handler( Closure $handler ): void {
    8787        $this->pop_handler = $handler;
    8888    }
    … …  
    9898     * @param Closure $handler The handler function.
    9999     */
    100     public function set_push_handler( Closure $handler ) {
     100    public function set_push_handler( Closure $handler ): void {
    101101        $this->push_handler = $handler;
    102102    }
    … …  
    110110     * @return bool Whether the referenced node is in the stack of open elements.
    111111     */
    112     public function contains_node( $token ) {
     112    public function contains_node( WP_HTML_Token $token ): bool {
    113113        foreach ( $this->walk_up() as $item ) {
    114114            if ( $token->bookmark_name === $item->bookmark_name ) {
    … …  
    127127     * @return int How many node are in the stack of open elements.
    128128     */
    129     public function count() {
     129    public function count(): int {
    130130        return count( $this->stack );
    131131    }
    … …  
    139139     * @return WP_HTML_Token|null Last node in the stack of open elements, if one exists, otherwise null.
    140140     */
    141     public function current_node() {
     141    public function current_node(): ?WP_HTML_Token {
    142142        $current_node = end( $this->stack );
    143143
    … …  
    198198     * @return bool Whether the element was found in a specific scope.
    199199     */
    200     public function has_element_in_specific_scope( $tag_name, $termination_list ) {
     200    public function has_element_in_specific_scope( string $tag_name, $termination_list ): bool {
    201201        foreach ( $this->walk_up() as $node ) {
    202202            if ( $node->node_name === $tag_name ) {
    … …  
    234234     * @return bool Whether given element is in scope.
    235235     */
    236     public function has_element_in_scope( $tag_name ) {
     236    public function has_element_in_scope( string $tag_name ): bool {
    237237        return $this->has_element_in_specific_scope(
    238238            $tag_name,
    … …  
    261261     * @return bool Whether given element is in scope.
    262262     */
    263     public function has_element_in_list_item_scope( $tag_name ) {
     263    public function has_element_in_list_item_scope( string $tag_name ): bool {
    264264        return $this->has_element_in_specific_scope(
    265265            $tag_name,
    … …  
    282282     * @return bool Whether given element is in scope.
    283283     */
    284     public function has_element_in_button_scope( $tag_name ) {
     284    public function has_element_in_button_scope( string $tag_name ): bool {
    285285        return $this->has_element_in_specific_scope( $tag_name, array( 'BUTTON' ) );
    286286    }
    … …  
    298298     * @return bool Whether given element is in scope.
    299299     */
    300     public function has_element_in_table_scope( $tag_name ) {
     300    public function has_element_in_table_scope( string $tag_name ): bool {
    301301        throw new WP_HTML_Unsupported_Exception( 'Cannot process elements depending on table scope.' );
    302302
    … …  
    324324     * @return bool Whether the given element is in SELECT scope.
    325325     */
    326     public function has_element_in_select_scope( $tag_name ) {
     326    public function has_element_in_select_scope( string $tag_name ): bool {
    327327        foreach ( $this->walk_up() as $node ) {
    328328            if ( $node->node_name === $tag_name ) {
    … …  
    350350     * @return bool Whether a P is in BUTTON scope.
    351351     */
    352     public function has_p_in_button_scope() {
     352    public function has_p_in_button_scope(): bool {
    353353        return $this->has_p_in_button_scope;
    354354    }
    … …  
    363363     * @return bool Whether a node was popped off of the stack.
    364364     */
    365     public function pop() {
     365    public function pop(): bool {
    366366        $item = array_pop( $this->stack );
    367367        if ( null === $item ) {
    … …  
    388388     * @return bool Whether a tag of the given name was found and popped off of the stack of open elements.
    389389     */
    390     public function pop_until( $tag_name ) {
     390    public function pop_until( string $tag_name ): bool {
    391391        foreach ( $this->walk_up() as $item ) {
    392392            if ( 'context-node' === $item->bookmark_name ) {
    … …  
    420420     * @param WP_HTML_Token $stack_item Item to add onto stack.
    421421     */
    422     public function push( $stack_item ) {
     422    public function push( WP_HTML_Token $stack_item ): void {
    423423        $this->stack[] = $stack_item;
    424424        $this->after_element_push( $stack_item );
    … …  
    433433     * @return bool Whether the node was found and removed from the stack of open elements.
    434434     */
    435     public function remove_node( $token ) {
     435    public function remove_node( WP_HTML_Token $token ): bool {
    436436        if ( 'context-node' === $token->bookmark_name ) {
    437437            return false;
    … …  
    503503     *                                            if provided and if the node exists.
    504504     */
    505     public function walk_up( $above_this_node = null ) {
     505    public function walk_up( ?WP_HTML_Token $above_this_node = null ) {
    506506        $has_found_node = null === $above_this_node;
    507507
    … …  
    535535     * @param WP_HTML_Token $item Element that was added to the stack of open elements.
    536536     */
    537     public function after_element_push( $item ) {
     537    public function after_element_push( WP_HTML_Token $item ): void {
    538538        /*
    539539         * When adding support for new elements, expand this switch to trap
    … …  
    568568     * @param WP_HTML_Token $item Element that was removed from the stack of open elements.
    569569     */
    570     public function after_element_pop( $item ) {
     570    public function after_element_pop( WP_HTML_Token $item ): void {
    571571        /*
    572572         * When adding support for new elements, expand this switch to trap

  • trunk/src/wp-includes/html-api/class-wp-html-processor-state.php

    r58680 r58769  
    334334     * @var WP_HTML_Open_Elements
    335335     */
    336     public $stack_of_open_elements = null;
     336    public $stack_of_open_elements;
    337337
    338338    /**
    … …  
    347347     * @var WP_HTML_Active_Formatting_Elements
    348348     */
    349     public $active_formatting_elements = null;
     349    public $active_formatting_elements;
    350350
    351351    /**

  • trunk/src/wp-includes/html-api/class-wp-html-processor.php

    r58742 r58769  
    160160     * @var WP_HTML_Processor_State
    161161     */
    162     private $state = null;
     162    private $state;
    163163
    164164    /**
    … …  
    209209     * @since 6.4.0
    210210     *
    211      * @var closure
     211     * @var Closure|null
    212212     */
    213213    private $release_internal_bookmark_on_destruct = null;
    … …  
    369369
    370370        $this->state->stack_of_open_elements->set_push_handler(
    371             function ( WP_HTML_Token $token ) {
     371            function ( WP_HTML_Token $token ): void {
    372372                $is_virtual            = ! isset( $this->state->current_token ) || $this->is_tag_closer();
    373373                $same_node             = isset( $this->state->current_token ) && $token->node_name === $this->state->current_token->node_name;
    … …  
    378378
    379379        $this->state->stack_of_open_elements->set_pop_handler(
    380             function ( WP_HTML_Token $token ) {
     380            function ( WP_HTML_Token $token ): void {
    381381                $is_virtual            = ! isset( $this->state->current_token ) || ! $this->is_tag_closer();
    382382                $same_node             = isset( $this->state->current_token ) && $token->node_name === $this->state->current_token->node_name;
    … …  
    391391         * exposing it to any public API.
    392392         */
    393         $this->release_internal_bookmark_on_destruct = function ( $name ) {
     393        $this->release_internal_bookmark_on_destruct = function ( string $name ): void {
    394394            parent::release_bookmark( $name );
    395395        };
    … …  
    404404     *
    405405     * @param string $message Explains support is missing in order to parse the current node.
    406      *
    407      * @return mixed
    408406     */
    409407    private function bail( string $message ) {
    … …  
    458456     * @return string|null The last error, if one exists, otherwise null.
    459457     */
    460     public function get_last_error() {
     458    public function get_last_error(): ?string {
    461459        return $this->last_error;
    462460    }
    … …  
    501499     * @return bool Whether a tag was matched.
    502500     */
    503     public function next_tag( $query = null ) {
     501    public function next_tag( $query = null ): bool {
    504502        $visit_closers = isset( $query['tag_closers'] ) && 'visit' === $query['tag_closers'];
    505503
    … …  
    591589     * @return bool
    592590     */
    593     public function next_token() {
     591    public function next_token(): bool {
    594592        $this->current_element = null;
    595593
    … …  
    644642    }
    645643
    646 
    647644    /**
    648645     * Indicates if the current tag token is a tag closer.
    … …  
    661658     * @return bool Whether the current tag is a tag closer.
    662659     */
    663     public function is_tag_closer() {
     660    public function is_tag_closer(): bool {
    664661        return $this->is_virtual()
    665662            ? ( WP_HTML_Stack_Event::POP === $this->current_element->operation && '#tag' === $this->get_token_type() )
    … …  
    675672     * @return bool Whether the current token is virtual.
    676673     */
    677     private function is_virtual() {
     674    private function is_virtual(): bool {
    678675        return (
    679676            isset( $this->current_element->provenance ) &&
    … …  
    707704     * @return bool Whether the currently-matched tag is found at the given nested structure.
    708705     */
    709     public function matches_breadcrumbs( $breadcrumbs ) {
     706    public function matches_breadcrumbs( $breadcrumbs ): bool {
    710707        // Everything matches when there are zero constraints.
    711708        if ( 0 === count( $breadcrumbs ) ) {
    … …  
    758755     *                   or `null` if not matched on any token.
    759756     */
    760     public function expects_closer( $node = null ) {
     757    public function expects_closer( $node = null ): ?bool {
    761758        $token_name = $node->node_name ?? $this->get_token_name();
    762759        if ( ! isset( $token_name ) ) {
    … …  
    789786     * @return bool Whether a tag was matched.
    790787     */
    791     public function step( $node_to_process = self::PROCESS_NEXT_NODE ) {
     788    public function step( $node_to_process = self::PROCESS_NEXT_NODE ): bool {
    792789        // Refuse to proceed if there was a previous error.
    793790        if ( null !== $this->last_error ) {
    … …  
    939936     * @return string[]|null Array of tag names representing path to matched node, if matched, otherwise NULL.
    940937     */
    941     public function get_breadcrumbs() {
     938    public function get_breadcrumbs(): ?array {
    942939        return $this->breadcrumbs;
    943940    }
    … …  
    968965     * @return int Nesting-depth of current location in the document.
    969966     */
    970     public function get_current_depth() {
     967    public function get_current_depth(): int {
    971968        return count( $this->breadcrumbs );
    972969    }
    … …  
    987984     * @return bool Whether an element was found.
    988985     */
    989     private function step_initial() {
     986    private function step_initial(): bool {
    990987        $this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
    991988    }
    … …  
    10061003     * @return bool Whether an element was found.
    10071004     */
    1008     private function step_before_html() {
     1005    private function step_before_html(): bool {
    10091006        $this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
    10101007    }
    … …  
    10251022     * @return bool Whether an element was found.
    10261023     */
    1027     private function step_before_head() {
     1024    private function step_before_head(): bool {
    10281025        $this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
    10291026    }
    … …  
    10441041     * @return bool Whether an element was found.
    10451042     */
    1046     private function step_in_head() {
     1043    private function step_in_head(): bool {
    10471044        $this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
    10481045    }
    … …  
    10631060     * @return bool Whether an element was found.
    10641061     */
    1065     private function step_in_head_noscript() {
     1062    private function step_in_head_noscript(): bool {
    10661063        $this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
    10671064    }
    … …  
    10821079     * @return bool Whether an element was found.
    10831080     */
    1084     private function step_after_head() {
     1081    private function step_after_head(): bool {
    10851082        $this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
    10861083    }
    … …  
    11011098     * @return bool Whether an element was found.
    11021099     */
    1103     private function step_in_body() {
     1100    private function step_in_body(): bool {
    11041101        $token_name = $this->get_token_name();
    11051102        $token_type = $this->get_token_type();
    … …  
    17241721     * @return bool Whether an element was found.
    17251722     */
    1726     private function step_in_table() {
     1723    private function step_in_table(): bool {
    17271724        $this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
    17281725    }
    … …  
    17431740     * @return bool Whether an element was found.
    17441741     */
    1745     private function step_in_table_text() {
     1742    private function step_in_table_text(): bool {
    17461743        $this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
    17471744    }
    … …  
    17621759     * @return bool Whether an element was found.
    17631760     */
    1764     private function step_in_caption() {
     1761    private function step_in_caption(): bool {
    17651762        $this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
    17661763    }
    … …  
    17811778     * @return bool Whether an element was found.
    17821779     */
    1783     private function step_in_column_group() {
     1780    private function step_in_column_group(): bool {
    17841781        $this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
    17851782    }
    … …  
    18001797     * @return bool Whether an element was found.
    18011798     */
    1802     private function step_in_table_body() {
     1799    private function step_in_table_body(): bool {
    18031800        $this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
    18041801    }
    … …  
    18191816     * @return bool Whether an element was found.
    18201817     */
    1821     private function step_in_row() {
     1818    private function step_in_row(): bool {
    18221819        $this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
    18231820    }
    … …  
    18381835     * @return bool Whether an element was found.
    18391836     */
    1840     private function step_in_cell() {
     1837    private function step_in_cell(): bool {
    18411838        $this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
    18421839    }
    … …  
    18571854     * @return bool Whether an element was found.
    18581855     */
    1859     private function step_in_select() {
     1856    private function step_in_select(): bool {
    18601857        $token_name = $this->get_token_name();
    18611858        $token_type = $this->get_token_type();
    … …  
    20382035     * @return bool Whether an element was found.
    20392036     */
    2040     private function step_in_select_in_table() {
     2037    private function step_in_select_in_table(): bool {
    20412038        $this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
    20422039    }
    … …  
    20572054     * @return bool Whether an element was found.
    20582055     */
    2059     private function step_in_template() {
     2056    private function step_in_template(): bool {
    20602057        $this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
    20612058    }
    … …  
    20762073     * @return bool Whether an element was found.
    20772074     */
    2078     private function step_after_body() {
     2075    private function step_after_body(): bool {
    20792076        $this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
    20802077    }
    … …  
    20952092     * @return bool Whether an element was found.
    20962093     */
    2097     private function step_in_frameset() {
     2094    private function step_in_frameset(): bool {
    20982095        $this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
    20992096    }
    … …  
    21142111     * @return bool Whether an element was found.
    21152112     */
    2116     private function step_after_frameset() {
     2113    private function step_after_frameset(): bool {
    21172114        $this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
    21182115    }
    … …  
    21332130     * @return bool Whether an element was found.
    21342131     */
    2135     private function step_after_after_body() {
     2132    private function step_after_after_body(): bool {
    21362133        $this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
    21372134    }
    … …  
    21522149     * @return bool Whether an element was found.
    21532150     */
    2154     private function step_after_after_frameset() {
     2151    private function step_after_after_frameset(): bool {
    21552152        $this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
    21562153    }
    … …  
    21712168     * @return bool Whether an element was found.
    21722169     */
    2173     private function step_in_foreign_content() {
     2170    private function step_in_foreign_content(): bool {
    21742171        $this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
    21752172    }
    … …  
    22232220     * @return string|null Name of currently matched tag in input HTML, or `null` if none found.
    22242221     */
    2225     public function get_tag() {
     2222    public function get_tag(): ?string {
    22262223        if ( null !== $this->last_error ) {
    22272224            return null;
    … …  
    22642261     * @return bool Whether the currently matched tag contains the self-closing flag.
    22652262     */
    2266     public function has_self_closing_flag() {
     2263    public function has_self_closing_flag(): bool {
    22672264        return $this->is_virtual() ? false : parent::has_self_closing_flag();
    22682265    }
    … …  
    22882285     * @return string|null Name of the matched token.
    22892286     */
    2290     public function get_token_name() {
     2287    public function get_token_name(): ?string {
    22912288        return $this->is_virtual()
    22922289            ? $this->current_element->token->node_name
    … …  
    23162313     * @return string|null What kind of token is matched, or null.
    23172314     */
    2318     public function get_token_type() {
     2315    public function get_token_type(): ?string {
    23192316        if ( $this->is_virtual() ) {
    23202317            /*
    … …  
    23782375     * @return bool Whether an attribute value was set.
    23792376     */
    2380     public function set_attribute( $name, $value ) {
     2377    public function set_attribute( $name, $value ): bool {
    23812378        return $this->is_virtual() ? false : parent::set_attribute( $name, $value );
    23822379    }
    … …  
    23902387     * @return bool Whether an attribute was removed.
    23912388     */
    2392     public function remove_attribute( $name ) {
     2389    public function remove_attribute( $name ): bool {
    23932390        return $this->is_virtual() ? false : parent::remove_attribute( $name );
    23942391    }
    … …  
    24202417     * @return array|null List of attribute names, or `null` when no tag opener is matched.
    24212418     */
    2422     public function get_attribute_names_with_prefix( $prefix ) {
     2419    public function get_attribute_names_with_prefix( $prefix ): ?array {
    24232420        return $this->is_virtual() ? null : parent::get_attribute_names_with_prefix( $prefix );
    24242421    }
    … …  
    24322429     * @return bool Whether the class was set to be added.
    24332430     */
    2434     public function add_class( $class_name ) {
     2431    public function add_class( $class_name ): bool {
    24352432        return $this->is_virtual() ? false : parent::add_class( $class_name );
    24362433    }
    … …  
    24442441     * @return bool Whether the class was set to be removed.
    24452442     */
    2446     public function remove_class( $class_name ) {
     2443    public function remove_class( $class_name ): bool {
    24472444        return $this->is_virtual() ? false : parent::remove_class( $class_name );
    24482445    }
    … …  
    24562453     * @return bool|null Whether the matched tag contains the given class name, or null if not matched.
    24572454     */
    2458     public function has_class( $wanted_class ) {
     2455    public function has_class( $wanted_class ): ?bool {
    24592456        return $this->is_virtual() ? null : parent::has_class( $wanted_class );
    24602457    }
    … …  
    25002497     * @return string
    25012498     */
    2502     public function get_modifiable_text() {
     2499    public function get_modifiable_text(): string {
    25032500        return $this->is_virtual() ? '' : parent::get_modifiable_text();
    25042501    }
    … …  
    25232520     * @return string|null
    25242521     */
    2525     public function get_comment_type() {
     2522    public function get_comment_type(): ?string {
    25262523        return $this->is_virtual() ? null : parent::get_comment_type();
    25272524    }
    … …  
    25382535     * @return bool Whether the bookmark already existed before removal.
    25392536     */
    2540     public function release_bookmark( $bookmark_name ) {
     2537    public function release_bookmark( $bookmark_name ): bool {
    25412538        return parent::release_bookmark( "_{$bookmark_name}" );
    25422539    }
    … …  
    25592556     * @return bool Whether the internal cursor was successfully moved to the bookmark's location.
    25602557     */
    2561     public function seek( $bookmark_name ) {
     2558    public function seek( $bookmark_name ): bool {
    25622559        // Flush any pending updates to the document before beginning.
    25632560        $this->get_updated_html();
    … …  
    27302727     * @return bool Whether the bookmark was successfully created.
    27312728     */
    2732     public function set_bookmark( $bookmark_name ) {
     2729    public function set_bookmark( $bookmark_name ): bool {
    27332730        return parent::set_bookmark( "_{$bookmark_name}" );
    27342731    }
    … …  
    27422739     * @return bool Whether that bookmark exists.
    27432740     */
    2744     public function has_bookmark( $bookmark_name ) {
     2741    public function has_bookmark( $bookmark_name ): bool {
    27452742        return parent::has_bookmark( "_{$bookmark_name}" );
    27462743    }
    … …  
    27592756     * @see https://html.spec.whatwg.org/#close-a-p-element
    27602757     */
    2761     private function close_a_p_element() {
     2758    private function close_a_p_element(): void {
    27622759        $this->generate_implied_end_tags( 'P' );
    27632760        $this->state->stack_of_open_elements->pop_until( 'P' );
    … …  
    27742771     * @param string|null $except_for_this_element Perform as if this element doesn't exist in the stack of open elements.
    27752772     */
    2776     private function generate_implied_end_tags( $except_for_this_element = null ) {
     2773    private function generate_implied_end_tags( ?string $except_for_this_element = null ): void {
    27772774        $elements_with_implied_end_tags = array(
    27782775            'DD',
    … …  
    28102807     * @see https://html.spec.whatwg.org/#generate-implied-end-tags
    28112808     */
    2812     private function generate_implied_end_tags_thoroughly() {
     2809    private function generate_implied_end_tags_thoroughly(): void {
    28132810        $elements_with_implied_end_tags = array(
    28142811            'CAPTION',
    … …  
    28522849     * @return bool Whether any formatting elements needed to be reconstructed.
    28532850     */
    2854     private function reconstruct_active_formatting_elements() {
     2851    private function reconstruct_active_formatting_elements(): bool {
    28552852        /*
    28562853         * > If there are no entries in the list of active formatting elements, then there is nothing
    … …  
    30753072     * @see https://html.spec.whatwg.org/#adoption-agency-algorithm
    30763073     */
    3077     private function run_adoption_agency_algorithm() {
     3074    private function run_adoption_agency_algorithm(): void {
    30783075        $budget       = 1000;
    30793076        $subject      = $this->get_tag();
    … …  
    31833180     * @param WP_HTML_Token $token Name of bookmark pointing to element in original input HTML.
    31843181     */
    3185     private function insert_html_element( $token ) {
     3182    private function insert_html_element( WP_HTML_Token $token ): void {
    31863183        $this->state->stack_of_open_elements->push( $token );
    31873184    }
    … …  
    32013198     * @return bool Whether the element of the given name is in the special category.
    32023199     */
    3203     public static function is_special( $tag_name ) {
     3200    public static function is_special( $tag_name ): bool {
    32043201        $tag_name = strtoupper( $tag_name );
    32053202
    … …  
    33163313     * @return bool Whether the given tag is an HTML Void Element.
    33173314     */
    3318     public static function is_void( $tag_name ) {
     3315    public static function is_void( $tag_name ): bool {
    33193316        $tag_name = strtoupper( $tag_name );
    33203317

  • trunk/src/wp-includes/html-api/class-wp-html-span.php

    r57179 r58769  
    5050     * @param int $length Byte length of span.
    5151     */
    52     public function __construct( $start, $length ) {
     52    public function __construct( int $start, int $length ) {
    5353        $this->start  = $start;
    5454        $this->length = $length;

  • trunk/src/wp-includes/html-api/class-wp-html-stack-event.php

    r58558 r58769  
    7575     * @param string        $provenance "virtual" or "real".
    7676     */
    77     public function __construct( $token, $operation, $provenance ) {
     77    public function __construct( WP_HTML_Token $token, string $operation, string $provenance ) {
    7878        $this->token      = $token;
    7979        $this->operation  = $operation;

  • trunk/src/wp-includes/html-api/class-wp-html-tag-processor.php

    r58740 r58769  
    785785     * @return bool Whether a tag was matched.
    786786     */
    787     public function next_tag( $query = null ) {
     787    public function next_tag( $query = null ): bool {
    788788        $this->parse_query( $query );
    789789        $already_found = 0;
    … …  
    833833     * @return bool Whether a token was parsed.
    834834     */
    835     public function next_token() {
     835    public function next_token(): bool {
    836836        return $this->base_class_next_token();
    837837    }
    … …  
    852852     * @return bool Whether a token was parsed.
    853853     */
    854     private function base_class_next_token() {
     854    private function base_class_next_token(): bool {
    855855        $was_at = $this->bytes_already_parsed;
    856856        $this->after_tag();
    … …  
    10341034     * @return bool Whether the parse paused at the start of an incomplete token.
    10351035     */
    1036     public function paused_at_incomplete_token() {
     1036    public function paused_at_incomplete_token(): bool {
    10371037        return self::STATE_INCOMPLETE_INPUT === $this->parser_state;
    10381038    }
    … …  
    11131113     * @return bool|null Whether the matched tag contains the given class name, or null if not matched.
    11141114     */
    1115     public function has_class( $wanted_class ) {
     1115    public function has_class( $wanted_class ): ?bool {
    11161116        if ( self::STATE_MATCHED_TAG !== $this->parser_state ) {
    11171117            return null;
    … …  
    12101210     * @return bool Whether the bookmark was successfully created.
    12111211     */
    1212     public function set_bookmark( $name ) {
     1212    public function set_bookmark( $name ): bool {
    12131213        // It only makes sense to set a bookmark if the parser has paused on a concrete token.
    12141214        if (
    … …  
    12431243     * @return bool Whether the bookmark already existed before removal.
    12441244     */
    1245     public function release_bookmark( $name ) {
     1245    public function release_bookmark( $name ): bool {
    12461246        if ( ! array_key_exists( $name, $this->bookmarks ) ) {
    12471247            return false;
    … …  
    12631263     * @return bool Whether an end to the RAWTEXT region was found before the end of the document.
    12641264     */
    1265     private function skip_rawtext( $tag_name ) {
     1265    private function skip_rawtext( string $tag_name ): bool {
    12661266        /*
    12671267         * These two functions distinguish themselves on whether character references are
    … …  
    12821282     * @return bool Whether an end to the RCDATA region was found before the end of the document.
    12831283     */
    1284     private function skip_rcdata( $tag_name ) {
     1284    private function skip_rcdata( string $tag_name ): bool {
    12851285        $html       = $this->html;
    12861286        $doc_length = strlen( $html );
    … …  
    13701370     * @return bool Whether the script tag was closed before the end of the document.
    13711371     */
    1372     private function skip_script_data() {
     1372    private function skip_script_data(): bool {
    13731373        $state      = 'unescaped';
    13741374        $html       = $this->html;
    … …  
    15171517     * @return bool Whether a tag was found before the end of the document.
    15181518     */
    1519     private function parse_next_tag() {
     1519    private function parse_next_tag(): bool {
    15201520        $this->after_tag();
    15211521
    … …  
    19071907     * @return bool Whether an attribute was found before the end of the document.
    19081908     */
    1909     private function parse_next_attribute() {
     1909    private function parse_next_attribute(): bool {
    19101910        $doc_length = strlen( $this->html );
    19111911
    … …  
    20422042     * @since 6.2.0
    20432043     */
    2044     private function skip_whitespace() {
     2044    private function skip_whitespace(): void {
    20452045        $this->bytes_already_parsed += strspn( $this->html, " \t\f\r\n", $this->bytes_already_parsed );
    20462046    }
    … …  
    20512051     * @since 6.2.0
    20522052     */
    2053     private function after_tag() {
     2053    private function after_tag(): void {
    20542054        /*
    20552055         * There could be lexical updates enqueued for an attribute that
    … …  
    21122112     * @see WP_HTML_Tag_Processor::$classname_updates
    21132113     */
    2114     private function class_name_updates_to_attributes_updates() {
     2114    private function class_name_updates_to_attributes_updates(): void {
    21152115        if ( count( $this->classname_updates ) === 0 ) {
    21162116            return;
    … …  
    22572257     * @return int How many bytes the given pointer moved in response to the updates.
    22582258     */
    2259     private function apply_attributes_updates( $shift_this_point ) {
     2259    private function apply_attributes_updates( int $shift_this_point ): int {
    22602260        if ( ! count( $this->lexical_updates ) ) {
    22612261            return 0;
    … …  
    23542354     * @return bool Whether that bookmark exists.
    23552355     */
    2356     public function has_bookmark( $bookmark_name ) {
     2356    public function has_bookmark( $bookmark_name ): bool {
    23572357        return array_key_exists( $bookmark_name, $this->bookmarks );
    23582358    }
    … …  
    23692369     * @return bool Whether the internal cursor was successfully moved to the bookmark's location.
    23702370     */
    2371     public function seek( $bookmark_name ) {
     2371    public function seek( $bookmark_name ): bool {
    23722372        if ( ! array_key_exists( $bookmark_name, $this->bookmarks ) ) {
    23732373            _doing_it_wrong(
    … …  
    24062406     * @return int Comparison value for string order.
    24072407     */
    2408     private static function sort_start_ascending( $a, $b ) {
     2408    private static function sort_start_ascending( WP_HTML_Text_Replacement $a, WP_HTML_Text_Replacement $b ): int {
    24092409        $by_start = $a->start - $b->start;
    24102410        if ( 0 !== $by_start ) {
    … …  
    24382438     * @return string|boolean|null Value of enqueued update if present, otherwise false.
    24392439     */
    2440     private function get_enqueued_attribute_value( $comparable_name ) {
     2440    private function get_enqueued_attribute_value( string $comparable_name ) {
    24412441        if ( self::STATE_MATCHED_TAG !== $this->parser_state ) {
    24422442            return false;
    … …  
    25892589     * @return array|null List of attribute names, or `null` when no tag opener is matched.
    25902590     */
    2591     public function get_attribute_names_with_prefix( $prefix ) {
     2591    public function get_attribute_names_with_prefix( $prefix ): ?array {
    25922592        if (
    25932593            self::STATE_MATCHED_TAG !== $this->parser_state ||
    … …  
    26242624     * @return string|null Name of currently matched tag in input HTML, or `null` if none found.
    26252625     */
    2626     public function get_tag() {
     2626    public function get_tag(): ?string {
    26272627        if ( null === $this->tag_name_starts_at ) {
    26282628            return null;
    … …  
    26622662     * @return bool Whether the currently matched tag contains the self-closing flag.
    26632663     */
    2664     public function has_self_closing_flag() {
     2664    public function has_self_closing_flag(): bool {
    26652665        if ( self::STATE_MATCHED_TAG !== $this->parser_state ) {
    26662666            return false;
    … …  
    26942694     * @return bool Whether the current tag is a tag closer.
    26952695     */
    2696     public function is_tag_closer() {
     2696    public function is_tag_closer(): bool {
    26972697        return (
    26982698            self::STATE_MATCHED_TAG === $this->parser_state &&
    … …  
    27232723     * @return string|null What kind of token is matched, or null.
    27242724     */
    2725     public function get_token_type() {
     2725    public function get_token_type(): ?string {
    27262726        switch ( $this->parser_state ) {
    27272727            case self::STATE_MATCHED_TAG:
    … …  
    27562756     * @return string|null Name of the matched token.
    27572757     */
    2758     public function get_token_name() {
     2758    public function get_token_name(): ?string {
    27592759        switch ( $this->parser_state ) {
    27602760            case self::STATE_MATCHED_TAG:
    … …  
    28022802     * @return string|null
    28032803     */
    2804     public function get_comment_type() {
     2804    public function get_comment_type(): ?string {
    28052805        if ( self::STATE_COMMENT !== $this->parser_state ) {
    28062806            return null;
    … …  
    28302830     * @return string
    28312831     */
    2832     public function get_modifiable_text() {
     2832    public function get_modifiable_text(): string {
    28332833        if ( null === $this->text_starts_at ) {
    28342834            return '';
    … …  
    29002900     * @return bool Whether an attribute value was set.
    29012901     */
    2902     public function set_attribute( $name, $value ) {
     2902    public function set_attribute( $name, $value ): bool {
    29032903        if (
    29042904            self::STATE_MATCHED_TAG !== $this->parser_state ||
    … …  
    30433043     * @return bool Whether an attribute was removed.
    30443044     */
    3045     public function remove_attribute( $name ) {
     3045    public function remove_attribute( $name ): bool {
    30463046        if (
    30473047            self::STATE_MATCHED_TAG !== $this->parser_state ||
    … …  
    31213121     * @return bool Whether the class was set to be added.
    31223122     */
    3123     public function add_class( $class_name ) {
     3123    public function add_class( $class_name ): bool {
    31243124        if (
    31253125            self::STATE_MATCHED_TAG !== $this->parser_state ||
    … …  
    31423142     * @return bool Whether the class was set to be removed.
    31433143     */
    3144     public function remove_class( $class_name ) {
     3144    public function remove_class( $class_name ): bool {
    31453145        if (
    31463146            self::STATE_MATCHED_TAG !== $this->parser_state ||
    … …  
    31663166     * @return string The processed HTML.
    31673167     */
    3168     public function __toString() {
     3168    public function __toString(): string {
    31693169        return $this->get_updated_html();
    31703170    }
    … …  
    31793179     * @return string The processed HTML.
    31803180     */
    3181     public function get_updated_html() {
     3181    public function get_updated_html(): string {
    31823182        $requires_no_updating = 0 === count( $this->classname_updates ) && 0 === count( $this->lexical_updates );
    31833183
    … …  
    33013301     * @return bool Whether the given tag and its attribute match the search criteria.
    33023302     */
    3303     private function matches() {
     3303    private function matches(): bool {
    33043304        if ( $this->is_closing_tag && ! $this->stop_on_tag_closers ) {
    33053305            return false;

  • trunk/src/wp-includes/html-api/class-wp-html-text-replacement.php

    r57179 r58769  
    5757     * @param string $text   Span of text to insert in document to replace existing content from start to end.
    5858     */
    59     public function __construct( $start, $length, $text ) {
     59    public function __construct( int $start, int $length, string $text ) {
    6060        $this->start  = $start;
    6161        $this->length = $length;

  • trunk/src/wp-includes/html-api/class-wp-html-token.php

    r57163 r58769  
    7373     * @since 6.4.0
    7474     *
    75      * @param string   $bookmark_name         Name of bookmark corresponding to location in HTML where token is found.
    76      * @param string   $node_name             Name of node token represents; if uppercase, an HTML element; if lowercase, a special value like "marker".
    77      * @param bool     $has_self_closing_flag Whether the source token contains the self-closing flag, regardless of whether it's valid.
    78      * @param callable $on_destroy            Function to call when destroying token, useful for releasing the bookmark.
     75     * @param string        $bookmark_name         Name of bookmark corresponding to location in HTML where token is found.
     76     * @param string        $node_name             Name of node token represents; if uppercase, an HTML element; if lowercase, a special value like "marker".
     77     * @param bool          $has_self_closing_flag Whether the source token contains the self-closing flag, regardless of whether it's valid.
     78     * @param callable|null $on_destroy            Optional. Function to call when destroying token, useful for releasing the bookmark.
    7979     */
    80     public function __construct( $bookmark_name, $node_name, $has_self_closing_flag, $on_destroy = null ) {
     80    public function __construct( string $bookmark_name, string $node_name, bool $has_self_closing_flag, ?callable $on_destroy = null ) {
    8181        $this->bookmark_name         = $bookmark_name;
    8282        $this->node_name             = $node_name;
Note: See TracChangeset for help on using the changeset viewer.