Restrict instantiation of a class to specific allowed classes

[jgrooen]

Feature Request

Add a language-level way to restrict instantiation of a class to only specific classes.

---

Use Case

For example, I want MysqlPostRepository and RedisPostRepository to be instantiated only inside PostRepository, and not from any other class.
Currently, there's no clean or built-in way to enforce this behavior in PHP.

---

Current Workaround

Using private or protected constructors with debug_backtrace() checks in static factory methods —
but this approach is runtime-only, fragile, and not enforced by the language.

---

Proposal

Introduce a syntax or attribute like:

#[AllowInstantiationOnlyBy(PostRepository::class)]
final class MysqlPostRepository {}

---

Benefit

Enforces encapsulation
Prevents misuse
Encourages better architecture

---

Compatibility

Fully opt-in, no breaking changes.

[bwoebi]

Personal opinion: I'd rather allow widening protected functions to be called from specific other classes, like

#[AllowScope(PostRepository::class)]
protected function __construct() { ... }

That way it'd be usable for any method, and not only class instantiation. Applied on class level, it'd then apply to the whole class.

[jgrooen]

@bwoebi

That's a great point — allowing protected methods to be scoped to specific classes like that would be more general and useful beyond just instantiation. I like that idea.

Do you think implementing this as an attribute is a good approach? Or do you see a better alternative?