Report constant-string arguments to #[JetBrains\PhpStorm\FileReference] parameters that do not resolve to an existing path

build/collision-detector.json

@@ -9,6 +9,8 @@
 		"../tests/PHPStan/Parser/data/cleaning-property-hooks-after.php",
 		"../tests/PHPStan/Rules/Functions/data/duplicate-function.php",
 		"../tests/PHPStan/Rules/Classes/data/duplicate-class.php",
+		"../tests/PHPStan/Rules/data/file-reference.php",
+		"../tests/PHPStan/Analyser/data/file-reference-attribute.php",
 		"../tests/PHPStan/Rules/Names/data/multiple-namespaces.php",
 		"../tests/PHPStan/Rules/Names/data/no-namespace.php",
 		"../tests/notAutoloaded",

src/File/FileExistenceChecker.php

@@ -0,0 +1,87 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\File;
+
+use PHPStan\DependencyInjection\AutowiredParameter;
+use PHPStan\DependencyInjection\AutowiredService;
+use function array_merge;
+use function explode;
+use function get_include_path;
+use function is_dir;
+use function is_file;
+use const PATH_SEPARATOR;
+
+/**
+ * Resolves a possibly-relative path the same way PHP would at runtime and checks whether it exists.
+ *
+ * We cannot use stream_resolve_include_path() because it works based on the calling script.
+ * This mirrors its behavior but for an arbitrary script directory. The priority order is:
+ * 	1. The base directories (e.g. from an attribute argument).
+ * 	2. The current working directory.
+ * 	3. The include path.
+ * 	4. The directory of the script that is being analysed.
+ */
+#[AutowiredService]
+final class FileExistenceChecker
+{
+
+	public function __construct(
+		#[AutowiredParameter]
+		private string $currentWorkingDirectory,
+	)
+	{
+	}
+
+	/**
+	 * @param list<string> $baseDirectories
+	 */
+	public function fileExists(string $path, string $scriptDirectory, array $baseDirectories = []): bool
+	{
+		return $this->exists($path, $scriptDirectory, $baseDirectories, false);
+	}
+
+	/**
+	 * Like fileExists(), but a directory at the resolved path also counts as existing.
+	 *
+	 * @param list<string> $baseDirectories
+	 */
+	public function pathExists(string $path, string $scriptDirectory, array $baseDirectories = []): bool
+	{
+		return $this->exists($path, $scriptDirectory, $baseDirectories, true);
+	}
+
+	/**
+	 * @param list<string> $baseDirectories
+	 */
+	private function exists(string $path, string $scriptDirectory, array $baseDirectories, bool $allowDirectory): bool
+	{
+		$scriptHelper = new FileHelper($scriptDirectory);
+		$resolvedBaseDirectories = [];
+		foreach ($baseDirectories as $baseDirectory) {
+			// a relative base directory is resolved against the directory of the analysed script
+			$resolvedBaseDirectories[] = $scriptHelper->absolutizePath($baseDirectory);
+		}
+
+		$directories = array_merge(
+			$resolvedBaseDirectories,
+			[$this->currentWorkingDirectory],
+			explode(PATH_SEPARATOR, get_include_path()),
+			[$scriptDirectory],
+		);
+
+		foreach ($directories as $directory) {
+			$absolutePath = (new FileHelper($directory))->absolutizePath($path);
+
+			if (is_file($absolutePath)) {
+				return true;
+			}
+
+			if ($allowDirectory && is_dir($absolutePath)) {
+				return true;
+			}
+		}
+
+		return false;
+	}
+
+}

src/Rules/FunctionCallParametersCheck.php

@@ -10,6 +10,7 @@
 use PHPStan\Analyser\Scope;
 use PHPStan\DependencyInjection\AutowiredParameter;
 use PHPStan\DependencyInjection\AutowiredService;
+use PHPStan\File\FileExistenceChecker;
 use PHPStan\Reflection\ConstantReflection;
 use PHPStan\Reflection\ExtendedParameterReflection;
 use PHPStan\Reflection\ParameterReflection;
@@ -37,6 +38,7 @@
 use function array_last;
 use function array_merge;
 use function count;
+use function dirname;
 use function implode;
 use function in_array;
 use function is_int;
