Specification Generator

Generate DDD-compliant Specifications for encapsulating business rules and filtering logic.

Specification Characteristics

• Single Responsibility: One business rule per specification
• Composable: AND, OR, NOT combinations
• Reusable: Same spec for validation and querying
• Domain Language: Named using ubiquitous language
• Testable: Easy to unit test in isolation
• Immutable: No state changes after creation

When to Use Specification

| Scenario | Example | |----------|---------| | Business rule validation | IsActiveCustomer, CanPlaceOrder | | Collection filtering | OverdueInvoice, PremiumProduct | | Repository queries | OrdersByCustomer, ActiveUsers | | Policy enforcement | EligibleForDiscount, CanBeShipped | | Complex conditions | Composite AND/OR specifications |

---

Generation Process

Step 1: Generate Base Infrastructure

Path: src/Domain/Shared/Specification/

1. SpecificationInterface.php — Generic interface with isSatisfiedBy()
2. AbstractSpecification.php — Base with AND/OR/NOT methods
3. AndSpecification.php — Composite AND
4. OrSpecification.php — Composite OR
5. NotSpecification.php — Negation wrapper

Step 2: Generate Concrete Specification

Path: src/Domain/{BoundedContext}/Specification/

1. {Name}Specification.php — Implements business rule

Step 3: Generate Tests

Path: tests/Unit/Domain/{BoundedContext}/Specification/

---

File Placement

| Component | Path | |-----------|------| | Base Interface | src/Domain/Shared/Specification/ | | Abstract Spec | src/Domain/Shared/Specification/ | | Composites | src/Domain/Shared/Specification/ | | Concrete Specs | src/Domain/{BoundedContext}/Specification/ | | Unit Tests | tests/Unit/Domain/{BoundedContext}/Specification/ |

---

Naming Conventions

| Pattern | Example | |---------|---------| | Is{Condition}Specification | IsActiveCustomerSpecification | | Has{Property}Specification | HasPurchaseHistorySpecification | | Can{Action}Specification | CanBeCancelledSpecification | | Factory Method | IsOverdueInvoiceSpecification::now() |

---

Quick Template Reference

Specification Interface

/**
 * @template T
 */
interface SpecificationInterface
{
    public function isSatisfiedBy(mixed $candidate): bool;
    public function and(self $other): self;
    public function or(self $other): self;
    public function not(): self;
}

Concrete Specification

/**
 * @extends AbstractSpecification<{Entity}>
 */
final readonly class {Name}Specification extends AbstractSpecification
{
    public function __construct({parameters}) {}

    public function isSatisfiedBy(mixed $candidate): bool
    {
        if (!$candidate instanceof {Entity}) {
            return false;
        }
        return {businessRule};
    }
}

Composite Usage

$eligible = $isActive
    ->and($hasPurchases)
    ->and($isNotBlacklisted->not());

$customers = array_filter(
    $all,
    fn($c) => $eligible->isSatisfiedBy($c)
);

---

Anti-patterns to Avoid

| Anti-pattern | Problem | Solution | |--------------|---------|----------| | God Specification | Too many conditions | Split into composable specs | | Side Effects | Modifies candidate | Keep pure, read-only | | Infrastructure | DB calls in spec | Keep in domain, use for in-memory | | Weak Typing | isSatisfiedBy(mixed) | Add type check first | | No Composition | Copy-paste conditions | Use AND/OR composition |

---

References

For complete PHP templates and examples, see:

• references/templates.md — Interface, Abstract, Composite, Concrete templates
• references/examples.md — Customer, Product, Invoice, Order specifications and tests