Skip to content

Commit 03e7452

Browse files
justlevinejustlevine
committed
PHPStan: improve @phpstan-return types for ambiguous unions
1 parent 614a8f4 commit 03e7452

23 files changed

Lines changed: 239 additions & 62 deletions

‎src/wp-admin/includes/bookmark.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -171,7 +171,7 @@ function get_link_to_edit( $link ) {
171171
* @param bool $wp_error Optional. Whether to return a WP_Error object on failure. Default false.
172172
* @return int|WP_Error Value 0 or WP_Error on failure. The link ID on success.
173173
*
174-
* @phpstan-return ($wp_error is false ? int<0, max> : int<1, max>|\WP_Error)
174+
* @phpstan-return ( $wp_error is false ? int<0, max> : (int<1, max>|\WP_Error) )
175175
*/
176176
function wp_insert_link( $linkdata, $wp_error = false ) {
177177
global $wpdb;

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -135,7 +135,7 @@ public function get_imported_comments( $blog_id ) {
135135
*
136136
* @phpstan-param int|string $blog_id
137137
*
138-
* @phpstan-return ( $blog_id is int|numeric-string ? int : int|never )
138+
* @phpstan-return ( $blog_id is (int|numeric-string) ? int : (int|never) )
139139
*/
140140
public function set_blog( $blog_id ) {
141141
if ( is_numeric( $blog_id ) ) {

‎src/wp-admin/includes/post.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -979,7 +979,7 @@ function wp_write_post() {
979979
*
980980
* @since 2.0.0
981981
*
982-
* @return int|void Post ID on success, void on failure.
982+
* @return int Post ID on success, dies on failure.
983983
*/
984984
function write_post() {
985985
$result = wp_write_post();

‎src/wp-admin/includes/taxonomy.php‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -118,7 +118,7 @@ function wp_create_categories( $categories, $post_id = 0 ) {
118118
* @return int|WP_Error The ID number of the new or updated Category on success. Zero or a WP_Error on failure,
119119
* depending on param `$wp_error`.
120120
*
121-
* @phpstan-return ($wp_error is false ? int<0, max> : int<1, max>|\WP_Error)
121+
* @phpstan-return ($wp_error is false ? int<0, max> : (int<1, max>|\WP_Error) )
122122
*/
123123
function wp_insert_category( $catarr, $wp_error = false ) {
124124
$cat_defaults = array(
@@ -221,7 +221,13 @@ function wp_update_category( $catarr ) {
221221
* Returns an array of the term ID and the term taxonomy ID if the pairing exists.
222222
* Returns 0 if term ID 0 is passed to the function.
223223
*
224-
* @phpstan-return ($tag_name is 0 ? 0 : ($tag_name is '' ? null : array{term_id: string, term_taxonomy_id: string}|null))
224+
* @phpstan-return (
225+
* $tag_name is 0 ? 0 : (
226+
* $tag_name is '' ? null : (
227+
* array{term_id: string, term_taxonomy_id: string}|null
228+
* )
229+
* )
230+
* )
225231
*/
226232
function tag_exists( $tag_name ) {
227233
return term_exists( $tag_name, 'post_tag' );

‎src/wp-includes/category-template.php‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -535,7 +535,7 @@ function wp_dropdown_categories( $args = '' ) {
535535
* @return void|string|false Void if 'echo' argument is true, HTML list of categories if 'echo' is false.
536536
* False if the taxonomy does not exist.
537537
*
538-
* @phpstan-return ($args is array{echo: false|0}&array ? string|false : false|void)
538+
* @phpstan-return ($args is array{echo: false|0}&array ? (string|false) : (false|void) )
539539
*/
540540
function wp_list_categories( $args = '' ) {
541541
$defaults = array(
@@ -715,7 +715,7 @@ function wp_list_categories( $args = '' ) {
715715
* @return void|string|string[] Void if 'echo' argument is true, or on failure. Otherwise, tag cloud
716716
* as a string or an array, depending on 'format' argument.
717717
*
718-
* @phpstan-return ($args is array{format: 'array'}&array ? array<int, string>|void : ($args is array{echo: false|0}&array ? string|void : void))
718+
* @phpstan-return ($args is array{format: 'array'}&array ? (array<int, string>|void) : ($args is array{echo: false|0}&array ? (string|void) : void))
719719
*/
720720
function wp_tag_cloud( $args = '' ) {
721721
$defaults = array(

‎src/wp-includes/category.php‎

Lines changed: 43 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,17 @@
2323
* }
2424
* @return array List of category objects.
2525
*
26-
* @phpstan-return ($args is array{fields: 'count'}&array ? list<numeric-string> : ($args is array{fields: 'names'|'slugs'}&array ? list<string> : ($args is array{fields: 'id=>name'|'id=>slug'}&array ? array<int, string> : ($args is array{fields: 'id=>parent'}&array ? array<int, int> : ($args is array{fields: 'ids'|'tt_ids'}&array ? list<int> : array<int, \WP_Term>)))))
26+
* @phpstan-return (
27+
* $args is array{fields: 'count'}&array ? list<numeric-string> : (
28+
* $args is array{fields: 'names'|'slugs'}&array ? list<string> : (
29+
* $args is array{fields: 'id=>name'|'id=>slug'}&array ? array<int, string> : (
30+
* $args is array{fields: 'id=>parent'}&array ? array<int, int> : (
31+
* $args is array{fields: 'ids'|'tt_ids'}&array ? list<int> : array<int, \WP_Term>
32+
* )
33+
* )
34+
* )
35+
* )
36+
* )
2737
*/
2838
function get_categories( $args = '' ) {
2939
$defaults = array( 'taxonomy' => 'category' );
@@ -92,7 +102,22 @@ function get_categories( $args = '' ) {
92102
* WP_Error if $category is empty, null if it does not exist.
93103
*
94104
* @phpstan-param 'OBJECT'|'ARRAY_A'|'ARRAY_N' $output
95-
* @phpstan-return ($category is object ? array<array-key, mixed>|\WP_Term : array<array-key, mixed>|\WP_Term|\WP_Error|null) & ($output is 'ARRAY_A' ? array<string, mixed>|\WP_Error|null : ($output is 'ARRAY_N' ? array<int, mixed>|\WP_Error|null : \WP_Term|\WP_Error|null))
105+
* @phpstan-return (
106+
* $category is object ? (
107+
* array<array-key, mixed>|\WP_Term
108+
* ) : (
109+
* array<array-key, mixed>|\WP_Term|\WP_Error|null) & (
110+
* $output is 'ARRAY_A' ?
111+
* ( array<string, mixed>|\WP_Error|null )
112+
* : (
113+
* $output is 'ARRAY_N' ?
114+
* ( array<int, mixed>|\WP_Error|null)
115+
* : ( \WP_Term|\WP_Error|null )
116+
* )
117+
* )
118+
* )
119+
* )
120+
* )
96121
*/
97122
function get_category( $category, $output = OBJECT, $filter = 'raw' ) {
98123
$category = get_term( $category, 'category', $output, $filter );
@@ -130,7 +155,11 @@ function get_category( $category, $output = OBJECT, $filter = 'raw' ) {
130155
* Returns null if it does not exist.
131156
*
132157
* @phpstan-param 'OBJECT'|'ARRAY_A'|'ARRAY_N' $output
133-
* @phpstan-return ($output is 'ARRAY_A' ? array<string, mixed>|\WP_Error|null : ($output is 'ARRAY_N' ? array<int, mixed>|\WP_Error|null : \WP_Term|\WP_Error|null))
158+
* @phpstan-return (
159+
* $output is 'ARRAY_A' ? (array<string, mixed>|\WP_Error|null) : (
160+
* $output is 'ARRAY_N' ? (array<int, mixed>|\WP_Error|null) : (\WP_Term|\WP_Error|null)
161+
* )
162+
* )
134163
*/
135164
function get_category_by_path( $category_path, $full_match = true, $output = OBJECT ) {
136165
$category_path = rawurlencode( urldecode( $category_path ) );
@@ -306,7 +335,17 @@ function sanitize_category_field( $field, $value, $cat_id, $context ) {
306335
* @return WP_Term[]|int|WP_Error Array of 'post_tag' term objects, a count thereof,
307336
* or WP_Error if any of the taxonomies do not exist.
308337
*
309-
* @phpstan-return ($args is array{fields: 'count'}&array ? numeric-string : ($args is array{fields: 'names'|'slugs'}&array ? list<string> : ($args is array{fields: 'id=>name'|'id=>slug'}&array ? array<int, string> : ($args is array{fields: 'id=>parent'}&array ? array<int, int> : ($args is array{fields: 'ids'|'tt_ids'}&array ? list<int> : array<int, \WP_Term>)))))|\WP_Error
338+
* @phpstan-return (
339+
* $args is array{fields: 'count'}&array ? numeric-string : (
340+
* $args is array{fields: 'names'|'slugs'}&array ? list<string> : (
341+
* $args is array{fields: 'id=>name'|'id=>slug'}&array ? array<int, string> : (
342+
* $args is array{fields: 'id=>parent'}&array ? array<int, int> : (
343+
* $args is array{fields: 'ids'|'tt_ids'}&array ? list<int> : array<int, \WP_Term>
344+
* )
345+
* )
346+
* )
347+
* )
348+
* ) |\WP_Error
310349
*/
311350
function get_tags( $args = '' ) {
312351
$defaults = array( 'taxonomy' => 'post_tag' );

‎src/wp-includes/class-wp-comment-query.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -361,7 +361,7 @@ public function parse_query( $query = '' ) {
361361
* @param string|array $query Array or URL query string of parameters.
362362
* @return WP_Comment[]|int[]|int List of comments, or number of comments when 'count' is passed as a query var.
363363
*
364-
* @phpstan-return ( $query is array{count:true}&array ? int : WP_Comment[]|int[] )
364+
* @phpstan-return ( $query is array{count:true}&array ? int : (WP_Comment[]|int[]) )
365365
*/
366366
public function query( $query ) {
367367
$this->query_vars = wp_parse_args( $query );

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

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -196,6 +196,13 @@ public function init( $data, $site_id = 0 ) {
196196
* @param string $field The field to query against: Accepts 'id', 'ID', 'slug', 'email' or 'login'.
197197
* @param string|int $value The field value.
198198
* @return object|false Raw user object.
199+
*
200+
* @phpstan-param 'id'|'ID'|'slug'|'email'|'login' $field
201+
* @phpstan-return (
202+
* $field is 'id'|'ID' ? (
203+
* $value is not numeric ? false : (object|false)
204+
* ) : ( $value is non-empty-string ? (object|false) : false )
205+
* )
199206
*/
200207
public static function get_data_by( $field, $value ) {
201208
global $wpdb;

‎src/wp-includes/comment.php‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -222,7 +222,13 @@ function get_approved_comments( $post_id, $args = array() ) {
222222
* @return WP_Comment|array|null Depends on $output value.
223223
*
224224
* @phpstan-param 'OBJECT'|'ARRAY_A'|'ARRAY_N' $output
225-
* @phpstan-return ($comment is \WP_Comment ? array<array-key, mixed>|\WP_Comment : array<array-key, mixed>|\WP_Comment|null) & ($output is 'ARRAY_A' ? array<string, mixed>|null : ($output is 'ARRAY_N' ? array<int, mixed>|null : \WP_Comment|null))
225+
* @phpstan-return (
226+
* $output is 'ARRAY_A' ? array<string, mixed> : (
227+
* $output is 'ARRAY_N' ? array<int, mixed> : (
228+
* $output is 'OBJECT' ? \WP_Comment : ( array<array-key, mixed>|\WP_Comment )
229+
* )
230+
* )
231+
* )|null
226232
*/
227233
function get_comment( $comment = null, $output = OBJECT ) {
228234
if ( empty( $comment ) && isset( $GLOBALS['comment'] ) ) {
@@ -2476,7 +2482,7 @@ function wp_new_comment_notify_postauthor( $comment_id ) {
24762482
* @param bool $wp_error Whether to return a WP_Error object if there is a failure. Default false.
24772483
* @return bool|WP_Error True on success, false or WP_Error on failure.
24782484
*
2479-
* @phpstan-return ($wp_error is false ? bool : true|\WP_Error)
2485+
* @phpstan-return ( $wp_error is false ? bool : (true|\WP_Error) )
24802486
*/
24812487
function wp_set_comment_status( $comment_id, $comment_status, $wp_error = false ) {
24822488
global $wpdb;
@@ -2552,7 +2558,7 @@ function wp_set_comment_status( $comment_id, $comment_status, $wp_error = false
25522558
* @return int|false|WP_Error The value 1 if the comment was updated, 0 if not updated.
25532559
* False or a WP_Error object on failure.
25542560
*
2555-
* @phpstan-return ($wp_error is false ? 0|1|false : 0|1|\WP_Error)
2561+
* @phpstan-return ( $wp_error is false ? (0|1|false) : (0|1|\WP_Error) )
25562562
*/
25572563
function wp_update_comment( $commentarr, $wp_error = false ) {
25582564
global $wpdb;

‎src/wp-includes/cron.php‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@
3636
* @param bool $wp_error Optional. Whether to return a WP_Error on failure. Default false.
3737
* @return bool|WP_Error True if event successfully scheduled. False or WP_Error on failure.
3838
*
39-
* @phpstan-return ($wp_error is false ? bool : true|\WP_Error)
39+
* @phpstan-return ( $wp_error is false ? bool : (true|\WP_Error) )
4040
*/
4141
function wp_schedule_single_event( $timestamp, $hook, $args = array(), $wp_error = false ) {
4242
// Make sure timestamp is a positive integer.
@@ -233,7 +233,7 @@ function wp_schedule_single_event( $timestamp, $hook, $args = array(), $wp_error
233233
* @param bool $wp_error Optional. Whether to return a WP_Error on failure. Default false.
234234
* @return bool|WP_Error True if event successfully scheduled. False or WP_Error on failure.
235235
*
236-
* @phpstan-return ($wp_error is false ? bool : true|\WP_Error)
236+
* @phpstan-return ( $wp_error is false ? bool : (true|\WP_Error) )
237237
*/
238238
function wp_schedule_event( $timestamp, $recurrence, $hook, $args = array(), $wp_error = false ) {
239239
// Make sure timestamp is a positive integer.
@@ -341,7 +341,7 @@ function wp_schedule_event( $timestamp, $recurrence, $hook, $args = array(), $wp
341341
* @param bool $wp_error Optional. Whether to return a WP_Error on failure. Default false.
342342
* @return bool|WP_Error True if event successfully rescheduled. False or WP_Error on failure.
343343
*
344-
* @phpstan-return ($wp_error is false ? bool : true|\WP_Error)
344+
* @phpstan-return ( $wp_error is false ? bool : (true|\WP_Error) )
345345
*/
346346
function wp_reschedule_event( $timestamp, $recurrence, $hook, $args = array(), $wp_error = false ) {
347347
// Make sure timestamp is a positive integer.
@@ -465,7 +465,7 @@ function wp_reschedule_event( $timestamp, $recurrence, $hook, $args = array(), $
465465
* @param bool $wp_error Optional. Whether to return a WP_Error on failure. Default false.
466466
* @return bool|WP_Error True if event successfully unscheduled. False or WP_Error on failure.
467467
*
468-
* @phpstan-return ($wp_error is false ? bool : true|\WP_Error)
468+
* @phpstan-return ( $wp_error is false ? bool : (true|\WP_Error) )
469469
*/
470470
function wp_unschedule_event( $timestamp, $hook, $args = array(), $wp_error = false ) {
471471
// Make sure timestamp is a positive integer.
@@ -554,7 +554,7 @@ function wp_unschedule_event( $timestamp, $hook, $args = array(), $wp_error = fa
554554
* events were registered with the hook and arguments combination), false or WP_Error
555555
* if unscheduling one or more events fail.
556556
*
557-
* @phpstan-return (int<0, max>|($wp_error is false ? false : \WP_Error))
557+
* @phpstan-return int<0, max>|( $wp_error is false ? false : \WP_Error )
558558
*/
559559
function wp_clear_scheduled_hook( $hook, $args = array(), $wp_error = false ) {
560560
/*
@@ -661,7 +661,7 @@ function wp_clear_scheduled_hook( $hook, $args = array(), $wp_error = false ) {
661661
* @return int|false|WP_Error On success an integer indicating number of events unscheduled (0 indicates no
662662
* events were registered on the hook), false or WP_Error if unscheduling fails.
663663
*
664-
* @phpstan-return ($wp_error is false ? int<0, max>|false : int<0, max>|\WP_Error)
664+
* @phpstan-return int<0, max>|($wp_error is false ? false : \WP_Error)
665665
*/
666666
function wp_unschedule_hook( $hook, $wp_error = false ) {
667667
/**

0 commit comments

Comments
 (0)