Skip to content

Commit c2f9731

Browse files
paulbalandanpaulbalandan
authored
refactor: precise PHPDocs for Autoloader (codeigniter4#9593)
1 parent a19b44c commit c2f9731

File tree

7 files changed

+45
-49
lines changed

7 files changed

+45
-49
lines changed

‎system/Autoloader/Autoloader.php‎

Lines changed: 24 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@
2121
use Config\Autoload;
2222
use Config\Kint as KintConfig;
2323
use Config\Modules;
24-
use Kint;
24+
use Kint\Kint;
2525
use Kint\Renderer\CliRenderer;
2626
use Kint\Renderer\RichRenderer;
2727

@@ -67,29 +67,29 @@ class Autoloader
6767
/**
6868
* Stores namespaces as key, and path as values.
6969
*
70-
* @var array<string, list<string>>
70+
* @var array<non-empty-string, list<non-empty-string>>
7171
*/
7272
protected $prefixes = [];
7373

7474
/**
7575
* Stores class name as key, and path as values.
7676
*
77-
* @var array<class-string, string>
77+
* @var array<class-string, non-empty-string>
7878
*/
7979
protected $classmap = [];
8080

8181
/**
8282
* Stores files as a list.
8383
*
84-
* @var list<string>
84+
* @var list<non-empty-string>
8585
*/
8686
protected $files = [];
8787

8888
/**
8989
* Stores helper list.
9090
* Always load the URL helper, it should be used in most apps.
9191
*
92-
* @var list<string>
92+
* @var list<non-empty-string>
9393
*/
9494
protected $helpers = ['url'];
9595

@@ -147,36 +147,35 @@ private function loadComposerAutoloader(Modules $modules): void
147147

148148
// Should we load through Composer's namespaces, also?
149149
if ($modules->discoverInComposer) {
150-
// @phpstan-ignore-next-line
151-
$this->loadComposerNamespaces($composer, $modules->composerPackages ?? []);
150+
$composerPackages = $modules->composerPackages;
151+
$this->loadComposerNamespaces($composer, $composerPackages ?? []);
152152
}
153153

154154
unset($composer);
155155
}
156156

157157
/**
158-
* Register the loader with the SPL autoloader stack.
158+
* Register the loader with the SPL autoloader stack
159+
* in the following order:
160+
*
161+
* 1. Classmap loader
162+
* 2. PSR-4 autoloader
163+
* 3. Non-class files
159164
*
160165
* @return void
161166
*/
162167
public function register()
163168
{
164-
// Register classmap loader for the files in our class map.
165169
spl_autoload_register($this->loadClassmap(...), true);
166-
167-
// Register the PSR-4 autoloader.
168170
spl_autoload_register($this->loadClass(...), true);
169171

170-
// Load our non-class files
171172
foreach ($this->files as $file) {
172173
$this->includeFile($file);
173174
}
174175
}
175176

