Skip to content

Commit a42f847

Browse files
adamsilversteinadamsilverstein
committed
Code Quality: Add PHPStan type coverage for media and upload functions.
Add `@phpstan-return`/`@phpstan-param` annotations describing the array shapes returned and accepted by various media files. Also load the `phpstan/phpstan-phpunit` extension so PHPUnit assertions narrow types during analysis. These changes are documentation and tooling only, with no runtime effect, and let the affected functions pass a higher PHPStan rule level. Props westonruter. See #64915. git-svn-id: https://develop.svn.wordpress.org/trunk@62618 602fd350-edb4-49c9-b593-d223f7449a82
1 parent 5231afc commit a42f847

6 files changed

Lines changed: 83 additions & 0 deletions

File tree

‎composer.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@
2525
"wp-coding-standards/wpcs": "~3.3.0",
2626
"phpcompatibility/phpcompatibility-wp": "~2.1.3",
2727
"phpstan/phpstan": "2.2.2",
28+
"phpstan/phpstan-phpunit": "2.0.16",
2829
"yoast/phpunit-polyfills": "^1.1.0"
2930
},
3031
"config": {

‎phpstan.neon.dist‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,12 @@ includes:
88
# The base configuration file for using PHPStan with the WordPress core codebase.
99
- tests/phpstan/base.neon
1010

11+
# Type-specifying extension so PHPUnit assertions (e.g. assertArrayHasKey(),
12+
# assertInstanceOf(), assertNotNull()) narrow types in the analysis. Only the
13+
# extension is included, not phpstan-phpunit's rules.neon, to avoid introducing
14+
# new strict rules.
15+
- vendor/phpstan/phpstan-phpunit/extension.neon
16+
1117
# The baseline file includes preexisting errors in the codebase that should be ignored.
1218
# https://phpstan.org/user-guide/baseline
1319
- tests/phpstan/baseline.php

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

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -801,6 +801,9 @@ function validate_file_to_edit( $file, $allowed_files = array() ) {
801801
* @type string $url URL of the newly-uploaded file.
802802
* @type string $type Mime type of the newly-uploaded file.
803803
* }
804+
*
805+
* @phpstan-return array{ file: non-empty-string, url: non-empty-string, type: non-empty-string }
806+
* |array{ error: non-empty-string }
804807
*/
805808
function _wp_handle_upload( &$file, $overrides, $time, $action ) {
806809
// The default error handler.
@@ -1094,6 +1097,9 @@ function wp_handle_upload_error( &$file, $message ) {
10941097
* See _wp_handle_upload() for accepted values.
10951098
* @param string|null $time Optional. Time formatted in 'yyyy/mm'. Default null.
10961099
* @return array See _wp_handle_upload() for return value.
1100+
*
1101+
* @phpstan-return array{ file: non-empty-string, url: non-empty-string, type: non-empty-string }
1102+
* |array{ error: non-empty-string }
10971103
*/
10981104
function wp_handle_upload( &$file, $overrides = false, $time = null ) {
10991105
/*
@@ -1121,6 +1127,9 @@ function wp_handle_upload( &$file, $overrides = false, $time = null ) {
11211127
* See _wp_handle_upload() for accepted values.
11221128
* @param string|null $time Optional. Time formatted in 'yyyy/mm'. Default null.
11231129
* @return array See _wp_handle_upload() for return value.
1130+
*
1131+
* @phpstan-return array{ file: non-empty-string, url: non-empty-string, type: non-empty-string }
1132+
* |array{ error: non-empty-string }
11241133
*/
11251134
function wp_handle_sideload( &$file, $overrides = false, $time = null ) {
11261135
/*

‎src/wp-includes/functions.php‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2341,6 +2341,14 @@ function win_is_writable( $path ) {
23412341
* @see wp_upload_dir()
23422342
*
23432343
* @return array See wp_upload_dir() for description.
2344+
* @phpstan-return array{
2345+
* path: non-empty-string,
2346+
* url: non-empty-string,
2347+
* subdir: non-empty-string,
2348+
* basedir: non-empty-string,
2349+
* baseurl: non-empty-string,
2350+
* }
2351+
* |array{ error: non-empty-string }
23442352
*/
23452353
function wp_get_upload_dir() {
23462354
return wp_upload_dir( null, false );
@@ -2382,6 +2390,14 @@ function wp_get_upload_dir() {
23822390
* @type string $baseurl URL path without subdir.
23832391
* @type string|false $error False or error message.
23842392
* }
2393+
* @phpstan-return array{
2394+
* path: non-empty-string,
2395+
* url: non-empty-string,
2396+
* subdir: non-empty-string,
2397+
* basedir: non-empty-string,
2398+
* baseurl: non-empty-string,
2399+
* }
2400+
* |array{ error: non-empty-string }
23852401
*/
23862402
function wp_upload_dir( $time = null, $create_dir = true, $refresh_cache = false ) {
23872403
static $cache = array(), $tested_paths = array();

‎src/wp-includes/post.php‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6911,6 +6911,39 @@ function wp_delete_attachment_files( $post_id, $meta, $backup_sizes, $file ) {
69116911
* @type array $image_meta Image metadata.
69126912
* @type int $filesize File size of the attachment.
69136913
* }
6914+
*
6915+
* @phpstan-return array{
6916+
* width?: int<1, max>,
6917+
* height?: int<1, max>,
6918+
* file?: non-empty-string,
6919+
* filesize?: int<0, max>,
6920+
* original_image?: non-empty-string,
6921+
* source_image?: non-empty-string,
6922+
* sizes?: array<non-empty-string, array{
6923+
* file: non-empty-string,
6924+
* width: int<1, max>,
6925+
* height: int<1, max>,
6926+
* 'mime-type': non-empty-string,
6927+
* filesize?: int<0, max>,
6928+
* ...
6929+
* }>,
6930+
* image_meta?: array{
6931+
* aperture: numeric-string|int,
6932+
* credit: string,
6933+
* camera: string,
6934+
* caption: string,
6935+
* created_timestamp: numeric-string|int,
6936+
* copyright: string,
6937+
* focal_length: numeric-string|int,
6938+
* iso: numeric-string|int,
6939+
* shutter_speed: numeric-string|int,
6940+
* title: string,
6941+
* orientation: numeric-string|int,
6942+
* keywords: list<string>,
6943+
* alt: string,
6944+
* },
6945+
* ...
6946+
* }|false
69146947
*/
69156948
function wp_get_attachment_metadata( $attachment_id = 0, $unfiltered = false ) {
69166949
$attachment_id = (int) $attachment_id;

‎src/wp-includes/rest-api/class-wp-rest-request.php‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -588,6 +588,15 @@ public function set_body_params( $params ) {
588588
* @since 4.4.0
589589
*
590590
* @return array Parameter map of key to value.
591+
*
592+
* @phpstan-return array<string, array{
593+
* name: non-empty-string,
594+
* type: non-empty-string,
595+
* size: non-negative-int,
596+
* tmp_name: non-empty-string,
597+
* error: int<0, 8>,
598+
* full_path?: non-empty-string,
599+
* }>
591600
*/
592601
public function get_file_params() {
593602
return $this->params['FILES'];
@@ -601,6 +610,15 @@ public function get_file_params() {
601610
* @since 4.4.0
602611
*
603612
* @param array $params Parameter map of key to value.
613+
*
614+
* @phpstan-param array<string, array{
615+
* name: non-empty-string,
616+
* type: non-empty-string,
617+
* size: non-negative-int,
618+
* tmp_name: non-empty-string,
619+
* error: int<0, 8>,
620+
* full_path?: non-empty-string,
621+
* }> $params
604622
*/
605623
public function set_file_params( $params ) {
606624
$this->params['FILES'] = $params;

0 commit comments

Comments
 (0)