Feature/aggregate invariant violations and enhance InvariantViolation exception handling

Author: othercodes

src/Exceptions/InvariantViolation.php

@@ -9,9 +9,73 @@
 /**
  * Class InvariantViolation
  *
+ * Exception thrown when one or more invariants are violated.
+ *
  * @author Unay Santisteban <usantisteban@othercode.io>
  * @package ComplexHeart\Domain\Model\Exceptions
  */
 class InvariantViolation extends Exception
 {
+    /**
+     * @var array<int, string> List of all violation messages
+     */
+    private array $violations = [];
+
+    /**
+     * Create an invariant violation exception from one or more violations.
+     *
+     * @param array<int, string> $violations
+     * @param int $code
+     * @param Exception|null $previous
+     * @return self
+     */
+    public static function fromViolations(array $violations, int $code = 0, ?Exception $previous = null): self
+    {
+        $count = count($violations);
+
+        // Format message based on count
+        if ($count === 1) {
+            $message = $violations[0];
+        } else {
+            $message = sprintf(
+                "Multiple invariant violations (%d):\n- %s",
+                $count,
+                implode("\n- ", $violations)
+            );
+        }
+
+        $exception = new self($message, $code, $previous);
+        $exception->violations = $violations;
+        return $exception;
+    }
+
+    /**
+     * Check if this exception has multiple violations.
+     *
+     * @return bool
+     */
+    public function hasMultipleViolations(): bool
+    {
+        return count($this->violations) > 1;
+    }
+
+    /**
+     * Get all violation messages.
+     *
+     * @return array<int, string>
+     */
+    public function getViolations(): array
+    {
+        return $this->violations;
+    }
+
+    /**
+     * Get the count of violations.
+     *
+     * @return int
+     */
+    public function getViolationCount(): int
+    {
+        return count($this->violations);
+    }
 }

src/IsModel.php

@@ -75,6 +75,21 @@ final public static function make(mixed ...$params): static
         return $instance;
     }
 
