Builder — constructing complex objects step by step

<?php
declare(strict_types=1);

// ── Product — immutable once built ─────────────────────────────────────────

final class Invoice
{
    private function __construct(
        public readonly string        $invoiceNumber,
        public readonly Customer      $customer,
        public readonly BillingAddress $billingAddress,
        /** @var LineItem[] */
        public readonly array         $lineItems,
        public readonly string        $currency,
        public readonly int           $paymentTermDays,
        public readonly ?Discount     $discount,
        public readonly ?TaxSettings  $taxSettings,
        public readonly \DateTimeImmutable $issuedAt,
        public readonly \DateTimeImmutable $dueAt,
    ) {}

    // Only the Builder may call the constructor
    public static function fromBuilder(InvoiceBuilder $builder): self
    {
        return new self(
            invoiceNumber:  $builder->invoiceNumber,
            customer:       $builder->customer,
            billingAddress: $builder->billingAddress,
            lineItems:      $builder->lineItems,
            currency:       $builder->currency,
            paymentTermDays: $builder->paymentTermDays,
            discount:       $builder->discount,
            taxSettings:    $builder->taxSettings,
            issuedAt:       $builder->issuedAt ?? new \DateTimeImmutable(),
            dueAt:          $builder->dueAt ?? new \DateTimeImmutable("+{$builder->paymentTermDays} days"),
        );
    }

    public function totalCents(): int
    {
        $subtotal = array_sum(array_map(fn(LineItem $l) => $l->totalCents(), $this->lineItems));
        $afterDiscount = $this->discount ? $this->discount->apply($subtotal) : $subtotal;
        return $this->taxSettings ? $this->taxSettings->apply($afterDiscount) : $afterDiscount;
    }
}

// ── Builder ─────────────────────────────────────────────────────────────────

final class InvoiceBuilder
{
    // Package-private fields — only Invoice::fromBuilder reads them
    public string $invoiceNumber;
    public Customer $customer;
    public BillingAddress $billingAddress;
    public array $lineItems = [];
    public string $currency = 'USD';
    public int $paymentTermDays = 30;
    public ?Discount $discount = null;
    public ?TaxSettings $taxSettings = null;
    public ?\DateTimeImmutable $issuedAt = null;
    public ?\DateTimeImmutable $dueAt = null;

    private function __construct() {}

    public static function new(): self
    {
        $builder = new self();
        $builder->invoiceNumber = 'INV-' . strtoupper(uniqid());
        return $builder;
    }

    public function forCustomer(Customer $customer): self
    {
        $this->customer = $customer;
        return $this;
    }

    public function billedTo(BillingAddress $address): self
    {
        $this->billingAddress = $address;
        return $this;
    }

    public function addLineItem(string $description, int $unitCents, int $quantity = 1): self
    {
        $this->lineItems[] = new LineItem($description, $unitCents, $quantity);
        return $this;
    }

    public function inCurrency(string $currency): self
    {
        $this->currency = strtoupper($currency);
        return $this;
    }

    public function withPaymentTerms(int $days): self
    {
        $this->paymentTermDays = $days;
        return $this;
    }

    public function withDiscount(Discount $discount): self
    {
        $this->discount = $discount;
        return $this;
    }

    public function withTax(TaxSettings $taxSettings): self
    {
        $this->taxSettings = $taxSettings;
        return $this;
    }

    public function issuedAt(\DateTimeImmutable $date): self
    {
        $this->issuedAt = $date;
        return $this;
    }

    public function build(): Invoice
    {
        // Validate completeness at build time — not during accumulation
        if (! isset($this->customer)) {
            throw new \LogicException('Invoice must have a customer');
        }
        if (! isset($this->billingAddress)) {
            throw new \LogicException('Invoice must have a billing address');
        }
        if (empty($this->lineItems)) {
            throw new \LogicException('Invoice must have at least one line item');
        }

        return Invoice::fromBuilder($this);
    }
}

// ── Optional Director — defines standard construction sequences ─────────────

final class InvoiceDirector
{
    public function buildStandardInvoice(
        Customer $customer,
        BillingAddress $address,
        array $items,
    ): Invoice {
        $builder = InvoiceBuilder::new()
            ->forCustomer($customer)
            ->billedTo($address)
            ->withPaymentTerms(30);

        foreach ($items as [$description, $unitCents, $qty]) {
            $builder->addLineItem($description, $unitCents, $qty);
        }

        return $builder->build();
    }

    public function buildProformaInvoice(Customer $customer, BillingAddress $address): Invoice
    {
        return InvoiceBuilder::new()
            ->forCustomer($customer)
            ->billedTo($address)
            ->withPaymentTerms(0)
            ->addLineItem('Estimated project cost', 500_000, 1)
            ->build();
    }
}

// ── Usage ───────────────────────────────────────────────────────────────────

$invoice = InvoiceBuilder::new()
    ->forCustomer($customer)
    ->billedTo($customer->primaryAddress())
    ->addLineItem('Laravel consulting — 10h', 15_000, 10)
    ->addLineItem('Code review', 8_000, 3)
    ->withDiscount(Discount::percentage(10))
    ->withTax(TaxSettings::vat(20))
    ->inCurrency('EUR')
    ->withPaymentTerms(14)
    ->build();