176177
/**
177-
* Unregister autoloader.
178-
*
179-
* This method is for testing.
178+
* Unregisters the autoloader from the SPL autoload stack.
180179
*/
181180
public function unregister(): void
182181
{
@@ -187,7 +186,7 @@ public function unregister(): void
187186
/**
188187
* Registers namespaces with the autoloader.
189188
*
190-
* @param array<string, list<string>|string>|string $namespace
189+
* @param array<non-empty-string, list<non-empty-string>|non-empty-string>|non-empty-string $namespace
191190
*
192191
* @return $this
193192
*/
@@ -219,7 +218,7 @@ public function addNamespace($namespace, ?string $path = null)
219218
*
220219
* If a prefix param is set, returns only paths to the given prefix.
221220
*
222-
* @return ($prefix is null ? array<string, list<string>> : list<string>)
221+
* @return ($prefix is null ? array<non-empty-string, list<non-empty-string>> : list<non-empty-string>)
223222
*/
224223
public function getNamespace(?string $prefix = null)
225224
{
@@ -247,6 +246,8 @@ public function removeNamespace(string $namespace)
247246
/**
248247
* Load a class using available class mapping.
249248
*
249+
* @param class-string $class The fully qualified class name.
250+
*
250251
* @internal For `spl_autoload_register` use.
251252
*/
252253
public function loadClassmap(string $class): void
@@ -261,9 +262,9 @@ public function loadClassmap(string $class): void
261262
/**
262263
* Loads the class file for a given class name.
263264
*
264-
* @internal For `spl_autoload_register` use.
265+
* @param class-string $class The fully qualified class name.
265266
*
266-
* @param string $class The fully qualified class name.
267+
* @internal For `spl_autoload_register` use.
267268
*/
268269
public function loadClass(string $class): void
269270
{
@@ -273,9 +274,9 @@ public function loadClass(string $class): void
273274
/**
274275
* Loads the class file for a given class name.
275276
*
276-
* @param string $class The fully-qualified class name
277+
* @param class-string $class The fully qualified class name.
277278
*
278-
* @return false|string The mapped file name on success, or boolean false on fail
279+
* @return false|non-empty-string The mapped file name on success, or boolean false on fail
279280
*/
280281
protected function loadInNamespace(string $class)
281282
{
@@ -293,21 +294,20 @@ protected function loadInNamespace(string $class)
293294
$filePath = $directory . $relativeClassPath . '.php';
294295
$filename = $this->includeFile($filePath);
295296

296-
if ($filename) {
297+
if ($filename !== false) {
297298
return $filename;
298299
}
299300
}
300301
}
301302
}
302303

303-
// never found a mapped file
304304
return false;
305305
}
306306

307307
/**
308308
* A central way to include a file. Split out primarily for testing purposes.
309309
*
310-
* @return false|string The filename on success, false if the file is not loaded
310+
* @return false|non-empty-string The filename on success, false if the file is not loaded
311311
*/
312312
protected function includeFile(string $file)
313313
{

‎system/Autoloader/FileLocator.php‎

Lines changed: 12 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ public function __construct(Autoloader $autoloader)
4444
* Attempts to locate a file by examining the name for a namespace
4545
* and looking through the PSR-4 namespaced files that we know about.
4646
*
47-
* @param string $file The relative file path or namespaced file to
47+
* @param non-empty-string $file The relative file path or namespaced file to
4848
* locate. If not namespaced, search in the app
4949
* folder.
5050
* @param non-empty-string|null $folder The folder within the namespace that we should
@@ -53,7 +53,7 @@ public function __construct(Autoloader $autoloader)
5353
* folder.
5454
* @param string $ext The file extension the file should have.
5555
*
56-
* @return false|string The path to the file, or false if not found.
56+
* @return false|non-empty-string The path to the file, or false if not found.
5757
*/
5858
public function locateFile(string $file, ?string $folder = null, string $ext = 'php')
5959
{
@@ -156,9 +156,11 @@ public function getClassname(string $file): string
156156
$dlm = false;
157157
}
158158

159-
if (($tokens[$i - 2][0] === T_CLASS || (isset($tokens[$i - 2][1]) && $tokens[$i - 2][1] === 'phpclass'))
159+
if (
160+
($tokens[$i - 2][0] === T_CLASS || (isset($tokens[$i - 2][1]) && $tokens[$i - 2][1] === 'phpclass'))
160161
&& $tokens[$i - 1][0] === T_WHITESPACE
161-
&& $token[0] === T_STRING) {
162+
&& $token[0] === T_STRING
163+
) {
162164
$className = $token[1];
163165
break;
164166
}
@@ -184,7 +186,7 @@ public function getClassname(string $file): string
184186
* 'app/Modules/bar/Config/Routes.php',
185187
* ]
186188
*
187-
* @return list<string>
189+
* @return list<non-empty-string>
188190
*/
189191
public function search(string $path, string $ext = 'php', bool $prioritizeApp = true): array
190192
{
@@ -213,7 +215,6 @@ public function search(string $path, string $ext = 'php', bool $prioritizeApp =
213215
$foundPaths = [...$foundPaths, ...$appPaths];
214216
}
215217

216-
// Remove any duplicates
217218
return array_values(array_unique($foundPaths));
218219
}
219220

@@ -236,13 +237,12 @@ protected function ensureExt(string $path, string $ext): string
236237
/**
237238
* Return the namespace mappings we know about.
238239
*
239-
* @return array<int, array<string, string>>
240+
* @return list<array{prefix: non-empty-string, path: non-empty-string}>
240241
*/
241242
protected function getNamespaces()
242243
{
243244
$namespaces = [];
244245

245-
// Save system for last
246246
$system = [];
247247

248248
foreach ($this->autoloader->getNamespace() as $prefix => $paths) {
@@ -263,6 +263,7 @@ protected function getNamespaces()
263263
}
264264
}
265265

266+
// Save system for last
266267
return array_merge($namespaces, $system);
267268
}
268269

@@ -295,19 +296,17 @@ public function findQualifiedNameFromPath(string $path)
295296
);
296297