@@ -49,6 +51,8 @@
 final class FunctionCallParametersCheck
 {
 
+	private const FILE_REFERENCE_ATTRIBUTE = 'JetBrains\PhpStorm\FileReference';
+
 	public function __construct(
 		private RuleLevelHelper $ruleLevelHelper,
 		private NullsafeCheck $nullsafeCheck,
@@ -63,6 +67,7 @@ public function __construct(
 		private bool $checkExtraArguments,
 		#[AutowiredParameter]
 		private bool $checkMissingTypehints,
+		private ?FileExistenceChecker $fileExistenceChecker = null,
 	)
 	{
 	}
@@ -324,6 +329,10 @@ public function check(
 			$errors[] = $error;
 		}
 
+		foreach ($this->checkFileReferences($argumentsWithParameters, $scope) as $error) {
+			$errors[] = $error;
+		}
+
 		if (!$this->checkArgumentTypes && !$this->checkArgumentsPassedByReference) {
 			return $errors;
 		}
@@ -782,6 +791,90 @@ private function processArguments(
 		return [$errors, $newArguments];
 	}
 
+	/**
+	 * Validates constant-string arguments passed to parameters annotated with
+	 * #[JetBrains\PhpStorm\FileReference], reusing the include/require file resolution.
+	 *
+	 * @param array<int, array{Expr, Type|null, bool, (string|null), int, (ParameterReflection|null), (ParameterReflection|null)}> $argumentsWithParameters
+	 * @return list<IdentifierRuleError>
+	 */
+	private function checkFileReferences(array $argumentsWithParameters, Scope $scope): array
+	{
+		if ($this->fileExistenceChecker === null) {
+			return [];
+		}
+
+		$errors = [];
+		$scriptDirectory = dirname($scope->getFile());
+		foreach ($argumentsWithParameters as $i => [$argumentValue, $argumentValueType, $unpack, $argumentName, $argumentLine, $parameter]) {
+			if ($unpack) {
+				continue;
+			}
+			if (!$parameter instanceof ExtendedParameterReflection) {
+				continue;
+			}
+
+			$baseDirectories = $this->getFileReferenceBaseDirectories($parameter);
+			if ($baseDirectories === null) {
+				continue;
+			}
+
+			$argumentValueType ??= $scope->getType($argumentValue);
+			foreach ($argumentValueType->getConstantStrings() as $constantString) {
+				$path = $constantString->getValue();
+				if ($path === '') {
+					continue;
+				}
+				if ($this->fileExistenceChecker->pathExists($path, $scriptDirectory, $baseDirectories)) {
+					continue;
+				}
+
+				$errors[] = RuleErrorBuilder::message(sprintf(
+					'Path "%s" passed to %s does not exist.',
+					$path,
+					lcfirst($this->describeParameter($parameter, $argumentName ?? $i + 1)),
+				))
+					->identifier('argument.fileReference')
+					->line($argumentLine)
+					->build();
+			}
+		}
+
+		return $errors;
+	}
+
+	/**
+	 * @return list<string>|null Base directories from the attribute's $basePath, or null when the parameter is not a file reference
+	 */
+	private function getFileReferenceBaseDirectories(ExtendedParameterReflection $parameter): ?array
+	{
+		$isFileReference = false;
+		$baseDirectories = [];
+		foreach ($parameter->getAttributes() as $attribute) {
+			if ($attribute->getName() !== self::FILE_REFERENCE_ATTRIBUTE) {
+				continue;
+			}
+			$isFileReference = true;
+
+			$basePathType = $attribute->getArgumentTypes()['basePath'] ?? null;
+			if ($basePathType === null) {
+				continue;
+			}
+			foreach ($basePathType->getConstantStrings() as $basePath) {
+				if ($basePath->getValue() === '') {
+					continue;
+				}
+				$baseDirectories[] = $basePath->getValue();
+			}
+		}
+
+		if (!$isFileReference) {
+			return null;
+		}
+
+		return $baseDirectories;
+	}
+
 	private function describeParameter(ParameterReflection $parameter, int|string|null $positionOrNamed): string
 	{
 		$parts = [];

src/Rules/Keywords/RequireFileExistsRule.php

@@ -11,20 +11,16 @@
 use PHPStan\Analyser\Scope;
 use PHPStan\DependencyInjection\AutowiredParameter;
 use PHPStan\DependencyInjection\RegisteredRule;
+use PHPStan\File\FileExistenceChecker;
 use PHPStan\File\FileHelper;
 use PHPStan\Node\Printer\ExprPrinter;
 use PHPStan\Rules\IdentifierRuleError;
 use PHPStan\Rules\Rule;
 use PHPStan\Rules\RuleErrorBuilder;
 use PHPStan\ShouldNotHappenException;
 use PHPStan\Type\Constant\ConstantStringType;
-use function array_merge;
 use function dirname;
-use function explode;
-use function get_include_path;
-use function is_file;
 use function sprintf;
-use const PATH_SEPARATOR;
 
 /**
  * @implements Rule<Include_>
@@ -47,12 +43,11 @@ final class RequireFileExistsRule implements Rule
 	];
 
 	public function __construct(
-		#[AutowiredParameter]
-		private string $currentWorkingDirectory,
 		private ExprPrinter $exprPrinter,
 		#[AutowiredParameter(ref: '%featureToggles.magicDirInInclude%')]
 		private bool $checkMagicDirInInclude,
 		private FileHelper $fileHelper,
+		private FileExistenceChecker $fileExistenceChecker,
 	)
 	{
 	}
@@ -91,37 +86,9 @@ public function processNode(Node $node, Scope $scope): array
 		return $errors;
 	}
 
-	/**
-	 * We cannot use `stream_resolve_include_path` as it works based on the calling script.
-	 * This method simulates the behavior of `stream_resolve_include_path` but for the given scope.
-	 * The priority order is the following:
-	 * 	1. The current working directory.
-	 * 	2. The include path.
-	 *  3. The path of the script that is being executed.
-	 */
 	private function doesFileExist(string $path, Scope $scope): bool
 	{
-		$directories = array_merge(
-			[$this->currentWorkingDirectory],
-			explode(PATH_SEPARATOR, get_include_path()),
-			[dirname($scope->getFile())],
-		);
-
-		foreach ($directories as $directory) {
-			if ($this->doesFileExistForDirectory($path, $directory)) {
-				return true;
-			}
-		}
-
-		return false;
-	}
-
-	private function doesFileExistForDirectory(string $path, string $workingDirectory): bool
-	{
-		$fileHelper = new FileHelper($workingDirectory);
-		$absolutePath = $fileHelper->absolutizePath($path);
-
-		return is_file($absolutePath);
+		return $this->fileExistenceChecker->fileExists($path, dirname($scope->getFile()));
 	}
 
 	private function getErrorMessage(Include_ $node, string $filePath): IdentifierRuleError

tests/PHPStan/Analyser/AnalyserIntegrationTest.php

@@ -1128,6 +1128,14 @@ public static function getAdditionalConfigFiles(): array
 		];
 	}
 
+	public function testFileReferenceAttribute(): void
+	{
+		$errors = $this->runAnalyse(__DIR__ . '/data/file-reference-attribute.php');
+		$this->assertCount(1, $errors);
+		$this->assertSame('Path "file-reference-attribute-missing.php" passed to parameter #1 $path does not exist.', $errors[0]->getMessage());
+		$this->assertSame(26, $errors[0]->getLine());
+	}
+
 	public function testBug8004(): void
 	{
 		// false positive

tests/PHPStan/Analyser/data/file-reference-attribute.php

@@ -0,0 +1,28 @@
+<?php declare(strict_types = 1); // lint >= 8.0
+
+namespace JetBrains\PhpStorm {
+
+	#[\Attribute(\Attribute::TARGET_PARAMETER)]
+	class FileReference
+	{
+
+		public function __construct(string $basePath = '')
+		{
+		}
+
+	}
+
+}
+
+namespace FileReferenceIntegration {
+
+	use JetBrains\PhpStorm\FileReference;
+
+	function loadFile(#[FileReference] string $path): void
+	{
+	}
+
+	loadFile('file-reference-attribute.php');
+	loadFile('file-reference-attribute-missing.php');
+
+}

tests/PHPStan/Rules/Classes/InstantiationRuleTest.php

@@ -2,6 +2,7 @@
 
 namespace PHPStan\Rules\Classes;
 
+use PHPStan\File\FileExistenceChecker;
 use PHPStan\Rules\ClassCaseSensitivityCheck;
 use PHPStan\Rules\ClassForbiddenNameCheck;
 use PHPStan\Rules\ClassNameCheck;
@@ -49,6 +50,7 @@ protected function getRule(): Rule
 				checkArgumentsPassedByReference: true,
 				checkExtraArguments: true,
 				checkMissingTypehints: true,
+				fileExistenceChecker: self::getContainer()->getByType(FileExistenceChecker::class),
 			),
 			new ClassNameCheck(
 				new ClassCaseSensitivityCheck($reflectionProvider, checkInternalClassCaseSensitivity: true),
@@ -728,4 +730,18 @@ public function testInstantiationWithNonObjectType(): void
 		]);
 	}
 
+	public function testFileReferenceAttribute(): void
+	{
+		$this->analyse([__DIR__ . '/../data/file-reference.php'], [
+			[
+				'Path "file-reference-missing.php" passed to parameter #1 $path does not exist.',
+				71,
+			],
+			[
+				'Path "file-reference-missing.php" passed to parameter #1 $path does not exist.',
+				84,
+			],
+		]);
+	}
+
 }