WordPress.org
Get WordPress

Make WordPress Core

Changeset 50967


Ignore:
Timestamp:
05/24/2021 01:24:05 PM (5 years ago)
Author:
SergeyBiryukov
Message:

Docs: Some documentation and test improvements for WP_Theme_JSON and WP_Theme_JSON_Resolver classes:

  • Add missing @since tags.
  • Update some DocBlocks per the documentation standards.
  • Rename test files and classes per the naming conventions.
  • Fix some code alignment issues reported by WPCS.

Follow-up to [50959], [50960].

See #52991, #53175.

Location:
trunk
Files:
2 edited
3 moved

Legend:

Unmodified
Added
Removed

  • trunk/src/wp-includes/class-wp-theme-json-resolver.php

    r50959 r50967  
    11<?php
    22/**
    3  * Process the different data sources for site-level
    4  * config and offers and API to work with them.
     3 * WP_Theme_JSON_Resolver class
    54 *
    65 * @package WordPress
     6 * @subpackage Theme
     7 * @since 5.8.0
    78 */
    89
    910/**
    10  * Class that abstracts the processing
    11  * of the different data sources.
     11 * Class that abstracts the processing of the different data sources
     12 * for site-level config and offers an API to work with them.
    1213 *
    1314 * @access private
    … …  
    1819         * Container for data coming from core.
    1920         *
     21         * @since 5.8.0
    2022         * @var WP_Theme_JSON
    2123         */
    … …  
    2527         * Container for data coming from the theme.
    2628         *
     29         * @since 5.8.0
    2730         * @var WP_Theme_JSON
    2831         */
    … …  
    3235         * Whether or not the theme supports theme.json.
    3336         *
    34          * @var boolean
     37         * @since 5.8.0
     38         * @var bool
    3539         */
    3640        private static $theme_has_support = null;
    … …  
    3943         * Structure to hold i18n metadata.
    4044         *
    41          * @var Array
     45         * @since 5.8.0
     46         * @var array
    4247         */
    4348        private static $theme_json_i18n = null;
    4449
    4550        /**
    46          * Processes a file that adheres to the theme.json
    47          * schema and returns an array with its contents,
    48          * or a void array if none found.
     51         * Processes a file that adheres to the theme.json schema
     52         * and returns an array with its contents, or a void array if none found.
     53         *
     54         * @since 5.8.0
    4955         *
    5056         * @param string $file_path Path to file. Empty if no file.
    51          *
    5257         * @return array Contents that adhere to the theme.json schema.
    5358         */
    … …  
    7984         * For example, given this input:
    8085         *
    81          * {
    82          *   "settings": {
    83          *     "*": {
    84          *       "typography": {
    85          *         "fontSizes": [ { "name": "Font size name" } ],
    86          *         "fontStyles": [ { "name": "Font size name" } ]
     86         *     {
     87         *       "settings": {
     88         *         "*": {
     89         *           "typography": {
     90         *             "fontSizes": [ { "name": "Font size name" } ],
     91         *             "fontStyles": [ { "name": "Font size name" } ]
     92         *           }
     93         *         }
    8794         *       }
    8895         *     }
    89          *   }
    90          * }
    9196         *
    9297         * will return this output:
    9398         *
    94          * [
    95          *   0 => [
    96          *     'path'    => [ 'settings', '*', 'typography', 'fontSizes' ],
    97          *     'key'     => 'name',
    98          *     'context' => 'Font size name'
    99          *   ],
    100          *   1 => [
    101          *     'path'    => [ 'settings', '*', 'typography', 'fontStyles' ],
    102          *     'key'     => 'name',
    103          *     'context' => 'Font style name'
    104          *   ]
    105          * ]
     99         *     [
     100         *       0 => [
     101         *         'path'    => [ 'settings', '*', 'typography', 'fontSizes' ],
     102         *         'key'     => 'name',
     103         *         'context' => 'Font size name'
     104         *       ],
     105         *       1 => [
     106         *         'path'    => [ 'settings', '*', 'typography', 'fontStyles' ],
     107         *         'key'     => 'name',
     108         *         'context' => 'Font style name'
     109         *       ]
     110         *     ]
     111         *
     112         * @since 5.8.0
    106113         *
    107114         * @param array $i18n_partial A tree that follows the format of i18n-theme.json.
    108115         * @param array $current_path Keeps track of the path as we walk down the given tree.
    109          *
    110116         * @return array A linear array containing the paths to translate.
    111117         */
    … …  
    135141         * Returns a data structure used in theme.json translation.
    136142         *
    137          * @return array An array of theme.json fields that are translatable and the keys that are translatable
     143         * @since 5.8.0
     144         *
     145         * @return array An array of theme.json fields that are translatable and the keys that are translatable.
    138146         */
    139147        public static function get_fields_to_translate() {
    … …  
    148156         * Translates a chunk of the loaded theme.json structure.
    149157         *
     158         * @since 5.8.0
     159         *
    150160         * @param array  $array_to_translate The chunk of theme.json to translate.
    151161         * @param string $key                The key of the field that contains the string to translate.
    152162         * @param string $context            The context to apply in the translation call.
    153163         * @param string $domain             Text domain. Unique identifier for retrieving translated strings.
    154          *
    155164         * @return array Returns the modified $theme_json chunk.
    156165         */
    … …  
    169178
    170179        /**
    171          * Given a theme.json structure modifies it in place
    172          * to update certain values by its translated strings
    173          * according to the language set by the user.
     180         * Given a theme.json structure modifies it in place to update certain values
     181         * by its translated strings according to the language set by the user.
     182         *
     183         * @since 5.8.0
    174184         *
    175185         * @param array  $theme_json The theme.json to translate.
    176          * @param string $domain    Optional. Text domain. Unique identifier for retrieving translated strings.
    177          *                          Default 'default'.
    178          *
     186         * @param string $domain     Optional. Text domain. Unique identifier for retrieving translated strings.
     187         *                           Default 'default'.
    179188         * @return array Returns the modified $theme_json_structure.
    180189         */
    … …  
    229238         * Return core's origin config.
    230239         *
     240         * @since 5.8.0
     241         *
    231242         * @return WP_Theme_JSON Entity that holds core data.
    232243         */
    … …  
    246257         * Returns the theme's data.
    247258         *
    248          * Data from theme.json can be augmented via the
    249          * $theme_support_data variable. This is useful, for example,
    250          * to backfill the gaps in theme.json that a theme has declared
    251          * via add_theme_supports.
    252          *
    253          * Note that if the same data is present in theme.json
    254          * and in $theme_support_data, the theme.json's is not overwritten.
     259         * Data from theme.json can be augmented via the $theme_support_data variable.
     260         * This is useful, for example, to backfill the gaps in theme.json that a theme
     261         * has declared via add_theme_supports.
     262         *
     263         * Note that if the same data is present in theme.json and in $theme_support_data,
     264         * the theme.json's is not overwritten.
     265         *
     266         * @since 5.8.0
    255267         *
    256268         * @param array $theme_support_data Theme support data in theme.json format.
    257          *
    258269         * @return WP_Theme_JSON Entity that holds theme data.
    259270         */
    … …  
    280291
    281292        /**
    282          * There are different sources of data for a site:
    283          * core and theme.
    284          *
    285          * While the getters {@link get_core_data},
    286          * {@link get_theme_data} return the raw data
    287          * from the respective origins, this method merges them
    288          * all together.
     293         * There are different sources of data for a site: core and theme.
     294         *
     295         * While the getters {@link get_core_data}, {@link get_theme_data} return the raw data
     296         * from the respective origins, this method merges them all together.
    289297         *
    290298         * If the same piece of data is declared in different origins (core and theme),
    291          * the last origin overrides the previous. For example,
    292          * if core disables custom colors but a theme enables them,
    293          * the theme config wins.
     299         * the last origin overrides the previous. For example, if core disables custom colors
     300         * but a theme enables them, the theme config wins.
     301         *
     302         * @since 5.8.0
    294303         *
    295304         * @param array  $settings Existing block editor settings.
    296305         *                         Empty array by default.
    297          *
    298306         * @return WP_Theme_JSON
    299307         */
    … …  
    322330
    323331        /**
    324          * Builds the path to the given file
    325          * and checks that it is readable.
    326          *
    327          * If it isn't, returns an empty string,
    328          * otherwise returns the whole file path.
     332         * Builds the path to the given file and checks that it is readable.
     333         *
     334         * If it isn't, returns an empty string, otherwise returns the whole file path.
     335         *
     336         * @since 5.8.0
    329337         *
    330338         * @param string $file_name Name of the file.
    … …  
    332340         */
    333341        private static function get_file_path_from_theme( $file_name ) {
    334                 // This used to be a locate_template call.
    335                 // However, that method proved problematic
    336                 // due to its use of constants (STYLESHEETPATH)
    337                 // that threw errors in some scenarios.
    338                 //
    339                 // When the theme.json merge algorithm properly supports
    340                 // child themes, this should also fallback
    341                 // to the template path, as locate_template did.
     342                /*
     343                 * This used to be a locate_template call. However, that method proved problematic
     344                 * due to its use of constants (STYLESHEETPATH) that threw errors in some scenarios.
     345                 *
     346                 * When the theme.json merge algorithm properly supports child themes,
     347                 * this should also fall back to the template path, as locate_template did.
     348                 */
    342349                $located   = '';
    343350                $candidate = get_stylesheet_directory() . '/' . $file_name;
    … …  
    350357        /**
    351358         * Cleans the cached data so it can be recalculated.
     359         *
     360         * @since 5.8.0
    352361         */
    353362        public static function clean_cached_data() {
    354                 self::$core                     = null;
    355                 self::$theme                    = null;
    356                 self::$theme_has_support        = null;
    357                 self::$theme_json_i18n          = null;
     363                self::$core              = null;
     364                self::$theme             = null;
     365                self::$theme_has_support = null;
     366                self::$theme_json_i18n   = null;
    358367        }
    359368

  • trunk/src/wp-includes/class-wp-theme-json.php

    r50959 r50967  
    11<?php
    22/**
    3  * Process of structures that adhere to the theme.json schema.
     3 * WP_Theme_JSON class
    44 *
    55 * @package WordPress
     6 * @subpackage Theme
     7 * @since 5.8.0
    68 */
    79
    810/**
    9  * Class that encapsulates the processing of
    10  * structures that adhere to the theme.json spec.
     11 * Class that encapsulates the processing of structures that adhere to the theme.json spec.
    1112 *
    1213 * @access private
    … …  
    1718         * Container of data in theme.json format.
    1819         *
     20         * @since 5.8.0
    1921         * @var array
    2022         */
    … …  
    2527         * Shared among all instances so we only process it once.
    2628         *
     29         * @since 5.8.0
    2730         * @var array
    2831         */
    … …  
    6366         * Constructor.
    6467         *
     68         * @since 5.8.0
     69         *
    6570         * @param array $theme_json A structure that follows the theme.json schema.
    6671         */
    … …  
    7176                }
    7277
    73                 $this->theme_json  = self::sanitize( $theme_json );
     78                $this->theme_json = self::sanitize( $theme_json );
    7479        }
    7580
    7681        /**
    7782         * Returns the allowed block names.
     83         *
     84         * @since 5.8.0
    7885         *
    7986         * @return array
    … …  
    9299         * Sanitizes the input according to the schemas.
    93100         *
     101         * @since 5.8.0
     102         *
    94103         * @param array $input Structure to sanitize.
    95          *
    96104         * @return array The sanitized output.
    97105         */
    … …  
    144152         * It is recursive and modifies the input in-place.
    145153         *
     154         * @since 5.8.0
     155         *
    146156         * @param array $tree Input to process.
    147157         * @param array $schema Schema to adhere to.
    148          *
    149158         * @return array Returns the modified $tree.
    150159         */
    … …  
    176185         * Example:
    177186         *
    178          * {
    179          *   'root': {
    180          *     'color': {
    181          *       'custom': true
     187         *     {
     188         *       'root': {
     189         *         'color': {
     190         *           'custom': true
     191         *         }
     192         *       },
     193         *       'core/paragraph': {
     194         *         'spacing': {
     195         *           'customPadding': true
     196         *         }
     197         *       }
    182198         *     }
    183          *   },
    184          *   'core/paragraph': {
    185          *     'spacing': {
    186          *       'customPadding': true
    187          *     }
    188          *   }
    189          * }
     199         *
     200         * @since 5.8.0
    190201         *
    191202         * @return array Settings per block.
    … …  
    202213         * Builds metadata for the setting nodes, which returns in the form of:
    203214         *
    204          * [
    205          *   [
    206          *     'path' => ['path', 'to', 'some', 'node' ]
    207          *   ],
    208          *   [
    209          *     'path' => [ 'path', 'to', 'other', 'node' ]
    210          *   ],
    211          * ]
     215         *     [
     216         *       [
     217         *         'path' => ['path', 'to', 'some', 'node' ]
     218         *       ],
     219         *       [
     220         *         'path' => [ 'path', 'to', 'other', 'node' ]
     221         *       ],
     222         *     ]
     223         *
     224         * @since 5.8.0
    212225         *
    213226         * @param array $theme_json The tree to extract setting nodes from.
    214          *
    215227         * @return array
    216228         */
    … …  
    243255         * Merge new incoming data.
    244256         *
     257         * @since 5.8.0
     258         *
    245259         * @param WP_Theme_JSON $incoming Data to merge.
    246260         */
    … …  
    249263                $this->theme_json = array_replace_recursive( $this->theme_json, $incoming_data );
    250264
    251                 // The array_replace_recursive algorithm merges at the leaf level.
    252                 // For leaf values that are arrays it will use the numeric indexes for replacement.
    253                 // In those cases, what we want is to use the incoming value, if it exists.
    254                 //
    255                 // These are the cases that have array values at the leaf levels.
     265                /*
     266                 * The array_replace_recursive algorithm merges at the leaf level.
     267                 * For leaf values that are arrays it will use the numeric indexes for replacement.
     268                 * In those cases, what we want is to use the incoming value, if it exists.
     269                 *
     270                 * These are the cases that have array values at the leaf levels.
     271                 */
    256272                $properties   = array();
    257273                $properties[] = array( 'color', 'palette' );
    … …  
    278294         * Returns the raw data.
    279295         *
     296         * @since 5.8.0
     297         *
    280298         * @return array Raw data.
    281299         */
    … …  
    285303
    286304        /**
    287          *
    288305         * Transforms the given editor settings according the
    289306         * add_theme_support format to the theme.json format.
    290307         *
     308         * @since 5.8.0
     309         *
    291310         * @param array $settings Existing editor settings.
    292          *
    293311         * @return array Config that adheres to the theme.json schema.
    294312         */
    … …  
    365383                }
    366384
    367                 // This allows to make the plugin work with WordPress 5.7 beta
    368                 // as well as lower versions. The second check can be removed
    369                 // as soon as the minimum WordPress version for the plugin
    370                 // is bumped to 5.7.
     385                /*
     386                 * This allows to make the plugin work with WordPress 5.8 beta
     387                 * as well as lower versions. The second check can be removed
     388                 * as soon as the minimum WordPress version for the plugin
     389                 * is bumped to 5.8.
     390                 */
    371391                if ( isset( $settings['enableCustomSpacing'] ) ) {
    372392                        if ( ! isset( $theme_settings['settings']['spacing'] ) ) {

  • trunk/tests/phpunit/tests/theme/wpTheme.php

    r50966 r50967  
    11<?php
    22/**
     3/**
     4 * Test WP_Theme class.
     5 *
     6 * @package WordPress
     7 * @subpackage Theme
     8 *
    39 * @group themes
    410 */
    5 class Tests_Theme_WPTheme extends WP_UnitTestCase {
     11class Tests_Theme_wpTheme extends WP_UnitTestCase {
    612        function setUp() {
    713                parent::setUp();

  • trunk/tests/phpunit/tests/theme/wpThemeJson.php

    r50966 r50967  
    55 *
    66 * @package WordPress
     7 * @subpackage Theme
    78 * @since 5.8.0
     9 *
     10 * @group themes
    811 */
    912
    10 class WP_Theme_JSON_Test extends WP_UnitTestCase {
     13class Tests_Theme_wpThemeJson extends WP_UnitTestCase {
    1114
    1215        /**

  • trunk/tests/phpunit/tests/theme/wpThemeJsonResolver.php

    r50966 r50967  
    55 *
    66 * @package WordPress
     7 * @subpackage Theme
    78 * @since 5.8.0
     9 *
     10 * @group themes
    811 */
    9 
    10 class WP_Theme_JSON_Resolver_Test extends WP_UnitTestCase {
     12class Tests_Theme_wpThemeJsonResolver extends WP_UnitTestCase {
    1113
    1214        function setUp() {
Note: See TracChangeset for help on using the changeset viewer.