Rule to check if required file exists

conf/bleedingEdge.neon

@@ -62,5 +62,6 @@ parameters:
 		tooWidePropertyType: true
 		explicitThrow: true
 		absentTypeChecks: true
+		requireFileExists: true
 	stubFiles:
 		- ../stubs/bleedingEdge/Rule.stub

conf/config.level0.neon

@@ -30,6 +30,8 @@ conditionalTags:
 		phpstan.rules.rule: %featureToggles.printfArrayParameters%
 	PHPStan\Rules\Regexp\RegularExpressionQuotingRule:
 		phpstan.rules.rule: %featureToggles.validatePregQuote%
+	PHPStan\Rules\Keywords\RequireFileExistsRule:
+		phpstan.rules.rule: %featureToggles.requireFileExists%
 
 rules:
 	- PHPStan\Rules\Api\ApiInstantiationRule
@@ -309,3 +311,7 @@ services:
 
 	-
 		class: PHPStan\Rules\Regexp\RegularExpressionQuotingRule
+	-
+		class: PHPStan\Rules\Keywords\RequireFileExistsRule
+		arguments:
+			currentWorkingDirectory: %currentWorkingDirectory%

conf/config.neon

@@ -94,6 +94,7 @@ parameters:
 		preciseMissingReturn: false
 		validatePregQuote: false
 		noImplicitWildcard: false
+		requireFileExists: false
 		narrowPregMatches: true
 		tooWidePropertyType: false
 		explicitThrow: false

conf/parametersSchema.neon

@@ -93,6 +93,7 @@ parametersSchema:
 		tooWidePropertyType: bool()
 		explicitThrow: bool()
 		absentTypeChecks: bool()
+		requireFileExists: bool()
 	])
 	fileExtensions: listOf(string())
 	checkAdvancedIsset: bool()

src/Rules/Keywords/RequireFileExistsRule.php

@@ -0,0 +1,138 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\Rules\Keywords;
+
+use PhpParser\Node;
+use PhpParser\Node\Expr\Include_;
+use PHPStan\Analyser\Scope;
+use PHPStan\File\FileHelper;
+use PHPStan\Rules\IdentifierRuleError;
+use PHPStan\Rules\Rule;
+use PHPStan\Rules\RuleErrorBuilder;
+use PHPStan\ShouldNotHappenException;
+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_>
+ */
+final class RequireFileExistsRule implements Rule
+{
+
+	public function __construct(private string $currentWorkingDirectory)
+	{
+	}
+
+	public function getNodeType(): string
+	{
+		return Include_::class;
+	}
+
+	public function processNode(Node $node, Scope $scope): array
+	{
+		$errors = [];
+		$paths = $this->resolveFilePaths($node, $scope);
+
+		foreach ($paths as $path) {
+			if ($this->doesFileExist($path, $scope)) {
+				continue;
+			}
+
+			$errors[] = $this->getErrorMessage($node, $path);
+		}
+
+		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);
+		$normalisedPath = $fileHelper->normalizePath($path);
+		$absolutePath = $fileHelper->absolutizePath($normalisedPath);
+
+		return is_file($absolutePath);
+	}
+
+	private function getErrorMessage(Include_ $node, string $filePath): IdentifierRuleError
+	{
+		$message = 'Path in %s() "%s" is not a file or it does not exist.';
+
+		switch ($node->type) {
+			case Include_::TYPE_REQUIRE:
+				$type = 'require';
+				$identifierType = 'require';
+				break;
+			case Include_::TYPE_REQUIRE_ONCE:
+				$type = 'require_once';
+				$identifierType = 'requireOnce';
+				break;
+			case Include_::TYPE_INCLUDE:
+				$type = 'include';
+				$identifierType = 'include';
+				break;
+			case Include_::TYPE_INCLUDE_ONCE:
+				$type = 'include_once';
+				$identifierType = 'includeOnce';
+				break;
+			default:
+				throw new ShouldNotHappenException('Rule should have already validated the node type.');
+		}
+
+		$identifier = sprintf('%s.fileNotFound', $identifierType);
+
+		return RuleErrorBuilder::message(
+			sprintf(
+				$message,
+				$type,
+				$filePath,
+			),
+		)->identifier($identifier)->build();
+	}
+
+	/**
+	 * @return array<string>
+	 */
+	private function resolveFilePaths(Include_ $node, Scope $scope): array
+	{
+		$paths = [];
+		$type = $scope->getType($node->expr);
+		$constantStrings = $type->getConstantStrings();
+
+		foreach ($constantStrings as $constantString) {
+			$paths[] = $constantString->getValue();
+		}
+
+		return $paths;
+	}
+
+}

tests/PHPStan/Rules/Keywords/RequireFileExistsRuleTest.php

