Title: WP_Token_Map::read_token
Published: July 16, 2024
Last modified: February 24, 2026

---

# WP_Token_Map::read_token( string $text, int $offset,  $matched_token_byte_length = null, string $case_sensitivity ): string|null

## In this article

 * [Description](https://developer.wordpress.org/reference/classes/wp_token_map/read_token/?output_format=md#description)
 * [Parameters](https://developer.wordpress.org/reference/classes/wp_token_map/read_token/?output_format=md#parameters)
 * [Return](https://developer.wordpress.org/reference/classes/wp_token_map/read_token/?output_format=md#return)
 * [Source](https://developer.wordpress.org/reference/classes/wp_token_map/read_token/?output_format=md#source)
 * [Related](https://developer.wordpress.org/reference/classes/wp_token_map/read_token/?output_format=md#related)
 * [Changelog](https://developer.wordpress.org/reference/classes/wp_token_map/read_token/?output_format=md#changelog)

[ Back to top](https://developer.wordpress.org/reference/classes/wp_token_map/read_token/?output_format=md#wp--skip-link--target)

If the text starting at a given offset is a lookup key in the map, return the corresponding
transformation from the map, else `false`.

## 󠀁[Description](https://developer.wordpress.org/reference/classes/wp_token_map/read_token/?output_format=md#description)󠁿

This function returns the translated string, but accepts an optional parameter `
$matched_token_byte_length`, which communicates how many bytes long the lookup key
was, if it found one. This can be used to advance a cursor in calling code if a 
lookup key was found.

Example:

    ```php
    false === $smilies->read_token( 'Not sure :?.', 0, $token_byte_length );
    '😕'  === $smilies->read_token( 'Not sure :?.', 9, $token_byte_length );
    2     === $token_byte_length;
    ```

Example:

    ```php
    while ( $at < strlen( $input ) ) {
        $next_at = strpos( $input, ':', $at );
        if ( false === $next_at ) {
            break;
        }

        $smily = $smilies->read_token( $input, $next_at, $token_byte_length );
        if ( false === $next_at ) {
            ++$at;
            continue;
        }

        $prefix  = substr( $input, $at, $next_at - $at );
        $at     += $token_byte_length;
        $output .= "{$prefix}{$smily}";
    }
    ```

## 󠀁[Parameters](https://developer.wordpress.org/reference/classes/wp_token_map/read_token/?output_format=md#parameters)󠁿

 `$text`stringrequired

String in which to search for a lookup key.

`$offset`intoptional

How many bytes into the string where the lookup key ought to start. Default 0.

&$matched_token_byte_length Optional. Holds byte-length of found token matched, 
otherwise not set. Default null.

`$case_sensitivity`stringoptional

Pass `'ascii-case-insensitive'` to ignore ASCII case when matching. Default `'case-
sensitive'`.

## 󠀁[Return](https://developer.wordpress.org/reference/classes/wp_token_map/read_token/?output_format=md#return)󠁿

 string|null Mapped value of lookup key if found, otherwise `null`.

## 󠀁[Source](https://developer.wordpress.org/reference/classes/wp_token_map/read_token/?output_format=md#source)󠁿

    ```php
    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 );

    	// Search for a long word first, if the text is long enough, and if that fails, a short one.
    	if ( $text_length > $this->key_length ) {
    		$group_key = substr( $text, $offset, $this->key_length );

    		$group_at = $ignore_case ? stripos( $this->groups, $group_key ) : strpos( $this->groups, $group_key );
    		if ( false === $group_at ) {
    			// Perhaps a short word then.
    			return strlen( $this->small_words ) > 0
    				? $this->read_small_token( $text, $offset, $matched_token_byte_length, $case_sensitivity )
    				: null;
    		}

    		$group        = $this->large_words[ $group_at / ( $this->key_length + 1 ) ];
    		$group_length = strlen( $group );
    		$at           = 0;
    		while ( $at < $group_length ) {
    			$token_length   = unpack( 'C', $group[ $at++ ] )[1];
    			$token          = substr( $group, $at, $token_length );
    			$at            += $token_length;
    			$mapping_length = unpack( 'C', $group[ $at++ ] )[1];
    			$mapping_at     = $at;

    			if ( 0 === substr_compare( $text, $token, $offset + $this->key_length, $token_length, $ignore_case ) ) {
    				$matched_token_byte_length = $this->key_length + $token_length;
    				return substr( $group, $mapping_at, $mapping_length );
    			}

    			$at = $mapping_at + $mapping_length;
    		}
    	}

    	// Perhaps a short word then.
    	return strlen( $this->small_words ) > 0
    		? $this->read_small_token( $text, $offset, $matched_token_byte_length, $case_sensitivity )
    		: null;
    }
    ```

[View all references](https://developer.wordpress.org/reference/files/wp-includes/class-wp-token-map.php/)
[View on Trac](https://core.trac.wordpress.org/browser/tags/6.9.4/src/wp-includes/class-wp-token-map.php#L530)
[View on GitHub](https://github.com/WordPress/wordpress-develop/blob/6.9.4/src/wp-includes/class-wp-token-map.php#L530-L569)

## 󠀁[Related](https://developer.wordpress.org/reference/classes/wp_token_map/read_token/?output_format=md#related)󠁿

| Uses | Description | 
| [WP_Token_Map::read_small_token()](https://developer.wordpress.org/reference/classes/wp_token_map/read_small_token/)`wp-includes/class-wp-token-map.php` |

Finds a match for a short word at the index.

  |

## 󠀁[Changelog](https://developer.wordpress.org/reference/classes/wp_token_map/read_token/?output_format=md#changelog)󠁿

| Version | Description | 
| [6.6.0](https://developer.wordpress.org/reference/since/6.6.0/) | Introduced. |

## User Contributed Notes

You must [log in](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Fclasses%2Fwp_token_map%2Fread_token%2F)
before being able to contribute a note or feedback.