Changeset 58579

Timestamp:

06/26/2024 01:19:47 PM (4 months ago)

Author:

Bernhard Reiter

Message:

Script Modules: Add new API to embed server data in HTML.

Add a new filter script_module_data_{$module_id} to associate data
with a Script Module. For example:

add_filter(
        'script_module_data_MyScriptModuleID',
        function ( array $data ): array {
                $data['script-needs-this-data'] = 'ok';
                return $data;
        }
);

If the Script Module is included in the page, enqueued or as a
dependency, the associated data will be JSON-encoded and embedded in the
HTML in a <script type="application/json"> tag with an ID of the form
wp-script-module-data-{$module_id} allowing the Script Module to
access the data on the client.

See the original proposal: ​https://make.wordpress.org/core/2024/05/06/proposal-server-to-client-data-sharing-for-script-modules/

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

Props jonsurrell, cbravobernal, westonruter, gziolo, bernhard-reiter, youknowriad, sergiomdgomes, czapla.
Fixes #61510. See #60647.

Location:

trunk

Files:

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

trunk/src/wp-includes/class-wp-script-modules.php

@@ -183 +183 @@
         add_action( 'admin_print_footer_scripts', array( $this, 'print_enqueued_script_modules' ) );
         add_action( 'admin_print_footer_scripts', array( $this, 'print_script_module_preloads' ) );
+
+        add_action( 'wp_footer', array( $this, 'print_script_module_data' ) );
+        add_action( 'admin_print_footer_scripts', array( $this, 'print_script_module_data' ) );
     }
 
@@ -364 +367 @@
         return $src;
     }
