HTML API: Add class name utilities has_class() and class_list()

[dmsnell]

This patch adds two new public methods to the HTML Tag Processor:

• has_class() indicates if a matched tag contains a given CSS class name.
• class_list() returns a generator to iterate over all the class names in a matched tag.

Included in this patch is a refactoring of the internal logic when matching a tag to reuse the new has_class() function. Previously it was relying on optimized code in the matches() function which performed byte-for-byte class name comparison. With the change in this patch it will perform class name matching on the decoded value, which might differ if a class attribute contains character references.

These methods may be useful for running more complicated queries based on the presence or absence of CSS class names. The use of these methods avoids the need to manually decode the class attribute as reported by $process->get_attribute( 'class' ).

Trac ticket: #59209

This patch adds two new public methods to the HTML Tag Processor:

• has_class() indicates if a matched tag contains a given CSS class name.
• class_list() returns a generator to iterate over all the class names in a matched tag.

Included in this patch is a refactoring of the internal logic when matching a tag to reuse the new has_class() function. Previously it was relying on optimized code in the matches() function which performed byte-for-byte class name comparison. With the change in this patch it will perform class name matching on the decoded value, which might differ if a class attribute contains character references.

These methods may be useful for running more complicated queries based on the presence or absence of CSS class names. The use of these methods avoids the need to manually decode the class attribute as reported by $process->get_attribute( 'class' ).

Unit tests are currently ​failing with what seems to be related to this change.

<details>

1) Tests_Blocks_Render::test_do_block_output with data set #9 ('core__columns.html', 'core__columns.server.html')
File '/var/www/tests/phpunit/includes/../data/blocks/fixtures/core__columns.html' does not match expected value
Failed asserting that two strings are identical.
--- Expected
+++ Actual
@@ @@
 '
-<div class="wp-block-columns has-3-columns is-layout-flex wp-container-1 wp-block-columns-is-layout-flex">
+<div class="wp-block-columns has-3-columns">
 	<div class="wp-block-column is-layout-flow wp-block-column-is-layout-flow">
 		<p>Column One, Paragraph One</p>
 		<p>Column One, Paragraph Two</p>

/var/www/tests/phpunit/tests/blocks/render.php:237
phpvfscomposer:///var/www/vendor/phpunit/phpunit/phpunit:106
/var/www/vendor/bin/phpunit:118

2) Tests_Blocks_Render::test_do_block_output with data set #10 ('core__columns__deprecated.html', 'core__columns__deprecated.server.html')
File '/var/www/tests/phpunit/includes/../data/blocks/fixtures/core__columns__deprecated.html' does not match expected value
Failed asserting that two strings are identical.
--- Expected
+++ Actual
@@ @@
 '
-<div class="wp-block-columns has-3-columns is-layout-flex wp-container-1 wp-block-columns-is-layout-flex">
+<div class="wp-block-columns has-3-columns">
 	<p class="layout-column-1">Column One, Paragraph One</p>
 	<p class="layout-column-1">Column One, Paragraph Two</p>
 	<p class="layout-column-2">Column Two, Paragraph One</p>
 	<p class="layout-column-3">Column Three, Paragraph One</p>
 </div>'

/var/www/tests/phpunit/tests/blocks/render.php:237
phpvfscomposer:///var/www/vendor/phpunit/phpunit/phpunit:106
/var/www/vendor/bin/phpunit:118

3) Tests_Blocks_Render::test_do_block_output with data set #21 ('core__gallery-with-caption.html', 'core__gallery-with-caption.server.html')
File '/var/www/tests/phpunit/includes/../data/blocks/fixtures/core__gallery-with-caption.html' does not match expected value
Failed asserting that two strings are identical.
--- Expected
+++ Actual
@@ @@
 '
 <figure
-	class="wp-block-gallery has-nested-images columns-default is-cropped columns-2 wp-block-gallery-1 is-layout-flex wp-block-gallery-is-layout-flex"
+	class="wp-block-gallery has-nested-images columns-default is-cropped columns-2 wp-block-gallery-1"
 >
 	<figure class="wp-block-image size-large">
 		<img data-id="1421"

