Changeset 58769 for trunk/src/wp-includes/class-wp-token-map.php

Timestamp:

07/19/2024 11:42:14 PM (10 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:

• trunk/src/wp-includes/class-wp-token-map.php (modified) (9 diffs)

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

@@ -281 +281 @@
      * @return WP_Token_Map|null Token map, unless unable to create it.
      */
-    public static function from_array( $mappings, $key_length = 2 ) {
+    public static function from_array( array $mappings, int $key_length = 2 ): ?WP_Token_Map {
         $map             = new WP_Token_Map();
         $map->key_length = $key_length;
@@ -329 +329 @@
             usort(
                 $groups[ $group_key ],
-                static function ( $a, $b ) {
+                static function ( array $a, array $b ): int {
                     return self::longest_first_then_alphabetical( $a[0], $b[0] );
                 }
@@ -386 +386 @@
      * @return WP_Token_Map Map with precomputed data loaded.
      */
-    public static function from_precomputed_table( $state ) {
+    public static function from_precomputed_table( $state ): ?WP_Token_Map {
         $has_necessary_state = isset(
             $state['storage_version'],
@@ -440 +440 @@
      * @return bool Whether there's an entry for the given word in the map.
      */
-    public function contains( $word, $case_sensitivity = 'case-sensitive' ) {
+    public function contains( string $word, string $case_sensitivity = 'case-sensitive' ): bool {
         $ignore_case = 'ascii-case-insensitive' === $case_sensitivity;
 
@@ -528 +528 @@
      * @return string|null Mapped value of lookup key if found, otherwise `null`.
      */
-    public function read_token( $text, $offset = 0, &$matched_token_byte_length = null, $case_sensitivity = 'case-sensitive' ) {
+    public function read_token( string $text, int $offset = 0, &$matched_token_byte_length = null, $case_sensitivity = 'case-sensitive' ): ?string {
         $ignore_case = 'ascii-case-insensitive' === $case_sensitivity;
         $text_length = strlen( $text );
@@ -572 +572 @@
      * Finds a match for a short word at the index.
      *
-     * @since 6.6.0.
-     *
-     * @param string $text                       String in which to search for a lookup key.
-     * @param int    $offset                     Optional. How many bytes into the string where the lookup key ought to start. Default 0.
-     * @param ?int   &$matched_token_byte_length Optional. Holds byte-length of found lookup key if matched, otherwise not set. Default null.
-     * @param string $case_sensitivity           Optional. Pass 'ascii-case-insensitive' to ignore ASCII case when matching. Default 'case-sensitive'.
+     * @since 6.6.0
+     *
+     * @param string   $text                       String in which to search for a lookup key.
+     * @param int      $offset                     Optional. How many bytes into the string where the lookup key ought to start. Default 0.
+     * @param int|null &$matched_token_byte_length Optional. Holds byte-length of found lookup key if matched, otherwise not set. Default null.
+     * @param string   $case_sensitivity           Optional. Pass 'ascii-case-insensitive' to ignore ASCII case when matching. Default 'case-sensitive'.
+     *
      * @return string|null Mapped value of lookup key if found, otherwise `null`.
      */
-    private function read_small_token( $text, $offset, &$matched_token_byte_length, $case_sensitivity = 'case-sensitive' ) {
+    private function read_small_token( string $text, int $offset = 0, &$matched_token_byte_length = null, $case_sensitivity = 'case-sensitive' ): ?string {
         $ignore_case  = 'ascii-case-insensitive' === $case_sensitivity;
         $small_length = strlen( $this->small_words );
@@ -635 +636 @@
      * @return array The lookup key/substitution values as an associate array.
      */
-    public function to_array() {
+    public function to_array(): array {
         $tokens = array();
 
@@ -697 +698 @@
      * @return string Value which can be pasted into a PHP source file for quick loading of table.
      */
-    public function precomputed_php_source_table( $indent = "\t" ) {
+    public function precomputed_php_source_table( string $indent = "\t" ): string {
         $i1 = $indent;
         $i2 = $i1 . $indent;
@@ -802 +803 @@
      * @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.
      */
-    private static function longest_first_then_alphabetical( $a, $b ) {
+    private static function longest_first_then_alphabetical( string $a, string $b ): int {
         if ( $a === $b ) {
             return 0;