Watch files through the OS instead of re-hashing them every second

PHPStan Pro's FileMonitor re-hashed every analysed and scanned file on
every poll - 2772 files and ~230ms on a mid-sized project, once a second,
for as long as the browser tab is open. That is also the floor on how
fast an edit can be noticed.

FileMonitor becomes an interface. The old implementation is
HashingFileMonitor and stays the answer for Windows and for anything the
native backends cannot do. FsEventsFileMonitor (macOS) and
InotifyFileMonitor (Linux) reach the kernel through FFI, which needs no
extra extension and works in CLI whatever ffi.enable says.

The native monitors are a gate in front of the hashing one rather than a
replacement: the kernel is only asked "was anything touched", and the
wrapped HashingFileMonitor still decides which files that means, so the
reported FileMonitorResult is what it always was. An idle poll costs one
non-blocking syscall instead of reading the project, which is what lets
the poll interval drop from 1s to 50ms.

kqueue would have been the smaller dependency on macOS but EVFILT_VNODE
on a directory reports directory-entry changes only - a file rewritten in
place, which is what most editor saves are, produces no event at all.

Registering a watch can succeed on a filesystem that then never delivers
anything, and a monitor that silently sees nothing would leave Pro
looking frozen. So initialize() writes a probe file into a watched
directory and refuses the backend unless the kernel reports it, which
costs ~17ms once and turns that failure into a fallback.

Measured on a 2760-file tree, hashing vs native:
  macOS   idle poll 81.9ms -> 0.002ms, detection 1110ms -> 143ms
  Linux   idle poll 34.2ms -> 0.002ms, detection 1065ms -> 104ms
End to end in Pro on a real project, edit to analysis start: 0.749s ->
0.250s, and the full hash passes over a 40s session went from 26 to 4 -
one per edit, none while idle.

PHPSTAN_DISABLE_NATIVE_FILE_MONITOR forces the hashing monitor.

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LD1Zy3qXBVk6ajYdn6QPKu
Amp-Thread-ID: https://ampcode.com/threads/T-01a19219-6ecc-7668-9fe2-6e4d943f7b8e

Author: ondrejmirtes

build/phpstan.neon

@@ -82,6 +82,14 @@ parameters:
 		- '#^Dynamic call to static method PHPUnit\\Framework\\\S+\(\)\.$#'
 		- '#should be contravariant with parameter \$node \(PhpParser\\Node\) of method PHPStan\\Rules\\Rule<PhpParser\\Node>::processNode\(\)$#'
 		- '#Variable property access on PhpParser\\Node#'
+		-
+			# FFI's methods are the C functions declared in the cdef string at
+			# runtime, so no reflection can know them
+			identifier: method.notFound
+			message: '#^Call to an undefined method FFI::#'
+			paths:
+				- ../src/File/FsEventsFileMonitor.php
+				- ../src/File/InotifyFileMonitor.php
 		-
 			identifier: shipmonk.deadMethod
 			message: '#^Unused .*?::__construct#' # likely used in DIC

src/Command/FixerApplication.php

@@ -16,6 +16,7 @@
 use PHPStan\DependencyInjection\AutowiredParameter;
 use PHPStan\DependencyInjection\AutowiredService;
 use PHPStan\File\FileMonitor;
+use PHPStan\File\FileMonitorFactory;
 use PHPStan\File\FileMonitorResult;
 use PHPStan\File\FileReader;
 use PHPStan\File\FileWriter;
