Make WordPress Core


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.

File:
1 edited

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
Note: See TracChangeset for help on using the changeset viewer.