Make WordPress Core


Ignore:
Timestamp:
07/19/2024 11:42:14 PM (18 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.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • 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
Note: See TracChangeset for help on using the changeset viewer.