@@ -0,0 +1,136 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\Rules\Keywords;
+
+use PHPStan\Rules\Rule;
+use PHPStan\Testing\RuleTestCase;
+use function get_include_path;
+use function implode;
+use function realpath;
+use function set_include_path;
+use const PATH_SEPARATOR;
+
+/**
+ * @extends RuleTestCase<RequireFileExistsRule>
+ */
+class RequireFileExistsRuleTest extends RuleTestCase
+{
+
+	private RequireFileExistsRule $rule;
+
+	public function setUp(): void
+	{
+		parent::setUp();
+
+		$this->rule = $this->getDefaultRule();
+	}
+
+	protected function getRule(): Rule
+	{
+		return $this->rule;
+	}
+
+	public static function getAdditionalConfigFiles(): array
+	{
+		return [
+			__DIR__ . '/../../Analyser/usePathConstantsAsConstantString.neon',
+		];
+	}
+
+	private function getDefaultRule(): RequireFileExistsRule
+	{
+		return new RequireFileExistsRule(__DIR__ . '/../');
+	}
+
+	public function testBasicCase(): void
+	{
+		$this->analyse([__DIR__ . '/data/require-file-simple-case.php'], [
+			[
+				'Path in include() "a-file-that-does-not-exist.php" is not a file or it does not exist.',
+				11,
+			],
+			[
+				'Path in include_once() "a-file-that-does-not-exist.php" is not a file or it does not exist.',
+				12,
+			],
+			[
+				'Path in require() "a-file-that-does-not-exist.php" is not a file or it does not exist.',
+				13,
+			],
+			[
+				'Path in require_once() "a-file-that-does-not-exist.php" is not a file or it does not exist.',
+				14,
+			],
+		]);
+	}
+
+	public function testFileDoesNotExistConditionally(): void
+	{
+		$this->analyse([__DIR__ . '/data/require-file-conditionally.php'], [
+			[
+				'Path in include() "a-file-that-does-not-exist.php" is not a file or it does not exist.',
+				9,
+			],
+			[
+				'Path in include_once() "a-file-that-does-not-exist.php" is not a file or it does not exist.',
+				10,
+			],
+			[
+				'Path in require() "a-file-that-does-not-exist.php" is not a file or it does not exist.',
+				11,
+			],
+			[
+				'Path in require_once() "a-file-that-does-not-exist.php" is not a file or it does not exist.',
+				12,
+			],
+		]);
+	}
+
+	public function testRelativePath(): void
+	{
+		$this->analyse([__DIR__ . '/data/require-file-relative-path.php'], [
+			[
+				'Path in include() "data/include-me-to-prove-you-work.txt" is not a file or it does not exist.',
+				8,
+			],
+			[
+				'Path in include_once() "data/include-me-to-prove-you-work.txt" is not a file or it does not exist.',
+				9,
+			],
+			[
+				'Path in require() "data/include-me-to-prove-you-work.txt" is not a file or it does not exist.',
+				10,
+			],
+			[
+				'Path in require_once() "data/include-me-to-prove-you-work.txt" is not a file or it does not exist.',
+				11,
+			],
+		]);
+	}
+
+	public function testRelativePathWithIncludePath(): void
+	{
+		$includePaths = [realpath(__DIR__)];
+		$includePaths[] = get_include_path();
+
+		set_include_path(implode(PATH_SEPARATOR, $includePaths));
+
+		try {
+			$this->analyse([__DIR__ . '/data/require-file-relative-path.php'], []);
+		} finally {
+			set_include_path($includePaths[1]);
+		}
+	}
+
+	public function testRelativePathWithSameWorkingDirectory(): void
+	{
+		$this->rule = new RequireFileExistsRule(__DIR__);
+
+		try {
+			$this->analyse([__DIR__ . '/data/require-file-relative-path.php'], []);
+		} finally {
+			$this->rule = $this->getDefaultRule();
+		}
+	}
+
+}

tests/PHPStan/Rules/Keywords/data/require-file-conditionally.php

@@ -0,0 +1,12 @@
+<?php declare(strict_types=1);
+
+$path = __DIR__ . '/include-me-to-prove-you-work.txt';
+
+if (rand(0,1)) {
+	$path = 'a-file-that-does-not-exist.php';
+}
+
+include $path;
+include_once $path;
+require $path;
+require_once $path;

tests/PHPStan/Rules/Keywords/data/require-file-relative-path.php

@@ -0,0 +1,11 @@
+<?php declare(strict_types=1);
+
+include 'include-me-to-prove-you-work.txt';
+include_once 'include-me-to-prove-you-work.txt';
+require 'include-me-to-prove-you-work.txt';
+require_once 'include-me-to-prove-you-work.txt';
+
+include 'data/include-me-to-prove-you-work.txt';
+include_once 'data/include-me-to-prove-you-work.txt';
+require 'data/include-me-to-prove-you-work.txt';
+require_once 'data/include-me-to-prove-you-work.txt';

tests/PHPStan/Rules/Keywords/data/require-file-simple-case.php

@@ -0,0 +1,14 @@
+<?php declare(strict_types=1);
+
+$fileThatExists = __DIR__ . '/include-me-to-prove-you-work.txt';
+$fileThatDoesNotExist = 'a-file-that-does-not-exist.php';
+
+include $fileThatExists;
+include_once $fileThatExists;
+require $fileThatExists;
+require_once $fileThatExists;
+
+include $fileThatDoesNotExist;
+include_once $fileThatDoesNotExist;
+require $fileThatDoesNotExist;
+require_once $fileThatDoesNotExist;