Fix more edge cases and add type alias support for inline variable validation

Author: rcalicdan

src/Contract/ContractParser.php

@@ -48,8 +48,23 @@ public static function parse(string $function): array
         try {
             if (str_contains($function, '::')) {
                 [$className, $methodName] = explode('::', $function, 2);
-                $ref = new \ReflectionMethod($className, $methodName);
-                $contract = self::parseMethod($ref);
+
+                /** @var class-string<object> $className */
+                $refClass = new \ReflectionClass($className);
+                if ($refClass->hasMethod($methodName)) {
+                    $ref = $refClass->getMethod($methodName);
+                    $contract = self::parseMethod($ref);
+                } else {
+                    $templates = [];
+                    $aliases = [];
+                    self::parseClassLevelDocs($refClass, $templates, $aliases);
+                    $contract = [
+                        'types' => [],
+                        'templates' => $templates,
+                        'return' => null,
+                        'aliases' => $aliases,
+                    ];
+                }
             } else {
                 $ref = new \ReflectionFunction($function);
                 $contract = self::parseFunction($ref);
@@ -81,7 +96,7 @@ public static function parseProperty(string $className, string $propertyName): ?
             $doc = false;
             $declaringClass = null;
 
-            // 1. Search Class and Parent Class Hierarchy
+            // Search Class and Parent Class Hierarchy
             $current = $refClass;
             while ($current !== false) {
                 if ($current->hasProperty($propertyName)) {
@@ -97,7 +112,7 @@ public static function parseProperty(string $className, string $propertyName): ?
                 $current = $current->getParentClass();
             }
 
-            // 2. Search Implemented Interfaces (PHP 8.4 Interface Properties)
+            //  Search Implemented Interfaces (PHP 8.4 Interface Properties)
             if ($doc === false) {
                 foreach ($refClass->getInterfaces() as $interface) {
                     if ($interface->hasProperty($propertyName)) {
@@ -143,6 +158,34 @@ public static function parseProperty(string $className, string $propertyName): ?
         }
     }
 
+    /**
+     * Extracts and returns all class-level type aliases for a given class.
+     *
+     * @return array<string, TypeNode>
+     */
+    public static function parseClassAliases(string $className): array
+    {
+        if (! class_exists($className) && ! interface_exists($className) && ! trait_exists($className)) {
+            return [];
+        }
+
+        try {
+            $refClass = new \ReflectionClass($className);
+            $doc = $refClass->getDocComment();
+            if ($doc === false) {
+                return [];
+            }
+
+            $phpDocNode = DocblockExtractor::parseDocString($doc);
+            $aliases = [];
+            DocblockExtractor::extractAliases($phpDocNode, $aliases, $refClass);
+
+            return $aliases;
+        } catch (\Throwable $e) {
+            return [];
+        }
+    }
+
     /**
      * Orchestrates parsing for class methods across the inheritance hierarchy.
      *
@@ -264,8 +307,10 @@ private static function parseClassLevelDocs(\ReflectionClass $declaringClass, ar
     /**
      * Resolves method-level docblocks (@param, @return, @template, aliases) up the method hierarchy.
      *
+     * @param \ReflectionMethod $ref
      * @param array<string, TypeNode> $types
      * @param array<string, TemplateTagValueNode> $templates
+     * @param TypeNode|null $returnType
      * @param array<string, TypeNode> $aliases
      */
     private static function parseMethodHierarchyDocs(

src/Internal/Checker/InlineChecker.php

@@ -67,6 +67,25 @@ public static function checkVariable(mixed $value, string $typeString, string $v
                 $typeNode = SpecialTypeResolver::resolveForFile($typeNode, $file);
             }
 
+            // Resolve local class-level aliases for the executing context by traversing back the call stack
+            $className = null;
+            $trace = debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS);
+            foreach ($trace as $frame) {
+                $classCandidate = $frame['class'] ?? null;
+                if ($classCandidate !== null && ! str_starts_with($classCandidate, 'TypePHP\\Internal\\') && ! str_starts_with($classCandidate, 'TypePHP\\Wrapper\\')) {
+                    $className = $classCandidate;
+
+                    break;
+                }
+            }
+
+            if ($className !== null) {
+                $classAliases = ContractParser::parseClassAliases($className);
+                if (\count($classAliases) > 0) {
+                    $typeNode = TemplateSubstitutor::substitute($typeNode, $classAliases);
+                }
+            }
+
             if (! self::shouldValidateType($typeNode, $config)) {
                 return $value;
             }

src/Internal/StreamWrapper.php

@@ -239,6 +239,17 @@ public function stream_lock(int $operation): bool
         return @flock($this->handle, $operation);
     }
 
+    public function stream_tell(): int
+    {
+        if ($this->handle === null) {
+            return 0;
+        }
+
+        $res = ftell($this->handle);
+
+        return $res !== false ? $res : 0;
+    }
+
     public function stream_flush(): bool
     {
         if ($this->handle === null) {

src/Internal/StreamWrapperInterface.php

@@ -63,4 +63,6 @@ public function stream_metadata(string $path, int $option, mixed $value): bool;
      * @return resource|false
      */
     public function stream_cast(int $cast_as);
+
+    public function stream_tell(): int;
 }