fix name argument parsing mismatch cuasing false positive type-errors and document it.

Author: rcalicdan

docs/advanced/liskov-and-inheritance.md

@@ -292,35 +292,42 @@ $service->update(10, 'Charlie');
 
 ---
 
-## Parameter Renaming ($id $\rightarrow$ $userId$)
+## Parameter Renaming ($id → $userId) & Position Shifts
 
-PHP permits child classes to rename parameters when implementing an interface or extending a class. TypePHP maps inherited parameter contracts by **index position** (0, 1, 2...) rather than parameter name:
+When a child class or attribute constructor overrides a parent method, parameter positions or parameter names may shift. TypePHP resolves parameter contract inheritance using **Name-First Resolution**:
+
+1. **Name Matching:** If a parameter name in the child method matches a parameter name in the parent class (e.g. `$api`), the parent's contract is inherited by that parameter regardless of its position index in the child.
+2. **Position Fallback:** If a parameter is renamed in the child class (e.g., `$id` $\rightarrow$ `$userId`), TypePHP falls back to matching by position index.
 
 ```php
-interface UserApiInterface
+class BaseField
 {
     /**
-     * Interface uses parameter name $id
+     * Parent constructor has $api at position #1
      *
-     * @param positive-int $id
+     * @param string $type
+     * @param bool|array{admin-api: bool} $api
      */
-    public function find(int $id): bool;
+    public function __construct(string $type, bool|array $api = false) {}
 }
 
-class UserApi implements UserApiInterface
+class OneToManyRelation extends BaseField
 {
-    // Child renames parameter $id to $userId
-    public function find(int $userId): bool
-    {
-        return true;
+    /**
+     * Child inserts $entity, $ref, $onDelete BEFORE $api (position shift!)
+     */
+    public function __construct(
+        string $entity,
+        string $ref,
+        OnDeleteOption $onDelete = OnDeleteOption::NO_ACTION,
+        bool|array $api = false
+    ) {
+        parent::__construct('one-to-many', $api);
     }
 }
 
-$api = new UserApi();
-
-// $userId = -50 is checked at index 0 against interface's @param positive-int $id!
-$api->find(-50);
-// Throws: TypeError: UserApi::find(): Argument $userId must be of type positive-int
+// $onDelete (position #2 in child) is NOT overwritten by $api's type (position #1 in parent)!
+$attr = new OneToManyRelation('unit', 'unit_id', OnDeleteOption::CASCADE, true);
 ```
 
 ---

docs/core-concepts/function-contracts.md

@@ -35,6 +35,33 @@ registerUser(-5, 'Alice', 'admin');
 
 > **Execution Order Note:** Native PHP type hints (e.g., `int $id`, `string $username`) are evaluated by PHP's C-engine *before* function execution begins. TypePHP's extended PHPDoc contracts (e.g., `positive-int`, `non-empty-string`) execute at the very start of the function/method body. If a native type hint fails, PHP throws its native `TypeError` before TypePHP's guard rails run.
 
+---
+## PHP 8.0+ Named Arguments
+
+TypePHP natively supports PHP 8.0+ Named Arguments. Because parameter contracts are mapped by parameter name rather than argument position index, you can pass named arguments in any order, and TypePHP will accurately validate each parameter:
+
+```php
+<?php
+
+declare(strict_types=1);
+
+/**
+ * @param positive-int $id
+ * @param non-empty-string $username
+ * @param int<1, 100> $age
+ */
+function registerUser(int $id, string $username, int $age): void
+{
+    // ...
+}
+
+// Valid Call: Arguments passed in completely reversed/swapped order
+registerUser(age: 25, username: 'Alice', id: 42);
+
+// Invalid Call: $id (-5) passed as 3rd named argument
+registerUser(age: 25, username: 'Alice', id: -5);
+// Throws: TypeError: registerUser(): Argument $id must be of type positive-int, negative int (-5) given
+```
 ---
 
 ## Class Methods (Instance & Static)

src/Contract/ContractParser.php

