WordPress.org
Get WordPress

Make WordPress Core

Changeset 50967


Ignore:
Timestamp:
05/24/2021 01:24:05 PM (4 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.