+
+    /**
+     * Print data associated with Script Modules.
+     *
+     * The data will be embedded in the page HTML and can be read by Script Modules on page load.
+     *
+     * @since 6.7.0
+     *
+     * Data can be associated with a Script Module via the
+     * {@see "script_module_data_{$module_id}"} filter.
+     *
+     * The data for a Script Module will be serialized as JSON in a script tag with an ID of the
+     * form `wp-script-module-data-{$module_id}`.
+     */
+    public function print_script_module_data(): void {
+        $modules = array();
+        foreach ( array_keys( $this->get_marked_for_enqueue() ) as $id ) {
+            $modules[ $id ] = true;
+        }
+        foreach ( array_keys( $this->get_import_map()['imports'] ) as $id ) {
+            $modules[ $id ] = true;
+        }
+
+        foreach ( array_keys( $modules ) as $module_id ) {
+            /**
+             * Filters data associated with a given Script Module.
+             *
+             * Script Modules 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.
+             *
+             * The dynamic portion of the hook name, `$module_id`, refers to the Script Module ID
+             * that the data is associated with.
+             *
+             * This is best suited to pass essential data that must be available to the module for
+             * initialization or immediately on page load. It does not replace the REST API or
+             * fetching data from the client.
+             *
+             * @example
+             *   add_filter(
+             *     'script_module_data_MyScriptModuleID',
+             *     function ( array $data ): array {
+             *       $data['script-needs-this-data'] = 'ok';
+             *       return $data;
+             *     }
+             *   );
+             *
+             * If the filter returns no data (an empty array), nothing will be embedded in the page.
+             *
+             * The data for a given Script Module, if provided, will be JSON serialized in a script
+             * tag with an ID of the form `wp-script-module-data-{$module_id}`.
+             *
+             * The data can be read on the client with a pattern like this:
+             *
+             * @example
+             *   const dataContainer = document.getElementById( 'wp-script-module-data-MyScriptModuleID' );
+             *   let data = {};
+             *   if ( dataContainer ) {
+             *     try {
+             *       data = JSON.parse( dataContainer.textContent );
+             *     } catch {}
+             *   }
+             *   initMyScriptModuleWithData( data );
+             *
+             * @since 6.7.0
+             *
+             * @param array $data The data associated with the Script Module.
+             */
+            $data = apply_filters( "script_module_data_{$module_id}", 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\u00E3`.
+                 *
+                 *   - 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(
+                    wp_json_encode(
+                        $data,
+                        $json_encode_flags
+                    ),
+                    array(
+                        'type' => 'application/json',
+                        'id'   => "wp-script-module-data-{$module_id}",
+                    )
+                );
+            }
+        }
+    }
 }

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

@@ -733 +733 @@
         $this->assertSame( 'wp-load-polyfill-importmap', $id );
     }
+
+    /**
+     * @ticket 61510
+     */
+    public function test_print_script_module_data_prints_enqueued_module_data() {
+        $this->script_modules->enqueue( '@test/module', '/example.js' );
+        add_action(
+            'script_module_data_@test/module',
+            function ( $data ) {
+                $data['foo'] = 'bar';
+                return $data;
+            }
+        );
+
+        $actual = get_echo( array( $this->script_modules, 'print_script_module_data' ) );
+
+        $expected = <<<HTML
+<script type="application/json" id="wp-script-module-data-@test/module">
+{"foo":"bar"}
+</script>
+
+HTML;
+        $this->assertSame( $expected, $actual );
+    }
+
+    /**
+     * @ticket 61510
+     */
+    public function test_print_script_module_data_prints_dependency_module_data() {
+        $this->script_modules->register( '@test/dependency', '/dependency.js' );
+        $this->script_modules->enqueue( '@test/module', '/example.js', array( '@test/dependency' ) );
+        add_action(
+            'script_module_data_@test/dependency',
+            function ( $data ) {
+                $data['foo'] = 'bar';
+                return $data;
+            }
+        );
+
+        $actual = get_echo( array( $this->script_modules, 'print_script_module_data' ) );
+
+        $expected = <<<HTML
+<script type="application/json" id="wp-script-module-data-@test/dependency">
+{"foo":"bar"}
+</script>
+
+HTML;
+        $this->assertSame( $expected, $actual );
+    }
+
+    /**
+     * @ticket 61510
+     */
+    public function test_print_script_module_data_does_not_print_nondependency_module_data() {
+        $this->script_modules->register( '@test/other', '/dependency.js' );
+        $this->script_modules->enqueue( '@test/module', '/example.js' );
+        add_action(
+            'script_module_data_@test/other',
+            function ( $data ) {
+                $data['foo'] = 'bar';
+                return $data;
+            }
+        );
+
+        $actual = get_echo( array( $this->script_modules, 'print_script_module_data' ) );
+
+        $this->assertSame( '', $actual );
+    }
+
+    /**
+     * @ticket 61510
+     */
+    public function test_print_script_module_data_does_not_print_empty_data() {
+        $this->script_modules->enqueue( '@test/module', '/example.js' );
+        add_action(
+            'script_module_data_@test/module',
+            function ( $data ) {
+                return $data;
+            }
+        );
+
+        $actual = get_echo( array( $this->script_modules, 'print_script_module_data' ) );
+
+        $this->assertSame( '', $actual );
+    }
+
+    /**
+     * @ticket 61510
+     *
+     * @dataProvider data_special_chars_script_encoding
+     * @param string $input    Raw input string.
+     * @param string $expected Expected output string.
+     * @param string $charset  Blog charset option.
+     */
+    public function test_print_script_module_data_encoding( $input, $expected, $charset ) {
+        add_filter(
+            'pre_option_blog_charset',
+            function () use ( $charset ) {
+                return $charset;
+            }
+        );
+
+        $this->script_modules->enqueue( '@test/module', '/example.js' );
+        add_action(
+            'script_module_data_@test/module',
+            function ( $data ) use ( $input ) {
+                $data[''] = $input;
+                return $data;
+            }
+        );
+
+        $actual = get_echo( array( $this->script_modules, 'print_script_module_data' ) );
+
+        $expected = <<<HTML
+<script type="application/json" id="wp-script-module-data-@test/module">
+{"":"{$expected}"}
+</script>
+
+HTML;
+
+        $this->assertSame( $expected, $actual );
+    }
+
+    /**
+     * Data provider.
+     *
+     * @return array
+     */
+    public static function data_special_chars_script_encoding(): array {
+        return array(
+            // UTF-8
+            'Solidus'                                => array( '/', '/', 'UTF-8' ),
+            'Double quote'                           => array( '"', '\\"', 'UTF-8' ),
+            'Single quote'                           => array( '\'', '\'', 'UTF-8' ),
+            'Less than'                              => array( '<', '\u003C', 'UTF-8' ),
+            'Greater than'                           => array( '>', '\u003E', 'UTF-8' ),
+            'Ampersand'                              => array( '&', '&', 'UTF-8' ),
+            'Newline'                                => array( "\n", "\\n", 'UTF-8' ),
+            'Tab'                                    => array( "\t", "\\t", 'UTF-8' ),
+            'Form feed'                              => array( "\f", "\\f", 'UTF-8' ),
+            'Carriage return'                        => array( "\r", "\\r", 'UTF-8' ),
+            'Line separator'                         => array( "\u{2028}", "\u{2028}", 'UTF-8' ),
+            'Paragraph separator'                    => array( "\u{2029}", "\u{2029}", 'UTF-8' ),
+
+            /*
+             * The following is the Flag of England emoji
+             * PHP: "\u{1F3F4}\u{E0067}\u{E0062}\u{E0065}\u{E006E}\u{E0067}\u{E007F}"
+             */
+            'Flag of england'                        => array( '🏴󠁧󠁢󠁥󠁮󠁧󠁿', '🏴󠁧󠁢󠁥󠁮󠁧󠁿', 'UTF-8' ),
+            'Malicious script closer'                => array( '</script>', '\u003C/script\u003E', 'UTF-8' ),
+            'Entity-encoded malicious script closer' => array( '&lt;/script&gt;', '&lt;/script&gt;', 'UTF-8' ),
+
+            // Non UTF-8
+            'Solidus'                                => array( '/', '/', 'iso-8859-1' ),
+            'Less than'                              => array( '<', '\u003C', 'iso-8859-1' ),
+            'Greater than'                           => array( '>', '\u003E', 'iso-8859-1' ),
+            'Ampersand'                              => array( '&', '&', 'iso-8859-1' ),
+            'Newline'                                => array( "\n", "\\n", 'iso-8859-1' ),
+            'Tab'                                    => array( "\t", "\\t", 'iso-8859-1' ),
+            'Form feed'                              => array( "\f", "\\f", 'iso-8859-1' ),
+            'Carriage return'                        => array( "\r", "\\r", 'iso-8859-1' ),
+            'Line separator'                         => array( "\u{2028}", "\u2028", 'iso-8859-1' ),
+            'Paragraph separator'                    => array( "\u{2029}", "\u2029", 'iso-8859-1' ),
+            /*
+             * The following is the Flag of England emoji
+             * PHP: "\u{1F3F4}\u{E0067}\u{E0062}\u{E0065}\u{E006E}\u{E0067}\u{E007F}"
+             */
+            'Flag of england'                        => array( '🏴󠁧󠁢󠁥󠁮󠁧󠁿', "\ud83c\udff4\udb40\udc67\udb40\udc62\udb40\udc65\udb40\udc6e\udb40\udc67\udb40\udc7f", 'iso-8859-1' ),
+            'Malicious script closer'                => array( '</script>', '\u003C/script\u003E', 'iso-8859-1' ),
+            'Entity-encoded malicious script closer' => array( '&lt;/script&gt;', '&lt;/script&gt;', 'iso-8859-1' ),
+
+        );
+    }
+
+    /**
+     * @ticket 61510
+     *
+     * @dataProvider data_invalid_script_module_data
+     * @param mixed $data Data to return in filter.
+     */
+    public function test_print_script_module_data_does_not_print_invalid_data( $data ) {
+        $this->script_modules->enqueue( '@test/module', '/example.js' );
+        add_action(
+            'script_module_data_@test/module',
+            function ( $_ ) use ( $data ) {
+                return $data;
+            }
+        );
+
+        $actual = get_echo( array( $this->script_modules, 'print_script_module_data' ) );
+
+        $this->assertSame( '', $actual );
+    }
+
+    /**
+     * Data provider.
+     *
+     * @return array
+     */
+    public static function data_invalid_script_module_data(): array {
+        return array(
+            'null'     => array( null ),
+            'stdClass' => array( new stdClass() ),
+            'number 1' => array( 1 ),
+            'string'   => array( 'string' ),
+        );
+    }
 }