Changeset 58925

Timestamp:

08/23/2024 02:53:59 PM (10 months ago)

Author:

dmsnell

Message:

HTML API: Parse DOCTYPE tokens and set HTML parser mode accordingly.

This patch adds until-now missing code to parse the structure of HTML DOCTYPE declarations. The DOCTYPE is mostly unused but can dictate the document compatability mode, which governs whether CSS class names match in a ASCII-case-insensitive way or not, and whether TABLE elements close an open P element.

The DOCTYPE information is made available through a new method on the Tag Processor, get_doctype_info().

Developed in ​https://github.com/wordpress/wordpress-develop/pull/7195
Discussed in https://core.trac.wordpress.org/ticket/61576

Props dmsnell, jonsurrell.
See #61576.

Location:

trunk

Files:

• phpcs.xml.dist (modified) (1 diff)
• src/wp-includes/html-api/class-wp-html-doctype-info.php (added)
• src/wp-includes/html-api/class-wp-html-processor.php (modified) (3 diffs)
• src/wp-includes/html-api/class-wp-html-tag-processor.php (modified) (2 diffs)
• src/wp-settings.php (modified) (1 diff)
• tests/phpunit/tests/html-api/wpHtmlDoctypeInfo.php (added)
• tests/phpunit/tests/html-api/wpHtmlProcessorHtml5lib.php (modified) (5 diffs)
• tests/phpunit/tests/html-api/wpHtmlTagProcessor.php (modified) (1 diff)

trunk/phpcs.xml.dist

@@ -263 +263 @@
     <rule ref="Generic.PHP.DiscourageGoto.Found">
         <exclude-pattern>/wp-includes/html-api/class-wp-html-processor\.php</exclude-pattern>
+        <exclude-pattern>/wp-includes/html-api/class-wp-html-doctype-info\.php</exclude-pattern>
     </rule>
 

trunk/src/wp-includes/html-api/class-wp-html-processor.php

@@ -1077 +1077 @@
              */
             case 'html':
-                $contents = $this->get_modifiable_text();
-                if ( ' html' !== $contents ) {
-                    /*
-                     * @todo When the HTML Tag Processor fully parses the DOCTYPE declaration,
-                     *       this code should examine the contents to set the compatability mode.
-                     */
-                    $this->bail( 'Cannot process any DOCTYPE other than a normative HTML5 doctype.' );
+                $doctype = $this->get_doctype_info();
+                if ( null !== $doctype && 'quirks' === $doctype->indicated_compatability_mode ) {
+                    $this->state->document_mode = WP_HTML_Processor_State::QUIRKS_MODE;
                 }
 
@@ -1090 +1086 @@
                  */
                 $this->state->insertion_mode = WP_HTML_Processor_State::INSERTION_MODE_BEFORE_HTML;
+                $this->insert_html_element( $this->state->current_token );
                 return true;
         }
@@ -1097 +1094 @@
          */
         initial_anything_else:
+        $this->state->document_mode  = WP_HTML_Processor_State::QUIRKS_MODE;
         $this->state->insertion_mode = WP_HTML_Processor_State::INSERTION_MODE_BEFORE_HTML;
         return $this->step( self::REPROCESS_CURRENT_NODE );

trunk/src/wp-includes/html-api/class-wp-html-tag-processor.php

