Update documentation and improve caching configuration details

Author: rcalicdan

docs/advanced/how-it-works.md

@@ -93,11 +93,13 @@ TypePHP solves this using `TypePHPPrinter` and regex post-processing. Injected g
 
 ### Disk Caching
 
-Once transformed, TypePHP saves the resulting code to disk in `sys_get_temp_dir() . '/typephp-cache/'`. On all subsequent requests:
+Once transformed, TypePHP saves the resulting code to disk in your configured `cache_dir` (which defaults to `sys_get_temp_dir() . '/typephp-cache/'`). On all subsequent requests:
 * AST parsing runs **0 times**.
 * PHP's **OPCache** compiles the cached file once into bytecode in RAM.
 * Stream file reads execute natively at C-level speed inside Zend Engine.
 
+*(TypePHP's stream wrapper automatically detects and skips intercepting files inside your configured `cache_dir` to prevent infinite loops and double-transformation overhead).*
+
 ---
 
 ## Typed Arrays and Array Shapes
@@ -182,10 +184,6 @@ For function-level templates (`@template T`), TypePHP pushes a temporary call fr
 
 ---
 
-Here is the updated, brief **Validation Error Messages and Trace Attribution** section for `docs/architecture/how-it-works.md`:
-
----
-
 ## Validation Error Messages and Trace Attribution
 
 When a type contract fails, TypePHP constructs informative error messages through a 3-tier pipeline:

docs/getting-started/configuration.md

@@ -54,11 +54,17 @@ return [
 
     /*
     |--------------------------------------------------------------------------
-    | Enable Caching
-    |--------------------------------------------------------------------------
-    | Pre-transforms and caches PHP files on disk for maximum speed.
+    | Enable Caching & Cache Directory
+    |--------------------------------------------------------------------------
+    | Pre-transforms and caches PHP files on disk for OPcache optimization.
+    |
+    | 'cache_dir' determines where these files are stored. By default (null), 
+    | it uses your system's temp directory. You can change this to a path
+    | inside your project (e.g., __DIR__ . '/storage/framework/typephp').
+    | TypePHP automatically protects this directory from being double-transformed.
     */
     'cache' => true,
+    'cache_dir' => null,
 
     /*
     |--------------------------------------------------------------------------
@@ -90,7 +96,7 @@ return [
     | Included Paths & Whitelisting
     |--------------------------------------------------------------------------
     | Globs or specific file paths that should be intercepted and type-checked.
-    | Note: you can just specify "*" glob pattern to include all files including in the root folder.
+    | Note: you can just specify "**" glob pattern to include all files including in the root folder.
     */
     'include' => [
         'src/**',
@@ -129,34 +135,42 @@ Key options explained:
 | **`'magic_properties'`** | `true` | Enforces class-level `@property`, `@property-read`, and `@property-write` annotations on dynamic assignments (`__set`). |
 | **`'magic_methods'`** | `true` | Enforces class-level `@method` annotations on dynamic method calls (`__call` / `__callStatic`). |
 | **`'respect_ignore_tags'`** | `true` | Respects `@typephp-ignore` and `@typephp-ignore-file` tags. Set to `false` in CI/CD to force audit checks. |
-| **`'cache'`** | `true` | Pre-transforms and caches PHP files on disk (`typephp-cache/`) for OPcache optimization. |
+| **`'cache'`** | `true` | Pre-transforms and caches PHP files on disk. |
+| **`'cache_dir'`** | `null` | Custom path to store cached files. Defaults to system temporary directory (`sys_get_temp_dir() . '/typephp-cache/'`). |
 
 ---
 
 ## Inline Variable Categories Reference (`inline_vars`)
 
-How each `inline_vars` toggle maps to PHPDoc type annotations:
+*(... rest of the file remains exactly the same ...)*
+```
 
-| Config Option | Covered PHPDoc Types | Examples |
-| :--- | :--- | :--- |
-| **`'scalars'`** | Primitive & Refined Scalars | `int`, `string`, `bool`, `positive-int`, `non-empty-string`, `truthy` |
-| **`'objects'`** | Class Instances & Bare Class References | `User`, `stdClass`, `class-string`, `interface-string`, `enum-string` |
-| **`'generics'`** | Template & Bound Types | `Collection<User>`, `Producer<T>`, `class-string<T>` |
-| **`'arrays'`** | All Arrays, Shapes, & Lists | `array{id: int}`, `int[]`, `User[]`, `list<string>`, `array<string, int>` |
-| **`'callables'`** | Callables & Closures | `callable`, `Closure`, `callable(int): string`, `static-closure` |
-| **`'properties'`** | Class Property Writes | `$this->id = 1`, `UserProfile::$username = 'Alice'` |
+---
+
+### 2. `docs/advanced/how-it-works.md`
+
+*(Find the "Zero Line-Drift Formatting and Caching" section and update the "Disk Caching" part to this:)*
 
-### Important Notes on `inline_vars` Behavior
+```markdown
+### Disk Caching
 
-* **Inner Structural Types Are Always Validated:** Disabling `'scalars' => false` only turns off standalone scalar assignments (such as `/** @var positive-int $x */`). If `'arrays'` or `'generics'` is enabled, TypePHP **will still validate inner scalar constraints** inside array shapes (`array{id: positive-int}`), lists (`list<positive-int>`), or generic containers (`Collection<positive-int>`) to maintain structural type integrity.
-* **Active Generic Instance Prebinding:** Enabling `'generics' => true` allows inline `@var` annotations on object instantiations (such as `/** @var Collection<User> $users */ $users = new Collection();`) to **actively prebind generic template parameters (`T = User`)** directly to that object instance in `WeakMap` memory. Every subsequent method call on that instance (`$users->add()`, `$users->get()`) will enforce `T = User`!
+Once transformed, TypePHP saves the resulting code to disk in your configured `cache_dir` (which defaults to `sys_get_temp_dir() . '/typephp-cache/'`). On all subsequent requests:
+* AST parsing runs **0 times**.
+* PHP's **OPCache** compiles the cached file once into bytecode in RAM.
+* Stream file reads execute natively at C-level speed inside Zend Engine.
+
+*(TypePHP's stream wrapper automatically detects and skips intercepting files inside your configured `cache_dir` to prevent infinite loops and double-transformation overhead).*
+```
 
 ---
 
-## Pattern Specificity Rules
+### 3. `docs/troubleshooting.md`
+
+*(Find the "How do I know if TypePHP is actively transforming a file?" question and update the answer:)*
 
-If a file matches both an `include` rule and an `exclude` rule, TypePHP compares pattern lengths:
+```markdown
 
-* **Specific Whitelist Wins:** `'vendor/my-org/package/**'` (length 25) takes precedence over `'vendor/**'` (length 8).
-* **Single File Override:** `'src/LegacyFile.php'` (length 22) takes precedence over `'src/**'` (length 6).
-* **Tie-Breaker:** If pattern lengths are equal, `exclude` takes precedence to ensure application safety.
+```
+
+---
+All docs are updated! What's our next target? Should we start refactoring validators, expanding the Extension System, or write a quick web-framework mock test?

docs/troubleshooting.md

@@ -22,7 +22,15 @@ If TypePHP is not enforcing contracts on a specific file or method, check the fo
 You can verify that a file is being intercepted and transformed in two ways:
 
 1. **Intentionally Trigger an Error:** Pass an invalid argument (such as a negative integer to a `positive-int` parameter). If a `TypePHP\Exception\TypeError` is thrown, TypePHP is active.
-2. **Inspect the Cache Directory:** Look inside your system temporary directory (`sys_get_temp_dir() . '/typephp-cache/'`). You will see transformed PHP files containing injected `RuntimeTypeChecker` calls.
+2. **Inspect the Cache Directory:** Look inside your configured `cache_dir` (if undefined, this defaults to your system temporary directory: `sys_get_temp_dir() . '/typephp-cache/'`). You will see transformed PHP files containing injected `RuntimeTypeChecker` calls.
+
+---
+
+### Why are files inside my custom `cache_dir` not being intercepted?
+
+If you configured a custom `cache_dir` inside your project directory (e.g., `__DIR__ . '/storage/typephp'`) and set your include paths to `['**']`, you might wonder why the cache files aren't being transformed.
+
+**This is a built-in safety mechanism.** TypePHP automatically detects your `cache_dir` and unconditionally excludes it from its internal `StreamWrapper` and `FileFilter`. This prevents catastrophic infinite loops and double-parsing overhead that would occur if TypePHP tried to intercept and transform its own cached files.
 
 ---
 

src/Contract/FileFilter.php

@@ -68,7 +68,7 @@ public static function isFileExcluded(string|false|null $fileName): bool
         // Equal specificity tie-breaker: Exclude wins!
         return $longestExcludeMatch >= $longestIncludeMatch;
     }
-    
+
     /**
      * Converts a glob pattern into an absolute regex pattern.
      */

src/Internal/StreamWrapper.php

@@ -504,9 +504,9 @@ private static function isReadOnlyCall(): bool
         return \in_array($callerFunc, ['file_get_contents', 'file', 'readfile', 'highlight_file', 'show_source', 'token_get_all'], true);
     }
 
-   /**
-     * Determines whether a target PHP file path should be intercepted using Pattern Specificity.
-     */
+    /**
+      * Determines whether a target PHP file path should be intercepted using Pattern Specificity.
+      */
     private static function isApplicationFile(string $path, string|false $resolvedPath): bool
     {
         if (! (bool) (Config::get()['enabled'] ?? true)) {

src/Internal/Visitor/PropertyHookInjector.php

@@ -124,4 +124,4 @@ public function enterNode(Node $node): int|null
 
         return $newStmts;
     }
-}
+}

tests/Contract/FileFilterTest.php

@@ -153,7 +153,8 @@
         $normalFilePath = str_replace('\\', '/', getcwd() . '/app/Models/User.php');
 
         expect(FileFilter::isFileExcluded($cachedFilePath))->toBeTrue()
-            ->and(FileFilter::isFileExcluded($normalFilePath))->toBeFalse();
+            ->and(FileFilter::isFileExcluded($normalFilePath))->toBeFalse()
+        ;
 
         Config::reset();
     });

tests/Visitor/PropertyHookInjectorTest.php

@@ -75,4 +75,4 @@
             ->and($body[0]->getAttribute('typephp_injected'))->toBeTrue()
         ;
     });
-});
+});

typephp.php

@@ -49,7 +49,7 @@
     | When enabled, transformed PHP files are cached on disk for speed.
     | Set to false to run AST transformations purely in RAM (php://memory).
     |
-    | 'cache_dir' determines where these files are stored. By default (null), 
+    | 'cache_dir' determines where these files are stored. By default (null),
     | it uses your system's temp directory. You can change this to a path
     | inside your project, e.g., __DIR__ . '/storage/framework/typephp'.
     | TypePHP will automatically protect this directory from being re-transformed.