Add support for script strategy (#34072)

* Add support for script strategy * Script strategy was introduced in 6.3 * Update projects/packages/assets/src/class-assets.php Co-authored-by: Brad Jorsch <[email protected]> * Update projects/packages/assets/src/class-assets.php Co-authored-by: Brad Jorsch <[email protected]> * Switch version check to use `$wp_versoin` global * Add strategy option * Enable async support for strategy option * Update projects/packages/assets/src/class-assets.php Co-authored-by: Brad Jorsch <[email protected]> * Simplify logic as per PR suggestion * Support deprecated `async` attribute using new strategy=‘defer’ * Deprecate add_async_script * Adjust use of add_async_script in class-tracking-pixel.php * Deprecate script_add_async * Hook `script_add_async` conditionally * Deprecate `enqueue_async_script` (and restore pre-PR code) * Update uses of enqueue_async_script to use register_script instead * Deprecate the async option, improve doc block * restore `enqueue_async_script` * Try: add tests for strategy * Remove pre-6.3 code from Stats This gives us the opportunity to remove the need for the Assets package entirely. * Update tests following feedback See https://github.com/Automattic/jetpack/pull/34072/files#r1396404112 Co-authored-by: Brad Jorsch <[email protected]> * Remove pre-6.3 code Jetpack now requires WordPress 6.3 * Address feedback from code review See: - https://github.com/Automattic/jetpack/pull/34072/files#r1396389177 - https://github.com/Automattic/jetpack/pull/34072/files#r1396389463 - https://github.com/Automattic/jetpack/pull/34072/files#r1396359251 - https://github.com/Automattic/jetpack/pull/34072/files#r1396389743 - https://github.com/Automattic/jetpack/pull/34072/files#r1396362871 - https://github.com/Automattic/jetpack/pull/34072/files#r1396363681 - https://github.com/Automattic/jetpack/pull/34072/files#r1396393051 - https://github.com/Automattic/jetpack/pull/34072/files#r1396373098 * Bump versions * Avoid PHP notice See https://github.com/Automattic/jetpack/pull/34072/files#r1396372023 * Update doc See #34072 (comment) Co-authored-by: Brad Jorsch <[email protected]> * Move changelog entry to the right package. * Remove tests for deprecated method * Fix tests * Version bumps * Have to use Mockery::type there rather than PHPUnit's Assert::isType * Bump version * Update enqueuing method for Forms script * Update enqueuing method, set defer directly when enqueuing See #34072 (comment) * bump version --------- Co-authored-by: Brad Jorsch <[email protected]> Co-authored-by: Jeremy Herve <[email protected]> Co-authored-by: Brad Jorsch <[email protected]>
Automattic · Feb 1, 2024 · ca5ff93 · ca5ff93
1 parent 1605022
commit ca5ff93
Show file tree

Hide file tree

Showing 37 changed files with 249 additions and 152 deletions.
diff --git a/projects/packages/assets/changelog/add-script-strategy-support b/projects/packages/assets/changelog/add-script-strategy-support
@@ -0,0 +1,4 @@
+Significance: minor
+Type: added
+
+Add support for script enqueuing strategies implemented in WordPress 6.3
diff --git a/projects/packages/assets/composer.json b/projects/packages/assets/composer.json
@@ -60,7 +60,7 @@
 			"link-template": "https://github.com/Automattic/jetpack-assets/compare/v${old}...v${new}"
 		},
 		"branch-alias": {
-			"dev-trunk": "2.0.x-dev"
+			"dev-trunk": "2.1.x-dev"
 		}
 	}
 }
diff --git a/projects/packages/assets/src/class-assets.php b/projects/packages/assets/src/class-assets.php
@@ -54,40 +54,35 @@ private function __construct() {}
 	public static function instance() {
 		if ( ! isset( self::$instance ) ) {
 			self::$instance = new Assets();
-			self::$instance->init_hooks();
 		}
 
 		return self::$instance;
 	}
 