/var/www/tests/phpunit/tests/blocks/render.php:237
phpvfscomposer:///var/www/vendor/phpunit/phpunit/phpunit:106
/var/www/vendor/bin/phpunit:118

4) Tests_Blocks_Render::test_do_block_output with data set #22 ('core__gallery.html', 'core__gallery.server.html')
File '/var/www/tests/phpunit/includes/../data/blocks/fixtures/core__gallery.html' does not match expected value
Failed asserting that two strings are identical.
--- Expected
+++ Actual
@@ @@
 '
 <figure
-	class="wp-block-gallery has-nested-images columns-default is-cropped columns-2 wp-block-gallery-1 is-layout-flex wp-block-gallery-is-layout-flex"
+	class="wp-block-gallery has-nested-images columns-default is-cropped columns-2 wp-block-gallery-1"
 >
 	<figure class="wp-block-image size-large">
 		<img data-id="1421"

/var/www/tests/phpunit/tests/blocks/render.php:237
phpvfscomposer:///var/www/vendor/phpunit/phpunit/phpunit:106
/var/www/vendor/bin/phpunit:118

5) Tests_Blocks_Render::test_do_block_output with data set #23 ('core__gallery__columns.html', 'core__gallery__columns.server.html')
File '/var/www/tests/phpunit/includes/../data/blocks/fixtures/core__gallery__columns.html' does not match expected value
Failed asserting that two strings are identical.
--- Expected
+++ Actual
@@ @@
 '
