diff --git a/src/wp-includes/css-api/class-wp-css-token-processor.php b/src/wp-includes/css-api/class-wp-css-token-processor.php index e9b0e27e4bd7e..de43b530bab3a 100644 --- a/src/wp-includes/css-api/class-wp-css-token-processor.php +++ b/src/wp-includes/css-api/class-wp-css-token-processor.php @@ -786,6 +786,46 @@ public function get_token_length(): ?int { return $this->token_length; } + /** + * Parses CSS that is exactly one token, other than whitespace or a comment. + * + * Any other text in the CSS, including whitespace or a comment before or + * after the token, returns null. Use this to check a value that must be + * one token, such as a length or an angle. + * + * Example: + * + * ```php interactive + * $token = WP_CSS_Token_Processor::parse_single_token( '45deg' ); + * echo $token->get_type() . ' ' . $token->get_value() . $token->get_unit() . "\n"; + * var_dump( WP_CSS_Token_Processor::parse_single_token( ' 45deg' ) ); + * var_dump( WP_CSS_Token_Processor::parse_single_token( '1px 2px' ) ); + * // Outputs: + * // dimension-token 45deg + * // NULL + * // NULL + * ``` + * + * @since 7.3.0 + * + * @param string $css CSS source to parse. + * @return WP_CSS_Token|null The token, or null when the CSS is not exactly one token + * or the token is whitespace or a comment. + */ + public static function parse_single_token( string $css ): ?WP_CSS_Token { + $processor = new self( $css ); + if ( + ! $processor->next_token() || + self::TOKEN_WHITESPACE === $processor->token_type || + self::TOKEN_COMMENT === $processor->token_type + ) { + return null; + } + + $token = $processor->get_token(); + return $processor->next_token() ? null : $token; + } + /** * Clears token state between tokens. * diff --git a/tests/phpunit/tests/css-api/wpCssTokenProcessor.php b/tests/phpunit/tests/css-api/wpCssTokenProcessor.php index c4c190e87cec9..7f1c515612e70 100644 --- a/tests/phpunit/tests/css-api/wpCssTokenProcessor.php +++ b/tests/phpunit/tests/css-api/wpCssTokenProcessor.php @@ -2619,4 +2619,80 @@ public function test_ident_start_codepoint_bounds_check(): void { ); $this->assertSame( $expected_tokens, $actual_tokens ); } + + /** + * Tests that CSS that is exactly one token parses as that token. + * + * @ticket 65738 + * @dataProvider data_parse_single_token + * + * @covers ::parse_single_token + * + * @param string $css CSS to parse. + * @param string $expected_type Expected token type. + * @param string $expected_text Expected source text of the token. + */ + public function test_parse_single_token( string $css, string $expected_type, string $expected_text ): void { + $token = WP_CSS_Token_Processor::parse_single_token( $css ); + + $this->assertInstanceOf( WP_CSS_Token::class, $token ); + $this->assertSame( $expected_type, $token->get_type() ); + $this->assertSame( $expected_text, substr( $css, $token->get_start(), $token->get_length() ) ); + } + + /** + * Data provider for test_parse_single_token(). + * + * @return array[] + */ + public static function data_parse_single_token(): array { + return array( + 'dimension' => array( '45deg', WP_CSS_Token_Processor::TOKEN_DIMENSION, '45deg' ), + 'number' => array( '0', WP_CSS_Token_Processor::TOKEN_NUMBER, '0' ), + 'percentage' => array( '50%', WP_CSS_Token_Processor::TOKEN_PERCENTAGE, '50%' ), + 'string with spaces' => array( '"a b"', WP_CSS_Token_Processor::TOKEN_STRING, '"a b"' ), + 'escaped unit' => array( '1\\64 eg', WP_CSS_Token_Processor::TOKEN_DIMENSION, '1\\64 eg' ), + 'url' => array( 'url(a.png)', WP_CSS_Token_Processor::TOKEN_URL, 'url(a.png)' ), + 'function token without close' => array( 'calc(', WP_CSS_Token_Processor::TOKEN_FUNCTION, 'calc(' ), + ); + } + + /** + * Tests that CSS that is not exactly one token, or is only whitespace or a + * comment, does not parse as a single token. + * + * @ticket 65738 + * @dataProvider data_parse_single_token_rejects + * + * @covers ::parse_single_token + * + * @param string $css CSS to parse. + */ + public function test_parse_single_token_rejects( string $css ): void { + $this->assertNull( WP_CSS_Token_Processor::parse_single_token( $css ) ); + } + + /** + * Data provider for test_parse_single_token_rejects(). + * + * @return array[] + */ + public static function data_parse_single_token_rejects(): array { + return array( + 'empty' => array( '' ), + 'whitespace only' => array( ' ' ), + 'comment only' => array( '/* a */' ), + 'leading whitespace' => array( ' 45deg' ), + 'trailing whitespace' => array( '45deg ' ), + 'trailing newline' => array( "45deg\n" ), + 'leading comment' => array( '/* a */1px' ), + 'trailing comment' => array( '1px/* b */' ), + 'unclosed comment' => array( '1px/*' ), + 'two values' => array( '1px 2px' ), + 'two values, no space' => array( '1px/**/2px' ), + 'function' => array( 'calc(1px)' ), + 'value and semicolon' => array( '1px;' ), + 'sign and number' => array( '- 1' ), + ); + } }