本文探讨 php 中构建器模式与不可变性的本质矛盾，指出纯不可变构建器在实践中不可行，并提供兼顾可读性、灵活性与合理不变性的实用方案——通过返回新实例而非修改自身来实现逻辑不可变。

在面向对象设计中，“构建器模式”（Builder Pattern）常用于简化复杂对象的创建过程，尤其适用于参数众多、部分可选的场景；而“不可变性”（Immutability）则强调对象一旦构造完成，其状态便不可更改。乍看之下，二者目标冲突：构建器需逐步设置属性，而不可变对象禁止任何状态变更。

但关键在于——不可变性应作用于最终产物，而非构建过程本身。真正的不可变构建器并非要求 Builder 实例自身不可变（这会使其无法链式调用），而是确保每次调用如 withName() 或 withId() 都返回一个全新的、状态确定的新构建器实例，原实例保持不变。这才是符合语义的“逻辑不可变”（value-level immutability）。

✅ 正确实现：值语义 + 不可变副本

自 PHP 8.2 起，readonly 属性配合构造器参数提升（constructor property promotion）和只读数组

id, $this->email, $this->roles);
    }

    public function withId(int $id): self
    {
        return new self($this->name, $id, $this->email, $this->roles);
    }

    public function withEmail(?string $email): self
    {
        return new self($this->name, $this->id, $email, $this->roles);
    }

    public function withRole(string $role): self
    {
        $roles = [...$this->roles, $role];
        return new self($this->name, $this->id, $this->email, $roles);
    }

    public function build(): array
    {
        return [
            'name' => $this->name,
            'id' => $this->id,
            'email' => $this->email,
            'roles' => $this->roles,
        ];
    }
}

// 使用示例：全程无副作用，每次调用都产生新实例
$user = (new UserBuilder())
    ->withName('Alice')
    ->withId(42)
    ->withEmail('alice@example.com')
    ->withRole('user')
    ->withRole('admin')
    ->build();

print_r($user);
// 输出：
// Array (
//   [name] => Alice
//   [id] => 42
//   [email] => alice@example.com
//   [roles] => Array ([0] => user, [1] => admin)
// )

⚠️ 注意事项与权衡

• 性能考量：频繁克隆对象会产生额外内存开销。对高性能敏感场景（如高频循环构建），可权衡是否采用“半不可变”策略（如仅保证 build() 后不可变，构建中允许内部可变，但对外不暴露修改接口）。
• 深拷贝陷阱：若属性含嵌套对象或资源（如 DateTime、Closure），需手动处理深拷贝逻辑，否则仍可能意外共享状态。
• 类型安全增强：结合 PHP 8.3+ 的 enum 和 readonly 类，或使用静态分析工具（如 PHPStan）校验构建路径，可进一步强化契约保障。
• 不必强求绝对不可变：正如答案所强调——理论是为理解服务，而非枷锁。若构建器仅作为临时工具、生命周期极短且不被共享，适度的内部可变性（如你第一个示例）完全可接受，且更直观高效。

✅ 总结

• 真正的“不可变构建器”，核心是方法调用不改变当前实例，而是返回新实例；
• 利用 readonly 属性 + 构造器参数 + 显式 new self(...) 是 PHP 当前最清晰、最安全的实现方式；
• 不必因追求理论完美而牺牲可维护性；明确构建器的职责边界（它只是通往不可变值的桥梁），比纠结其自身是否“100% 不可变”更有实践价值。