-<figure class="wp-block-gallery has-nested-images columns-1 is-cropped wp-block-gallery-1 is-layout-flex wp-block-gallery-is-layout-flex">
+<figure class="wp-block-gallery has-nested-images columns-1 is-cropped wp-block-gallery-1">
 	<figure class="wp-block-image size-large">
 		[[Image(https://i0.wp.com/sergioestevaofolio.files.wordpress.com/2016/09/cropped-img_9054-1.jpg?w=190)]]
+<figure class="wp-block-gallery has-nested-images columns-default is-cropped wp-block-gallery-1">
 		<figure class="wp-block-image size-large"><a href="http://wptest.local/wp-content/uploads/2020/09/test-image-edited-1-[https://github.com/WordPress/wordpress-develop/actions/runs/5982522041/job/16231701670?pr=5096#step:14:683 682]x1024.jpg">[[Image(https://i0.wp.com/wptest.local/wp-content/uploads/2020/09/test-image-edited-1-682x1024.jpg)]]</a></figure>
 		<figure class="wp-block-image size-large"><a href="http://wptest.local/wp-content/uploads/2020/09/test-image-edited-1024x682.jpg">[[Image(https://i0.wp.com/wptest.local/wp-content/uploads/2020/09/test-image-edited-1024x682.jpg)]]</a></figure>
 		<figure class="wp-block-image size-large"><a href="http://wptest.local/wp-content/uploads/2020/04/test-image-1024x[https://github.com/WordPress/wordpress-develop/actions/runs/5982522041/job/16231701670?pr=5096#step:14:684 683].jpg">[[Image(https://i0.wp.com/wptest.local/wp-content/uploads/2020/04/test-image-1024x683.jpg)]]</a></figure>
 </figure>
-<figure class="wp-block-gallery has-nested-images columns-default is-cropped wp-block-gallery-1 is-layout-flex wp-block-gallery-is-layout-flex">
+<figure class="wp-block-gallery has-nested-images columns-default is-cropped wp-block-gallery-1">
 	<figure class="wp-block-image size-large"><a href="http://wptest.local/wp-content/uploads/2020/09/test-image-edited-1-682x1024.jpg">[[Image(https://i0.wp.com/wptest.local/wp-content/uploads/2020/09/test-image-edited-1-682x1024.jpg)]]</a></figure>
 	<figure class="wp-block-image size-large"><a href="http://wptest.local/wp-content/uploads/2020/09/test-image-edited-1024x682.jpg">[[Image(https://i0.wp.com/wptest.local/wp-content/uploads/2020/09/test-image-edited-1024x682.jpg)]]</a></figure>
 	<figure class="wp-block-image size-large"><a href="http://wptest.local/wp-content/uploads/2020/04/test-image-1024x683.jpg">[[Image(https://i0.wp.com/wptest.local/wp-content/uploads/2020/04/test-image-1024x683.jpg)]]</a></figure>
 	<figcaption class="blocks-gallery-caption">This gallery has a caption</figcaption>
 </figure>'

/var/www/tests/phpunit/tests/blocks/render.php:237
phpvfscomposer:///var/www/vendor/phpunit/phpunit/phpunit:106
/var/www/vendor/bin/phpunit:118

</details>

@ockham I saw those errors but assumed they were unrelated. I'm running them again rebased against an updated trunk and will investigate further if they still fail

@ockham quick update: I found some code calling the Tag Processor to search by class name, but it was searching for the whole class attribute including multiple class names. this is something we ran into early on in the adoption: the expectation that add_class (singular) works with classes (plural).

so what broke is that when _improving_ the class_name query parameter to focus on actual class names, it broke code that relied on doing a full byte-for-byte comparison of the value. not only did it perform byte-for-byte comparison before, but it wasn't breaking apart the sought-after class, so whitespace inside that should be splitting class names was treated as one big class name.

I believe we want to maintain the new behavior as it's going to be a faulty endeavor to search by class name with multiple classes. simple reordering of class names will break that. I'm going to update the code that depends on this behavior.

@ockham with the merge of #5252 I think this one is also ready to go

Unit tests are currently ​failing with what seems to be related to this change.

oh darn I missed this, and I won't be able to address it before you're active. I'll try and prioritize it tomorrow and see if it's something small

tests seem to be passing now after my last update.

I was curious if class_list() would pick up classes added via add_class() (which are only flushed into the class attribute when class_name_updates_to_attributes_updates() is run), remembering ​this problem we had in a similar scenario with attributes.

Fortunately, it seems to work:

tests/phpunit/tests/html-api/wpHtmlTagProcessor.php

@@ -2070 +2070 @@
                $this->assertSame( array( 'one' ), $found_classes, 'Visited multiple copies of the same class name when it should have skipped the duplicates.' );
        }
 
+       public function test_class_list_finds_unflushed_class_names() {
+               $p = new WP_HTML_Tag_Processor( '<div class="one">' );
+               $p->next_tag();
+
+               $p->add_class( 'two' );
+
+               $found_classes = array();
+               foreach ( $p->class_list() as $class ) {
+                       $found_classes[] = $class;
+               }
+               $this->assertSame( array( 'one', 'two' ), $found_classes, 'Failed to report class names added via add_class.' );
+       }
+
+
        /**
         * @ticket 59209
         *

I won't add this test for now, but we might want to consider adding a bit of coverage in a follow-up for how changes made by add_class and remove_class are picked up by class_list and has_class.

[Bernhard Reiter]

In 56703:

HTML API: Add class name utilities has_class() and class_list().

This patch adds two new public methods to the HTML Tag Processor:

• has_class() indicates if a matched tag contains a given CSS class name.
• class_list() returns a generator to iterate over all the class names in a matched tag.

Included in this patch is a refactoring of the internal logic when matching
a tag to reuse the new has_class() function. Previously it was relying on
optimized code in the matches() function which performed byte-for-byte
class name comparison. With the change in this patch it will perform class
name matching on the decoded value, which might differ if a class attribute
contains character references.

These methods may be useful for running more complicated queries based
on the presence or absence of CSS class names. The use of these methods
avoids the need to manually decode the class attribute as reported by
$process->get_attribute( 'class' ).

Props dmsnell.
Fixes #59209.

Committed to Core in https://core.trac.wordpress.org/changeset/56703.

Fortunately, it seems to work:

this is the OO principle of delegation at work here. by the way, I had the same thought and double-checked at some point early on. as long as don't reach into our own internals _inside our internals_ then all these invariants should remain in place.

good thinking for double-checking this.