minor #53670 [Config] Provide more precise phpdoc for FileLocatorInterface::locate() (VincentLanglet)

nicolas-grekas · nicolas-grekas · commit cb68bf3cd563 · 2024-01-30T09:32:35.000+01:00
This PR was merged into the 6.4 branch. Discussion ---------- [Config] Provide more precise phpdoc for `FileLocatorInterface::locate()` | Q | A | ------------- | --- | Branch? | 6.4 | Bug fix? | ? | New feature? | ? | Deprecations? | no | Issues | Fix #... | License | MIT When working with psalm/phpstan, they believe `$locator->locate('...');` returns possibly an array which is not true. This can be defined with ``@psalm`-return` annotation that Symfony started to integrate in the code base. Commits ------- b2afd32 Provide more precise phpdoc for FileLocatorInterface::locate
diff --git a/src/Symfony/Component/Config/FileLocator.php b/src/Symfony/Component/Config/FileLocator.php
@@ -31,7 +31,9 @@ public function __construct(string|array $paths = [])
     }
 
     /**
-     * @return string|array
+     * @return string|string[]
+     *
+     * @psalm-return ($first is true ? string : string[])
      */
     public function locate(string $name, ?string $currentPath = null, bool $first = true)
     {
diff --git a/src/Symfony/Component/Config/FileLocatorInterface.php b/src/Symfony/Component/Config/FileLocatorInterface.php
@@ -25,10 +25,12 @@ interface FileLocatorInterface
      * @param string|null $currentPath The current path
      * @param bool        $first       Whether to return the first occurrence or an array of filenames
      *
-     * @return string|array The full path to the file or an array of file paths
+     * @return string|string[] The full path to the file or an array of file paths
      *
      * @throws \InvalidArgumentException        If $name is empty
      * @throws FileLocatorFileNotFoundException If a file is not found
+     *
+     * @psalm-return ($first is true ? string : string[])
      */
     public function locate(string $name, ?string $currentPath = null, bool $first = true);
 }

Original file line number	Diff line number	Diff line change
`@@ -31,7 +31,9 @@ public function __construct(string\|array $paths = [])`
`31`	`31`	`}`
`32`	`32`
`33`	`33`	`/**`
`34`		`- * @return string\|array`
	`34`	`+ * @return string\|string[]`
	`35`	`+ *`
	`36`	`+ * @psalm-return ($first is true ? string : string[])`
`35`	`37`	`*/`
`36`	`38`	`public function locate(string $name, ?string $currentPath = null, bool $first = true)`
`37`	`39`	`{`
Original file line number	Diff line number	Diff line change
`@@ -25,10 +25,12 @@ interface FileLocatorInterface`
`25`	`25`	`* @param string\|null $currentPath The current path`
`26`	`26`	`* @param bool $first Whether to return the first occurrence or an array of filenames`
`27`	`27`	`*`
`28`		`- * @return string\|array The full path to the file or an array of file paths`
	`28`	`+ * @return string\|string[] The full path to the file or an array of file paths`
`29`	`29`	`*`
`30`	`30`	`* @throws \InvalidArgumentException If $name is empty`
`31`	`31`	`* @throws FileLocatorFileNotFoundException If a file is not found`
	`32`	`+ *`
	`33`	`+ * @psalm-return ($first is true ? string : string[])`
`32`	`34`	`*/`
`33`	`35`	`public function locate(string $name, ?string $currentPath = null, bool $first = true);`
`34`	`36`	`}`