Feature/Add documentation for named parameter and union type support in factory methods

Author: othercodes

README.md

@@ -30,6 +30,8 @@ On top of those base traits **Complex Heart** provide ready to use compositions:
 
 - **Type-Safe Factory Method**: The `make()` static factory validates constructor parameters at runtime with clear error messages
 - **Automatic Invariant Checking**: When using `make()`, Value Objects and Entities automatically validate invariants after construction (no manual `$this->check()` needed)
+- **Named Parameter Support**: Full support for PHP 8.0+ named parameters for improved readability and flexibility
+- **Union Type Support**: Complete support for PHP 8.0+ union types (e.g., `int|float`, `string|null`)
 - **Readonly Properties Support**: Full compatibility with PHP 8.1+ readonly properties
 - **PHPStan Level 8**: Complete static analysis support
 

wiki/Domain-Modeling-Aggregates.md

@@ -87,10 +87,14 @@ final class Order implements Aggregate
 
 **Benefits of using `make()` in factory methods:**
 - Automatic invariant checking when using `make()`
-- Type validation at runtime
+- Type validation at runtime with clear error messages
+- Named parameter support for improved readability (as shown above)
+- Union type support (e.g., `int|float`, `string|null`)
 - Cleaner factory method code
 - Consistent with Value Objects and Entities
 
+**Why named parameters?** As shown in the example above, using named parameters (`reference:`, `customer:`, etc.) makes the code self-documenting and prevents parameter mix-ups, especially important in Aggregates with many constructor parameters.
+
 **Important:** Auto-check ONLY works when using `make()`. In the alternative approach using direct constructor calls, you must manually call `$this->check()` inside the constructor.
 
 #### Alternative: Direct Constructor with Manual Check

wiki/Domain-Modeling-Entities.md

@@ -49,11 +49,19 @@ final class Customer implements Entity
 
 // Type-safe instantiation with automatic invariant validation
 $customer = Customer::make(UUIDValue::random(), 'Vincent Vega');
+
+// Named parameters for improved readability (PHP 8.0+)
+$customer = Customer::make(
+    id: UUIDValue::random(),
+    name: 'Vincent Vega'
+);
 ```
 
 **Benefits:**
 - Automatic invariant checking when using `make()`
-- Type validation at runtime
+- Type validation at runtime with clear error messages
+- Named parameter support for improved readability
+- Union type support (e.g., `int|float`, `string|null`)
 - Cleaner constructor code
 
 **Important:** Auto-check ONLY works when using `make()`. If you call the constructor directly (`new Customer(...)`), you must manually call `$this->check()` inside the constructor.

wiki/Domain-Modeling-Value-Objects.md

@@ -92,16 +92,53 @@ class Email implements ValueObject
 $email = Email::make('user@example.com'); // ✅ Valid
 $email = Email::make(123); // ❌ TypeError: parameter "value" must be of type string, int given
 $email = Email::make('invalid'); // ❌ InvariantViolation: Valid format
+
+// Named parameters for improved readability (PHP 8.0+)
+$email = Email::make(value: 'user@example.com'); // ✅ Self-documenting code
 ```
 
 **Benefits of `make()`:**
 - Runtime type validation with clear error messages
 - Automatic invariant checking after construction
+- Named parameter support for improved readability
+- Union type support (e.g., `int|float`, `string|null`)
 - Works seamlessly with readonly properties
 - PHPStan level 8 compliant
 
 **Important:** Auto-check ONLY works when using `make()`. Direct constructor calls do NOT trigger automatic invariant checking, so you must manually call `$this->check()` in the constructor.
 
+#### Named Parameters Example
+
+Named parameters (PHP 8.0+) make code more readable and allow parameters in any order:
+
+```php
+final class Money implements ValueObject
+{
+    use IsValueObject;
+
+    public function __construct(
+        private readonly int|float $amount,
+        private readonly string $currency
+    ) {}
+
+    protected function invariantPositiveAmount(): bool
+    {
+        return $this->amount > 0;
+    }
+
+    public function __toString(): string
+    {
+        return sprintf('%s %s', $this->amount, $this->currency);
+    }
+}
+
+// All equivalent, choose the most readable for your context:
+$money = Money::make(100, 'USD');                    // Positional
+$money = Money::make(amount: 100, currency: 'USD'); // Named
+$money = Money::make(currency: 'USD', amount: 100); // Named, different order
+$money = Money::make(100, currency: 'USD');         // Mixed
+```
+
 #### Alternative: Constructor Property Promotion with Manual Check
 
 If you prefer direct constructor calls, you **must** manually call `$this->check()`: