Implement script_data_{$handle} filter correctly - outputs JSON script tags separate from wp_localize_script

Co-authored-by: sirreal <[email protected]>

Author: Copilot

src/wp-admin/includes/admin-filters.php

@@ -59,6 +59,7 @@
 add_action( 'admin_print_scripts', 'print_emoji_detection_script' );
 add_action( 'admin_print_scripts', 'print_head_scripts', 20 );
 add_action( 'admin_print_footer_scripts', '_wp_footer_scripts' );
+add_action( 'admin_print_footer_scripts', 'wp_print_script_data', 21 );
 add_action( 'admin_enqueue_scripts', 'wp_enqueue_emoji_styles' );
 add_action( 'admin_print_styles', 'print_emoji_styles' ); // Retained for backwards-compatibility. Unhooked by wp_enqueue_emoji_styles().
 add_action( 'admin_print_styles', 'print_admin_styles', 20 );

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

@@ -634,23 +634,6 @@ public function localize( $handle, $object_name, $l10n ) {
 			}
 		}
 
-		/**
-		 * Filters data associated with a given script.
-		 *
-		 * The dynamic portion of the hook name, `$handle`, refers to the script handle.
-		 *
-		 * This filter allows developers to modify the data passed to a script via
-		 * wp_localize_script() before it is output. This is analogous to the
-		 * `script_module_data_{$module_id}` filter for script modules.
-		 *
-		 * @since 6.8.0
-		 *
-		 * @param array|string $l10n        The data to be localized.
-		 * @param string       $object_name The JavaScript object name.
-		 * @param string       $handle      The script handle.
-		 */
-		$l10n = apply_filters( "script_data_{$handle}", $l10n, $object_name, $handle );
-
 		$script = "var $object_name = " . wp_json_encode( $l10n, JSON_HEX_TAG | JSON_UNESCAPED_SLASHES ) . ';';
 
 		if ( ! empty( $after ) ) {
@@ -1199,4 +1182,120 @@ protected function get_dependency_warning_message( $handle, $missing_dependency_
 			implode( ', ', $missing_dependency_handles )
 		);
 	}
+
+	/**
+	 * Prints data associated with scripts.
+	 *
+	 * The data will be embedded in the page HTML and can be read by scripts on page load.
+	 *
+	 * Data can be associated with a script via the {@see "script_data_{$handle}"} filter.
+	 *
+	 * The data for a script will be serialized as JSON in a script tag with an ID of the
+	 * form `wp-script-data-{$handle}`.
+	 *
+	 * @since 6.8.0
+	 */
+	public function print_script_data() {
+		$scripts = array();
+
+		// Collect all enqueued scripts and their dependencies.
+		foreach ( array_unique( $this->queue ) as $handle ) {
+			$scripts[ $handle ] = true;
+		}
+
+		foreach ( array_keys( $scripts ) as $handle ) {
+			/**
+			 * Filters data associated with a given script.
+			 *
+			 * The dynamic portion of the hook name, `$handle`, refers to the script handle.
+			 *
+			 * Scripts may require data that is required for initialization or is essential
+			 * to have immediately available on page load. These are suitable use cases for
+			 * this data.
+			 *
+			 * This is best suited to pass essential data that must be available to the script for
+			 * initialization or immediately on page load. It does not replace the REST API or
+			 * fetching data from the client.
+			 *
+			 * Example:
+			 *
+			 *     add_filter(
+			 *         'script_data_my-script-handle',
+			 *         function ( array $data ): array {
+			 *             $data['myData'] = array(
+			 *                 'option' => get_option( 'my_option' ),
+			 *             );
+			 *             return $data;
+			 *         }
+			 *     );
+			 *
+			 * If the filter returns no data (an empty array), nothing will be embedded in the page.
+			 *
+			 * The data for a given script, if provided, will be JSON serialized in a script
+			 * tag with an ID of the form `wp-script-data-{$handle}`.
+			 *
+			 * The data can be read on the client with a pattern like this:
+			 *
+			 * Example:
+			 *
+			 *     const dataContainer = document.getElementById( 'wp-script-data-my-script-handle' );
+			 *     let data = {};
+			 *     if ( dataContainer ) {
+			 *         try {
+			 *             data = JSON.parse( dataContainer.textContent );
+			 *         } catch {}
+			 *     }
+			 *     initMyScriptWithData( data );
+			 *
+			 * @since 6.8.0
+			 *
+			 * @param array $data The data associated with the script.
+			 */
+			$data = apply_filters( "script_data_{$handle}", array() );
+
+			if ( is_array( $data ) && array() !== $data ) {
+				/*
+				 * This data will be printed as JSON inside a script tag like this:
+				 *   <script type="application/json"></script>
+				 *
+				 * A script tag must be closed by a sequence beginning with `</`. It's impossible to
+				 * close a script tag without using `<`. We ensure that `<` is escaped and `/` can
+				 * remain unescaped, so `</script>` will be printed as `\u003C/script>`.
+				 *
+				 *   - JSON_HEX_TAG: All < and > are converted to \u003C and \u003E.
+				 *   - JSON_UNESCAPED_SLASHES: Don't escape /.
+				 *
+				 * If the page will use UTF-8 encoding, it's safe to print unescaped unicode:
+				 *
+				 *   - JSON_UNESCAPED_UNICODE: Encode multibyte Unicode characters literally (instead of as `\uXXXX`).
+				 *   - JSON_UNESCAPED_LINE_TERMINATORS: The line terminators are kept unescaped when
+				 *     JSON_UNESCAPED_UNICODE is supplied. It uses the same behaviour as it was
+				 *     before PHP 7.1 without this constant. Available as of PHP 7.1.0.
+				 *
+				 * The JSON specification requires encoding in UTF-8, so if the generated HTML page
+				 * is not encoded in UTF-8 then it's not safe to include those literals. They must
+				 * be escaped to avoid encoding issues.
+				 *
+				 * @see https://www.rfc-editor.org/rfc/rfc8259.html for details on encoding requirements.
+				 * @see https://www.php.net/manual/en/json.constants.php for details on these constants.
+				 * @see https://html.spec.whatwg.org/#script-data-state for details on script tag parsing.
+				 */
+				$json_encode_flags = JSON_HEX_TAG | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_LINE_TERMINATORS;
+				if ( ! is_utf8_charset() ) {
+					$json_encode_flags = JSON_HEX_TAG | JSON_UNESCAPED_SLASHES;
+				}
+
+				wp_print_inline_script_tag(
+					(string) wp_json_encode(
+						$data,
+						$json_encode_flags
+					),
+					array(
+						'type' => 'application/json',
+						'id'   => "wp-script-data-{$handle}",
+					)
+				);
+			}
+		}
+	}
 }

src/wp-includes/default-filters.php

@@ -361,6 +361,7 @@
 add_action( 'wp_head', 'wp_site_icon', 99 );
 add_action( 'wp_footer', 'wp_print_speculation_rules' );
 add_action( 'wp_footer', 'wp_print_footer_scripts', 20 );
+add_action( 'wp_footer', 'wp_print_script_data', 21 );
 add_action( 'template_redirect', 'wp_shortlink_header', 11, 0 );
 add_action( 'wp_print_footer_scripts', '_wp_footer_scripts' );
 add_action( 'init', '_register_core_block_patterns_and_categories' );

src/wp-includes/functions.wp-scripts.php

@@ -450,3 +450,20 @@ function wp_script_is( $handle, $status = 'enqueued' ) {
 function wp_script_add_data( $handle, $key, $value ) {
 	return wp_scripts()->add_data( $handle, $key, $value );
 }
+
+/**
+ * Prints data associated with enqueued scripts.
+ *
+ * @since 6.8.0
+ *
+ * @see WP_Scripts::print_script_data()
+ */
+function wp_print_script_data() {
+	global $wp_scripts;
+
+	if ( ! ( $wp_scripts instanceof WP_Scripts ) ) {
+		return;
+	}
+
+	$wp_scripts->print_script_data();
+}