About Docblock in wp_style_add_data

[tmatsuur]

In version 5.8, I think 'path' can be specified in the parameter $key, but there is no mention of this in Docblock.

I think it is also important to add that if the pathname specified in $value is an absolute path, it will be output inline.

[hilayt24]

Hi @tmatsuur thank you for the ticket. Can you please provide some more details.

[tmatsuur]

Thanks @hilayt24

In the docblock of the wp_maybe_inline_styles function, which was added in version 5.8, there is a statement like this

 * This improves performance and sustainability, and is opt-in. Stylesheets can opt in
 * by adding `path` data using `wp_style_add_data`, and defining the file's absolute path:
 *
 *     wp_style_add_data( $style_handle, 'path', $file_path );

In the docblock of the wp_style_add_data function in version 5.8.1, there is no description of "path" for the second parameter.

/**
 * Add metadata to a CSS stylesheet.
 *
 * Works only if the stylesheet has already been added.
 *
 * Possible values for $key and $value:
 * 'conditional' string      Comments for IE 6, lte IE 7 etc.
 * 'rtl'         bool|string To declare an RTL stylesheet.
 * 'suffix'      string      Optional suffix, used in combination with RTL.
 * 'alt'         bool        For rel="alternate stylesheet".
 * 'title'       string      For preferred/alternate stylesheets.
 *
 * @see WP_Dependencies::add_data()
 *
 * @since 3.6.0
 *
 * @param string $handle Name of the stylesheet.
 * @param string $key    Name of data point for which we're storing a value.
 *                       Accepts 'conditional', 'rtl' and 'suffix', 'alt' and 'title'.
 * @param mixed  $value  String containing the CSS data to be added.
 * @return bool True on success, false on failure.
 */

An example of the use of "path" as the second parameter of the wp_style_add_data function is the register_block_style_handle function added in version 5.5.

Lines 169 - 171 of wp-includes/blocks.php

	if ( $has_style_file ) {
		wp_style_add_data( $style_handle, 'path', $style_file );
	}

This made me think that the docblock of the wp_style_add_data function needs to be modified.

[desrosj]

Thanks @tmatsuur for the additional details! Indeed this should be noted in the docblock. 53792.diff​ adds this.

[desrosj]

In 52216:

Script Loader: Document path as an accepted value for $key in wp_style_add_data().

Follow up to [50836].

Props tmatsuur.
Fixes #53792.