From 639ce0f9dbf5848f94a1f7bc369cf7afaa26880b Mon Sep 17 00:00:00 2001 From: Jon Surrell Date: Tue, 17 Nov 2026 17:22:38 +0400 Subject: [PATCH 1/2] Add WP_CSS_Token_Processor::parse_single_token() Code that holds CSS text and must check it is one value of a type, such as the transform value checks in the style engine, theme.json, block supports and safecss_filter_attr(), needs the text's single token or a rejection. Each wrote its own loop over the tokenizer. The method ignores whitespace and comments around the token, as CSS Syntax 3 discards whitespace around a component value and drops comments while tokenizing. A caller that must reject surrounding whitespace compares the token's length with the text's. --- .../css-api/class-wp-css-token-processor.php | 48 +++++++++++++ .../tests/css-api/wpCssTokenProcessor.php | 72 +++++++++++++++++++ 2 files changed, 120 insertions(+) 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..e68367e7a8ce7 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,54 @@ public function get_token_length(): ?int { return $this->token_length; } + /** + * Parses CSS that should hold exactly one token. + * + * Whitespace and comments before and after the token are ignored, as + * CSS Syntax 3 discards whitespace around a component value and drops + * comments while tokenizing. 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( '1px 2px' ) ); + * // Outputs: + * // dimension-token 45deg + * // NULL + * ``` + * + * The token's offsets index the given CSS, so a caller that writes the + * value back as it was written can take the token's own bytes from it. + * + * @since 7.3.0 + * + * @link https://www.w3.org/TR/css-syntax-3/#parse-component-value + * + * @param string $css CSS source to parse. + * @return WP_CSS_Token|null The token, or null when the CSS holds no token or more than one. + */ + public static function parse_single_token( string $css ): ?WP_CSS_Token { + $processor = new self( $css ); + $token = null; + + while ( $processor->next_token() ) { + if ( self::TOKEN_WHITESPACE === $processor->token_type || self::TOKEN_COMMENT === $processor->token_type ) { + continue; + } + + if ( null !== $token ) { + return null; + } + + $token = $processor->get_token(); + } + + return $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..e7a8a38eb9545 100644 --- a/tests/phpunit/tests/css-api/wpCssTokenProcessor.php +++ b/tests/phpunit/tests/css-api/wpCssTokenProcessor.php @@ -2619,4 +2619,76 @@ public function test_ident_start_codepoint_bounds_check(): void { ); $this->assertSame( $expected_tokens, $actual_tokens ); } + + /** + * Tests that CSS holding exactly one token, with whitespace and comments + * around it, 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' ), + 'whitespace around' => array( " \t45deg\n", WP_CSS_Token_Processor::TOKEN_DIMENSION, '45deg' ), + 'comments around' => array( '/* a */1px/* b */', WP_CSS_Token_Processor::TOKEN_DIMENSION, '1px' ), + '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 holding no token or more than one 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 */' ), + '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' ), + ); + } } From f7dd807999e86b4f7995b0f289496d3a6cdf450a Mon Sep 17 00:00:00 2001 From: Jon Surrell Date: Wed, 18 Nov 2026 11:49:41 +0400 Subject: [PATCH 2/2] CSS API: Require parse_single_token() input to be exactly one token. Whitespace or a comment before or after the token now returns null, as does input that is only whitespace or a comment. Callers check values that must be one token, such as a stored `rotate` angle, and some write the value back as given; accepting surrounding whitespace or comments would let that text through unchecked. --- .../css-api/class-wp-css-token-processor.php | 42 ++++++++----------- .../tests/css-api/wpCssTokenProcessor.php | 14 ++++--- 2 files changed, 26 insertions(+), 30 deletions(-) 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 e68367e7a8ce7..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 @@ -787,51 +787,43 @@ public function get_token_length(): ?int { } /** - * Parses CSS that should hold exactly one token. + * Parses CSS that is exactly one token, other than whitespace or a comment. * - * Whitespace and comments before and after the token are ignored, as - * CSS Syntax 3 discards whitespace around a component value and drops - * comments while tokenizing. Use this to check a value that must be one - * token, such as a length or an angle. + * 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 ' ); + * $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 * ``` * - * The token's offsets index the given CSS, so a caller that writes the - * value back as it was written can take the token's own bytes from it. - * * @since 7.3.0 * - * @link https://www.w3.org/TR/css-syntax-3/#parse-component-value - * * @param string $css CSS source to parse. - * @return WP_CSS_Token|null The token, or null when the CSS holds no token or more than one. + * @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 ); - $token = null; - - while ( $processor->next_token() ) { - if ( self::TOKEN_WHITESPACE === $processor->token_type || self::TOKEN_COMMENT === $processor->token_type ) { - continue; - } - - if ( null !== $token ) { - return null; - } - - $token = $processor->get_token(); + if ( + ! $processor->next_token() || + self::TOKEN_WHITESPACE === $processor->token_type || + self::TOKEN_COMMENT === $processor->token_type + ) { + return null; } - return $token; + $token = $processor->get_token(); + return $processor->next_token() ? null : $token; } /** diff --git a/tests/phpunit/tests/css-api/wpCssTokenProcessor.php b/tests/phpunit/tests/css-api/wpCssTokenProcessor.php index e7a8a38eb9545..7f1c515612e70 100644 --- a/tests/phpunit/tests/css-api/wpCssTokenProcessor.php +++ b/tests/phpunit/tests/css-api/wpCssTokenProcessor.php @@ -2621,8 +2621,7 @@ public function test_ident_start_codepoint_bounds_check(): void { } /** - * Tests that CSS holding exactly one token, with whitespace and comments - * around it, parses as that token. + * Tests that CSS that is exactly one token parses as that token. * * @ticket 65738 * @dataProvider data_parse_single_token @@ -2649,8 +2648,6 @@ public function test_parse_single_token( string $css, string $expected_type, str public static function data_parse_single_token(): array { return array( 'dimension' => array( '45deg', WP_CSS_Token_Processor::TOKEN_DIMENSION, '45deg' ), - 'whitespace around' => array( " \t45deg\n", WP_CSS_Token_Processor::TOKEN_DIMENSION, '45deg' ), - 'comments around' => array( '/* a */1px/* b */', WP_CSS_Token_Processor::TOKEN_DIMENSION, '1px' ), '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"' ), @@ -2661,7 +2658,8 @@ public static function data_parse_single_token(): array { } /** - * Tests that CSS holding no token or more than one does not parse as a single token. + * 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 @@ -2684,6 +2682,12 @@ public static function data_parse_single_token_rejects(): 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)' ),