297298
// Remove the file extension (.php)
298-
/** @var class-string */
299+
/** @var class-string $className */
299300
$className = mb_substr($className, 0, -4);
300301

301302
if (in_array($className, $this->invalidClassnames, true)) {
302303
continue;
303304
}
304305

305-
// Check if this exists
306306
if (class_exists($className)) {
307307
return $className;
308308
}
309309

310-
// If the class does not exist, it is an invalid classname.
311310
$this->invalidClassnames[] = $className;
312311
}
313312
}
@@ -353,11 +352,11 @@ public function listFiles(string $path): array
353352
* Scans the provided namespace, returning a list of all files
354353
* that are contained within the sub path specified by $path.
355354
*
356-
* @return list<string> List of file paths
355+
* @return list<non-empty-string> List of file paths
357356
*/
358357
public function listNamespaceFiles(string $prefix, string $path): array
359358
{
360-
if ($path === '' || ($prefix === '')) {
359+
if ($path === '' || $prefix === '') {
361360
return [];
362361
}
363362

‎system/Autoloader/FileLocatorCached.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -117,7 +117,7 @@ public function getClassname(string $file): string
117117
}
118118

119119
/**
120-
* @return list<string>
120+
* @return list<non-empty-string>
121121
*/
122122
public function search(string $path, string $ext = 'php', bool $prioritizeApp = true): array
123123
{

‎system/Autoloader/FileLocatorInterface.php‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ interface FileLocatorInterface
2323
* Attempts to locate a file by examining the name for a namespace
2424
* and looking through the PSR-4 namespaced files that we know about.
2525
*
26-
* @param string $file The relative file path or namespaced file to
26+
* @param non-empty-string $file The relative file path or namespaced file to
2727
* locate. If not namespaced, search in the app
2828
* folder.
2929
* @param non-empty-string|null $folder The folder within the namespace that we should
@@ -32,12 +32,14 @@ interface FileLocatorInterface
3232
* folder.
3333
* @param string $ext The file extension the file should have.
3434
*
35-
* @return false|string The path to the file, or false if not found.
35+
* @return false|non-empty-string The path to the file, or false if not found.
3636
*/
3737
public function locateFile(string $file, ?string $folder = null, string $ext = 'php');
3838

3939
/**
4040
* Examines a file and returns the fully qualified class name.
41+
*
42+
* @param non-empty-string $file
4143
*/
4244
public function getClassname(string $file): string;
4345

@@ -54,7 +56,7 @@ public function getClassname(string $file): string;
5456
* 'app/Modules/bar/Config/Routes.php',
5557
* ]
5658
*
57-
* @return list<string>
59+
* @return list<non-empty-string>
5860
*/
5961
public function search(string $path, string $ext = 'php', bool $prioritizeApp = true): array;
6062

‎tests/system/Autoloader/AutoloaderTest.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -394,7 +394,7 @@ public function testAutoloaderLoadsNonClassFiles(): void
394394

395395
$this->assertTrue(function_exists('autoload_foo'));
396396
$this->assertSame('I am autoloaded by Autoloader through $files!', autoload_foo());
397-
$this->assertTrue(defined('AUTOLOAD_CONSTANT'));
397+
$this->assertTrue(defined('AUTOLOAD_CONSTANT')); // @phpstan-ignore method.alreadyNarrowedType
398398
$this->assertSame('foo', AUTOLOAD_CONSTANT);
399399

400400
$loader->unregister();

‎utils/phpstan-baseline/loader.neon‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# total 3075 errors
1+
# total 3074 errors
22
includes:
33
- argument.type.neon
44
- assign.propertyType.neon

‎utils/phpstan-baseline/method.alreadyNarrowedType.neon‎

Lines changed: 1 addition & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# total 24 errors
1+
# total 23 errors
22

33
parameters:
44
ignoreErrors:
@@ -7,11 +7,6 @@ parameters:
77
count: 1
88
path: ../../admin/starter/tests/unit/HealthTest.php
99

10-
-
11-
message: '#^Call to method PHPUnit\\Framework\\Assert\:\:assertTrue\(\) with bool will always evaluate to true\.$#'
12-
count: 1
13-
path: ../../tests/system/Autoloader/AutoloaderTest.php
14-
1510
-
1611
message: '#^Call to method PHPUnit\\Framework\\Assert\:\:assertIsBool\(\) with bool will always evaluate to true\.$#'
1712
count: 1

0 commit comments

Comments
 (0)