Optimize stream wrapper performance (#41)

* Enhance PathMatcher and StreamWrapper with caching improvements; add tests for new functionality in PathMatcher and StreamWrapper

* Remove isReadOnlyCall method from StreamWrapper to streamline code

* Add read-only function detection to StreamWrapper for optimized handling

* Fix missing newline at end of file in StreamWrapper and PathMatcherTest

* Refactor PathMatcherTest and StreamWrapperTest to ensure Config resets after each test case

Author: rcalicdan

src/Internal/PathMatcher.php

@@ -23,6 +23,13 @@ final class PathMatcher
      */
     private static array $compiledExcludesCache = [];
 
+    /**
+     * Cache for include prefix lookup decisions.
+     *
+     * @var array<string, bool>
+     */
+    private static array $includePrefixCache = [];
+
     /**
      * Cached normalized cache directory path.
      */
@@ -40,6 +47,7 @@ public static function reset(): void
     {
         self::$compiledIncludesCache = [];
         self::$compiledExcludesCache = [];
+        self::$includePrefixCache = [];
         self::$cachedCacheDir = null;
         self::$cachedLibSrcDir = null;
     }
@@ -82,8 +90,6 @@ public static function isCachePath(string $normalizedPath): bool
 
     /**
      * Determines whether a path belongs to TypePHP's own internal engine source files.
-     * In vendor mode: skips the entire library package.
-     * In development mode: skips only actual internal subdirectories, allowing test fixtures to be tested.
      */
     public static function isLibraryInternal(string $normalizedPath): bool
     {
@@ -125,6 +131,80 @@ public static function isLibraryInternal(string $normalizedPath): bool
         return false;
     }
 
+    /**
+     * Fast-checks if an include glob list contains any pattern matching a given prefix.
+     *
+     * @param array<int, string> $includes
+     */
+    public static function hasIncludeMatchingPrefix(string $prefix, array $includes): bool
+    {
+        $cacheKey = $prefix . '|' . implode(',', $includes);
+        if (isset(self::$includePrefixCache[$cacheKey])) {
+            return self::$includePrefixCache[$cacheKey];
+        }
+
+        foreach ($includes as $inc) {
+            if (\is_string($inc)) {
+                $norm = str_replace('\\', '/', trim($inc));
+                if (str_starts_with($norm, $prefix) || str_contains($norm, '/' . $prefix)) {
+                    return self::$includePrefixCache[$cacheKey] = true;
+                }
+            }
+        }
+
+        return self::$includePrefixCache[$cacheKey] = false;
+    }
+
+    /**
+     * Determines whether a directory path is a dynamic writable cache/log directory.
+     */
+    public static function isDynamicWritablePath(string $normalizedPath): bool
+    {
+        return str_contains($normalizedPath, '/var/cache/') || str_starts_with($normalizedPath, 'var/cache/')
+            || str_contains($normalizedPath, '/var/log/') || str_starts_with($normalizedPath, 'var/log/')
+            || str_contains($normalizedPath, '/storage/') || str_starts_with($normalizedPath, 'storage/')
+            || str_contains($normalizedPath, '/cache/') || str_starts_with($normalizedPath, 'cache/');
+    }
+
+    /**
+     * High-speed $O(1)$ string pre-filter to determine if a raw path can possibly be included,
+     * while respecting user whitelists for vendor, var, and storage directories.
+     */
+    public static function mayPathBeIncluded(string $normalizedPath): bool
+    {
+        if (str_contains($normalizedPath, '/node_modules/') || str_starts_with($normalizedPath, 'node_modules/')) {
+            return false;
+        }
+
+        if (self::isCachePath($normalizedPath)) {
+            return false;
+        }
+
+        $config = Config::get();
+        /** @var array<int, string> $includes */
+        $includes = \is_array($config['include'] ?? null) ? $config['include'] : ['**'];
+
+        if (str_contains($normalizedPath, '/vendor/') || str_starts_with($normalizedPath, 'vendor/')) {
+            if (! self::hasIncludeMatchingPrefix('vendor/', $includes)) {
+                return false;
+            }
+        }
+
+        if (str_contains($normalizedPath, '/var/') || str_starts_with($normalizedPath, 'var/')) {
+            if (! self::hasIncludeMatchingPrefix('var/', $includes)) {
+                return false;
+            }
+        }
+
+        if (str_contains($normalizedPath, '/storage/') || str_starts_with($normalizedPath, 'storage/')) {
+            if (! self::hasIncludeMatchingPrefix('storage/', $includes)) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
     /**
      * Converts a glob pattern into an absolute anchored regex pattern.
      */

src/Internal/StreamWrapper.php

@@ -48,19 +48,42 @@ final class StreamWrapper implements StreamWrapperInterface
      */
     private static array $statCache = [];
 
+    /**
+     * In-memory cache for static-path negative misses only (e.g. vendor).
+     * Never stores negative misses for dynamic paths (var/cache, storage).
+     *
+     * @var array<string, true>
+     */
+    private static array $staticNegativeStatCache = [];
+
     /**
      * In-memory cache for isApplicationFile path decisions.
      *
      * @var array<string, bool>
      */
     private static array $appFileDecisionCache = [];
 
+    /**
+     * Fast-lookup table for read-only source view functions.
+     *
+     * @var array<string, true>
+     */
+    private const READ_ONLY_FUNCTIONS = [
+        'file_get_contents' => true,
+        'file' => true,
+        'readfile' => true,
+        'highlight_file' => true,
+        'show_source' => true,
+        'token_get_all' => true,
+    ];
+
     /**
      * Resets all internal caches.
      */
     public static function reset(): void
     {
         self::$statCache = [];
+        self::$staticNegativeStatCache = [];
         self::$appFileDecisionCache = [];
         PathMatcher::reset();
     }
@@ -171,26 +194,47 @@ public static function transformSource(string $source, string $filePath = ''): s
      */
     public function stream_open(string $path, string $mode, int $options, ?string &$openedPath): bool
     {
-        // Fast-path: non-PHP files are never transformed
+        if ($mode !== 'r' && $mode !== 'rb' && $mode !== 'rt') {
+            return $this->openDirectHandle($path, $mode);
+        }
+
         if (! str_ends_with(strtolower($path), '.php')) {
             return $this->openDirectHandle($path, $mode);
         }
 
-        // Fast-path: unwhitelisted vendor files are never transformed
+        if (! Config::isEnabled()) {
+            return $this->openDirectHandle($path, $mode);
+        }
+
         $normalizedRaw = str_replace('\\', '/', $path);
-        if (str_contains($normalizedRaw, '/vendor/') || str_starts_with($normalizedRaw, 'vendor/')) {
+
+        if (! PathMatcher::mayPathBeIncluded($normalizedRaw)) {
             return $this->openDirectHandle($path, $mode);
         }
 
+        if (isset(self::$appFileDecisionCache[$normalizedRaw])) {
+            if (! self::$appFileDecisionCache[$normalizedRaw]) {
+                return $this->openDirectHandle($path, $mode);
+            }
+        }
+
         self::unregister();
-        $exists = self::silent(fn () => file_exists($path));
-        $resolvedPath = $exists ? realpath($path) : '';
+        $exists = (bool) self::silent(fn () => file_exists($path));
+        $resolvedPath = $exists ? self::silent(fn () => realpath($path)) : false;
         self::register();
 
-        $isAppFile = $exists && ! self::isReadOnlyCall() && self::isApplicationFile($path, $resolvedPath);
+        if (! $exists || $resolvedPath === false) {
+            return $this->openDirectHandle($path, $mode);
+        }
+
+        $normalizedResolved = str_replace('\\', '/', $resolvedPath);
+
+        if (! self::isApplicationFile($path, $resolvedPath)) {
+            return $this->openDirectHandle($normalizedResolved, $mode);
+        }
 
-        if (! $isAppFile || $resolvedPath === false) {
-            return $this->openDirectHandle(($resolvedPath !== false && $resolvedPath !== '') ? $resolvedPath : $path, $mode);
+        if (self::isReadOnlyCall()) {
+            return $this->openDirectHandle($normalizedResolved, $mode);
         }
 
         self::unregister();
@@ -204,6 +248,20 @@ public function stream_open(string $path, string $mode, int $options, ?string &$
         return $success;
     }
 
+    /**
+     * Determines if the stream_open call is for reading raw file contents/snippets
+     * (e.g. error screen renderers) rather than PHP engine execution.
+     */
+    private static function isReadOnlyCall(): bool
+    {
+        $trace = debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, 3);
+
+        $caller1 = strtolower($trace[1]['function'] ?? '');
+        $caller2 = strtolower($trace[2]['function'] ?? '');
+
+        return isset(self::READ_ONLY_FUNCTIONS[$caller1]) || isset(self::READ_ONLY_FUNCTIONS[$caller2]);
+    }
+
     /**
      * Opens a raw file handle directly without stream interception.
      */
@@ -338,25 +396,36 @@ public function stream_close(): void
 
     /**
      * High-speed stat resolution with $O(1)$ memoization cache.
-     * Never caches false (negative lookups) so newly created directories and files are immediately discovered.
+     * Caches positive stat hits.
+     * Only caches negative misses for STATIC directories (vendor, tests).
+     * NEVER caches negative misses for dynamic writable paths (var/cache, storage),
+     * guaranteeing Symfony/Shopware cache creation is detected immediately.
      *
      * @return array<int|string, int>|false
      */
     public function url_stat(string $path, int $flags): array|false
     {
         $normalized = str_replace('\\', '/', $path);
+
         if (isset(self::$statCache[$normalized])) {
             return self::$statCache[$normalized];
         }
 
+        if (isset(self::$staticNegativeStatCache[$normalized])) {
+            return false;
+        }
+
         self::unregister();
         /** @var array<int|string, int>|false $result */
         $result = self::silent(fn () => stat($path));
         self::register();
 
-        // Only cache positive results (existing files/dirs)
         if ($result !== false) {
             self::$statCache[$normalized] = $result;
+        } else {
+            if (! PathMatcher::isDynamicWritablePath($normalized)) {
+                self::$staticNegativeStatCache[$normalized] = true;
+            }
         }
 
         return $result;
@@ -365,7 +434,7 @@ public function url_stat(string $path, int $flags): array|false
     public function stream_metadata(string $path, int $option, mixed $value): bool
     {
         $normalized = str_replace('\\', '/', $path);
-        unset(self::$statCache[$normalized]);
+        unset(self::$statCache[$normalized], self::$staticNegativeStatCache[$normalized]);
 
         self::unregister();
         $result = false;
@@ -429,10 +498,10 @@ public function dir_closedir(): bool
     public function mkdir(string $path, int $mode, int $options): bool
     {
         $normalized = str_replace('\\', '/', $path);
-        unset(self::$statCache[$normalized]);
+        unset(self::$statCache[$normalized], self::$staticNegativeStatCache[$normalized]);
 
         self::unregister();
-        $result = (bool) self::silent(fn () => mkdir($path, $mode, (bool) ($options & STREAM_MKDIR_RECURSIVE)));
+        $result = (bool) self::silent(fn () => mkdir($path, $mode, ($options & STREAM_MKDIR_RECURSIVE) !== 0));
         self::register();
 
         return $result;
@@ -441,7 +510,7 @@ public function mkdir(string $path, int $mode, int $options): bool
     public function rmdir(string $path, int $options): bool
     {
         $normalized = str_replace('\\', '/', $path);
-        unset(self::$statCache[$normalized]);
+        unset(self::$statCache[$normalized], self::$staticNegativeStatCache[$normalized]);
 
         self::unregister();
         $result = (bool) self::silent(fn () => rmdir($path));
@@ -453,7 +522,7 @@ public function rmdir(string $path, int $options): bool
     public function unlink(string $path): bool
     {
         $normalized = str_replace('\\', '/', $path);
-        unset(self::$statCache[$normalized]);
+        unset(self::$statCache[$normalized], self::$staticNegativeStatCache[$normalized]);
 
         self::unregister();
         $result = (bool) self::silent(fn () => unlink($path));
@@ -466,7 +535,12 @@ public function rename(string $pathFrom, string $pathTo): bool
     {
         $normFrom = str_replace('\\', '/', $pathFrom);
         $normTo = str_replace('\\', '/', $pathTo);
-        unset(self::$statCache[$normFrom], self::$statCache[$normTo]);
+        unset(
+            self::$statCache[$normFrom],
+            self::$statCache[$normTo],
+            self::$staticNegativeStatCache[$normFrom],
+            self::$staticNegativeStatCache[$normTo]
+        );
 
         self::unregister();
         $result = (bool) self::silent(fn () => rename($pathFrom, $pathTo));
@@ -475,18 +549,6 @@ public function rename(string $pathFrom, string $pathTo): bool
         return $result;
     }
 
-    /**
-     * Determines if the current stream_open call is directly for reading file contents
-     * rather than PHP engine's require/include execution.
-     */
-    private static function isReadOnlyCall(): bool
-    {
-        $trace = debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, 3);
-        $callerFunc = strtolower($trace[2]['function'] ?? '');
-
-        return \in_array($callerFunc, ['file_get_contents', 'file', 'readfile', 'highlight_file', 'show_source', 'token_get_all'], true);
-    }
-
     /**
      * Executes a callback while temporarily suppressing PHP error and warning handlers.
      *