@@ -75,7 +76,7 @@ final class FixerApplication
 	 * @param string[] $bootstrapFiles
 	 */
 	public function __construct(
-		private FileMonitor $fileMonitor,
+		private FileMonitorFactory $fileMonitorFactory,
 		private IgnoredErrorHelper $ignoredErrorHelper,
 		private StubFilesProvider $stubFilesProvider,
 		#[AutowiredParameter]
@@ -103,6 +104,8 @@ public function __construct(
 	{
 	}
 
+	private ?FileMonitor $fileMonitor = null;
+
 	public function run(
 		InceptionResult $inceptionResult,
 		InputInterface $input,
@@ -154,7 +157,7 @@ public function run(
 				}
 			});
 
-			$this->fileMonitor->initialize(array_merge(
+			$this->fileMonitor = $this->fileMonitorFactory->create(array_merge(
 				$this->getComposerLocks(),
 				$this->getComposerInstalled(),
 				$this->getExecutedFiles(),
@@ -402,24 +405,29 @@ private function writeInfoFile(string $infoPath, string $version, string $branch
 	 */
 	private function monitorFileChanges(LoopInterface $loop, callable $hasChangesCallback): void
 	{
-		$callback = function () use (&$callback, $loop, $hasChangesCallback): void {
+		if ($this->fileMonitor === null) {
+			throw new ShouldNotHappenException();
+		}
+		$fileMonitor = $this->fileMonitor;
+		$interval = $fileMonitor->getPollInterval();
+		$callback = function () use (&$callback, $loop, $hasChangesCallback, $fileMonitor, $interval): void {
 			if (!$this->fileMonitorActive) {
-				$loop->addTimer(1.0, $callback);
+				$loop->addTimer($interval, $callback);
 				return;
 			}
 			if ($this->processInProgress !== null) {
-				$loop->addTimer(1.0, $callback);
+				$loop->addTimer($interval, $callback);
 				return;
 			}
-			$changes = $this->fileMonitor->getChanges();
+			$changes = $fileMonitor->getChanges();
 
 			if ($changes->hasAnyChanges()) {
 				$hasChangesCallback($changes);
 			}
 
-			$loop->addTimer(1.0, $callback);
+			$loop->addTimer($interval, $callback);
 		};
-		$loop->addTimer(1.0, $callback);
+		$loop->addTimer($interval, $callback);
 	}
 
 	private function analyse(

src/File/DirectoryWalker.php

@@ -42,7 +42,7 @@
  * walk between the two - both happen before the analysis starts, on a file set that is snapshotted
  * for the whole run anyway.
  *
- * FileMonitor detects changes by re-running the finder and must see the filesystem as it is now,
+ * HashingFileMonitor detects changes by re-running the finder and must see the filesystem as it is now,
  * so it walks uncached and clears the shared walks before each check.
  *
  * Reading the directories is what a walk costs - on a tree the size of Drupal core (28k directories)

src/File/FileMonitor.php

@@ -2,151 +2,28 @@
 
 namespace PHPStan\File;
 
-use PHPStan\DependencyInjection\AutowiredParameter;
-use PHPStan\DependencyInjection\AutowiredService;
-use PHPStan\ShouldNotHappenException;
-use function array_diff;
-use function array_key_exists;
-use function array_keys;
-use function array_merge;
-use function array_unique;
-use function hash_file;
-use function is_dir;
-use function is_file;
-
-#[AutowiredService]
-final class FileMonitor
+/**
+ * Watches the analysed and scanned files for changes between PHPStan Pro analyses.
+ *
+ * {@see HashingFileMonitor} is the portable implementation: it re-hashes every
+ * monitored file on every poll. The native implementations
+ * ({@see FsEventsFileMonitor}, {@see InotifyFileMonitor}) wrap it and let the
+ * kernel answer "did anything change at all", so an idle poll touches no files;
+ * once the kernel says yes, they delegate to the hashing monitor so the reported
+ * result is identical either way.
+ *
+ * {@see FileMonitorFactory} picks the implementation for the current platform
+ * and hands it back initialized.
+ */
+interface FileMonitor
 {
 
-	/** @var array<string, string>|null */
-	private ?array $fileHashes = null;
-
-	/** @var array<string>|null */
-	private ?array $filePaths = null;
-
-	/**
-	 * @param string[] $analysedPaths
-	 * @param string[] $analysedPathsFromConfig
-	 * @param string[] $scanFiles
-	 * @param string[] $scanDirectories
-	 */
-	public function __construct(
-		#[AutowiredParameter(ref: '@fileFinderAnalyse')]
-		private FileFinder $analyseFileFinder,
-		#[AutowiredParameter(ref: '@fileFinderScan')]
-		private FileFinder $scanFileFinder,
-		#[AutowiredParameter]
-		private array $analysedPaths,
-		#[AutowiredParameter]
-		private array $analysedPathsFromConfig,
-		#[AutowiredParameter]
-		private array $scanFiles,
-		#[AutowiredParameter]
-		private array $scanDirectories,
-		private DirectoryWalker $directoryWalker,
-	)
-	{
-	}
+	public function getChanges(): FileMonitorResult;
 
 	/**
-	 * @param array<string> $filePaths
+	 * How often the caller should poll. A monitor whose idle poll is free can
+	 * afford a much shorter interval, which is what makes an edit noticed sooner.
 	 */
-	public function initialize(array $filePaths): void
-	{
-		$finderResult = $this->analyseFileFinder->findFiles($this->analysedPaths);
-		$fileHashes = [];
-		foreach (array_unique(array_merge($finderResult->getFiles(), $filePaths, $this->getScannedFiles($finderResult->getFiles()))) as $filePath) {
-			$fileHashes[$filePath] = $this->getFileHash($filePath);
-		}
-
-		$this->fileHashes = $fileHashes;
-		$this->filePaths = $filePaths;
-	}
-
-	public function getChanges(): FileMonitorResult
-	{
-		if ($this->fileHashes === null || $this->filePaths === null) {
-			throw new ShouldNotHappenException();
-		}
-
-		// Detecting a change means looking at the filesystem as it is now, so the walks shared
-		// with the analysis file discovery must not be reused here.
-		$this->directoryWalker->clearCachedWalks();
-		$finderResult = $this->analyseFileFinder->findFiles($this->analysedPaths);
-		$oldFileHashes = $this->fileHashes;
-		$fileHashes = [];
-		$newFiles = [];
-		$changedFiles = [];
-		$deletedFiles = [];
-		$filePaths = array_unique(array_merge($finderResult->getFiles(), $this->filePaths, $this->getScannedFiles($finderResult->getFiles())));
-		foreach ($filePaths as $filePath) {
-			if (!array_key_exists($filePath, $oldFileHashes)) {
-				$newFiles[] = $filePath;
-				$fileHashes[$filePath] = $this->getFileHash($filePath);
-				continue;
-			}
-
-			$oldHash = $oldFileHashes[$filePath];
-			unset($oldFileHashes[$filePath]);
-			$newHash = $this->getFileHash($filePath);
-			$fileHashes[$filePath] = $newHash;
-			if ($oldHash === $newHash) {
-				continue;
-			}
-
-			$changedFiles[] = $filePath;
-		}
-
-		$this->fileHashes = $fileHashes;
-
-		foreach (array_keys($oldFileHashes) as $file) {
-			$deletedFiles[] = $file;
-		}
-
-		return new FileMonitorResult(
-			$newFiles,
-			$changedFiles,
-			$deletedFiles,
-		);
-	}
-
-	private function getFileHash(string $filePath): string
-	{
-		$hash = hash_file('sha256', $filePath);
-
-		if ($hash === false) {
-			throw new CouldNotReadFileException($filePath);
-		}
-
-		return $hash;
-	}
-
-	/**
-	 * @param string[] $allAnalysedFiles
-	 * @return array<string>
-	 */
-	private function getScannedFiles(array $allAnalysedFiles): array
-	{
-		$scannedFiles = $this->scanFiles;
-		$analysedDirectories = [];
-		foreach (array_merge($this->analysedPaths, $this->analysedPathsFromConfig) as $analysedPath) {
-			if (is_file($analysedPath)) {
-				continue;
-			}
-
-			if (!is_dir($analysedPath)) {
-				continue;
-			}
-
-			$analysedDirectories[] = $analysedPath;
-		}
-
-		$directories = array_unique(array_merge($analysedDirectories, $this->scanDirectories));
-		foreach ($this->scanFileFinder->findFiles($directories)->getFiles() as $file) {
-			$scannedFiles[] = $file;
-		}
-
-		return array_diff($scannedFiles, $allAnalysedFiles);
-	}
+	public function getPollInterval(): float;
 
 }

src/File/FileMonitorFactory.php

@@ -0,0 +1,94 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\File;
+
+use PHPStan\DependencyInjection\AutowiredParameter;
+use PHPStan\DependencyInjection\AutowiredService;
+use function getenv;
+use const PHP_OS_FAMILY;
+
+/**
+ * Picks the {@see FileMonitor} for this platform and hands it back initialized.
+ *
+ * Whether a native monitor can actually run is only known once it has opened
+ * its kernel handle and armed every watch, so the fallback decision belongs
+ * here rather than at the call site: a native monitor that cannot promise to
+ * see every change is discarded whole, and {@see HashingFileMonitor} - correct
+ * everywhere, just slower - answers instead.
+ */
+#[AutowiredService]
+final class FileMonitorFactory
+{
+
+	/** Set to anything to force {@see HashingFileMonitor}. */
+	private const DISABLE_ENV_VARIABLE = 'PHPSTAN_DISABLE_NATIVE_FILE_MONITOR';
+
+	/**
+	 * @param string[] $analysedPaths
+	 * @param string[] $analysedPathsFromConfig
+	 * @param string[] $scanDirectories
+	 */
+	public function __construct(
+		private HashingFileMonitor $hashingFileMonitor,
+		#[AutowiredParameter]
+		private array $analysedPaths,
+		#[AutowiredParameter]
+		private array $analysedPathsFromConfig,
+		#[AutowiredParameter]
+		private array $scanDirectories,
+	)
+	{
+	}
+
+	/**
+	 * @param array<string> $filePaths extra files to monitor besides the analysed and scanned ones
+	 */
+	public function create(array $filePaths): FileMonitor
+	{
+		$native = $this->createNative();
+		if ($native !== null) {
+			try {
+				$native->initialize($filePaths);
+
+				return $native;
+			} catch (FileMonitorNotSupportedException) {
+				// fall through to hashing
+			}
+		}
+
+		$this->hashingFileMonitor->initialize($filePaths);
+
+		return $this->hashingFileMonitor;
+	}
+
+	private function createNative(): ?NativeFileMonitor
+	{
+		// escape hatch: the native monitors depend on FFI and on kernel
+		// facilities a container or a hardened host can take away in ways they
+		// cannot detect
+		if (getenv(self::DISABLE_ENV_VARIABLE) !== false) {
+			return null;
+		}
+
+		if (PHP_OS_FAMILY === 'Darwin') {
+			return new FsEventsFileMonitor(
+				$this->hashingFileMonitor,
+				$this->analysedPaths,
+				$this->analysedPathsFromConfig,
+				$this->scanDirectories,
+			);
+		}
+
+		if (PHP_OS_FAMILY === 'Linux') {
+			return new InotifyFileMonitor(
+				$this->hashingFileMonitor,
+				$this->analysedPaths,
+				$this->analysedPathsFromConfig,
+				$this->scanDirectories,
+			);
+		}
+
+		return null;
+	}
+
+}

src/File/FileMonitorNotSupportedException.php

@@ -0,0 +1,15 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\File;
+
+use Exception;
+
+/**
+ * A native file monitor cannot run here - no FFI, the kernel refused a watch,
+ * or the project has more directories than we are willing to watch.
+ * {@see FileMonitorFactory} answers with {@see HashingFileMonitor} instead.
+ */
+final class FileMonitorNotSupportedException extends Exception
+{
+
+}