goaop
diff --git a/‎.github/workflows/phpstan.yml‎
Lines changed: 36 additions & 0 deletions b/‎.github/workflows/phpstan.yml‎
Lines changed: 36 additions & 0 deletions
diff --git a/‎.github/workflows/phpunit.yml‎
Lines changed: 1 addition & 2 deletions b/‎.github/workflows/phpunit.yml‎
Lines changed: 1 addition & 2 deletions
diff --git a/‎CLAUDE.md‎
Lines changed: 64 additions & 0 deletions b/‎CLAUDE.md‎
Lines changed: 64 additions & 0 deletions
diff --git a/‎composer.json‎
Lines changed: 3 additions & 3 deletions b/‎composer.json‎
Lines changed: 3 additions & 3 deletions
diff --git a/‎phpstan.neon‎
Lines changed: 19 additions & 0 deletions b/‎phpstan.neon‎
Lines changed: 19 additions & 0 deletions
diff --git a/‎src/Instrument/PathResolver.php‎
Lines changed: 6 additions & 5 deletions b/‎src/Instrument/PathResolver.php‎
Lines changed: 6 additions & 5 deletions
diff --git a/‎src/Locator/CallableLocator.php‎
Lines changed: 6 additions & 8 deletions b/‎src/Locator/CallableLocator.php‎
Lines changed: 6 additions & 8 deletions
diff --git a/‎src/Locator/ComposerLocator.php‎
Lines changed: 4 additions & 5 deletions b/‎src/Locator/ComposerLocator.php‎
Lines changed: 4 additions & 5 deletions
diff --git a/‎src/NodeVisitor/RootNamespaceNormalizer.php‎
Lines changed: 6 additions & 1 deletion b/‎src/NodeVisitor/RootNamespaceNormalizer.php‎
Lines changed: 6 additions & 1 deletion
diff --git a/‎src/NodeVisitor/StaticVariablesCollector.php‎
Lines changed: 16 additions & 4 deletions b/‎src/NodeVisitor/StaticVariablesCollector.php‎
Lines changed: 16 additions & 4 deletions
@@ -0,0 +1,36 @@
+name: "PHPStan analysis"
+
+permissions:
+  contents: read
+
+on:
+  pull_request:
+  push:
+    branches:
+      - master
+
+jobs:
+  build:
+    name: "PHPStan analysis - PHP8.4"
+    runs-on: ubuntu-latest
+    steps:
+      - name: "Checkout"
+        uses: actions/checkout@v4
+      - name: "Install PHP"
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: "8.4"
+          ini-values: memory_limit=-1
+          tools: composer:v2
+      - name: "Cache dependencies"
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.composer/cache
+            vendor
+          key: "php-8.4"
+          restore-keys: "php-8.4"
+      - name: "Install dependencies"
+        run: "composer install --no-interaction --no-progress"
+      - name: "Static analysis"
+        run: "vendor/bin/phpstan analyze --memory-limit=1G"
@@ -15,9 +15,8 @@ jobs:
           - "lowest"
           - "highest"
         php-version:
+          - "8.5"
           - "8.4"
-          - "8.3"
-          - "8.2"
         operating-system:
           - "ubuntu-latest"
 
 
