feat: add verbose specification

This decorator will throw an exception when the origin specification is dissatisfied.

Author: maartenpaauw

src/SpecificationException.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Maartenpaauw\Specifications;
+
+use Exception;
+
+class SpecificationException extends Exception
+{
+}

src/VerboseSpecification.php

@@ -0,0 +1,43 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Maartenpaauw\Specifications;
+
+/**
+ * @template TCandidate
+ * @extends CompositeSpecification<TCandidate>
+ */
+class VerboseSpecification extends CompositeSpecification
+{
+    public function __construct(
+        private Specification $origin,
+        private string $message = '',
+    ) {
+    }
+
+    /**
+     * @return VerboseSpecification<TCandidate>
+     */
+    public function withMessage(string $message): self
+    {
+        return new self(
+            $this->origin,
+            $message,
+        );
+    }
+
+    /**
+     * @param TCandidate $candidate
+     *
+     * @throws SpecificationException
+     */
+    public function isSatisfiedBy(mixed $candidate): bool
+    {
+        if ($this->origin->isSatisfiedBy($candidate)) {
+            return true;
+        }
+
+        throw new SpecificationException($this->message);
+    }
+}

tests/VerboseExceptionTest.php

@@ -0,0 +1,58 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Maartenpaauw\Specifications\Tests;
+
+use Maartenpaauw\Specifications\SpecificationException;
+use Maartenpaauw\Specifications\Tests\Dummy\LengthSpecification;
+use Maartenpaauw\Specifications\VerboseSpecification;
+
+class VerboseExceptionTest extends TestCase
+{
+    /** @var VerboseSpecification<string> */
+    private VerboseSpecification $specification;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+
+        $this->specification = new VerboseSpecification(
+            new LengthSpecification(12),
+        );
+    }
+
+    /** @test */
+    public function it_should_throw_an_exception_with_an_empty_message_when_the_specification_is_not_satisfied(): void
+    {
+        // Assert
+        $this->expectException(SpecificationException::class);
+        $this->expectExceptionMessage('');
+
+        // Act
+        $this->specification->isSatisfiedBy('Hello Laravel!');
+    }
+
+    /** @test */
+    public function it_should_be_possible_to_customize_the_exception_message(): void
+    {
+        // Assert
+        $this->expectException(SpecificationException::class);
+        $this->expectExceptionMessage('The given string is longer than 12 characters!');
+
+        // Act
+        $this->specification
+            ->withMessage('The given string is longer than 12 characters!')
+            ->isSatisfiedBy('Hello Laravel!');
+    }
+
+    /** @test */
+    public function it_should_return_true_when_the_specification_is_satisfied_with_the_given_candidate(): void
+    {
+        // Act
+        $satisfied = $this->specification->isSatisfiedBy('Hello world!');
+
+        // Assert
+        $this->assertTrue($satisfied);
+    }
+}