+    /**
+     * Alias for make() method - more idiomatic for domain objects.
+     *
+     * Example: Customer::new(id: $id, name: 'John Doe')
+     *
+     * @param mixed ...$params Constructor parameters
+     * @return static
+     * @throws InvalidArgumentException When required parameters are missing
+     * @throws TypeError When parameter types don't match
+     */
+    final public static function new(mixed ...$params): static
+    {
+        return static::make(...$params);
+    }
+
     /**
      * Validate parameters match constructor signature.
      *

src/Traits/HasInvariants.php

@@ -121,6 +121,13 @@ private function computeInvariantHandler(string|callable $handlerFn, string $exc
                 $this->{$handlerFn}($violations, $exception);
             }
         : function (array $violations) use ($exception): void {
+            // Always aggregate violations for InvariantViolation
+            if ($exception === InvariantViolation::class) {
+                $messages = map(fn (Throwable $e): string => $e->getMessage(), $violations);
+                throw InvariantViolation::fromViolations(array_values($messages));
+            }
+
+            // Legacy behavior for custom exception classes
             if (count($violations) === 1) {
                 throw array_shift($violations);
             }

tests/TraitsTest.php

@@ -76,4 +76,92 @@ protected function invariantAlwaysFailTwo(): bool
     };
 })
     ->group('Unit')
-    ->throws(InvariantViolation::class, 'always fail one, always fail two');
+    ->throws(InvariantViolation::class, 'Multiple invariant violations (2)');
+
+test('InvariantViolation should support multiple violations aggregation', function () {
+    try {
+        new class () {
+            use HasInvariants;
+
+            public function __construct()
+            {
+                $this->check();
+            }
+
+            protected function invariantAlwaysFailOne(): bool
+            {
+                return false;
+            }
+
+            protected function invariantAlwaysFailTwo(): bool
+            {
+                return false;
+            }
+
+            protected function invariantAlwaysFailThree(): bool
+            {
+                return false;
+            }
+        };
+    } catch (InvariantViolation $e) {
+        expect($e->hasMultipleViolations())->toBeTrue()
+            ->and($e->getViolationCount())->toBe(3)
+            ->and($e->getViolations())->toHaveCount(3)
+            ->and($e->getViolations())->toContain('always fail one')
+            ->and($e->getViolations())->toContain('always fail two')
+            ->and($e->getViolations())->toContain('always fail three')
+            ->and($e->getMessage())->toContain('Multiple invariant violations (3)');
+    }
+})
+    ->group('Unit');
+
+test('InvariantViolation::fromViolations should handle single violation cleanly', function () {
+    try {
+        new class () {
+            use HasInvariants;
+
+            public function __construct()
+            {
+                $this->check();
+            }
+
+            protected function invariantSingleFailure(): bool
+            {
+                return false;
+            }
+        };
+    } catch (InvariantViolation $e) {
+        expect($e->hasMultipleViolations())->toBeFalse()
+            ->and($e->getViolationCount())->toBe(1)
+            ->and($e->getViolations())->toBe(['single failure'])
+            ->and($e->getMessage())->toBe('single failure')
+            ->and($e->getMessage())->not->toContain('Multiple invariant violations');
+    }
+})
+    ->group('Unit');
+
+test('InvariantViolation::fromViolations should format multiple violations', function () {
+    $violations = ['First error', 'Second error', 'Third error'];
+    $exception = InvariantViolation::fromViolations($violations);
+
+    expect($exception)->toBeInstanceOf(InvariantViolation::class)
+        ->and($exception->hasMultipleViolations())->toBeTrue()
+        ->and($exception->getViolationCount())->toBe(3)
+        ->and($exception->getViolations())->toBe($violations)
+        ->and($exception->getMessage())->toContain('Multiple invariant violations (3)')
+        ->and($exception->getMessage())->toContain('First error')
+        ->and($exception->getMessage())->toContain('Second error')
+        ->and($exception->getMessage())->toContain('Third error');
+})
+    ->group('Unit');
+
+test('InvariantViolation::fromViolations with single violation should not show count', function () {
+    $exception = InvariantViolation::fromViolations(['Single error message']);
+
+    expect($exception)->toBeInstanceOf(InvariantViolation::class)
+        ->and($exception->hasMultipleViolations())->toBeFalse()
+        ->and($exception->getViolationCount())->toBe(1)
+        ->and($exception->getViolations())->toBe(['Single error message'])
+        ->and($exception->getMessage())->toBe('Single error message');
+})
+    ->group('Unit');

tests/TypeValidationTest.php

@@ -204,3 +204,39 @@
 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');
+
+test('new() should work as alias for make()', function () {
+    $email = Email::new('test@example.com');
+
+    expect($email)->toBeInstanceOf(Email::class)
+        ->and((string) $email)->toBe('test@example.com');
+});
+
+test('new() should support positional parameters', function () {
+    $money = Money::new(100, 'USD');
+
+    expect($money)->toBeInstanceOf(Money::class)
+        ->and((string) $money)->toBe('100 USD');
+});
+
+test('new() should support named parameters', function () {
+    $email = Email::new(value: 'user@example.com');
+
+    expect($email)->toBeInstanceOf(Email::class)
+        ->and((string) $email)->toBe('user@example.com');
+});
+
+test('new() should support named parameters in any order', function () {
+    $money = Money::new(currency: 'EUR', amount: 99.99);
+
+    expect($money)->toBeInstanceOf(Money::class)
+        ->and((string) $money)->toBe('99.99 EUR');
+});
+
+test('new() should throw TypeError for invalid types', function () {
+    Email::new(123);
+})->throws(TypeError::class, 'parameter "value" must be of type string, int given');
+
+test('new() should validate union types', function () {
+    Money::new(['invalid'], 'USD');
+})->throws(TypeError::class, 'parameter "amount" must be of type int|float');

tests/ValueObjectsTest.php

@@ -55,7 +55,7 @@
         protected string $_pattern = '[a-z]';
     };
 })
-    ->throws(InvalidArgumentException::class)
+    ->throws(InvariantViolation::class)
     ->group('Unit');
 
 test('BooleanValue should create a valid BooleanValue Object.', function () {