Changeset 61550

Timestamp:

01/28/2026 09:28:06 PM (6 weeks ago)

Author:

jorbin

Message:

Script Loader: Emit notices when enqueueing a script, style, or script module with missing dependencies.

First Developed in ​https://github.com/WordPress/wordpress-develop/pull/10545. Backport developed in ​https://github.com/WordPress/wordpress-develop/pull/10789.

Follow-up to [60999].

Reviewed by jorbin, wildworks.
Merges [61323], [61357], and [61542].

Props deepakprajapati, westonruter, mukeshpanchal27, jorbin, wildworks.
See #63486.
Fixes #64229.

Location:

branches/6.9

Files:

• . (modified) (1 prop)
• src/wp-includes/class-wp-dependencies.php (modified) (3 diffs)
• src/wp-includes/class-wp-script-modules.php (modified) (2 diffs)
• src/wp-includes/class-wp-scripts.php (modified) (1 diff)
• src/wp-includes/class-wp-styles.php (modified) (1 diff)
• tests/phpunit/tests/dependencies/scripts.php (modified) (1 diff)
• tests/phpunit/tests/dependencies/styles.php (modified) (1 diff)
• tests/phpunit/tests/script-modules/wpScriptModules.php (modified) (2 diffs)

branches/6.9/src/wp-includes/class-wp-dependencies.php

@@ -104 +104 @@
      */
     private $queued_before_register = array();
+
+    /**
+     * List of handles for dependencies encountered which themselves have missing dependencies.
+     *
+     * A dependency handle is added to this list when it is discovered to have missing dependencies. At this time, a
+     * warning is emitted with {@see _doing_it_wrong()}. The handle is then added to this list, so that duplicate
+     * warnings don't occur.
+     *
+     * @since 6.9.1
+     * @var string[]
+     */
+    private $dependencies_with_missing_dependencies = array();
 
     /**
@@ -200 +212 @@
             }
 
-            $keep_going = true;
+            $keep_going           = true;
+            $missing_dependencies = array();
+            if ( isset( $this->registered[ $handle ] ) && count( $this->registered[ $handle ]->deps ) > 0 ) {
+                $missing_dependencies = array_diff( $this->registered[ $handle ]->deps, array_keys( $this->registered ) );
+            }
             if ( ! isset( $this->registered[ $handle ] ) ) {
                 $keep_going = false; // Item doesn't exist.
-            } elseif ( $this->registered[ $handle ]->deps && array_diff( $this->registered[ $handle ]->deps, array_keys( $this->registered ) ) ) {
+            } elseif ( count( $missing_dependencies ) > 0 ) {
+                if ( ! in_array( $handle, $this->dependencies_with_missing_dependencies, true ) ) {
+                    _doing_it_wrong(
+                        get_class( $this ) . '::add',
+                        $this->get_dependency_warning_message( $handle, $missing_dependencies ),
+                        '6.9.1'
+                    );
+                    $this->dependencies_with_missing_dependencies[] = $handle;
+                }
                 $keep_going = false; // Item requires dependencies that don't exist.
             } elseif ( $this->registered[ $handle ]->deps && ! $this->all_deps( $this->registered[ $handle ]->deps, true, $new_group ) ) {
@@ -536 +560 @@
         return 'W/"' . md5( $etag ) . '"';
     }
+
+    /**
+     * Gets a dependency warning message for a handle.
+     *
+     * @since 6.9.1
+     *
+     * @param string   $handle                     Handle with missing dependencies.
+     * @param string[] $missing_dependency_handles Missing dependency handles.
+     * @return string Formatted, localized warning message.
+     */
+    protected function get_dependency_warning_message( $handle, $missing_dependency_handles ) {
+        return sprintf(
+            /* translators: 1: Handle, 2: List of missing dependency handles. */
+            __( 'The handle "%1$s" was enqueued with dependencies that are not registered: %2$s.' ),
+            $handle,
+            implode( wp_get_list_item_separator(), $missing_dependency_handles )
+        );
+    }
 }

