Docs: Add PHPStan purity annotations

src/wp-admin/includes/image-edit.php

@@ -525,6 +525,8 @@ function wp_save_image_file( $filename, $image, $mime_type, $post_id ) {
  * @param int $w Image width in pixels.
  * @param int $h Image height in pixels.
  * @return float|int Image preview ratio.
+ *
+ * @phpstan-pure
  */
 function _image_get_preview_ratio( $w, $h ) {
 	$max = max( $w, $h );

src/wp-admin/includes/image.php

@@ -757,6 +757,8 @@ function wp_generate_attachment_metadata( $attachment_id, $file ) {
  *
  * @param string $str Fraction string.
  * @return int|float Returns calculated fraction or integer 0 on invalid input.
+ *
+ * @phpstan-pure
  */
 function wp_exif_frac2dec( $str ) {
 	if ( ! is_scalar( $str ) || is_bool( $str ) ) {

src/wp-admin/includes/media.php

@@ -1351,6 +1351,7 @@ function image_link_input_fields( $post, $url_type = '' ) {
  * @param WP_Post $edit_post Attachment WP_Post object.
  * @return string HTML markup for the textarea element.
  *
+ * @phpstan-pure
  * @phpstan-return non-falsy-string
  */
 function wp_caption_input_textarea( $edit_post ) {

src/wp-admin/includes/menu.php

@@ -211,6 +211,7 @@
  *
  * @phpstan-template T of string
  * @phpstan-param T $class_to_add
+ * @phpstan-pure
  * @phpstan-return ( $classes is empty ? T : non-empty-string )
  */
 function add_cssclass( $class_to_add, $classes ) {

src/wp-admin/includes/misc.php

@@ -363,6 +363,8 @@ function update_recently_edited( $file ) {
  *
  * @param array $allowed_files List of theme file paths.
  * @return array Tree structure for listing theme files.
+ *
+ * @phpstan-pure
  */
 function wp_make_theme_file_tree( $allowed_files ) {
 	$tree_list = array();

src/wp-admin/includes/upgrade.php

@@ -3640,6 +3640,8 @@ function make_site_theme() {
  *
  * @param int $level User level.
  * @return string User role name.
+ *
+ * @phpstan-pure
  */
 function translate_level_to_role( $level ) {
 	switch ( $level ) {

src/wp-includes/abilities-api.php

@@ -592,6 +592,8 @@ function wp_get_abilities( array $args = array() ): array {
  * @param array $meta       The ability's meta array.
  * @param array $conditions The required key/value conditions to match against.
  * @return bool True if all conditions match, false otherwise.
+ *
+ * @phpstan-pure
  */
 function _wp_get_abilities_match_meta( array $meta, array $conditions ): bool {
 	foreach ( $conditions as $key => $value ) {

src/wp-includes/block-editor.php

@@ -397,6 +397,8 @@ function _wp_get_iframed_editor_assets() {
  * @param array  $blocks     Array of blocks.
  * @param string $block_name Name of the block to find.
  * @return array Found block, or empty array if none found.
+ *
+ * @phpstan-pure
  */
 function wp_get_first_block( $blocks, $block_name ) {
 	foreach ( $blocks as $block ) {

src/wp-includes/block-patterns.php

@@ -252,6 +252,8 @@ function _register_core_block_patterns_and_categories() {
  *
  * @param array $pattern Pattern as returned from the Pattern Directory API.
  * @return array Normalized pattern.
+ *
+ * @phpstan-pure
  */
 function wp_normalize_remote_block_pattern( $pattern ) {
 	if ( isset( $pattern['block_types'] ) ) {

src/wp-includes/block-supports/dimensions.php

@@ -94,6 +94,8 @@ function wp_apply_dimensions_support( $block_type, $block_attributes ) {
  *
  * @param mixed $aspect_ratio Aspect-ratio value.
  * @return bool Whether the value is an explicit aspect ratio.
+ *
+ * @phpstan-pure
  */
 function wp_is_explicit_aspect_ratio_value( $aspect_ratio ) {
 	if ( ! is_string( $aspect_ratio ) && ! is_numeric( $aspect_ratio ) ) {

src/wp-includes/block-supports/elements.php

@@ -29,6 +29,8 @@ function wp_get_elements_class_name(): string {
  * @param array $block   Block object.
  * @param array $options Per element type options e.g. whether to skip serialization.
  * @return bool Whether the block needs an elements class name.
+ *
+ * @phpstan-pure
  */
 function wp_should_add_elements_class_name( $block, $options ) {
 	if ( ! isset( $block['attrs']['style']['elements'] ) ) {

src/wp-includes/block-supports/layout.php

@@ -44,6 +44,8 @@ function wp_get_block_style_variation_name_from_registered_style( string $class_
  *
  * @param mixed $layout Layout object.
  * @return array Child layout values, or an empty array.
+ *
+ * @phpstan-pure
  */
 function wp_get_layout_child_values( $layout ) {
 	if ( ! is_array( $layout ) ) {
@@ -63,6 +65,8 @@ function wp_get_layout_child_values( $layout ) {
  *
  * @param mixed $layout Layout object.
  * @return array Container layout values, or an empty array.
+ *
+ * @phpstan-pure
  */
 function wp_get_layout_container_values( $layout ) {
 	if ( ! is_array( $layout ) ) {
@@ -300,6 +304,8 @@ function wp_get_child_layout_style_rules( $selector, $child_layout, $parent_layo
  * @access private
  *
  * @return array[] Layout definitions.
+ *
+ * @phpstan-pure
  */
 function wp_get_layout_definitions() {
 	$layout_definitions = array(

src/wp-includes/block-supports/states.php

@@ -78,6 +78,8 @@ function wp_normalize_state_style_for_css_output( $style ) {
  *
  * @param array $declarations CSS declarations generated by the style engine.
  * @return array CSS declarations with fallback border styles applied where needed.
+ *
+ * @phpstan-pure
  */
 function wp_get_state_declarations_with_fallback_border_styles( $declarations ) {
 	if ( ! is_array( $declarations ) ) {
@@ -123,6 +125,8 @@ function wp_get_state_declarations_with_fallback_border_styles( $declarations )
  *
  * @param array $declarations CSS declarations generated by the style engine.
  * @return array CSS declarations with background resets applied where needed.
+ *
+ * @phpstan-pure
  */
 function wp_get_state_declarations_with_background_resets( $declarations ) {
 	if ( ! is_array( $declarations ) ) {
@@ -154,6 +158,8 @@ function wp_get_state_declarations_with_background_resets( $declarations ) {
  *
  * @param array $state_style State style object.
  * @return array State style object with fallback dimension styles applied where needed.
+ *
+ * @phpstan-pure
  */
 function wp_get_state_style_with_fallback_dimension_styles( $state_style ) {
 	if ( ! is_array( $state_style ) ) {
@@ -295,6 +301,8 @@ function wp_get_state_style_groups( $state_style, $block_selectors ) {
  * @param array $state_style State style object.
  * @param array $nested_keys Keys to remove from the root style object.
  * @return array Root-only style object.
+ *
+ * @phpstan-pure
  */
 function wp_get_root_state_style( $state_style, $nested_keys ) {
 	if ( ! is_array( $state_style ) ) {

src/wp-includes/blocks.php

@@ -1391,6 +1391,8 @@ function apply_block_hooks_to_content_from_post_object(
  *
  * @param string $serialized_block The serialized markup of a block and its inner blocks.
  * @return string The serialized markup of the inner blocks.
+ *
+ * @phpstan-pure
  */
 function remove_serialized_parent_block( $serialized_block ) {
 	$start = strpos( $serialized_block, '-->' ) + strlen( '-->' );
@@ -1408,6 +1410,8 @@ function remove_serialized_parent_block( $serialized_block ) {
  *
  * @param string $serialized_block The serialized markup of a block and its inner blocks.
  * @return string The serialized markup of the wrapper block.
+ *
+ * @phpstan-pure
  */
 function extract_serialized_parent_block( $serialized_block ) {
 	$start = strpos( $serialized_block, '-->' ) + strlen( '-->' );
@@ -1597,6 +1601,8 @@ function insert_hooked_blocks_into_rest_response( $response, $post ) {
  *                                                       Default: 'insert_hooked_blocks'.
  * @return callable A function that returns the serialized markup for the given block,
  *                  including the markup for any hooked blocks before it.
+ *
+ * @phpstan-pure
  */
 function make_before_block_visitor( $hooked_blocks, $context, $callback = 'insert_hooked_blocks' ) {
 	/**
@@ -1654,6 +1660,8 @@ function make_before_block_visitor( $hooked_blocks, $context, $callback = 'inser
  *                                                       Default: 'insert_hooked_blocks'.
  * @return callable A function that returns the serialized markup for the given block,
  *                  including the markup for any hooked blocks after it.
+ *
+ * @phpstan-pure
  */
 function make_after_block_visitor( $hooked_blocks, $context, $callback = 'insert_hooked_blocks' ) {
 	/**
@@ -3086,6 +3094,7 @@ static function ( $format ) {
  * @param bool     $is_next Flag for handling `next/previous` blocks.
  * @return string|null The pagination arrow HTML or null if there is none.
  *
+ * @phpstan-pure
  * @phpstan-return non-falsy-string|null
  */
 function get_query_pagination_arrow( $block, $is_next ) {
@@ -3188,6 +3197,7 @@ function build_comment_query_vars_from_block( $block ) {
  *                                  Accepts 'next' or 'previous'. Default 'next'.
  * @return string|null The pagination arrow HTML or null if there is none.
  *
+ * @phpstan-pure
  * @phpstan-return non-falsy-string|null
  */
 function get_comments_pagination_arrow( $block, $pagination_type = 'next' ) {

src/wp-includes/category-template.php

@@ -803,6 +803,8 @@ function wp_tag_cloud( $args = '' ) {
  *
  * @param int $count Number of posts with that tag.
  * @return int Scaled count.
+ *
+ * @phpstan-pure
  */
 function default_topic_count_scale( $count ) {
 	return (int) round( log10( $count + 1 ) * 100 );

src/wp-includes/connectors.php

@@ -418,6 +418,8 @@ function _wp_connectors_register_default_ai_providers( WP_Connector_Registry $re
  *
  * @param string $key The API key to mask.
  * @return string The masked key, e.g. "************fj39".
+ *
+ * @phpstan-pure
  */
 function _wp_connectors_mask_api_key( string $key ): string {
 	if ( strlen( $key ) <= 4 ) {
@@ -480,6 +482,8 @@ function _wp_connectors_get_api_key_source( string $setting_name, string $env_va
  * @param string $value The raw credentials string.
  * @return array{username: string, password: string} Parsed credentials. Both values
  *                                                   are empty when the string is malformed.
+ *
+ * @phpstan-pure
  */
 function wp_connectors_parse_application_password_credentials( string $value ): array {
 	$separator = strpos( $value, ':' );

src/wp-includes/formatting.php

@@ -727,6 +727,8 @@ function _get_wptexturize_split_regex( $shortcode_regex = '' ) {
  *
  * @param string[] $tagnames Array of shortcodes to find.
  * @return string The regular expression.
+ *
+ * @phpstan-pure
  */
 function _get_wptexturize_shortcode_regex( $tagnames ) {
 	$tagregexp = implode( '|', array_map( 'preg_quote', $tagnames ) );
@@ -2834,6 +2836,7 @@ function format_to_edit( $content, $rich_text = false ) {
  * @param int $threshold  Digit places number needs to be to not have zeros added.
  * @return string Adds leading zeros to number if needed.
  *
+ * @phpstan-pure
  * @phpstan-return (
  *     $threshold is 0
  *         ? lowercase-string&non-empty-string&numeric-string
@@ -2855,6 +2858,8 @@ function zeroise( $number, $threshold ) {
  *
  * @param string $value Value to which backslashes will be added.
  * @return string String with backslashes inserted.
+ *
+ * @phpstan-pure
  */
 function backslashit( $value ) {
 	if ( isset( $value[0] ) && $value[0] >= '0' && $value[0] <= '9' ) {
@@ -2878,6 +2883,7 @@ function backslashit( $value ) {
  * @return string String with trailing slash added.
  *
  * @phpstan-return non-falsy-string
+ * @phpstan-pure
  */
 function trailingslashit( $value ) {
 	return untrailingslashit( $value ) . '/';
@@ -2893,6 +2899,8 @@ function trailingslashit( $value ) {
  *
  * @param string $value Value from which trailing slashes will be removed.
  * @return string String without the trailing slashes.
+ *
+ * @phpstan-pure
  */
 function untrailingslashit( $value ) {
 	return rtrim( $value, '/\\' );
@@ -3306,6 +3314,8 @@ function make_clickable( $text ) {
  * @param string $text   The string to split.
  * @param int    $goal   The desired chunk length.
  * @return array Numeric array of chunks.
+ *
+ * @phpstan-pure
  */
 function _split_str_by_whitespace( $text, $goal ) {
 	$chunks = array();
@@ -5839,6 +5849,8 @@ function _sanitize_text_fields( $str, $keep_newlines = false ) {
  * @param string $path   A path.
  * @param string $suffix If the filename ends in suffix this will also be cut off.
  * @return string The base name of the given path.
+ *
+ * @phpstan-pure
  */
 function wp_basename( $path, $suffix = '' ) {
 	return urldecode( basename( str_replace( array( '%2F', '%5C' ), '/', urlencode( $path ) ), $suffix ) );
@@ -5945,6 +5957,8 @@ function sanitize_trackback_urls( $to_ping ) {
  *         T is array ? array<key-of<T>, ( value-of<T> is string ? string : value-of<T> )> : T
  *     )
  * )
+ *
+ * @phpstan-pure
  */
 function wp_slash( $value ) {
 	if ( is_array( $value ) ) {
@@ -6374,6 +6388,8 @@ function wp_staticize_emoji_for_email( $mail ) {
  *
  * @param string $type Optional. Which array type to return. Accepts 'partials' or 'entities', default 'entities'.
  * @return array An array to match all emoji that WordPress recognises.
+ *
+ * @phpstan-pure
  */
 function _wp_emoji_list( $type = 'entities' ) {
 	// Do not remove the START/END comments - they're used to find where to insert the arrays.
@@ -6399,6 +6415,8 @@ function _wp_emoji_list( $type = 'entities' ) {
  * @param string $url    URL to shorten.
  * @param int    $length Optional. Maximum length of the shortened URL. Default 35 characters.
  * @return string Shortened URL.
+ *
+ * @phpstan-pure
  */
 function url_shorten( $url, $length = 35 ) {
 	$stripped  = str_replace( array( 'https://', 'http://', 'www.' ), '', $url );