Changeset 61323

Timestamp:

11/30/2025 12:54:26 AM (10 months ago)

Author:

westonruter

Message:

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

Developed in ​https://github.com/WordPress/wordpress-develop/pull/10545

Follow-up to [60999].

Props deepakprajapati, westonruter.
See #63486.
Fixes #64229.

Location:

trunk

Files:

• 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)

trunk/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 7.0.0
+         * @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 ),
+                                                '7.0.0'
+                                        );
+                                        $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 7.0.0
+         *
+         * @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: Comma-separated list of missing dependency handles. */
+                        __( 'The handle "%1$s" was enqueued with dependencies that are not registered: %2$s.' ),
+                        $handle,
+                        implode( ', ', $missing_dependency_handles )
+                );
+        }
 }

trunk/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 7.0.0
+         * @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: Comma-separated 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( ', ', $missing_dependencies )
+                                        ),
+                                        '7.0.0'
+                                );
+                                $this->modules_with_missing_dependencies[] = $id;
+                        }
+
                         return false;
                 }

trunk/src/wp-includes/class-wp-scripts.php

@@ -1165 +1165 @@
                 $this->ext_handles    = '';
         }
+
+        /**
+         * Gets a script-specific dependency warning message.
+         *
+         * @since 7.0.0
+         *
+         * @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: Comma-separated list of missing dependency handles. */
+                        __( 'The script with the handle "%1$s" was enqueued with dependencies that are not registered: %2$s.' ),
+                        $handle,
+                        implode( ', ', $missing_dependency_handles )
+                );
+        }
 }

trunk/src/wp-includes/class-wp-styles.php

@@ -494 +494 @@
                 $this->print_html     = '';
         }
+
+        /**
+         * Gets a style-specific dependency warning message.
+         *
+         * @since 7.0.0
+         *
+         * @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: Comma-separated list of missing dependency handles. */
+                        __( 'The style with the handle "%1$s" was enqueued with dependencies that are not registered: %2$s.' ),
+                        $handle,
+                        implode( ', ', $missing_dependency_handles )
+                );
+        }
 }

trunk/tests/phpunit/tests/dependencies/scripts.php

@@ -4094 +4094 @@
                 $this->assertStringNotContainsStringIgnoringCase( 'sourceURL=', $translations_script_data );
         }
+
+        /**
+         * 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.'
+                );
+        }
 }

trunk/tests/phpunit/tests/dependencies/styles.php

@@ -815 +815 @@
                 $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.'
+                );
+        }
 }

trunk/tests/phpunit/tests/script-modules/wpScriptModules.php

@@ -2060 +2060 @@
                 );
 
-                $deregister( array( 'b', 'c ' ) );
+                $deregister( array( 'b', 'c' ) );
 
                 // Test that registered dependency in footer doesn't place dependant in footer.
@@ -2313 +2313 @@
                 );
         }
+
+        /**
+         * 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 ]
+                );
+        }
 }