Skip to content

CSS API: Add WP_CSS_Token_Processor::parse_single_token() - #112

Open
sirreal wants to merge 3 commits into
css-api/css-token-processor-foundationsfrom
css-api/parse-single-token
Open

sirreal wants to merge 3 commits into
css-api/css-token-processor-foundationsfrom
css-api/parse-single-token

Conversation

@sirreal

@sirreal sirreal commented Nov 17, 2026 •

Copy link
Copy Markdown
Owner

Caution

This is a work in progress draft and is not ready for any serious review.

Add WP_CSS_Token_Processor::parse_single_token( $css ), which returns the token when the CSS is exactly one token other than whitespace or a comment, and null otherwise. Code that holds CSS text and must check it is one value of a type needs this: the transform value checks in #100 call it from the style engine, WP_Theme_JSON, block supports and safecss_filter_attr(), each through its own tokenizer loop.

CSS Result
45deg dimension token 45deg
␠45deg␠ null
/* a */1px null
1px 2px null
calc(1px) null (three tokens)
empty, whitespace or a comment only null

Whitespace or a comment around the token returns null. Callers such as the style engine in #100 write the value back as given, so text around the token would reach the output unchecked. This differs from CSS Syntax 3, which discards whitespace around a component value.

The method returns a token, not a component value: a function such as calc(1px) is not one token. With #110, an angle check is $token = WP_CSS_Token_Processor::parse_single_token( $value ); $is_angle = null !== $token && $token->is_angle();.

Tests cover each case above. The css-api group passes (1028 tests); PHPCS and PHPStan are clean.

Depends on WordPress#14781.

Trac ticket: TBD

Use of AI Tools

AI assistance: Yes
Tools: Claude Code
Models: Claude Opus 5.5
Used for: implementation, tests and this description.


This pull request is for code review only. Keep other discussion in the Trac ticket. Do not merge. See GitHub Pull Requests for Code Review in the Core Handbook.

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.
@github-actions

Copy link
Copy Markdown

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs.

Core Committers: Use this line as a base for the props when committing in SVN:

Props jonsurrell.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.


Props Bot commands

You can trigger Props Bot actions by commenting on this PR:

  • @propsbot add <username> to give props to a GitHub or WordPress.org user. Requires write access.
  • @propsbot remove <username> to leave a user out of the props. Requires write access.
  • @propsbot refresh to refresh this list. Adding the props-bot label works too.

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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant