Feature/Add support for named parameters in make() method

Author: othercodes

src/IsModel.php

@@ -56,6 +56,11 @@ final public static function make(mixed ...$params): static
             );
         }
 
+        // Handle named parameters if provided
+        if (self::hasNamedParameters($params)) {
+            $params = self::mapNamedToPositional($constructor, $params);
+        }
+
         // Validate parameters against constructor signature
         // array_values ensures we have a proper indexed array
         self::validateConstructorParameters($constructor, array_values($params));
@@ -211,6 +216,74 @@ private static function validateUnionType(mixed $value, ReflectionUnionType $uni
         return false;
     }
 
+    /**
+     * Check if parameters include named parameters.
+     *
+     * @param array<int|string, mixed> $params
+     * @return bool
+     */
+    private static function hasNamedParameters(array $params): bool
+    {
+        if (empty($params)) {
+            return false;
+        }
+
+        // Named parameters have string keys
+        // Positional parameters have sequential integer keys [0, 1, 2, ...]
+        return array_keys($params) !== range(0, count($params) - 1);
+    }
+
+    /**
+     * Map named parameters to positional parameters based on constructor signature.
+     *
+     * Supports three scenarios:
+     * 1. Pure named parameters: make(value: 'test')
+     * 2. Pure positional parameters: make('test')
+     * 3. Mixed parameters: make(1, name: 'test', description: 'desc')
+     *
+     * @param ReflectionMethod $constructor
+     * @param array<int|string, mixed> $params
+     * @return array<int, mixed>
+     * @throws InvalidArgumentException When required named parameter is missing
+     */
+    private static function mapNamedToPositional(
+        ReflectionMethod $constructor,
+        array $params
+    ): array {
+        $positional = [];
+        $constructorParams = $constructor->getParameters();
+
+        foreach ($constructorParams as $index => $param) {
+            $name = $param->getName();
+
+            // Check if parameter was provided positionally (by index)
+            if (array_key_exists($index, $params)) {
+                $positional[$index] = $params[$index];
+            }
+            // Check if parameter was provided by name
+            elseif (array_key_exists($name, $params)) {
+                $positional[$index] = $params[$name];
+            }
+            // Check if parameter has a default value
+            elseif ($param->isDefaultValueAvailable()) {
+                $positional[$index] = $param->getDefaultValue();
+            }
+            // Check if parameter is required
+            elseif (!$param->isOptional()) {
+                throw new InvalidArgumentException(
+                    sprintf(
+                        '%s::make() missing required parameter: %s',
+                        basename(str_replace('\\', '/', static::class)),
+                        $name
+                    )
+                );
+            }
+            // else: optional parameter without default (e.g., nullable), will be handled by PHP
+        }
+
+        return $positional;
+    }
+
     /**
      * Determine if invariants should be checked automatically after construction.
      *

tests/TypeValidationTest.php

@@ -142,3 +142,65 @@
             ->and($e->getMessage())->toContain('array given');
     }
 });
+
+test('make() should accept named parameters', function () {
+    $email = Email::make(value: 'test@example.com');
+
+    expect($email)->toBeInstanceOf(Email::class)
+        ->and((string) $email)->toBe('test@example.com');
+});
+
+test('make() should accept named parameters in any order', function () {
+    $money = Money::make(currency: 'USD', amount: 100);
+
+    expect($money)->toBeInstanceOf(Money::class)
+        ->and((string) $money)->toBe('100 USD');
+});
+
+test('make() should mix named and positional parameters', function () {
+    // First positional, rest named
+    $model = ComplexModel::make(1, name: 'Test', description: 'Desc', tags: []);
+
+    expect($model)->toBeInstanceOf(ComplexModel::class);
+});
+
+test('make() should skip optional parameters with named params', function () {
+    // Skip optional 'label' parameter
+    $value = FlexibleValue::make(value: 42);
+
+    expect($value)->toBeInstanceOf(FlexibleValue::class)
+        ->and((string) $value)->toBe('42');
+});
+
+test('make() should use default values for omitted named params', function () {
+    // FlexibleValue has label with default null
+    $value = FlexibleValue::make(value: 'test');
+
+    expect($value)->toBeInstanceOf(FlexibleValue::class);
+});
+
+test('make() should throw error for missing required named parameter', function () {
+    Money::make(amount: 100);
+})->throws(InvalidArgumentException::class, 'missing required parameter: currency');
+
+test('make() should validate types with named parameters', function () {
+    Email::make(value: 123);
+})->throws(TypeError::class, 'parameter "value" must be of type string, int given');
+
+test('make() should handle nullable types with named parameters', function () {
+    $model = ComplexModel::make(id: 1, name: 'Test', description: null, tags: []);
+
+    expect($model)->toBeInstanceOf(ComplexModel::class);
+});
+
+test('make() should handle union types with named parameters', function () {
+    $money1 = Money::make(amount: 100, currency: 'USD');
+    $money2 = Money::make(amount: 99.99, currency: 'EUR');
+
+    expect($money1)->toBeInstanceOf(Money::class)
+        ->and($money2)->toBeInstanceOf(Money::class);
+});
+
+test('make() should validate union types with named parameters', function () {
+    Money::make(amount: 'invalid', currency: 'USD');
+})->throws(TypeError::class, 'parameter "amount" must be of type int|float');