@@ -0,0 +1,64 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+Parser Reflection is a **deprecated** PHP library (deprecated in favor of [BetterReflection](https://github.com/Roave/BetterReflection)) that extends PHP's internal reflection classes using nikic/PHP-Parser for static analysis. It reflects PHP code without loading classes into memory by parsing source files into an AST.
+
+Requires PHP >=8.4. Namespace: `Go\ParserReflection\`.
+
+## Commands
+
+```bash
+# Install dependencies (slow locally — see note below)
+composer install --prefer-source --no-interaction
+
+# Run tests (~6 seconds, ~10,500 tests)
+vendor/bin/phpunit
+
+# Run a single test file
+vendor/bin/phpunit tests/ReflectionClassTest.php
+
+# Run a specific test method
+vendor/bin/phpunit --filter testMethodName
+
+# Static analysis (~5 seconds, 18 known existing errors are normal)
+vendor/bin/phpstan analyse src --no-progress
+```
+
+> **Note on `composer install` locally**: due to GitHub API rate limits, use `--prefer-source` and set a long timeout: `composer config --global process-timeout 2000`. In CI, standard `composer install` works fine with GitHub tokens.
+
+## Architecture
+
+### Request flow
+
+When you call `new ReflectionClass('SomeClass')`:
+1. `ReflectionClass` asks `ReflectionEngine` for the class's AST node
+2. `ReflectionEngine` uses the registered `LocatorInterface` to find the file
+3. The file is parsed by PHP-Parser into an AST
+4. Two node visitors run: `NameResolver` (resolves FQCNs) and `RootNamespaceNormalizer` (normalizes global namespace)
+5. The resulting `ClassLike` AST node is stored in `ReflectionEngine::$parsedFiles` (in-memory LRU cache)
+6. The node is wrapped in the appropriate reflection class
+
+### Key components
+
+- **`ReflectionEngine`** (`src/ReflectionEngine.php`) — static class; central hub. Owns the PHP-Parser instance, AST cache, and locator. Entry points: `parseFile()`, `parseClass()`, `parseClassMethod()`, etc.
+- **`LocatorInterface`** / **`ComposerLocator`** — pluggable class file finder. `ComposerLocator` delegates to Composer's classmap/autoloader. `bootstrap.php` auto-registers `ComposerLocator` on load.
+- **Reflection classes** (`src/Reflection*.php`) — each extends its PHP internal counterpart (e.g. `ReflectionClass extends \ReflectionClass`) and holds an AST node. Methods that require a live object (e.g. `invoke()`) trigger actual class loading and fall back to native reflection.
+- **Traits** (`src/Traits/`) — shared logic extracted to avoid duplication:
+  - `ReflectionClassLikeTrait` — used by `ReflectionClass`; implements most class inspection methods against the AST
+  - `ReflectionFunctionLikeTrait` — shared by `ReflectionMethod` and `ReflectionFunction`
+  - `InitializationTrait` — lazy initialization of AST node from engine
+  - `InternalPropertiesEmulationTrait` — makes `var_dump`/serialization look like native reflection
+  - `AttributeResolverTrait` — resolves PHP 8 attributes from AST nodes
+- **Resolvers** (`src/Resolver/`) — `NodeExpressionResolver` evaluates constant expressions in the AST (used for default values, constants). `TypeExpressionResolver` resolves type AST nodes into reflection type objects.
+- **`ReflectionFile` / `ReflectionFileNamespace`** — library-specific (not in native PHP reflection). Allow reflecting arbitrary PHP files and iterating their namespaces, classes, functions without knowing class names in advance.
+
+### Test structure
+
+Tests in `tests/` mirror the reflection class names (e.g. `ReflectionClassTest.php`). PHP version-specific stub files in `tests/Stub/` (e.g. `FileWithClasses84.php`) contain the PHP code being reflected. Tests extend `AbstractTestCase` which sets up the `ReflectionEngine` with a `ComposerLocator`.
+
+### CI
+
+GitHub Actions (`.github/workflows/phpunit.yml`) runs PHPUnit on PHP 8.2, 8.3, 8.4 with both lowest and highest dependency versions.
@@ -22,14 +22,14 @@
     }
   },
   "require": {
-    "php": ">=8.2",
+    "php": ">=8.4",
     "nikic/php-parser": "^5.4"
   },
   "require-dev": {
     "phpunit/phpunit": "^11.0.7",
+    "phpstan/phpstan": "^2.0",
     "tracy/tracy": "^2.10",
-    "rector/rector": "^1.0",
-    "rector/rector-php-parser": "^0.14.0"
+    "rector/rector": "^2.0"
   },
   "extra": {
     "branch-alias": {
 
@@ -0,0 +1,19 @@
+parameters:
+  level: 10
+  paths:
+    - src
+  ignoreErrors:
+    # Both classes are final, so "might have hooks in a subclass" is a false positive
+    - identifier: unset.possiblyHookedProperty
+      path: src/ReflectionFunction.php
+    - identifier: unset.possiblyHookedProperty
+      path: src/ReflectionMethod.php
+    # Class names from the AST are semantically class-strings by construction (they come from
+    # parsed PHP class declarations), but PHPStan cannot verify this without autoloading, which
+    # would violate the library's contract of reflecting code without loading classes.
+    - identifier: return.type
+      path: src/Traits/ReflectionClassLikeTrait.php
+      message: '#resolveAsClassString#'
+    - identifier: return.type
+      path: src/Traits/AttributeResolverTrait.php
+      message: '#resolveAttributeClassName#'
@@ -26,10 +26,10 @@ class PathResolver
     /**
      * Custom replacement for realpath() and stream_resolve_include_path()
      *
-     * @param string|array $somePath             Path without normalization or array of paths
-     * @param bool         $shouldCheckExistence Flag for checking existence of resolved filename
+     * @param string|array<int, string> $somePath             Path without normalization or array of paths
+     * @param bool                      $shouldCheckExistence Flag for checking existence of resolved filename
      *
-     * @return array|bool|string
+     * @return ($somePath is array ? array<int, string|false> : string|false)
      */
     public static function realpath($somePath, $shouldCheckExistence = false)
     {
@@ -50,13 +50,14 @@ public static function realpath($somePath, $shouldCheckExistence = false)
             return $fastPath;
         }
 
-        $isRelative = !$pathScheme && ($path[0] !== '/') && ($path[1] !== ':');
+        $isWindowsAbsolutePath = $path !== null && strlen($path) > 1 && preg_match('/^[A-Za-z]:/', $path) === 1;
+        $isRelative = !$pathScheme && $path !== null && !str_starts_with($path, '/') && !$isWindowsAbsolutePath;
         if ($isRelative) {
             $path = getcwd() . DIRECTORY_SEPARATOR . $path;
         }
 
         // resolve path parts (single dot, double dot and double delimiters)
-        $path = str_replace(['/', '\\'], DIRECTORY_SEPARATOR, $path);
+        $path = str_replace(['/', '\\'], DIRECTORY_SEPARATOR, $path ?? '');
         if (strpos($path, '.') !== false) {
             $parts     = explode(DIRECTORY_SEPARATOR, $path);
             $absolutes = [];
 
@@ -12,22 +12,18 @@
 
 namespace Go\ParserReflection\Locator;
 
+use Closure;
 use Go\ParserReflection\LocatorInterface;
 
 /**
  * Locator, that can find a file for the given class name by asking composer
  * @see \Go\ParserReflection\Locator\CallableLocatorTest
  */
-class CallableLocator implements LocatorInterface
+final readonly class CallableLocator implements LocatorInterface
 {
-    /**
-     * @var callable
-     */
-    private $callable;
 
-    public function __construct(callable $callable)
+    public function __construct(private Closure $callable)
     {
-        $this->callable = $callable;
     }
 
     /**
@@ -37,6 +33,8 @@ public function __construct(callable $callable)
      */
     public function locateClass(string $className): false|string
     {
-        return call_user_func($this->callable, ltrim($className, '\\'));
+        $result = ($this->callable)(ltrim($className, '\\'));
+
+        return is_string($result) ? $result : false;
     }
 }
@@ -23,10 +23,8 @@
  */
 class ComposerLocator implements LocatorInterface
 {
-    /**
-     * @var ClassLoader
-     */
-    private $loader;
+
+    private ClassLoader $loader;
 
     public function __construct(?ClassLoader $composerLoader = null)
     {
@@ -54,7 +52,8 @@ public function locateClass(string $className): false|string
     {
         $filePath = $this->loader->findFile(ltrim($className, '\\'));
         if (!empty($filePath)) {
-            $filePath = PathResolver::realpath($filePath);
+            $resolvedPath = PathResolver::realpath($filePath);
+            $filePath = is_string($resolvedPath) ? $resolvedPath : false;
         }
 
         return $filePath;
 
@@ -12,6 +12,7 @@
 
 namespace Go\ParserReflection\NodeVisitor;
 
+use PhpParser\Node\Stmt;
 use PhpParser\Node\Stmt\Declare_;
 use PhpParser\Node\Stmt\Namespace_;
 use PhpParser\NodeVisitorAbstract;
@@ -45,7 +46,11 @@ public function beforeTraverse(array $nodes)
             }
         }
         // Wrap all statements into the namespace block
-        $globalNamespaceNode = new Namespace_(null, array_slice($nodes, $lastDeclareOffset));
+        $stmts = array_values(array_filter(
+            array_slice($nodes, $lastDeclareOffset),
+            static fn ($node) => $node instanceof Stmt
+        ));
+        $globalNamespaceNode = new Namespace_(null, $stmts);
         // Replace top-level nodes with namespaced node
         array_splice($nodes, $lastDeclareOffset, count($nodes), [$globalNamespaceNode]);
 
 
@@ -12,6 +12,7 @@
 
 namespace Go\ParserReflection\NodeVisitor;
 
+use Go\ParserReflection\ReflectionFileNamespace;
 use Go\ParserReflection\Resolver\NodeExpressionResolver;
 use PhpParser\Node;
 use PhpParser\NodeVisitorAbstract;
@@ -23,17 +24,22 @@ class StaticVariablesCollector extends NodeVisitorAbstract
 {
     /**
      * Reflection context, eg. ReflectionClass, ReflectionMethod, etc
+     *
+     * @var \ReflectionClass<object>|\ReflectionFunction|\ReflectionMethod|\ReflectionClassConstant|\ReflectionParameter|\ReflectionAttribute<object>|\ReflectionProperty|ReflectionFileNamespace|null
      */
-    private mixed $context;
+    private \ReflectionClass|\ReflectionFunction|\ReflectionMethod|\ReflectionClassConstant|\ReflectionParameter|\ReflectionAttribute|\ReflectionProperty|ReflectionFileNamespace|null $context;
 
+    /**
+     * @var array<string, mixed>
+     */
     private array $staticVariables = [];
 
     /**
      * Default constructor
      *
-     * @param mixed $context Reflection context, eg. ReflectionClass, ReflectionMethod, etc
+     * @param \ReflectionClass<object>|\ReflectionFunction|\ReflectionMethod|\ReflectionClassConstant|\ReflectionParameter|\ReflectionAttribute<object>|\ReflectionProperty|ReflectionFileNamespace|null $context Reflection context, eg. ReflectionClass, ReflectionMethod, etc
      */
-    public function __construct(mixed $context)
+    public function __construct(\ReflectionClass|\ReflectionFunction|\ReflectionMethod|\ReflectionClassConstant|\ReflectionParameter|\ReflectionAttribute|\ReflectionProperty|ReflectionFileNamespace|null $context)
     {
         $this->context = $context;
     }
@@ -62,7 +68,11 @@ public function enterNode(Node $node)
 
                 if ($staticVariable->var->name instanceof Node\Expr) {
                     $expressionSolver->process($staticVariable->var->name);
-                    $name = $expressionSolver->getValue();
+                    $resolvedName = $expressionSolver->getValue();
+                    if (!is_string($resolvedName)) {
+                        throw new \InvalidArgumentException("Unknown value for the key, " . gettype($resolvedName) . " has given, but string is expected");
+                    }
+                    $name = $resolvedName;
                 } else {
                     $name = $staticVariable->var->name;
                 }
@@ -75,6 +85,8 @@ public function enterNode(Node $node)
 
     /**
      * Returns an associative map of static variables in the method/function body
+     *
+     * @return array<string, mixed>
      */
     public function getStaticVariables(): array
     {
Original file line number	Diff line number	Diff line change
`@@ -26,10 +26,10 @@ class PathResolver`
`26`	`26`	`/**`
`27`	`27`	`* Custom replacement for realpath() and stream_resolve_include_path()`
`28`	`28`	`*`
`29`		`- * @param string\|array $somePath Path without normalization or array of paths`
`30`		`- * @param bool $shouldCheckExistence Flag for checking existence of resolved filename`
	`29`	`+ * @param string\|array<int, string> $somePath Path without normalization or array of paths`
	`30`	`+ * @param bool $shouldCheckExistence Flag for checking existence of resolved filename`
`31`	`31`	`*`
`32`		`- * @return array\|bool\|string`
	`32`	`+ * @return ($somePath is array ? array<int, string\|false> : string\|false)`
`33`	`33`	`*/`
`34`	`34`	`public static function realpath($somePath, $shouldCheckExistence = false)`
`35`	`35`	`{`
`@@ -50,13 +50,14 @@ public static function realpath($somePath, $shouldCheckExistence = false)`
`50`	`50`	`return $fastPath;`
`51`	`51`	`}`
`52`	`52`
`53`		`- $isRelative = !$pathScheme && ($path[0] !== '/') && ($path[1] !== ':');`
	`53`	`+ $isWindowsAbsolutePath = $path !== null && strlen($path) > 1 && preg_match('/^[A-Za-z]:/', $path) === 1;`
	`54`	`+ $isRelative = !$pathScheme && $path !== null && !str_starts_with($path, '/') && !$isWindowsAbsolutePath;`
`54`	`55`	`if ($isRelative) {`
`55`	`56`	`$path = getcwd() . DIRECTORY_SEPARATOR . $path;`
`56`	`57`	`}`
`57`	`58`
`58`	`59`	`// resolve path parts (single dot, double dot and double delimiters)`
`59`		`- $path = str_replace(['/', '\\'], DIRECTORY_SEPARATOR, $path);`
	`60`	`+ $path = str_replace(['/', '\\'], DIRECTORY_SEPARATOR, $path ?? '');`
`60`	`61`	`if (strpos($path, '.') !== false) {`
`61`	`62`	`$parts = explode(DIRECTORY_SEPARATOR, $path);`
`62`	`63`	`$absolutes = [];`
Original file line number	Diff line number	Diff line change
`@@ -12,22 +12,18 @@`
`12`	`12`
`13`	`13`	`namespace Go\ParserReflection\Locator;`
`14`	`14`
	`15`	`+use Closure;`
`15`	`16`	`use Go\ParserReflection\LocatorInterface;`
`16`	`17`
`17`	`18`	`/**`
`18`	`19`	`* Locator, that can find a file for the given class name by asking composer`
`19`	`20`	`* @see \Go\ParserReflection\Locator\CallableLocatorTest`
`20`	`21`	`*/`
`21`		`-class CallableLocator implements LocatorInterface`
	`22`	`+final readonly class CallableLocator implements LocatorInterface`
`22`	`23`	`{`
`23`		`- /**`
`24`		`- * @var callable`
`25`		`- */`
`26`		`- private $callable;`
`27`	`24`
`28`		`- public function __construct(callable $callable)`
	`25`	`+ public function __construct(private Closure $callable)`
`29`	`26`	`{`
`30`		`- $this->callable = $callable;`
`31`	`27`	`}`
`32`	`28`
`33`	`29`	`/**`
`@@ -37,6 +33,8 @@ public function __construct(callable $callable)`
`37`	`33`	`*/`
`38`	`34`	`public function locateClass(string $className): false\|string`
`39`	`35`	`{`
`40`		`- return call_user_func($this->callable, ltrim($className, '\\'));`
	`36`	`+ $result = ($this->callable)(ltrim($className, '\\'));`
	`37`	`+`
	`38`	`+ return is_string($result) ? $result : false;`
`41`	`39`	`}`
`42`	`40`	`}`
Original file line number	Diff line number	Diff line change
`@@ -23,10 +23,8 @@`
`23`	`23`	`*/`
`24`	`24`	`class ComposerLocator implements LocatorInterface`
`25`	`25`	`{`
`26`		`- /**`
`27`		`- * @var ClassLoader`
`28`		`- */`
`29`		`- private $loader;`
	`26`	`+`
	`27`	`+ private ClassLoader $loader;`
`30`	`28`
`31`	`29`	`public function __construct(?ClassLoader $composerLoader = null)`
`32`	`30`	`{`
`@@ -54,7 +52,8 @@ public function locateClass(string $className): false\|string`
`54`	`52`	`{`
`55`	`53`	`$filePath = $this->loader->findFile(ltrim($className, '\\'));`
`56`	`54`	`if (!empty($filePath)) {`
`57`		`- $filePath = PathResolver::realpath($filePath);`
	`55`	`+ $resolvedPath = PathResolver::realpath($filePath);`
	`56`	`+ $filePath = is_string($resolvedPath) ? $resolvedPath : false;`
`58`	`57`	`}`
`59`	`58`
`60`	`59`	`return $filePath;`