Enhance support for upper bound and default template

.github/workflows/ci.yml

@@ -45,18 +45,21 @@ jobs:
       - name: Warm Up TypePHP Cache
         run: php bin/typephp cache:warm
 
-      - name: Run Test Suite with Coverage (Pest)
+      - name: Run Runtime Type Checking Engine Suite (Pest)
+        run: ./vendor/bin/pest tests/TypeChecking --compact
+
+      - name: Run Full Test Suite with Coverage (Pest)
         run: ./vendor/bin/pest --coverage-clover=clover.xml --compact
         if: matrix.os == 'ubuntu-latest' && matrix.php == '8.4'
 
+      - name: Run Full Test Suite (Pest)
+        run: ./vendor/bin/pest --compact
+        if: "! (matrix.os == 'ubuntu-latest' && matrix.php == '8.4')"
+
       - name: Upload Coverage to Codecov
         uses: codecov/codecov-action@v5
         if: matrix.os == 'ubuntu-latest' && matrix.php == '8.4'
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
           files: clover.xml
-          fail_ci_if_error: false
-
-      - name: Run Test Suite (Pest)
-        run: ./vendor/bin/pest --compact
-        if: "! (matrix.os == 'ubuntu-latest' && matrix.php == '8.4')"
+          fail_ci_if_error: false

src/Contract/ContractParser.php

@@ -524,7 +524,7 @@ private static function parseFunction(\ReflectionFunction $ref): array
         $stubDoc = StubManager::getFunctionDoc($funcName);
         $doc = $stubDoc ?? $ref->getDocComment();
 
