Builder Pattern Generator

Creates Builder pattern infrastructure for step-by-step construction of complex objects.

When to Use

Component Characteristics

Builder Interface

• Defines building steps
• Returns self for fluent interface
• Has build() method for final product

Concrete Builder

• Implements building steps
• Maintains product state
• Validates before building

Director (Optional)

• Defines construction order
• Reusable build sequences
• Hides complexity from client

Generation Process

Step 1: Analyze Requirements

Determine:

• Target product class
• Required vs optional properties
• Validation rules
• Whether Director is needed

Step 2: Generate Builder Components

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

1. {Name}BuilderInterface.php — Builder contract
2. {Name}Builder.php — Concrete builder implementation
3. BuilderValidationException.php — Validation exception
4. {Name}Director.php — Optional director for common builds

Step 3: Generate Tests

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

1. {Name}BuilderTest.php — Builder functionality tests

File Placement

Naming Conventions

Quick Template Reference

Builder Interface

interface {Name}BuilderInterface
{
    public function with{Property1}({Type1} $value): self;
    public function with{Property2}({Type2} $value): self;
    public function build(): {Product};
    public function reset(): self;
}

Concrete Builder

final class {Name}Builder implements {Name}BuilderInterface
{
    private ?{Type1} ${property1} = null;
    private ?{Type2} ${property2} = null;
    private array $errors = [];

    public function with{Property1}({Type1} $value): self
    {
        $this->{property1} = $value;
        return $this;
    }

    public function build(): {Product}
    {
        $this->validate();
        if ($this->errors !== []) {
            throw new BuilderValidationException($this->errors);
        }
        return new {Product}(...);
    }

    public function reset(): self
    {
        $this->{property1} = null;
        $this->errors = [];
        return $this;
    }
}

Director

final readonly class {Name}Director
{
    public function __construct(private {Name}BuilderInterface $builder) {}

    public function buildMinimal{Name}(/* required params */): {Product}
    {
        return $this->builder
            ->reset()
            ->with{Required1}($value1)
            ->build();
    }

    public function buildFull{Name}(/* all params */): {Product}
    {
        return $this->builder
            ->reset()
            ->with{Property1}($value1)
            ->with{Property2}($value2)
            ->build();
    }
}

Usage Example

// Direct builder usage
$order = (new OrderBuilder())
    ->forCustomer($customerId)
    ->withShippingAddress($address)
    ->addItem($item1)
    ->addItem($item2)
    ->withDiscountCode('SAVE10')
    ->build();

// Using Director
$director = new OrderDirector(new OrderBuilder());
$minimalOrder = $director->buildMinimalOrder($customerId, $address, $item);
$giftOrder = $director->buildGiftOrder($customerId, $shipping, $billing, $items, 'Happy Birthday!');

Anti-patterns to Avoid

References

For complete PHP templates and examples, see:

• references/templates.md — Builder, QueryBuilder templates
• references/examples.md — OrderBuilder, EmailBuilder examples and tests