Docs: Add PHPStan integer ranges and literal types

src/wp-admin/includes/bookmark.php

@@ -12,6 +12,8 @@
  * @since 2.0.0
  *
  * @return int The link ID on success. The value 0 on failure.
+ *
+ * @phpstan-return non-negative-int
  */
 function add_link() {
 	return edit_link();
@@ -24,6 +26,8 @@ function add_link() {
  *
  * @param int $link_id Optional. ID of the link to edit. Default 0.
  * @return int The link ID on success. The value 0 on failure.
+ *
+ * @phpstan-return non-negative-int
  */
 function edit_link( $link_id = 0 ) {
 	if ( ! current_user_can( 'manage_links' ) ) {
@@ -174,7 +178,7 @@ function get_link_to_edit( $link ) {
  * @param bool  $wp_error Optional. Whether to return a WP_Error object on failure. Default false.
  * @return int|WP_Error The link ID on success. The value 0 or WP_Error on failure.
  *
- * @phpstan-return ( $wp_error is false ? int : int|WP_Error )
+ * @phpstan-return ( $wp_error is false ? non-negative-int : non-negative-int|WP_Error )
  */
 function wp_insert_link( $linkdata, $wp_error = false ) {
 	global $wpdb;
@@ -189,10 +193,14 @@ function wp_insert_link( $linkdata, $wp_error = false ) {
 	$parsed_args = wp_parse_args( $linkdata, $defaults );
 	$parsed_args = wp_unslash( sanitize_bookmark( $parsed_args, 'db' ) );
 
-	$link_id   = $parsed_args['link_id'];
+	$link_id   = (int) $parsed_args['link_id'];
 	$link_name = $parsed_args['link_name'];
 	$link_url  = $parsed_args['link_url'];
 
+	if ( $link_id < 0 ) {
+		return 0;
+	}
+
 	$update = false;
 	if ( ! empty( $link_id ) ) {
 		$update = true;
@@ -301,6 +309,8 @@ function wp_set_link_cats( $link_id = 0, $link_categories = array() ) {
  *
  * @param array $linkdata Link data to update. See wp_insert_link() for accepted arguments.
  * @return int The updated link ID on success. The value 0 on failure.
+ *
+ * @phpstan-return non-negative-int
  */
 function wp_update_link( $linkdata ) {
 	$link_id = (int) $linkdata['link_id'];

src/wp-admin/includes/class-custom-image-header.php

@@ -310,6 +310,8 @@ public function process_default_headers() {
 	 *
 	 * @param string $type The header type. One of 'default' (for the Uploaded Images control)
 	 *                     or 'uploaded' (for the Uploaded Images control).
+	 *
+	 * @phpstan-param 'default'|'uploaded' $type
 	 */
 	public function show_header_selector( $type = 'default' ) {
 		if ( 'default' === $type ) {

src/wp-admin/includes/class-wp-importer.php

@@ -280,8 +280,8 @@ public function min_whitespace( $text ) {
 	 *
 	 * @since 3.0.0
 	 *
-	 * @global wpdb  $wpdb       WordPress database abstraction object.
-	 * @global int[] $wp_actions Stores the number of times each action was triggered.
+	 * @global wpdb                        $wpdb       WordPress database abstraction object.
+	 * @global array<string, positive-int> $wp_actions Stores the number of times each action was triggered.
 	 */
 	public function stop_the_insanity() {
 		global $wpdb, $wp_actions;

src/wp-admin/includes/taxonomy.php

@@ -119,7 +119,7 @@ function wp_create_categories( $categories, $post_id = 0 ) {
  *                      depending on param `$wp_error`.
  *
  * @phpstan-return (
- *     $wp_error is false ? int : int|WP_Error
+ *     $wp_error is false ? non-negative-int : non-negative-int|WP_Error
  * )
  */
 function wp_insert_category( $catarr, $wp_error = false ) {
@@ -188,6 +188,8 @@ function wp_insert_category( $catarr, $wp_error = false ) {
  *
  * @param array $catarr The 'cat_ID' value is required. All other keys are optional.
  * @return int|false The ID number of the new or updated Category on success. Zero or FALSE on failure.
+ *
+ * @phpstan-return non-negative-int|false
  */
 function wp_update_category( $catarr ) {
 	$cat_id = (int) $catarr['cat_ID'];

src/wp-admin/includes/template.php

@@ -1302,6 +1302,8 @@ function _get_plugin_from_callback( $callback ) {
  *                                      Often this is the object that's the focus of the current screen,
  *                                      for example a `WP_Post` or `WP_Comment` object.
  * @return int Number of meta_boxes.
+ *
+ * @phpstan-return non-negative-int
  */
 function do_meta_boxes( $screen, $context, $data_object ) {
 	global $wp_meta_boxes;

src/wp-includes/bookmark.php

@@ -80,16 +80,15 @@ function get_bookmark( $bookmark, $output = OBJECT, $filter = 'raw' ) {
  * @param string $field    The name of the data field to return.
  * @param int    $bookmark The bookmark ID to get field.
  * @param string $context  Optional. The context of how the field will be used. Default 'display'.
- * @return string|WP_Error
+ * @return mixed The sanitized field value, or an empty string if the bookmark or field does not exist.
+ *
+ * @phpstan-param 'link_id'|'link_url'|'link_name'|'link_image'|'link_target'|'link_description'|'link_visible'|'link_owner'|'link_rating'|'link_updated'|'link_rel'|'link_notes'|'link_rss'|'link_category' $field
+ * @phpstan-return ( $field is 'link_category' ? array<int, non-negative-int>|'' : ( $field is 'link_id'|'link_rating' ? int|'' : mixed ) )
  */
 function get_bookmark_field( $field, $bookmark, $context = 'display' ) {
 	$bookmark = (int) $bookmark;
 	$bookmark = get_bookmark( $bookmark );
 
-	if ( is_wp_error( $bookmark ) ) {
-		return $bookmark;
-	}
-
 	if ( ! is_object( $bookmark ) ) {
 		return '';
 	}
@@ -403,6 +402,9 @@ function sanitize_bookmark( $bookmark, $context = 'display' ) {
  * @param string $context     How to filter the field value. Accepts 'raw', 'edit', 'db',
  *                            'display', 'attribute', or 'js'. Default 'display'.
  * @return mixed The filtered value.
+ *
+ * @phpstan-param 'link_id'|'link_url'|'link_name'|'link_image'|'link_target'|'link_description'|'link_visible'|'link_owner'|'link_rating'|'link_updated'|'link_rel'|'link_notes'|'link_rss'|'link_category' $field
+ * @phpstan-return ($field is 'link_category' ? array<int, non-negative-int> : ($field is 'link_id'|'link_rating' ? int : mixed))
  */
 function sanitize_bookmark_field( $field, $value, $bookmark_id, $context ) {
 	$int_fields = array( 'link_id', 'link_rating' );

src/wp-includes/class-wp-locale.php

@@ -118,7 +118,9 @@ class WP_Locale {
 	 * Default is 'words'.
 	 *
 	 * @since 6.2.0
-	 * @var string
+	 * @var string|null
+	 *
+	 * @phpstan-var 'characters_excluding_spaces'|'characters_including_spaces'|'words'|null
 	 */
 	public $word_count_type;
 

src/wp-includes/class-wp-user.php

@@ -58,6 +58,7 @@ class WP_User {
 	 *
 	 * @since 2.1.0
 	 * @var int
+	 * @phpstan-var non-negative-int
 	 */
 	public $ID = 0;
 
@@ -181,11 +182,13 @@ public function __construct( $id = 0, $name = '', $site_id = 0 ) {
 	 * @param int    $site_id Optional. The site ID to initialize for.
 	 */
 	public function init( $data, $site_id = 0 ) {
-		if ( ! isset( $data->ID ) ) {
+		$id = isset( $data->ID ) ? (int) $data->ID : 0;
+		if ( ! isset( $data->ID ) || $id < 0 ) {
+			$id       = 0;
 			$data->ID = 0;
 		}
 		$this->data = $data;
-		$this->ID   = (int) $data->ID;
+		$this->ID   = $id;
 
 		$this->for_site( $site_id );
 	}
@@ -364,7 +367,7 @@ public function __set( $key, $value ) {
 					'<code>WP_User->ID</code>'
 				)
 			);
-			$this->ID = (int) $value;
+			$this->ID = max( 0, (int) $value );
 			return;
 		}
 

src/wp-includes/class-wpdb.php

@@ -116,6 +116,7 @@ class wpdb {
 	 * @since 0.71
 	 *
 	 * @var int
+	 * @phpstan-var non-negative-int
 	 */
 	public $insert_id = 0;
 
@@ -3098,6 +3099,8 @@ public function get_var( $query = null, $x = 0, $y = 0 ) {
 	 *         )
 	 *         : null
 	 * )
+	 *
+	 * @phpstan-param non-negative-int $y
 	 */
 	public function get_row( $query = null, $output = OBJECT, $y = 0 ) {
 		$this->func_call = "\$db->get_row(\"$query\",$output,$y)";

src/wp-includes/comment.php

@@ -1899,6 +1899,8 @@ function wp_unspam_comment( $comment_id ) {
  *
  * @param int|WP_Comment $comment_id Comment ID or WP_Comment object
  * @return string|false Status might be 'trash', 'approved', 'unapproved', 'spam'. False on failure.
+ *
+ * @phpstan-return 'approved'|'spam'|'trash'|'unapproved'|false
  */
 function wp_get_comment_status( $comment_id ) {
 	$comment = get_comment( $comment_id );

src/wp-includes/formatting.php

@@ -2834,6 +2834,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-param non-negative-int $threshold
  * @phpstan-return (
  *     $threshold is 0
  *         ? lowercase-string&non-empty-string&numeric-string
@@ -3005,6 +3006,8 @@ function urldecode_deep( $value ) {
  * @param string $email_address Email address.
  * @param int    $hex_encoding  Optional. Set to 1 to enable hex encoding.
  * @return string Converted email address.
+ *
+ * @phpstan-param 0|1 $hex_encoding
  */
 function antispambot( $email_address, $hex_encoding = 0 ) {
 	$obfuscated     = '';

src/wp-includes/functions.php

@@ -1036,6 +1036,8 @@ function wp_get_http_headers( $url, $deprecated = false ) {
  * @global string $previousday The day of the previous post in the loop.
  *
  * @return int 1 when new day, 0 if not a new day.
+ *
+ * @phpstan-return 0|1
  */
 function is_new_day() {
 	global $currentday, $previousday;
@@ -4485,6 +4487,7 @@ function _wp_die_process_input( $message, $title = '', $args = array() ) {
  *                     greater than 0. Default 512.
  * @return string|false The JSON encoded string, or false if it cannot be encoded.
  *
+ * @phpstan-param positive-int $depth
  * @phpstan-return non-empty-string|false
  */
 function wp_json_encode( $value, $flags = 0, $depth = 512 ) {
@@ -6256,6 +6259,8 @@ function _doing_it_wrong( $function_name, $message, $version ) {
  *                              before passing to this function to avoid being stripped {@see wp_kses()}.
  * @param int    $error_level   Optional. The designated error type for this error.
  *                              Only works with E_USER family of constants. Default E_USER_NOTICE.
+ *
+ * @phpstan-param \E_USER_ERROR|\E_USER_WARNING|\E_USER_NOTICE|\E_USER_DEPRECATED $error_level
  */
 function wp_trigger_error( $function_name, $message, $error_level = E_USER_NOTICE ) {
 	/**
@@ -6692,6 +6697,8 @@ function is_main_network( $network_id = null ) {
  * @since 4.3.0
  *
  * @return int The ID of the main network.
+ *
+ * @phpstan-return non-negative-int
  */
 function get_main_network_id() {
 	if ( ! is_multisite() ) {
@@ -6722,7 +6729,7 @@ function get_main_network_id() {
 	 *
 	 * @param int $main_network_id The ID of the main network.
 	 */
-	return (int) apply_filters( 'get_main_network_id', $main_network_id );
+	return max( 0, (int) apply_filters( 'get_main_network_id', $main_network_id ) );
 }
 
 /**
@@ -7203,6 +7210,8 @@ function __return_false() { // phpcs:ignore WordPress.NamingConventions.ValidFun
  * @since 3.0.0
  *
  * @return int 0.
+ *
+ * @phpstan-return 0
  */
 function __return_zero() { // phpcs:ignore WordPress.NamingConventions.ValidFunctionName.FunctionDoubleUnderscore,PHPCompatibility.FunctionNameRestrictions.ReservedFunctionNames.FunctionDoubleUnderscore
 	return 0;
@@ -7216,6 +7225,8 @@ function __return_zero() { // phpcs:ignore WordPress.NamingConventions.ValidFunc
  * @since 3.0.0
  *
  * @return array Empty array.
+ *
+ * @phpstan-return array{}
  */
 function __return_empty_array() { // phpcs:ignore WordPress.NamingConventions.ValidFunctionName.FunctionDoubleUnderscore,PHPCompatibility.FunctionNameRestrictions.ReservedFunctionNames.FunctionDoubleUnderscore
 	return array();
@@ -7244,6 +7255,8 @@ function __return_null() { // phpcs:ignore WordPress.NamingConventions.ValidFunc
  * @see __return_null()
  *
  * @return string Empty string.
+ *
+ * @phpstan-return ''
  */
 function __return_empty_string() { // phpcs:ignore WordPress.NamingConventions.ValidFunctionName.FunctionDoubleUnderscore,PHPCompatibility.FunctionNameRestrictions.ReservedFunctionNames.FunctionDoubleUnderscore
 	return '';

src/wp-includes/load.php

@@ -11,6 +11,8 @@
  * @since 4.4.0
  *
  * @return string The HTTP protocol. Default: HTTP/1.0.
+ *
+ * @phpstan-return 'HTTP/1.0'|'HTTP/1.1'|'HTTP/2'|'HTTP/2.0'|'HTTP/3'
  */
 function wp_get_server_protocol() {
 	$protocol = $_SERVER['SERVER_PROTOCOL'] ?? '';
@@ -1509,6 +1511,8 @@ function absint( $maybeint ): int {
  * @global int $blog_id
  *
  * @return int Site ID.
+ *
+ * @phpstan-return non-negative-int
  */
 function get_current_blog_id() {
 	global $blog_id;
@@ -1522,6 +1526,8 @@ function get_current_blog_id() {
  * @since 4.6.0
  *
  * @return int The ID of the current network.
+ *
+ * @phpstan-return non-negative-int
  */
 function get_current_network_id() {
 	if ( ! is_multisite() ) {

src/wp-includes/pluggable.php

@@ -1375,7 +1375,7 @@ function auth_redirect() {
 	 *                   2 if the nonce is valid and generated between 12-24 hours ago.
 	 *                   False if the nonce is invalid. Only possible when `$action` is -1,
 	 *                   as the function otherwise exits rather than returning false.
-	 * @phpstan-return ( $action is -1 ? int|false : int )
+	 * @phpstan-return ( $action is -1 ? 1|2|false : 1|2 )
 	 */
 	function check_admin_referer( $action = -1, $query_arg = '_wpnonce' ) {
 		if ( -1 === $action ) {
@@ -1422,7 +1422,7 @@ function check_admin_referer( $action = -1, $query_arg = '_wpnonce' ) {
 	 *                   2 if the nonce is valid and generated between 12-24 hours ago.
 	 *                   False if the nonce is invalid. Only possible when `$stop` is false,
 	 *                   as the function otherwise exits rather than returning false.
-	 * @phpstan-return ( $stop is true ? int : int|false )
+	 * @phpstan-return ( $stop is true ? 1|2 : 1|2|false )
 	 */
 	function check_ajax_referer( $action = -1, $query_arg = false, $stop = true ) {
 		if ( -1 === $action ) {
@@ -2477,6 +2477,8 @@ function wp_nonce_tick( $action = -1 ) {
 	 * @return int|false 1 if the nonce is valid and generated between 0-12 hours ago,
 	 *                   2 if the nonce is valid and generated between 12-24 hours ago.
 	 *                   False if the nonce is invalid.
+	 *
+	 * @phpstan-return 1|2|false
 	 */
 	function wp_verify_nonce( $nonce, $action = -1 ) {
 		$nonce = (string) $nonce;