-        if ($doc === false || $doc === null) {
+        if ($doc === false || $doc === null || self::shouldIgnoreDoc($doc)) {
             return [
                 'types' => [],
                 'templates' => [],
@@ -563,12 +563,10 @@ private static function parseFunction(\ReflectionFunction $ref): array
             }
 
             $pObj = $baseParamObjects[$paramName] ?? null;
-            $isTemplateType = ($type instanceof IdentifierTypeNode && isset($templates[$type->name]));
             if (
                 Config::isRespectNativeNullabilityEnabled()
                 && $pObj !== null
                 && self::parameterExplicitlyAllowsNull($pObj)
-                && ! $isTemplateType
                 && ! self::typeContainsNull($type)
             ) {
                 $type = new NullableTypeNode($type);
@@ -692,7 +690,7 @@ private static function parseMethodHierarchyDocs(
             }
 
             $doc = $stubDoc ?? $hierRef->getDocComment();
-            if ($doc === false || $doc === null) {
+            if ($doc === false || $doc === null || self::shouldIgnoreDoc($doc)) {
                 continue;
             }
 
@@ -734,12 +732,10 @@ private static function parseMethodHierarchyDocs(
                     }
 
                     $pObj = $baseParamObjects[$targetParamName] ?? null;
-                    $isTemplateType = ($type instanceof IdentifierTypeNode && isset($templates[$type->name]));
                     if (
                         Config::isRespectNativeNullabilityEnabled()
                         && $pObj !== null
                         && self::parameterExplicitlyAllowsNull($pObj)
-                        && ! $isTemplateType
                         && ! self::typeContainsNull($type)
                     ) {
                         $type = new NullableTypeNode($type);
@@ -857,11 +853,9 @@ private static function applyConstructorPromotionFallback(
                             $resolvedProp = new ArrayTypeNode($resolvedProp);
                         }
 
-                        $isTemplateType = ($resolvedProp instanceof IdentifierTypeNode && isset($classTemplates[$resolvedProp->name]));
                         if (
                             Config::isRespectNativeNullabilityEnabled()
                             && self::parameterExplicitlyAllowsNull($p)
-                            && ! $isTemplateType
                             && ! self::typeContainsNull($resolvedProp)
                         ) {
                             $resolvedProp = new NullableTypeNode($resolvedProp);

src/Internal/Checker/ParamChecker.php

@@ -348,8 +348,7 @@ private static function validateSingleParam(
 
         $isClassStringT = ($typeNode instanceof GenericTypeNode && self::isClassStringTemplate($typeNode, $templates));
 
-        $isBareTemplate = ($typeNode instanceof IdentifierTypeNode && isset($templates[$typeNode->name]))
-            || ($typeNode instanceof ArrayTypeNode && $typeNode->type instanceof IdentifierTypeNode && isset($templates[$typeNode->type->name]));
+        $isBareTemplate = self::getTemplateName($typeNode, $templates) !== null;
 
         $shouldSkipTemplateSub = $isBareTemplate || $isClassStringT;
 
@@ -557,10 +556,27 @@ private static function getTemplateName(TypeNode $typeNode, array $templates): ?
             return $typeNode->name;
         }
 
+        if ($typeNode instanceof NullableTypeNode && $typeNode->type instanceof IdentifierTypeNode && isset($templates[$typeNode->type->name])) {
+            return $typeNode->type->name;
+        }
+
         if ($typeNode instanceof ArrayTypeNode && $typeNode->type instanceof IdentifierTypeNode && isset($templates[$typeNode->type->name])) {
             return $typeNode->type->name;
         }
 
+        if ($typeNode instanceof UnionTypeNode && \count($typeNode->types) === 2) {
+            $t0 = $typeNode->types[0];
+            $t1 = $typeNode->types[1];
+
+            if ($t0 instanceof IdentifierTypeNode && isset($templates[$t0->name]) && $t1 instanceof IdentifierTypeNode && strtolower($t1->name) === 'null') {
+                return $t0->name;
+            }
+
+            if ($t1 instanceof IdentifierTypeNode && isset($templates[$t1->name]) && $t0 instanceof IdentifierTypeNode && strtolower($t0->name) === 'null') {
+                return $t1->name;
+            }
+        }
+
         return null;
     }
 
@@ -583,6 +599,11 @@ private static function resolveTemplateParam(
 
         $templateNode = $templates[$templateName];
         $isVariadic = $typeNode instanceof ArrayTypeNode;
+        $isNullable = ($typeNode instanceof NullableTypeNode) || ($typeNode instanceof UnionTypeNode && self::typeContainsNull($typeNode));
+
+        if ($isNullable && $val === null) {
+            return null;
+        }
 
         $contract = ContractParser::parse($function);
         $classTemplates = $contract['classTemplates'] ?? [];
@@ -641,4 +662,25 @@ private static function resolveTemplateParam(
 
         return null;
     }
+
+    private static function typeContainsNull(TypeNode $node): bool
+    {
+        if ($node instanceof NullableTypeNode) {
+            return true;
+        }
+
+        if ($node instanceof IdentifierTypeNode && strtolower($node->name) === 'null') {
+            return true;
+        }
+
+        if ($node instanceof UnionTypeNode) {
+            foreach ($node->types as $t) {
+                if (self::typeContainsNull($t)) {
+                    return true;
+                }
+            }
+        }
+
+        return false;
+    }
 }

src/Internal/ContractVisitor.php

@@ -5,7 +5,6 @@
 namespace TypePHP\Internal;
 
 use PhpParser\Node;
-use PhpParser\NodeTraverser;
 use PhpParser\NodeVisitorAbstract;
 use TypePHP\Contract\DocblockExtractor;
 use TypePHP\Internal\Visitor\FunctionContractInjector;
@@ -28,9 +27,9 @@ public function __construct()
     /**
      * Traverses and transforms AST nodes during entry.
      *
-     * @return array<Node>|int|null
+     * @return array<Node>|null
      */
-    public function enterNode(Node $node): array|int|null
+    public function enterNode(Node $node): ?array
     {
         if ($node instanceof Node\Stmt\Function_
             || $node instanceof Node\Stmt\ClassMethod
@@ -49,15 +48,6 @@ public function enterNode(Node $node): array|int|null
         }
 
         if ($node instanceof Node\Stmt\Function_ || $node instanceof Node\Stmt\ClassMethod) {
-            $doc = $node->getDocComment();
-            if ($doc !== null) {
-                $docText = $doc->getText();
-                $shouldRespectIgnore = (bool) (Config::get()['respect_ignore_tags'] ?? true);
-                if ($shouldRespectIgnore && (str_contains($docText, '@typephp-ignore') || str_contains($docText, '@typephp-disable'))) {
-                    return NodeTraverser::DONT_TRAVERSE_CHILDREN;
-                }
-            }
-
             FunctionContractInjector::inject($node);
 
             return null;

src/Internal/Visitor/FunctionContractInjector.php

@@ -7,7 +7,6 @@
 use PhpParser\Node;
 use PhpParser\NodeTraverser;
 use PhpParser\NodeVisitorAbstract;
-use TypePHP\Internal\Config;
 
 /**
  * @internal Injects parameter checks, return checks, and generator interceptors into functions and methods.
@@ -29,10 +28,6 @@ public static function inject(Node\Stmt\Function_|Node\Stmt\ClassMethod $node):
 
         $docText = $doc !== null ? $doc->getText() : '';
 
-        if (self::shouldSkipInjection($docText)) {
-            return;
-        }
-
         $methodName = $isClassMethod ? strtolower($node->name->toString()) : '';
         $isMagicLifecycle = $isClassMethod && \in_array($methodName, ['__construct', '__destruct', '__clone'], true);
 
@@ -123,13 +118,6 @@ private static function hasReturnContracts(string $docText, bool $isClassMethod)
         return false;
     }
 
-    private static function shouldSkipInjection(string $docText): bool
-    {
-        $shouldRespectIgnore = (bool) (Config::get()['respect_ignore_tags'] ?? true);
-
-        return $shouldRespectIgnore && (str_contains($docText, '@typephp-ignore') || str_contains($docText, '@typephp-disable'));
-    }
-
     private static function resolveThisArg(bool $isClassMethod, Node\Stmt\Function_|Node\Stmt\ClassMethod $node): Node\Expr
     {
         if (! $isClassMethod) {

src/Resolver/SpecialTypeResolver.php

@@ -374,6 +374,11 @@ private static function getReflectionContext(\ReflectionClass|\ReflectionFunctio
                 return self::$reflectionContextCache[$context] = new \ReflectionClass($fallbackClass);
             }
 
+            if (class_exists($context) || interface_exists($context) || trait_exists($context) || enum_exists($context)) {
+                /** @var class-string<object> $context */
+                return self::$reflectionContextCache[$context] = new \ReflectionClass($context);
+            }
+
             try {
                 return self::$reflectionContextCache[$context] = new \ReflectionFunction($context);
             } catch (\ReflectionException $e) {