branches/6.9/src/wp-includes/class-wp-script-modules.php

@@ -70 +70 @@
         'high',
     );
+
+    /**
+     * List of IDs for script modules encountered which have missing dependencies.
+     *
+     * An ID is added to this list when it is discovered to have missing dependencies. At this time, a warning is
+     * emitted with {@see _doing_it_wrong()}. The ID is then added to this list, so that duplicate warnings don't occur.
+     *
+     * @since 6.9.1
+     * @var string[]
+     */
+    private $modules_with_missing_dependencies = array();
 
     /**
@@ -723 +734 @@
 
         // If the item requires dependencies that do not exist, fail.
-        if ( count( array_diff( $dependency_ids, array_keys( $this->registered ) ) ) > 0 ) {
+        $missing_dependencies = array_diff( $dependency_ids, array_keys( $this->registered ) );
+        if ( count( $missing_dependencies ) > 0 ) {
+            if ( ! in_array( $id, $this->modules_with_missing_dependencies, true ) ) {
+                _doing_it_wrong(
+                    get_class( $this ) . '::register',
+                    sprintf(
+                        /* translators: 1: Script module ID, 2: List of missing dependency IDs. */
+                        __( 'The script module with the ID "%1$s" was enqueued with dependencies that are not registered: %2$s.' ),
+                        $id,
+                        implode( wp_get_list_item_separator(), $missing_dependencies )
+                    ),
+                    '6.9.1'
+                );
+                $this->modules_with_missing_dependencies[] = $id;
+            }
+
             return false;
         }

branches/6.9/src/wp-includes/class-wp-scripts.php

@@ -1165 +1165 @@
         $this->ext_handles    = '';
     }
+
+    /**
+     * Gets a script-specific dependency warning message.
+     *
+     * @since 6.9.1
+     *
+     * @param string   $handle                     Script handle with missing dependencies.
+     * @param string[] $missing_dependency_handles Missing dependency handles.
+     * @return string Formatted, localized warning message.
+     */
+    protected function get_dependency_warning_message( $handle, $missing_dependency_handles ) {
+        return sprintf(
+            /* translators: 1: Script handle, 2: List of missing dependency handles. */
+            __( 'The script with the handle "%1$s" was enqueued with dependencies that are not registered: %2$s.' ),
+            $handle,
+            implode( wp_get_list_item_separator(), $missing_dependency_handles )
+        );
+    }
 }

branches/6.9/src/wp-includes/class-wp-styles.php

@@ -494 +494 @@
         $this->print_html     = '';
     }
+
+    /**
+     * Gets a style-specific dependency warning message.
+     *
+     * @since 6.9.1
+     *
+     * @param string   $handle                     Style handle with missing dependencies.
+     * @param string[] $missing_dependency_handles Missing dependency handles.
+     * @return string Formatted, localized warning message.
+     */
+    protected function get_dependency_warning_message( $handle, $missing_dependency_handles ) {
+        return sprintf(
+            /* translators: 1: Style handle, 2: List of missing dependency handles. */
+            __( 'The style with the handle "%1$s" was enqueued with dependencies that are not registered: %2$s.' ),
+            $handle,
+            implode( wp_get_list_item_separator(), $missing_dependency_handles )
+        );
+    }
 }

branches/6.9/tests/phpunit/tests/dependencies/scripts.php

@@ -4133 +4133 @@
         return $processor->get_updated_html();
     }
