diff -r 7b1b88e27a20 -r 48c4eec2b7e6 wp/wp-includes/functions.wp-scripts.php --- a/wp/wp-includes/functions.wp-scripts.php Thu Sep 29 08:06:27 2022 +0200 +++ b/wp/wp-includes/functions.wp-scripts.php Fri Sep 05 18:40:08 2025 +0200 @@ -9,12 +9,12 @@ */ /** - * Initialize $wp_scripts if it has not been set. + * Initializes $wp_scripts if it has not been set. + * + * @since 4.2.0 * * @global WP_Scripts $wp_scripts * - * @since 4.2.0 - * * @return WP_Scripts WP_Scripts instance. */ function wp_scripts() { @@ -34,11 +34,11 @@ * @since 4.2.0 * @since 5.5.0 Added the `$handle` parameter. * - * @param string $function Function name. - * @param string $handle Optional. Name of the script or stylesheet that was - * registered or enqueued too early. Default empty. + * @param string $function_name Function name. + * @param string $handle Optional. Name of the script or stylesheet that was + * registered or enqueued too early. Default empty. */ -function _wp_scripts_maybe_doing_it_wrong( $function, $handle = '' ) { +function _wp_scripts_maybe_doing_it_wrong( $function_name, $handle = '' ) { if ( did_action( 'init' ) || did_action( 'wp_enqueue_scripts' ) || did_action( 'admin_enqueue_scripts' ) || did_action( 'login_enqueue_scripts' ) ) { @@ -62,7 +62,7 @@ } _doing_it_wrong( - $function, + $function_name, $message, '3.3.0' ); @@ -73,15 +73,15 @@ * * Called by admin-header.php and {@see 'wp_head'} hook. Since it is called by wp_head on every page load, * the function does not instantiate the WP_Scripts object unless script names are explicitly passed. - * Makes use of already-instantiated $wp_scripts global if present. Use provided {@see 'wp_print_scripts'} + * Makes use of already-instantiated `$wp_scripts` global if present. Use provided {@see 'wp_print_scripts'} * hook to register/enqueue new scripts. * * @see WP_Scripts::do_item() + * @since 2.1.0 + * * @global WP_Scripts $wp_scripts The WP_Scripts object for printing scripts. * - * @since 2.1.0 - * - * @param string|bool|array $handles Optional. Scripts to be printed. Default 'false'. + * @param string|string[]|false $handles Optional. Scripts to be printed. Default 'false'. * @return string[] On success, an array of handles of processed WP_Dependencies items; otherwise, an empty array. */ function wp_print_scripts( $handles = false ) { @@ -113,8 +113,8 @@ * Adds extra code to a registered script. * * Code will only be added if the script is already in the queue. - * Accepts a string $data containing the Code. If two or more code blocks - * are added to the same script $handle, they will be printed in the order + * Accepts a string `$data` containing the code. If two or more code blocks + * are added to the same script `$handle`, they will be printed in the order * they were added, i.e. the latter added code can redeclare the previous. * * @since 4.5.0 @@ -148,7 +148,7 @@ } /** - * Register a new script. + * Registers a new script. * * Registers a script to be enqueued later using the wp_enqueue_script() function. * @@ -157,40 +157,53 @@ * * @since 2.1.0 * @since 4.3.0 A return value was added. + * @since 6.3.0 The $in_footer parameter of type boolean was overloaded to be an $args parameter of type array. * * @param string $handle Name of the script. Should be unique. - * @param string|bool $src Full URL of the script, or path of the script relative to the WordPress root directory. + * @param string|false $src Full URL of the script, or path of the script relative to the WordPress root directory. * If source is set to false, script is an alias of other scripts it depends on. * @param string[] $deps Optional. An array of registered script handles this script depends on. Default empty array. * @param string|bool|null $ver Optional. String specifying script version number, if it has one, which is added to the URL * as a query string for cache busting purposes. If version is set to false, a version * number is automatically added equal to current installed WordPress version. * If set to null, no version is added. - * @param bool $in_footer Optional. Whether to enqueue the script before `` instead of in the ``. - * Default 'false'. + * @param array|bool $args { + * Optional. An array of additional script loading strategies. Default empty array. + * Otherwise, it may be a boolean in which case it determines whether the script is printed in the footer. Default false. + * + * @type string $strategy Optional. If provided, may be either 'defer' or 'async'. + * @type bool $in_footer Optional. Whether to print the script in the footer. Default 'false'. + * } * @return bool Whether the script has been registered. True on success, false on failure. */ -function wp_register_script( $handle, $src, $deps = array(), $ver = false, $in_footer = false ) { +function wp_register_script( $handle, $src, $deps = array(), $ver = false, $args = array() ) { + if ( ! is_array( $args ) ) { + $args = array( + 'in_footer' => (bool) $args, + ); + } _wp_scripts_maybe_doing_it_wrong( __FUNCTION__, $handle ); $wp_scripts = wp_scripts(); $registered = $wp_scripts->add( $handle, $src, $deps, $ver ); - if ( $in_footer ) { + if ( ! empty( $args['in_footer'] ) ) { $wp_scripts->add_data( $handle, 'group', 1 ); } - + if ( ! empty( $args['strategy'] ) ) { + $wp_scripts->add_data( $handle, 'strategy', $args['strategy'] ); + } return $registered; } /** - * Localize a script. + * Localizes a script. * * Works only if the script has already been registered. * - * Accepts an associative array $l10n and creates a JavaScript object: + * Accepts an associative array `$l10n` and creates a JavaScript object: * - * "$object_name" = { + * "$object_name": { * key: value, * key: value, * ... @@ -198,7 +211,6 @@ * * @see WP_Scripts::localize() * @link https://core.trac.wordpress.org/ticket/11520 - * @global WP_Scripts $wp_scripts The WP_Scripts object for printing scripts. * * @since 2.2.0 * @@ -211,12 +223,7 @@ * @return bool True if the script was successfully localized, false otherwise. */ function wp_localize_script( $handle, $object_name, $l10n ) { - global $wp_scripts; - - if ( ! ( $wp_scripts instanceof WP_Scripts ) ) { - _wp_scripts_maybe_doing_it_wrong( __FUNCTION__, $handle ); - return false; - } + $wp_scripts = wp_scripts(); return $wp_scripts->localize( $handle, $object_name, $l10n ); } @@ -227,17 +234,17 @@ * Works only if the script has already been registered. * * @see WP_Scripts::set_translations() - * @global WP_Scripts $wp_scripts The WP_Scripts object for printing scripts. - * * @since 5.0.0 * @since 5.1.0 The `$domain` parameter was made optional. * + * @global WP_Scripts $wp_scripts The WP_Scripts object for printing scripts. + * * @param string $handle Script handle the textdomain will be attached to. * @param string $domain Optional. Text domain. Default 'default'. * @param string $path Optional. The full file path to the directory containing translation files. * @return bool True if the text domain was successfully localized, false otherwise. */ -function wp_set_script_translations( $handle, $domain = 'default', $path = null ) { +function wp_set_script_translations( $handle, $domain = 'default', $path = '' ) { global $wp_scripts; if ( ! ( $wp_scripts instanceof WP_Scripts ) ) { @@ -249,7 +256,7 @@ } /** - * Remove a registered script. + * Removes a registered script. * * Note: there are intentional safeguards in place to prevent critical admin scripts, * such as jQuery core, from being unregistered. @@ -322,15 +329,16 @@ } /** - * Enqueue a script. + * Enqueues a script. * - * Registers the script if $src provided (does NOT overwrite), and enqueues it. + * Registers the script if `$src` provided (does NOT overwrite), and enqueues it. * * @see WP_Dependencies::add() * @see WP_Dependencies::add_data() * @see WP_Dependencies::enqueue() * * @since 2.1.0 + * @since 6.3.0 The $in_footer parameter of type boolean was overloaded to be an $args parameter of type array. * * @param string $handle Name of the script. Should be unique. * @param string $src Full URL of the script, or path of the script relative to the WordPress root directory. @@ -340,31 +348,43 @@ * as a query string for cache busting purposes. If version is set to false, a version * number is automatically added equal to current installed WordPress version. * If set to null, no version is added. - * @param bool $in_footer Optional. Whether to enqueue the script before `` instead of in the ``. - * Default 'false'. + * @param array|bool $args { + * Optional. An array of additional script loading strategies. Default empty array. + * Otherwise, it may be a boolean in which case it determines whether the script is printed in the footer. Default false. + * + * @type string $strategy Optional. If provided, may be either 'defer' or 'async'. + * @type bool $in_footer Optional. Whether to print the script in the footer. Default 'false'. + * } */ -function wp_enqueue_script( $handle, $src = '', $deps = array(), $ver = false, $in_footer = false ) { +function wp_enqueue_script( $handle, $src = '', $deps = array(), $ver = false, $args = array() ) { _wp_scripts_maybe_doing_it_wrong( __FUNCTION__, $handle ); $wp_scripts = wp_scripts(); - if ( $src || $in_footer ) { + if ( $src || ! empty( $args ) ) { $_handle = explode( '?', $handle ); + if ( ! is_array( $args ) ) { + $args = array( + 'in_footer' => (bool) $args, + ); + } if ( $src ) { $wp_scripts->add( $_handle[0], $src, $deps, $ver ); } - - if ( $in_footer ) { + if ( ! empty( $args['in_footer'] ) ) { $wp_scripts->add_data( $_handle[0], 'group', 1 ); } + if ( ! empty( $args['strategy'] ) ) { + $wp_scripts->add_data( $_handle[0], 'strategy', $args['strategy'] ); + } } $wp_scripts->enqueue( $handle ); } /** - * Remove a previously enqueued script. + * Removes a previously enqueued script. * * @see WP_Dependencies::dequeue() * @@ -389,18 +409,18 @@ * @since 3.5.0 'enqueued' added as an alias of the 'queue' list. * * @param string $handle Name of the script. - * @param string $list Optional. Status of the script to check. Default 'enqueued'. + * @param string $status Optional. Status of the script to check. Default 'enqueued'. * Accepts 'enqueued', 'registered', 'queue', 'to_do', and 'done'. * @return bool Whether the script is queued. */ -function wp_script_is( $handle, $list = 'enqueued' ) { +function wp_script_is( $handle, $status = 'enqueued' ) { _wp_scripts_maybe_doing_it_wrong( __FUNCTION__, $handle ); - return (bool) wp_scripts()->query( $handle, $list ); + return (bool) wp_scripts()->query( $handle, $status ); } /** - * Add metadata to a script. + * Adds metadata to a script. * * Works only if the script has already been registered. *