-	/**
-	 * Initalize the hooks as needed.
-	 */
-	private function init_hooks() {
-		/*
-		 * Load some scripts asynchronously.
-		 */
-		add_filter( 'script_loader_tag', array( $this, 'script_add_async' ), 10, 2 );
-	}
-
 	/**
 	 * A public method for adding the async script.
 	 *
+	 * @deprecated Since $$next-version$$, the `strategy` feature should be used instead, with the "defer" setting.
+	 *
 	 * @param string $script_handle Script handle.
 	 */
 	public static function add_async_script( $script_handle ) {
-		$assets_instance                         = self::instance();
-		$assets_instance->defer_script_handles[] = $script_handle;
+		_deprecated_function( __METHOD__, '$$next-version$$' );
+
+		wp_script_add_data( $script_handle, 'strategy', 'defer' );
 	}
 
 	/**
 	 * Add an async attribute to scripts that can be loaded deferred.
 	 * https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script
 	 *
+	 * @deprecated Since $$next-version$$, the `strategy` feature should be used instead.
+	 *
 	 * @param string $tag    The <script> tag for the enqueued script.
 	 * @param string $handle The script's registered handle.
 	 */
 	public function script_add_async( $tag, $handle ) {
+		_deprecated_function( __METHOD__, '$$next-version$$' );
 		if ( empty( $this->defer_script_handles ) ) {
 			return $tag;
 		}
@@ -103,6 +98,8 @@ public function script_add_async( $tag, $handle ) {
 	/**
 	 * A helper function that lets you enqueue scripts in an async fashion.
 	 *
+	 * @deprecated Since $$next-version$$ - use the strategy feature instead.
+	 *
 	 * @param string $handle        Name of the script. Should be unique.
 	 * @param string $min_path      Minimized script path.
 	 * @param string $non_min_path  Full Script path.
@@ -111,6 +108,7 @@ public function script_add_async( $tag, $handle ) {
 	 * @param bool   $in_footer       Should the script be included in the footer.
 	 */
 	public static function enqueue_async_script( $handle, $min_path, $non_min_path, $deps = array(), $ver = false, $in_footer = true ) {
+		_deprecated_function( __METHOD__, '$$next-version$$' );
 		$assets_instance = self::instance();
 		$assets_instance->add_async_script( $handle );
 		wp_enqueue_script( $handle, self::get_file_url_for_environment( $min_path, $non_min_path ), $deps, $ver, $in_footer );
@@ -307,12 +305,13 @@ public static function normalize_path( $path ) {
 	 * This wrapper handles all of that.
 	 *
 	 * @since 1.12.0
+	 * @since $$next-version$$ Add a new `strategy` option to leverage WP >= 6.3 script strategy feature. The `async` option is deprecated.
 	 * @param string $handle      Name of the script. Should be unique across both scripts and styles.
 	 * @param string $path        Minimized script path.
 	 * @param string $relative_to File that `$path` is relative to. Pass `__FILE__`.
 	 * @param array  $options     Additional options:
 	 *  - `asset_path`:       (string|null) `.asset.php` to load. Default is to base it on `$path`.
-	 *  - `async`:            (bool) Set true to register the script as async, like `Assets::enqueue_async_script()`
+	 *  - `async`:            (bool) Set true to register the script as deferred, like `Assets::enqueue_async_script()`. Deprecated in favor of `strategy`.
 	 *  - `css_dependencies`: (string[]) Additional style dependencies to queue.
 	 *  - `css_path`:         (string|null) `.css` to load. Default is to base it on `$path`.
 	 *  - `dependencies`:     (string[]) Additional script dependencies to queue.
@@ -321,6 +320,7 @@ public static function normalize_path( $path ) {
 	 *  - `media`:            (string) Media for the css file. Default 'all'.
 	 *  - `minify`:           (bool|null) Set true to pass `minify=true` in the query string, or `null` to suppress the normal `minify=false`.
 	 *  - `nonmin_path`:      (string) Non-minified script path.
+	 *  - `strategy`:         (string) Specify a script strategy to use, eg. `defer` or `async`. Default is `""`.
 	 *  - `textdomain`:       (string) Text domain for the script. Required if the script depends on wp-i18n.
 	 *  - `version`:          (string) Override the version from the `asset_path` file.
 	 * @throws \InvalidArgumentException If arguments are invalid.
@@ -330,6 +330,10 @@ public static function register_script( $handle, $path, $relative_to, array $opt
 			throw new \InvalidArgumentException( '$path must end in ".js"' );
 		}
 
+		if ( isset( $options['async'] ) ) {
+			_deprecated_argument( __METHOD__, '$$next-version$$', 'The `async` option is deprecated in favor of `strategy`' );
+		}
+
 		$dir      = dirname( $relative_to );
 		$base     = substr( $path, 0, -3 );
 		$options += array(
@@ -342,6 +346,7 @@ public static function register_script( $handle, $path, $relative_to, array $opt
 			'in_footer'        => false,
 			'media'            => 'all',
 			'minify'           => false,
+			'strategy'         => '',
 			'textdomain'       => null,
 		);
 
@@ -376,10 +381,20 @@ function ( $d ) {
 			$ver = isset( $options['version'] ) ? $options['version'] : filemtime( "$dir/$path" );
 		}
 
-		wp_register_script( $handle, $url, $options['dependencies'], $ver, $options['in_footer'] );
-		if ( $options['async'] ) {
-			self::instance()->add_async_script( $handle );
+		if ( $options['async'] && '' === $options['strategy'] ) { // Handle the deprecated `async` option
+			$options['strategy'] = 'defer';
 		}
+		wp_register_script(
+			$handle,
+			$url,
+			$options['dependencies'],
+			$ver,
+			array(
+				'in_footer' => $options['in_footer'],
+				'strategy'  => $options['strategy'],
+			)
+		);
+
 		if ( $options['textdomain'] ) {
 			// phpcs:ignore Jetpack.Functions.I18n.DomainNotLiteral
 			wp_set_script_translations( $handle, $options['textdomain'] );