WordPress.org
Get WordPress

Make WordPress Core

Changeset 62966


Ignore:
Timestamp:
08/02/2026 07:05:51 AM (3 months ago)
Author:
westonruter
Message:

Docs: Improve block asset registration docblocks.

Per the inline documentation standards, a docblock's summary belongs on its own line separated from the description, and the description should not open with "It". This is applied to register_block_script_module_id(), register_block_script_handle(), and register_block_style_handle(), together with some missing articles in the same descriptions.

Two of those descriptions no longer matched the code. register_block_script_handle() said the script is registered under an automatically generated handle, but since 6.5.0 the handle is taken from the asset file whenever one provides it, and generation is only the fallback. register_block_style_handle() said it returns the unprocessed style handle otherwise, which does not hold for the first style of a core block: that one is registered from the block's own stylesheet when separate core block assets are loaded, and skipped entirely when they are not.

The same functions gain @phpstan- annotations describing the shape of the $metadata they accept and the narrower strings they return. The shapes follow the block.json schema, which constrains only name, so the remaining fields stay plain strings; file is nullable and name optional because register_block_type_from_metadata() can reach all three functions with neither present.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/11851.
Follow-up to r48141, r55447, r57559, r57565.

Props deepakrohilla, westonruter, sabernhardt, wildworks, audrasjb.
See #64898.
Fixes #65259.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/wp-includes/blocks.php

    r62726 r62966  
    4444 *                           Default 0.
    4545 * @return string Generated asset name for the block's field.
     46 *
     47 * @phpstan-param non-falsy-string $block_name
     48 * @phpstan-param 'editorScript'|'editorStyle'|'script'|'style'|'viewScript'|'viewScriptModule'|'viewStyle' $field_name
     49 * @phpstan-param int<0, max> $index
     50 * @phpstan-return non-falsy-string
    4651 */
    4752function generate_block_asset_handle( $block_name, $field_name, $index = 0 ) {
    … …  
    8792 * @param string $path A normalized path to a block asset.
    8893 * @return string|false The URL to the block asset or false on failure.
     94 *
     95 * @phpstan-return non-falsy-string|false
    8996 */
    9097function get_block_asset_url( $path ) {
    … …  
    103110        }
    104111
     112        /** @var array<string, string> $template_paths_norm */
    105113        static $template_paths_norm = array();
    106114
    … …  
    129137
    130138/**
    131  * Finds a script module ID for the selected block metadata field. It detects
    132  * when a path to file was provided and optionally finds a corresponding asset
    133  * file with details necessary to register the script module under with an
    134  * automatically generated module ID. It returns unprocessed script module
    135  * ID otherwise.
     139 * Finds a script module ID for the selected block metadata field.
     140 *
     141 * Detects when a path to a file was provided and optionally finds a
     142 * corresponding asset file with details necessary to register the script
     143 * module with an automatically generated module ID. It returns the
     144 * unprocessed script module ID otherwise.
    136145 *
    137146 * @since 6.5.0
    … …  
    142151 *                           items passed. Default 0.
    143152 * @return string|false Script module ID or false on failure.
     153 *
     154 * @phpstan-param array{
     155 *     name?: non-falsy-string,
     156 *     file: non-falsy-string|null,
     157 *     version?: string,
     158 *     supports?: array{
     159 *         interactivity?: bool|array{interactive?: bool, clientNavigation?: bool, ...},
     160 *         ...
     161 *     },
     162 *     viewScriptModule?: string|list<string>,
     163 *     ...
     164 * } $metadata
     165 * @phpstan-param 'viewScriptModule' $field_name
     166 * @phpstan-param int<0, max> $index
     167 * @phpstan-return non-falsy-string|false
    144168 */
    145169function register_block_script_module_id( $metadata, $field_name, $index = 0 ) {
    … …  
    171195        $module_uri       = get_block_asset_url( $module_path_norm );
    172196
     197        /** @var array{ dependencies?: list<non-falsy-string|array{id: non-falsy-string, import?: 'static'|'dynamic'}>, version?: string|false|null, ... } $module_asset */
    173198        $module_asset        = ! empty( $module_asset_path ) ? require $module_asset_path : array();
    174199        $module_dependencies = $module_asset['dependencies'] ?? array();
    … …  
    207232
    208233/**
    209  * Finds a script handle for the selected block metadata field. It detects
    210  * when a path to file was provided and optionally finds a corresponding asset
    211  * file with details necessary to register the script under automatically
    212  * generated handle name. It returns unprocessed script handle otherwise.
     234 * Finds a script handle for the selected block metadata field.
     235 *
     236 * Detects when a path to a file was provided and optionally finds a
     237 * corresponding asset file with details necessary to register the script. The
     238 * handle is taken from the asset file when it provides one, and is otherwise
     239 * generated automatically. It returns the unprocessed script handle when a
     240 * handle rather than a path was given.
    213241 *
    214242 * @since 5.5.0
    … …  
    222250 * @return string|false Script handle provided directly or created through
    223251 *                      script's registration, or false on failure.
     252 *
     253 * @phpstan-param array{
     254 *     name?: non-falsy-string,
     255 *     file: non-falsy-string|null,
     256 *     version?: string,
     257 *     textdomain?: string,
     258 *     editorScript?: string|list<string>,
     259 *     script?: string|list<string>,
     260 *     viewScript?: string|list<string>,
     261 *     ...
     262 * } $metadata
     263 * @phpstan-param 'editorScript'|'script'|'viewScript' $field_name
     264 * @phpstan-param int<0, max> $index
     265 * @phpstan-return non-falsy-string|false
    224266 */
    225267function register_block_script_handle( $metadata, $field_name, $index = 0 ) {
    … …  
    248290
    249291        // Asset file for blocks is optional. See https://core.trac.wordpress.org/ticket/60460.
     292        /** @var array{ handle?: non-falsy-string, dependencies?: list<non-falsy-string>, version?: string|false|null, ... } $script_asset */
    250293        $script_asset  = ! empty( $script_asset_path ) ? require $script_asset_path : array();
    251294        $script_handle = $script_asset['handle'] ??
    … …  
    284327
    285328/**
    286  * Finds a style handle for the block metadata field. It detects when a path
    287  * to file was provided and registers the style under automatically
    288  * generated handle name. It returns unprocessed style handle otherwise.
     329 * Finds a style handle for the block metadata field.
     330 *
     331 * Detects when a path to a file was provided and registers the style under an
     332 * automatically generated handle name. It returns the unprocessed style handle
     333 * otherwise, except for the first style of a core block, which is instead
     334 * registered from the block's own stylesheet when separate core block assets
     335 * are loaded. Core blocks accept only handles, not paths.
    289336 *
    290337 * @since 5.5.0
    … …  
    297344 * @return string|false Style handle provided directly or created through
    298345 *                      style's registration, or false on failure.
     346 *
     347 * @phpstan-param array{
     348 *     name?: non-falsy-string,
     349 *     file: non-falsy-string|null,
     350 *     version?: string,
     351 *     editorStyle?: string|list<string>,
     352 *     style?: string|list<string>,
     353 *     viewStyle?: string|list<string>,
     354 *     ...
     355 * } $metadata
     356 * @phpstan-param 'editorStyle'|'style'|'viewStyle' $field_name
     357 * @phpstan-param int<0, max> $index
     358 * @phpstan-return non-falsy-string|false
    299359 */
    300360function register_block_style_handle( $metadata, $field_name, $index = 0 ) {
    … …  
    27792839                                /*
    27802840                                 * Passing an empty array to post__in will return have_posts() as true (and all posts will be returned).
    2781                                  * Logic should be used before hand to determine if WP_Query should be used in the event that the array
     2841                                 * Logic should be used beforehand to determine if WP_Query should be used in the event that the array
    27822842                                 * being passed to post__in is empty.
    27832843                                 *
Note: See TracChangeset for help on using the changeset viewer.