PR Feedback

Author: dmsnell

src/wp-includes/class-wp-token-map.php

@@ -36,8 +36,20 @@
  *      '😕' === $smilies->read_token( 'Not sure :?.', 9, $bytes_skipped );
  *      2    === $bytes_skipped;
  *
- *      echo $smilies->precomputed_php_source_table( '    ' );
- *      // Output.
+ * ## Precomputing the Token Map.
+ *
+ * Creating the class involves some work sorting and organizing the tokens and their
+ * replacement values. In order to skip this, it's possible for the class to export
+ * its state and be used as actual PHP source code.
+ *
+ * Example:
+ *
+ *      // Export with four spaces as the indent, only for the sake of this docblock.
+ *      // The default indent is a tab character.
+ *      $indent = '    ';
+ *      echo $smilies->precomputed_php_source_table( $indent );
+ *
+ *      // Output, to be pasted into a PHP source file:
  *      WP_Token_Map::from_precomputed_table(
  *          2,
  *          "",
@@ -253,7 +265,7 @@ public static function from_array( $mappings, $key_length = 2 ) {
 				_doing_it_wrong(
 					__METHOD__,
 					__( 'Token Map tokens and substitutions must all be shorter than 256 bytes.' ),
-					'6. .0'
+					'6.6.0'
 				);
 				return null;
 			}

src/wp-includes/html-api/html5-named-character-references.php

@@ -26,6 +26,10 @@
  * for an ambiguous ampersand govern whether the following text is
  * to be interpreted as a character reference or not.
  *
+ * The list of entities is sourced directly from the WHATWG server
+ * and cached in the test directory to avoid needing to download it
+ * every time this file is updated.
+ *
  * @link https://html.spec.whatwg.org/entities.json.
  */
 $html5_named_character_references = WP_Token_Map::from_precomputed_table(

tests/phpunit/tests/html-api/generate-html5-named-character-references.php

@@ -66,6 +66,10 @@
  * for an ambiguous ampersand govern whether the following text is
  * to be interpreted as a character reference or not.
  *
+ * The list of entities is sourced directly from the WHATWG server
+ * and cached in the test directory to avoid needing to download it
+ * every time this file is updated.
+ *
  * @link https://html.spec.whatwg.org/entities.json.
  */
 \$html5_named_character_references = {$html5_map->precomputed_php_source_table()};

tests/phpunit/tests/wp-token-map/wpTokenMap.php

@@ -9,6 +9,19 @@
  * @coversDefaultClass WP_Token_map
  */
 class Tests_WpTokenMap extends WP_UnitTestCase {
+	/**
+	 * Small test array matching names to Emoji.
+	 *
+	 * @var array.
+	 */
+	const ANIMAL_EMOJI = array(
+		'cat'     => '🐈',
+		'dog'     => '🐶',
+		'fish'    => '🐟',
+		'mammoth' => '🦣',
+		'seal'    => '🦭',
+	);
+
 	/**
 	 * Returns an associative array whose keys are tokens to replace and
 	 * whose values are the replacement strings for those tokens.
@@ -17,6 +30,11 @@ class Tests_WpTokenMap extends WP_UnitTestCase {
 	 * For example, the HTML5 dataset is very large and best served as a
 	 * separate file.
 	 *
+	 * The HTML5 named character reference list is pulled directly from the
+	 * WHATWG spec and stored in the tests directory so it doesn't need to
+	 * be downloaded on every test run. By specification, it cannot change
+	 * and will not be updated.
+	 *
 	 * @ticket 60698.
 	 *
 	 * @param string $dataset_name Which dataset to return.
@@ -31,7 +49,7 @@ private static function get_test_input_array( $dataset_name ) {
 
 			case 'HTML5':
 				if ( ! isset( $html5_character_references ) ) {
-					$dataset = json_decode( file_get_contents( __DIR__ . '/../../data/html5-entities.json' ), JSON_OBJECT_AS_ARRAY ); // phpcs:ignore.
+					$dataset = wp_json_file_decode( __DIR__ . '/../../data/html5-entities.json', JSON_OBJECT_AS_ARRAY );
 
 					$html5_character_references = array();
 					foreach ( $dataset as $name => $value ) {
@@ -48,7 +66,7 @@ private static function get_test_input_array( $dataset_name ) {
 	 *
 	 * @return array[].
 	 */
-	public static function data_input_arrays() {
+	private static function data_input_arrays() {
 		$dataset_names = array(
 			'ANIMALS',
 			'HTML5',
@@ -357,7 +375,7 @@ public static function data_html5_test_dataset() {
 	 *
 	 * @return WP_Token_Map
 	 */
-	public static function get_html5_token_map() {
+	private static function get_html5_token_map() {
 		static $html5_token_map = null;
 
 		if ( ! isset( $html5_token_map ) ) {
@@ -366,12 +384,4 @@ public static function get_html5_token_map() {
 
 		return $html5_token_map;
 	}
-
-	const ANIMAL_EMOJI = array(
-		'cat'     => '🐈',
-		'dog'     => '🐶',
-		'fish'    => '🐟',
-		'mammoth' => '🦣',
-		'seal'    => '🦭',
-	);
 }