make array optmization configurable

Author: rcalicdan

src/Command/ConfigInitCommand.php

@@ -110,6 +110,21 @@ private static function getTemplate(): string
         // \Acme\Domain\TypePHPExtension::class,
     ],
 
+    /*
+    |--------------------------------------------------------------------------
+    | Array Validation Strategy
+    |--------------------------------------------------------------------------
+    | Controls how collections (list<T>, array<K, V>, Type[]) are verified:
+    |
+    | - 'full'   : (Default / Strict) 100% exhaustive scan. Checks every single 
+    |             item in every array, guaranteeing every single offending item
+    |             is caught without exception.
+    |
+    | - 'hybrid' : (Beartype O(1) Mode) Fast boundary + random sampling on
+    |             arrays > 64 items. Ideal for massive production datasets.
+    */
+    'array_validation' => 'full',
+
     /*
     |--------------------------------------------------------------------------
     | Inline Variable Validation (@var $x = ...)

src/Internal/Config.php

@@ -42,6 +42,8 @@ final class Config
 
     private static bool $respectIgnoreTags = true;
 
+    private static string $arrayValidation = 'full';
+
     public static function isEnabled(): bool
     {
         if (self::$cachedConfig === null) {
@@ -96,6 +98,24 @@ public static function isRespectIgnoreTagsEnabled(): bool
         return self::$respectIgnoreTags;
     }
 
+    public static function isArrayValidationHybrid(): bool
+    {
+        if (self::$cachedConfig === null) {
+            self::get();
+        }
+
+        return self::$arrayValidation === 'hybrid';
+    }
+
+    public static function getArrayValidationStrategy(): string
+    {
+        if (self::$cachedConfig === null) {
+            self::get();
+        }
+
+        return self::$arrayValidation;
+    }
+
     /**
      * Locates the project root directory by searching upwards for vendor/autoload.php or composer.json.
      * Caches the result in memory so the search happens exactly once.
@@ -158,6 +178,7 @@ public static function get(): array
             'magic_properties' => true,
             'magic_methods' => true,
             'respect_ignore_tags' => true,
+            'array_validation' => 'full',
             'cache' => true,
             'cache_dir' => null,
             'inline_vars' => [
@@ -232,6 +253,7 @@ public static function reset(): void
         self::$magicProperties = true;
         self::$magicMethods = true;
         self::$respectIgnoreTags = true;
+        self::$arrayValidation = 'full';
 
         ContractParser::reset();
         ParamChecker::reset();
@@ -256,5 +278,6 @@ private static function syncFlags(array $config): void
         self::$magicProperties = (bool) ($config['magic_properties'] ?? true);
         self::$magicMethods = (bool) ($config['magic_methods'] ?? true);
         self::$respectIgnoreTags = (bool) ($config['respect_ignore_tags'] ?? true);
+        self::$arrayValidation = (string) ($config['array_validation'] ?? 'full');
     }
 }

src/Validator/ArrayValidator.php

@@ -8,19 +8,20 @@
 use PHPStan\PhpDocParser\Ast\Type\ArrayTypeNode;
 use PHPStan\PhpDocParser\Ast\Type\TypeNode;
 use Traversable;
+use TypePHP\Internal\Config;
 use TypePHP\Internal\ErrorFactory;
 use TypePHP\Internal\ErrorMessage;
 use TypePHP\Internal\TypeFormatter;
 
 /**
  * Validates array and Traversable collection instances against ArrayTypeNode ASTs (Type[]).
- * Implements a Beartype-inspired hybrid O(1) sampling algorithm for large collections.
+ * Supports both exhaustive O(n) verification and Beartype-style hybrid O(1) sampling.
  *
  * @internal
  */
 final class ArrayValidator implements TypeValidatorInterface
 {
-    private const HYBRID_SAMPLE_THRESHOLD = 64;
+    private const HYBRID_SAMPLE_THRESHOLD = 128;
 
     /**
      * Validates an array or Traversable collection against an ArrayTypeNode (Type[]).
@@ -46,7 +47,7 @@ public function validate(mixed $value, TypeNode $node, string $context, TypeVali
                 return null;
             }
 
-            if ($count > self::HYBRID_SAMPLE_THRESHOLD) {
+            if ($count > self::HYBRID_SAMPLE_THRESHOLD && Config::isArrayValidationHybrid()) {
                 return $this->validateArrayHybrid($value, $arrayNode, $context, $registry, $count);
             }
 
@@ -119,4 +120,4 @@ private function validateArrayHybrid(
 
         return null;
     }
-}
+}

src/Validator/GenericValidator.php

@@ -13,6 +13,7 @@
 use PHPStan\PhpDocParser\Ast\Type\IdentifierTypeNode;
 use PHPStan\PhpDocParser\Ast\Type\TypeNode;
 use TypePHP\Internal\ClassNameValidator;
+use TypePHP\Internal\Config;
 use TypePHP\Internal\ErrorFactory;
 use TypePHP\Internal\ErrorMessage;
 use TypePHP\Internal\RuntimeTypeChecker;
@@ -361,7 +362,6 @@ private function validateClassString(mixed $value, GenericTypeNode $node, string
 
     /**
      * Validates sequential list structures (e.g. list<string> or non-empty-list<int>).
-     * Uses Beartype-style O(1) hybrid sampling for large lists (> 64 items).
      */
     private function validateList(mixed $value, GenericTypeNode $node, string $context, TypeValidatorRegistry $registry): ?ErrorMessage
     {
@@ -381,8 +381,7 @@ private function validateList(mixed $value, GenericTypeNode $node, string $conte
         if ($valueTypeNode !== null && $count > 0) {
             $isComplexObjectGeneric = ($valueTypeNode instanceof GenericTypeNode && ! \in_array(strtolower($valueTypeNode->type->name), ['class-string', 'list', 'array', 'iterable'], strict: true));
 
-            // O(1) Beartype Hybrid Sampling for large lists (> 64 items)
-            if ($count > self::HYBRID_SAMPLE_THRESHOLD) {
+            if ($count > self::HYBRID_SAMPLE_THRESHOLD && Config::isArrayValidationHybrid()) {
                 $sampleIndices = [0, $count - 1];
                 $samplesToTake = min(3, $count - 2);
                 for ($i = 0; $i < $samplesToTake; $i++) {
@@ -403,7 +402,6 @@ private function validateList(mixed $value, GenericTypeNode $node, string $conte
                 return null;
             }
 
-            // Full O(n) scan for small/medium lists (<= 64 items)
             foreach ($value as $k => $v) {
                 $err = $isComplexObjectGeneric
                     ? $this->validateObjectGeneric($v, $valueTypeNode, '')
@@ -420,7 +418,6 @@ private function validateList(mixed $value, GenericTypeNode $node, string $conte
 
     /**
      * Validates key-value array structures (e.g. array<string, int>).
-     * Uses Beartype-style O(1) hybrid sampling for large maps (> 64 items).
      */
     private function validateArray(mixed $value, GenericTypeNode $node, string $context, TypeValidatorRegistry $registry): ?ErrorMessage
     {
@@ -448,8 +445,7 @@ private function validateArray(mixed $value, GenericTypeNode $node, string $cont
         if ($typesCount === 1) {
             $valTypeNode = $node->genericTypes[0];
             $isComplexObjectGeneric = ($valTypeNode instanceof GenericTypeNode && ! \in_array(strtolower($valTypeNode->type->name), ['class-string', 'list', 'array', 'iterable'], strict: true));
-
-            if ($count > self::HYBRID_SAMPLE_THRESHOLD) {
+            if ($count > self::HYBRID_SAMPLE_THRESHOLD && Config::isArrayValidationHybrid()) {
                 $keys = array_keys($value);
                 $sampleKeys = [$keys[0], $keys[$count - 1]];
                 $samplesToTake = min(3, $count - 2);
@@ -485,7 +481,7 @@ private function validateArray(mixed $value, GenericTypeNode $node, string $cont
             $valTypeNode = $node->genericTypes[1];
             $isComplexObjectGeneric = ($valTypeNode instanceof GenericTypeNode && ! \in_array(strtolower($valTypeNode->type->name), ['class-string', 'list', 'array', 'iterable'], strict: true));
 
-            if ($count > self::HYBRID_SAMPLE_THRESHOLD) {
+            if ($count > self::HYBRID_SAMPLE_THRESHOLD && Config::isArrayValidationHybrid()) {
                 $keys = array_keys($value);
                 $sampleKeys = [$keys[0], $keys[$count - 1]];
                 $samplesToTake = min(3, $count - 2);
@@ -547,4 +543,4 @@ private function validateObjectGeneric(mixed $value, GenericTypeNode $node, stri
 
         return RuntimeTypeChecker::bindInstanceFromNode($value, $node, $context);
     }
-}
+}

typephp.php

@@ -67,6 +67,21 @@
         // \Acme\Domain\TypePHPExtension::class,
     ],
 
+     /*
+    |--------------------------------------------------------------------------
+    | Array Validation Strategy
+    |--------------------------------------------------------------------------
+    | Controls how collections (list<T>, array<K, V>, Type[]) are verified:
+    |
+    | - 'full'   : (Default / Strict) 100% exhaustive scan. Checks every single
+    |             item in every array, guaranteeing every single offending item
+    |             is caught without exception.
+    |
+    | - 'hybrid' : (Beartype O(1) Mode) Fast boundary + random sampling on
+    |             arrays > 64 items. Ideal for massive production datasets.
+    */
+    'array_validation' => 'hybrid',
+
     /*
     |--------------------------------------------------------------------------
     | Inline Variable Validation (@var $x = ...)