@@ -332,10 +332,12 @@ private static function parseMethodHierarchyDocs(
         $hierarchy = HierarchyResolver::getMethodHierarchy($ref);
         $baseParams = $ref->getParameters();
         $baseParamNames = [];
+        $baseParamSet = [];
         $baseParamVariadic = [];
 
         foreach ($baseParams as $idx => $p) {
             $baseParamNames[$idx] = $p->getName();
+            $baseParamSet[$p->getName()] = $idx;
             $baseParamVariadic[$p->getName()] = $p->isVariadic();
         }
 
@@ -369,20 +371,24 @@ private static function parseMethodHierarchyDocs(
 
             foreach ($phpDocNode->getParamTagValues() as $paramTag) {
                 $paramName = ltrim($paramTag->parameterName, '$');
-                $paramIndex = $hierNameToIndex[$paramName] ?? null;
 
-                if ($paramIndex !== null && isset($baseParamNames[$paramIndex])) {
-                    $baseParamName = $baseParamNames[$paramIndex];
+                if (isset($baseParamSet[$paramName])) {
+                    $targetParamName = $paramName;
+                } else {
+                    $paramIndex = $hierNameToIndex[$paramName] ?? null;
+                    $targetParamName = ($paramIndex !== null && isset($baseParamNames[$paramIndex]))
+                        ? $baseParamNames[$paramIndex]
+                        : null;
+                }
 
-                    if (! isset($types[$baseParamName])) {
-                        $type = $paramTag->type;
-                        $isVariadic = $paramTag->isVariadic || $baseParamVariadic[$baseParamName];
-                        if ($isVariadic) {
-                            $type = new ArrayTypeNode($type);
-                        }
-                        $substitutedType = self::substituteAliases($type, $aliases);
-                        $types[$baseParamName] = SpecialTypeResolver::resolve($substitutedType, $hierRef);
+                if ($targetParamName !== null && ! isset($types[$targetParamName])) {
+                    $type = $paramTag->type;
+                    $isVariadic = $paramTag->isVariadic || ($baseParamVariadic[$targetParamName] ?? false);
+                    if ($isVariadic) {
+                        $type = new ArrayTypeNode($type);
                     }
+                    $substitutedType = self::substituteAliases($type, $aliases);
+                    $types[$targetParamName] = SpecialTypeResolver::resolve($substitutedType, $hierRef);
                 }
             }
 

tests/Fixtures/Attributes/BaseField.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypePHP\Tests\Fixtures\Attributes;
+
+class BaseField
+{
+    /**
+     * Parent constructor has $api at index 2
+     *
+     * @param string $type
+     * @param string|null $storageName
+     * @param bool|array{admin-api: bool, store-api: bool} $api
+     */
+    public function __construct(
+        string $type,
+        ?string $storageName = null,
+        bool|array $api = false
+    ) {
+    }
+}

tests/Fixtures/Attributes/DeepMultiLevelField.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypePHP\Tests\Fixtures\Attributes;
+
+class DeepMultiLevelField extends ParentField
+{
+    /**
+     * Child inserts $id at index 0!
+     *
+     * @param positive-int $id
+     */
+    public function __construct(
+        public int $id,
+        string $type,
+        string $name,
+        bool $api = false
+    ) {
+        parent::__construct($type, $name, $api);
+    }
+}

tests/Fixtures/Attributes/GrandParentField.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypePHP\Tests\Fixtures\Attributes;
+
+abstract class GrandParentField
+{
+    /**
+     * @param non-empty-string $type
+     * @param bool $api
+     */
+    public function __construct(
+        string $type,
+        bool $api = false
+    ) {
+    }
+}

tests/Fixtures/Attributes/MeasurementSystemEntity.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypePHP\Tests\Fixtures\Attributes;
+
+class MeasurementSystemEntity
+{
+    /**
+     * @var array<string, mixed>|null
+     */
+    #[OneToManyRelation(
+        entity: 'measurement_display_unit',
+        ref: 'measurement_system_id',
+        onDelete: OnDeleteOption::CASCADE,
+        api: true
+    )]
+    public ?array $units = null;
+}

tests/Fixtures/Attributes/OnDeleteOption.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypePHP\Tests\Fixtures\Attributes;
+
+enum OnDeleteOption
+{
+    case CASCADE;
+    case NO_ACTION;
+}

tests/Fixtures/Attributes/OneToManyRelation.php

@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypePHP\Tests\Fixtures\Attributes;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_PROPERTY)]
+class OneToManyRelation extends BaseField
+{
+    /**
+     * Child constructor has $onDelete at index 2
+     */
+    public function __construct(
+        public string $entity,
+        public string $ref,
+        public OnDeleteOption $onDelete = OnDeleteOption::NO_ACTION,
+        public bool|array $api = false
+    ) {
+        parent::__construct('one-to-many', null, $api);
+    }
+}

tests/Fixtures/Attributes/ParentField.php

@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypePHP\Tests\Fixtures\Attributes;
+
+abstract class ParentField extends GrandParentField
+{
+    /**
+     * ParentField inserts $name at index 1
+     *
+     * @param non-empty-string $name
+     */
+    public function __construct(
+        string $type,
+        string $name,
+        bool $api = false
+    ) {
+        parent::__construct($type, $api);
+    }
+}