+
+    /**
+     * Tests that WP_Scripts emits a _doing_it_wrong() notice for missing dependencies.
+     *
+     * @ticket 64229
+     * @covers WP_Dependencies::all_deps
+     */
+    public function test_wp_scripts_doing_it_wrong_for_missing_dependencies() {
+        $expected_incorrect_usage = 'WP_Scripts::add';
+        $this->setExpectedIncorrectUsage( $expected_incorrect_usage );
+
+        wp_register_script( 'registered-dep', '/registered-dep.js' );
+        wp_enqueue_script( 'main', '/main.js', array( 'registered-dep', 'missing-dep' ) );
+
+        $markup = get_echo( 'wp_print_scripts' );
+        $this->assertStringNotContainsString( 'main.js', $markup, 'Expected script to be absent.' );
+
+        $this->assertArrayHasKey(
+            $expected_incorrect_usage,
+            $this->caught_doing_it_wrong,
+            "Expected $expected_incorrect_usage to trigger a _doing_it_wrong() notice for missing dependency."
+        );
+
+        $this->assertStringContainsString(
+            'The script with the handle "main" was enqueued with dependencies that are not registered: missing-dep',
+            $this->caught_doing_it_wrong[ $expected_incorrect_usage ],
+            'Expected _doing_it_wrong() notice to indicate missing dependencies for enqueued script.'
+        );
+    }
 }

branches/6.9/tests/phpunit/tests/dependencies/styles.php

@@ -816 +816 @@
         $this->assertEqualHTML( $expected, $printed );
     }
+
+    /**
+     * Tests that WP_Styles emits a _doing_it_wrong() notice for missing dependencies.
+     *
+     * @ticket 64229
+     * @covers WP_Dependencies::all_deps
+     */
+    public function test_wp_style_doing_it_wrong_for_missing_dependencies() {
+        $expected_incorrect_usage = 'WP_Styles::add';
+        $this->setExpectedIncorrectUsage( $expected_incorrect_usage );
+
+        wp_enqueue_style(
+            'main-style',
+            '/main-style.css',
+            array( 'missing-style-dep' )
+        );
+
+        $markup = get_echo( 'wp_print_styles' );
+        $this->assertStringNotContainsString( 'main-style.css', $markup, 'Expected style to be absent.' );
+
+        $this->assertArrayHasKey(
+            $expected_incorrect_usage,
+            $this->caught_doing_it_wrong,
+            "Expected $expected_incorrect_usage to trigger a _doing_it_wrong() notice for missing dependency."
+        );
+
+        $this->assertStringContainsString(
+            'The style with the handle "main-style" was enqueued with dependencies that are not registered: missing-style-dep',
+            $this->caught_doing_it_wrong[ $expected_incorrect_usage ],
+            'Expected _doing_it_wrong() notice to indicate missing dependencies for enqueued styles.'
+        );
+    }
 }

branches/6.9/tests/phpunit/tests/script-modules/wpScriptModules.php

@@ -2107 +2107 @@
         );
 
-        $deregister( array( 'b', 'c ' ) );
+        $deregister( array( 'b', 'c' ) );
 
         // Test that registered dependency in footer doesn't place dependant in footer.
@@ -2356 +2356 @@
         );
     }
+
+    /**
+     * Tests that a missing script module dependency triggers a _doing_it_wrong() notice.
+     *
+     * @ticket 64229
+     * @covers WP_Script_Modules::sort_item_dependencies
+     */
+    public function test_missing_script_module_dependency_triggers_incorrect_usage() {
+        $expected_incorrect_usage = 'WP_Script_Modules::register';
+        $this->setExpectedIncorrectUsage( $expected_incorrect_usage );
+
+        $this->script_modules->enqueue( 'main-module', '/main-module.js', array( 'missing-mod-dep' ) );
+
+        $markup = get_echo( array( $this->script_modules, 'print_enqueued_script_modules' ) );
+        $this->assertStringNotContainsString( 'main-module.js', $markup, 'Expected script module to be absent.' );
+
+        $this->assertArrayHasKey(
+            $expected_incorrect_usage,
+            $this->caught_doing_it_wrong,
+            'Expected WP_Script_Modules::register to be reported via doing_it_wrong().'
+        );
+
+        // Assert the message mentions the missing dependency handle.
+        $this->assertStringContainsString(
+            'The script module with the ID "main-module" was enqueued with dependencies that are not registered: missing-mod-dep',
+            $this->caught_doing_it_wrong[ $expected_incorrect_usage ]
+        );
+    }
 }