Skip to content

Fonts: Parse font-family values with the CSS API - #103

Open
sirreal wants to merge 3 commits into
css-api/comma-separated-listsfrom
css-api/font-family-list
Open

sirreal wants to merge 3 commits into
css-api/comma-separated-listsfrom
css-api/font-family-list

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.

Font names with commas, quotes or CSS escapes change or break on their way to CSS. WP_Font_Utils::sanitize_font_family() splits the value at every comma and adds quotes without escaping, and WP_Font_Face quotes a descriptor only when it has a space and no quote:

Input Where Trunk This branch
"ACME, Sans", sans-serif sanitize_font_family() "ACME", "Sans", sans-serif "ACME\2c Sans", sans-serif
O'Reilly Sans @font-face descriptor font-family:O'Reilly Sans; font-family:"O\27 Reilly Sans";
Inter\ sanitize_font_family() "Inter\" (unterminated string) "Inter\5c "

This is an alternative to WordPress#13610 (PR 13610 below, https://core.trac.wordpress.org/ticket/63568) built on the CSS API. It covers that PR's parser, sanitize_font_family() and their callers; it does not change kses.php.

Design

  • WP_Font_Utils::parse_font_family_list( $value, $allow_plain_names = false ) reads the groups of WP_CSS_Token_Processor::parse_comma_separated_list() against the font-family grammar: one string, a sequence of identifiers, a generic family, generic() with kai, fangsong, khmer-mul or nastaliq, or a CSS-wide keyword or default as the whole value. Entries use PR 13610's array shape. The parser and serializer are about 140 non-comment lines; PR 13610's are about 250.

  • Names are written with WP_CSS_Builder::string(). A name stays unquoted only if it matches PR 13610's /^-?[a-zA-Z][a-zA-Z-]*\z/ and is not a keyword; this uses \z where PR 13610 uses $, so a\a (a name ending in a newline) stays quoted and sanitizing twice gives the same value. WP_CSS_Builder::ident( $name ) === $name is the CSS API alternative to the regex; it would also leave names such as Inter2 or _Foo unquoted.

  • Plain names: an entry that is not valid CSS becomes a plain name, as in PR 13610. Its text up to its first comma is one name, and the rest of the entry is read again as a list, once; an invalid entry in that second reading splits at each comma and each part is read on its own. Each byte is tokenized at most three times. PR 13610 re-reads the rest of the whole value after every failed entry, which is quadratic; the results agree except where a third reading would be needed:

    Input PR 13610 This branch
    O'Reilly, "ACME, Sans" O'Reilly, ACME, Sans O'Reilly, ACME, Sans
    A'B, C"D, "E, F" A'B, C"D, E, F A'B, C"D, "E, F"
  • generic() is accepted as in PR 13610. PR 3 (KSES: Parse declarations in safecss_filter_attr() WordPress/wordpress-develop#14784) drops generic() in safecss_filter_attr(), because its function allowlist requires a function that Blink, Gecko and WebKit ship unprefixed, and MDN browser-compat-data 8.1.9 lists no generic() support.

  • get_font_face_slug() uses PR 13610's decoded-name key. The REST duplicate check looks up two titles: the current slug, and get_legacy_font_face_slug(), the format of WordPress 6.5 to 7.2 computed from the decoded names. PR 13610 reads every font face post when the first lookup finds nothing. A saved face whose name differs from the request only in escape spelling is not found as a duplicate; trunk does not find it either.

  • kses.php is unchanged. Of the 70 non-empty sanitize_font_family() results of the ported sanitizer tests, safecss_filter_attr() on trunk's legacy path keeps 37: it drops every value with a backslash escape (26) and 5 quoted names with (, = or /*. PR 3 keeps 68 with the same decoded entries and drops the 2 values with generic().

Design finding: ' in names

WP_CSS_Builder::string() escapes ', { and }, which PR 13610 writes as they are, and writes " as \22 where PR 13610 writes \". Of 159 inputs (the sanitizer vectors and the font name guide of PR 13610), 24 give a different spelling of the same decoded names; 9 contain an apostrophe. For those 9 the values are 38 bytes longer in total ("O\27 Reilly Sans" against "O'Reilly Sans"), and trunk's legacy safecss_filter_attr() keeps 0 of them where it keeps 5 of PR 13610's. PR 3 keeps all 9 in both spellings. The escape set of WP_CSS_Builder is unchanged here.

CSS API additions

  • 562585d WP_CSS_Token::ends_with_eof_escape(): CSS Syntax 3 decodes a \ at the end of the input to U+FFFD and the identifier token is otherwise complete. PR 13610 reads Inter\ as invalid CSS and keeps the backslash in a plain name; without this method the consumer has to read source bytes to tell that U+FFFD apart.

Keyword tables stay in WP_Font_Utils: the reserved list includes default, which is specific to font-family. preprocess_range() stays private; plain names replace NUL with U+FFFD and reject other control characters, which gives PR 13610's result without it.

Comparison with PR 13610

PR 13610's tests are ported. Tests call public methods instead of ReflectionMethod::setAccessible(), data providers are static, and expected strings use the spelling of WP_CSS_Builder::string(). All pass, with these differences:

  • is_valid_css_font_family() is not added; it has no caller without the kses change. Its tests call parse_font_family_list( $value ) and expect null.
  • test_serialize_name_survives_safecss_filter_attr and test_theme_json_keeps_a_valid_preset are not ported, because they test PR 13610's kses change. With PR 3's safecss_filter_attr() in a standalone harness, 29 of 29 serialized names and 10 of 10 sanitized preset values pass through unchanged; with trunk's legacy path, 15 and 4.
  • The legacy duplicate case "\54 om & Jerry" against "Tom & Jerry" is removed (see the duplicate check above).
  • New tests cover the second reading, an entry of only a comment, names ending in an escaped newline, and 40,000 entries with unterminated comments.

Fuzzing sanitize_font_family() and the strict parser against PR 13610 with the alphabet of the earlier prototype:

Inputs Decoded differences Not idempotent: PR 13610 Not idempotent: this branch
100,000 of 1 to 8 items 0 214 0
100,000 of 1 to 20 items 2 155 0
100,000 of 1 to 12 items, quotes and \, only 3,016 0 0

Every difference comes from the reading limit above; the strict parser agrees on all inputs. Every non-idempotent PR 13610 result is a name ending in an escaped newline.

Time for sanitize_font_family() on PHP 8.5:

Input PR 13610 This branch
/*, repeated, 30 KB 0.28 s 0.008 s
/*, repeated, 120 KB 4.5 s 0.033 s
\, repeated then x(, 30 KB 10.3 s 0.060 s
\, repeated then x(, 120 KB 165 s 0.24 s
A, repeated (valid), 120 KB 0.029 s 0.081 s
"Open Sans", repeated (valid), 120 KB 0.005 s 0.013 s

Known limitations

  • Valid lists take 2.5 to 4 times as long as with PR 13610 (last two rows). parse_comma_separated_list() creates a WP_CSS_Token object for every token, including whitespace.
  • The face slug and duplicate check go beyond the parser; they could be a separate PR.

Depends on WordPress#14781 and #98.

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.

CSS Syntax 3 decodes a `\` at the end of the input to U+FFFD in an
identifier or url, and the identifier token is otherwise complete, so
is_terminated() returns true for it. A consumer that rejects input with
parse errors cannot tell this U+FFFD from a literal one or one decoded
from NUL or `\0` without reading the source bytes.

The font-family parser needs the signal: it reads `Inter\` as invalid
CSS and keeps the backslash as part of a plain name, as WordPress
reads a font name ending in a backslash today.
sanitize_font_family() splits the value at each comma and wraps items
in quotes without escaping, so a name with a comma, an apostrophe, a
quotation mark or a CSS escape changes or breaks:

    "ACME, Sans"     -> "ACME", "Sans"
    O'Reilly Sans    -> "OReilly Sans" in the @font-face descriptor

WP_Font_Utils::parse_font_family_list() reads the value with
WP_CSS_Token_Processor::parse_comma_separated_list() and the
font-family grammar: a string, a sequence of identifiers, a generic
family, generic() with a defined argument, or a CSS-wide keyword
alone. Names are written back with WP_CSS_Builder::string(), except an
ASCII letter-and-hyphen identifier that is not a keyword.

For compatibility, an entry that is not valid CSS is a plain name: its
text up to its first comma is one name, and the rest of the entry is
read again as a list, once; an invalid entry in that second reading
splits at each comma. Re-reading the rest of the whole value after
each failed entry, as WordPress#13610 does, is quadratic: 120 KB of `/*,` takes
4.5 s there and 0.03 s here, and 30 KB of `\,` followed by `x(` takes
10 s there and 0.06 s here.

The @font-face descriptor, the font face resolver, the font collection
schema and the REST controllers use the parser. The face slug uses the
decoded names, and the duplicate check also looks up the title in the
earlier slug format, so faces saved by earlier versions stay
duplicates without reading every face.

Tests are ported from WordPress#13610; expected strings use the escapes of
WP_CSS_Builder::string(), such as `\27 ` for an apostrophe.
@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.

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