Merge pull request #7535 from kenjis/test-FileLocator

docs: improve doc comment and tests for locateFile()

Author: kenjis

system/Autoloader/FileLocator.php

@@ -33,8 +33,13 @@ public function __construct(Autoloader $autoloader)
      * Attempts to locate a file by examining the name for a namespace
      * and looking through the PSR-4 namespaced files that we know about.
      *
-     * @param string      $file   The namespaced file to locate
-     * @param string|null $folder The folder within the namespace that we should look for the file.
+     * @param string      $file   The relative file path or namespaced file to
+     *                            locate. If not namespaced, search in the app
+     *                            folder.
+     * @param string|null $folder The folder within the namespace that we should
+     *                            look for the file. If $file does not contain
+     *                            this value, it will be appended to the namespace
+     *                            folder.
      * @param string      $ext    The file extension the file should have.
      *
      * @return false|string The path to the file, or false if not found.

tests/system/Autoloader/FileLocatorTest.php

@@ -51,64 +51,67 @@ protected function setUp(): void
         $this->locator = new FileLocator($autoloader);
     }
 
-    public function testLocateFileWorksWithLegacyStructure()
+    public function testLocateFileNotNamespacedFindsInAppDirectory()
     {
-        $file = 'Controllers/Home';
+        $file = 'Controllers/Home'; // not namespaced
 
         $expected = APPPATH . 'Controllers/Home.php';
 
         $this->assertSame($expected, $this->locator->locateFile($file));
     }
 
-    public function testLocateFileWithLegacyStructureNotFound()
+    public function testLocateFileNotNamespacedNotFound()
     {
-        $file = 'Unknown';
+        $file = 'Unknown'; // not namespaced
 
         $this->assertFalse($this->locator->locateFile($file));
     }
 
-    public function testLocateFileWorksInApplicationDirectory()
+    public function testLocateFileNotNamespacedFindsWithFolderInAppDirectory()
     {
-        $file = 'welcome_message';
+        $file = 'welcome_message'; // not namespaced
 
         $expected = APPPATH . 'Views/welcome_message.php';
 
         $this->assertSame($expected, $this->locator->locateFile($file, 'Views'));
     }
 
-    public function testLocateFileWorksInApplicationDirectoryWithoutFolder()
+    public function testLocateFileNotNamespacedFindesWithoutFolderInAppDirectory()
     {
-        $file = 'Common';
+        $file = 'Common'; // not namespaced
 
         $expected = APPPATH . 'Common.php';
 
         $this->assertSame($expected, $this->locator->locateFile($file));
     }
 
-    public function testLocateFileWorksInNestedApplicationDirectory()
+    public function testLocateFileNotNamespacedWorksInNestedAppDirectory()
     {
-        $file = 'Controllers/Home';
+        $file = 'Controllers/Home'; // not namespaced
 
         $expected = APPPATH . 'Controllers/Home.php';
 
+        // This works because $file contains `Controllers`.
         $this->assertSame($expected, $this->locator->locateFile($file, 'Controllers'));
     }
 
-    public function testLocateFileReplacesFolderName()
+    public function testLocateFileWithFolderNameInFile()
     {
         $file = '\App\Views/errors/html/error_404.php';
 
         $expected = APPPATH . 'Views/errors/html/error_404.php';
 
+        // This works because $file contains `Views`.
         $this->assertSame($expected, $this->locator->locateFile($file, 'Views'));
     }
 
-    public function testLocateFileReplacesFolderNameLegacy()
+    public function testLocateFileNotNamespacedWithFolderNameInFile()
     {
-        $file = 'Views/welcome_message.php';
+        $file = 'Views/welcome_message.php'; // not namespaced
 
         $expected = APPPATH . 'Views/welcome_message.php';
 
+        // This works because $file contains `Views`.
         $this->assertSame($expected, $this->locator->locateFile($file, 'Views'));
     }
 
@@ -118,6 +121,7 @@ public function testLocateFileCanFindNamespacedView()
 
         $expected = APPPATH . 'Views/errors/html/error_404.php';
 
+        // The namespace `Errors` (APPPATH . 'Views/errors') + the folder (`html`) + `error_404`
         $this->assertSame($expected, $this->locator->locateFile($file, 'html'));
     }