Add class whitespace doc#37
Conversation
Note that the `class_name` argument to `WP_HTML_Tag_Processor::add_class()` and `WP_HTML_Processor::add_class()` is inserted verbatim into the `class` attribute, which is a whitespace-separated token list. Whitespace in the value therefore adds multiple classes; a single class whose name contains whitespace cannot be expressed.
Drop the inline enumeration of HTML ASCII whitespace code points and shorten the explanation; keep the worked single- and multi-class examples.
Identify the term and list the characters (tab, line feed, form feed, carriage return, space) so readers know exactly what splits a value into multiple class names.
Replace the paraphrased whitespace list with a blockquote of the Infra Standard definition and add a `@see` link to the source.
Adopt the simpler note on the Tag Processor and mirror it on the HTML Processor so both `add_class()` docblocks read the same.
Rewrite the lead sentence so it parses on one read, and restore the explicit "not one class" cue on the multi-class example so the docblock directly contradicts the natural misreading.
State directly that the value is added verbatim and may yield multiple class names in the element's class list — "may" because trailing or leading whitespace alone still produces a single class.
The body prose already names ASCII whitespace and explains the multi-class effect, so the `@see` link and expanded `@param` description are redundant. Restore the original `@param` text.
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
This comment was marked as off-topic.
This comment was marked as off-topic.
Sorry, something went wrong.
…e value. The class name itself is HTML-escaped when written into the attribute; only the whitespace passes through unchanged, which is what splits the value into multiple class names.
…ace.
A class name cannot contain whitespace; the HTML class attribute is a
whitespace-separated token list. Pass-through whitespace in the
`$wanted_class` / `$class_name` argument can therefore never match a
real token, so reject it up front and return false. Document the new
behavior in both the Tag Processor and HTML Processor docblocks.
Behavior note: previously, `add_class('a b')` followed by
`remove_class('a b')` was an accidental no-op because the REMOVE
overwrote the ADD in the keyed updates map. With the short-circuit the
REMOVE is rejected and the ADD survives, so the element gets classes
"a" and "b" as the lone `add_class()` call would have produced.
The short-circuit is purely a performance refinement of an already guaranteed result (no token can contain whitespace), not a meaningful behavior change worth versioning. Keep the inline docblock note.
Add a `_doing_it_wrong()` call on the whitespace short-circuit in `has_class()` and `remove_class()` so developers passing a value that can never identify a class token see an actionable warning rather than a silent false.
… docblocks. The `_doing_it_wrong()` warning now communicates the constraint at the point of misuse, so the docblock note is redundant.
| * Removes a class name from the currently matched tag. | ||
| * | ||
| * @since 6.6.0 Subclassed for the HTML Processor. | ||
| * @since 7.1.0 Returns false when `$class_name` contains ASCII whitespace. |
There was a problem hiding this comment.
is this new in 7.1.0? I don’t see any change in behavior that would make it start returning false now
| * | ||
| * $p->add_class( 'wp-block alignwide' ); | ||
| * // Adds two classes: "wp-block" and "alignwide". | ||
| * |
There was a problem hiding this comment.
what if we started calling _doing_it_wrong() here and tried to push code away, so that some day we can reject multiple class name updates?
| * Adds a new class name to the currently matched tag. | ||
| * | ||
| * Whitespace in `$class_name` is preserved verbatim. This may result | ||
| * in multiple class names being added to the element's class list. |
There was a problem hiding this comment.
another thought is that maybe we should not preserve this, and especially not declare that we are preserving it. a problem here is adding duplicate class names.
I’d really like the interface to be raw PHP strings that aren’t decoded, added as a class name with appropriate encoding.
we can trivially add add_classes( ...$class_names ) or even extend add_class() to support varargs.
as a stepping stone, maybe we break on appropriate whitespace just to we can deduplicate tags.
There was a problem hiding this comment.
this is a good opportunity to use my PHP extension in normal cases to explore what happens if someone sends a value like add_class( '—experimental' ) and then flag it. that should be sent as —experimental otherwise it would/should be encoded as &\; mdash\; experimental or something like that
There was a problem hiding this comment.
I believe I saw something adding multiple class names this way, which prompted my investigation. I'd have to dig around.
2 participants
Trac ticket:
Use of AI Tools
This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See GitHub Pull Requests for Code Review in the Core Handbook for more details.