@@ -4028 +4028 @@
 
     /**
+     * Gets DOCTYPE declaration info from a DOCTYPE token.
+     *
+     * DOCTYPE tokens may appear in many places in an HTML document. In most places, they are
+     * simply ignored. The main parsing functions find the basic shape of DOCTYPE tokens but
+     * do not perform detailed parsing.
+     *
+     * This method can be called to perform a full parse of the DOCTYPE token and retrieve
+     * its information.
+     *
+     * @return WP_HTML_Doctype_Info|null The DOCTYPE declaration information or `null` if not
+     *                                   currently at a DOCTYPE node.
+     */
+    public function get_doctype_info(): ?WP_HTML_Doctype_Info {
+        if ( self::STATE_DOCTYPE !== $this->parser_state ) {
+            return null;
+        }
+
+        return WP_HTML_Doctype_Info::from_doctype_token( substr( $this->html, $this->token_starts_at, $this->token_length ) );
+    }
+
+    /**
      * Parser Ready State.
      *
@@ -4118 +4139 @@
     /**
      * Indicates that the parser has found a DOCTYPE node and it's
-     * possible to read and modify its modifiable text.
+     * possible to read its DOCTYPE information via `get_doctype_info()`.
      *
      * @since 6.5.0

trunk/src/wp-settings.php

@@ -253 +253 @@
 require ABSPATH . WPINC . '/html-api/class-wp-html-attribute-token.php';
 require ABSPATH . WPINC . '/html-api/class-wp-html-span.php';
+require ABSPATH . WPINC . '/html-api/class-wp-html-doctype-info.php';
 require ABSPATH . WPINC . '/html-api/class-wp-html-text-replacement.php';
 require ABSPATH . WPINC . '/html-api/class-wp-html-decoder.php';

trunk/tests/phpunit/tests/html-api/wpHtmlProcessorHtml5lib.php

@@ -28 +28 @@
         'comments01/line0155'    => 'Unimplemented: Need to access raw comment text on non-normative comments.',
         'comments01/line0169'    => 'Unimplemented: Need to access raw comment text on non-normative comments.',
+        'doctype01/line0380'     => 'Bug: Mixed whitespace, non-whitespace text in head not split correctly',
         'html5test-com/line0129' => 'Unimplemented: Need to access raw comment text on non-normative comments.',
         'noscript01/line0014'    => 'Unimplemented: This parser does not add missing attributes to existing HTML or BODY tags.',
@@ -116 +117 @@
                 $test_context_element = $test[1];
 
-                if ( self::should_skip_test( $test_context_element, $test_name, $test[3] ) ) {
+                if ( self::should_skip_test( $test_context_element, $test_name ) ) {
                     continue;
                 }
@@ -134 +135 @@
      * @return bool True if the test case should be skipped. False otherwise.
      */
-    private static function should_skip_test( ?string $test_context_element, string $test_name, string $expected_tree ): bool {
+    private static function should_skip_test( ?string $test_context_element, string $test_name ): bool {
         if ( null !== $test_context_element && 'body' !== $test_context_element ) {
             return true;
@@ -190 +191 @@
 
             switch ( $token_type ) {
+                case '#doctype':
+                    $doctype = $processor->get_doctype_info();
+                    $output .= "<!DOCTYPE {$doctype->name}";
+                    if ( null !== $doctype->public_identifier || null !== $doctype->system_identifier ) {
+                        $output .= " \"{$doctype->public_identifier}\" \"{$doctype->system_identifier}\"";
+                    }
+                    $output .= ">\n";
+                    break;
+
                 case '#tag':
                     $namespace = $processor->get_namespace();
@@ -451 +461 @@
                 case 'document':
                     if ( '|' === $line[0] ) {
-                        /*
-                         * The next_token() method these tests rely on do not stop
-                         * at doctype nodes. Strip doctypes from output.
-                         * @todo Restore this line if and when the processor
-                         * exposes doctypes.
-                         */
-                        if ( '| <!DOCTYPE ' !== substr( $line, 0, 12 ) ) {
-                            $test_dom .= substr( $line, 2 );
-                        }
+                        $test_dom .= substr( $line, 2 );
                     } else {
                         // This is a text node that includes unescaped newlines.

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

@@ -2940 +2940 @@
         $this->assertTrue( $processor->paused_at_incomplete_token() );
     }
+
+    /**
+     * Test basic DOCTYPE handling.
+     *
+     * @ticket 61576
+     */
+    public function test_doctype_doc_name() {
+        $processor = new WP_HTML_Tag_Processor( '<!DOCTYPE html>' );
+        $this->assertTrue( $processor->next_token() );
+        $doctype = $processor->get_doctype_info();
+        $this->assertNotNull( $doctype );
+        $this->assertSame( 'html', $doctype->name );
+        $this->assertSame( 'no-quirks', $doctype->indicated_compatability_mode );
+        $this->assertNull( $doctype->public_identifier );
+        $this->assertNull( $doctype->system_identifier );
+    }
 }