[12.x] Improve docblocks for file related methods of InteractsWithInput #55156
Conversation
SanderMuller
changed the title
|
Thanks for submitting a PR! Note that draft PR's are not reviewed. If you would like a review, please mark your pull request as ready for review in the GitHub user interface. Pull requests that are abandoned in draft may be closed due to inactivity. |
| @@ -240,7 +240,7 @@ protected function isValidFile($file) | |||
| * | |||
| * @param string|null $key | |||
| * @param mixed $default | |||
| * @return \Illuminate\Http\UploadedFile|\Illuminate\Http\UploadedFile[]|array|null | |||
| * @return ($key is null ? array<int, \Illuminate\Http\UploadedFile|array<int, \Illuminate\Http\UploadedFile>> : \Illuminate\Http\UploadedFile|\Illuminate\Http\UploadedFile[]|null) | |||
There was a problem hiding this comment.
when $key is null, the return type is always an array of files, otherwise it can be either an instance of a file, an array of files, or null
| @@ -175,7 +175,7 @@ public function cookie($key = null, $default = null) | |||
| /** | |||
| * Get an array of all of the files on the request. | |||
| * | |||
| * @return array | |||
| * @return array<int, \Illuminate\Http\UploadedFile|\Illuminate\Http\UploadedFile[]> | |||
There was a problem hiding this comment.
I think most codebases don't take an array containing another array of files into consideration, but it is possible according tot he code. convertUploadedFiles recursively maps the array to files or if the array contains an array, to an array of files (inside the array of files) resulting in nested arrays of files.
I guess not flat mapping this is on purpose (would be a breaking change now anyway), so the docblocks reflect the possibility of an array of items of which each item is either a file or an array of files.
| @@ -175,7 +175,7 @@ public function cookie($key = null, $default = null) | |||
| /** | |||
| * Get an array of all of the files on the request. | |||
| * | |||
| * @return array | |||
| * @return array<int, \Illuminate\Http\UploadedFile|\Illuminate\Http\UploadedFile[]> | |||
There was a problem hiding this comment.
The key here appears to be wrong, on FormRequest the key will be the name of the file input.
There was a problem hiding this comment.
I was actually looking in to adding types to this a few weeks ago, but backed off when I saw some of the nested logic so I'm glad you handled most of it :)
This PR improves the PHPDoc annotations for file-related methods and properties in the
InteractsWithInputtrait and theRequestclass.allFiles()andconvertUploadedFiles()file()return type with a conditional PHPStan-style annotation$convertedFilesproperty docblock accordinglyThese changes improve static analysis, IDE autocomplete, and developer understanding of the expected data structures, particularly for nested or multiple file uploads.
No functional code changes were made.