RFC: Namespace-Scoped Visibility for Methods and Properties

One advantage of keeping this RFC small is that it can be expanded
later without a BC break. For example, prefix matching (maybe
something like private(namespace: Acme\AuthLib)) or a
protected-namespace variant could be layered on top if the community
wants to go in that direction.

That's a reasonable argument, but the risk is that if we don't consider
what that future scope would look like, we can end up with syntax or
semantics that makes our lives unnecessarily difficult later. As I
understand it, this happened to some extent with the "readonly" keyword.

Exactly the example I was thinking of. :-) "Junior version first" approaches sometimes work out (FCC doesn't seem to have caused issues for PFA in practice), and other times not (readonly was a major PITA for aviz, and even delayed it for a release as we figured out how they should interact). I'd much rather know what the "full solution" looks like and plan for it, even if it's in incremental steps, than throw a junior version at the wall and hope for the best.

This RFC isn’t intended to solve the entire space; it’s the smallest
useful step that seems to fairly cleanly fit into PHP’s current model
without too much churn on the engine.

I think my fundamental question is: is it actually that useful? How
often, in practice, do people want exact namespace matching, vs
something more flexible?

In practice, the extra-class boundary I most often want is "my composer package." I rarely need to protect things beyond that.

I am broadly in favor of extra-class visibility controls, whether they go through a module system or something else. Whether the current RFC is a good way of doing so, I am not convinced.

In particular, the syntax is a hard-no. It runs contrary to how the aviz syntax was defined, as others have already noted.

If you don't want to use internal(set) to save internal for some other use, that's fine. Come up with a different keyword. :-) But <allowed scope>(<operation>) is the syntax model that aviz established, and tossing extra parens in there just confuses things for everyone.

If it really does need to be an entirely separate dimension of scoping, then I would argue it's too complex to capture in just keywords and Rowan's attribute proposal becomes even more compelling.

That said, I'm not convinced it is a separate dimension yet. I'd put "nsviz" between public and protected, not protected and private. The assumption is that your "allowed" scope is something you control. So if you don't want to use that property from child classes in your own namespace... just don't. If you don't want to allow it to be used by child classes in another namespace... then nsviz(get) solves that problem.

I will also note that while it's typical for namespace and file path to be 1:1, there's nothing that requires it. That means any strictly namespace-based visibility is trivial to bypass.

For example:

[snip]

Whether that is a design flaw or a feature is, I suppose, debatable.

--Larry Garfield

Hi Larry (and everyone else following the thread),

I think we’re all aligned that PHP would benefit from a proper module or package boundary. Many features people want — including namespace visibility — become cleaner once such a boundary exists. One doesn’t strictly require the other, but they definitely complement each other. The difficulty is that PHP currently has no agreed-upon definition of what a “module” or “package” is:
• Composer root namespaces?
• Physical directories?
• Compilation units?
• Attributes?
• Something else entirely?
Because of that, there’s no existing boundary we can safely build on without first settling that much larger question. That’s why this RFC deliberately stays within a boundary the language already defines: the lexical namespace. It doesn’t try to define packages or introduce any new scoping model. It also doesn’t prevent a future RFC from doing so.

If the community reaches consensus on a formal module/package boundary later, namespace-level visibility can coexist with it or even be folded into it. Nothing in this RFC blocks that path.

What this RFC does is provide a useful, enforceable intermediate step that doesn’t require the community to solve “packages” first. If we require a full module system before adding any visibility improvements, we’re essentially saying that no incremental progress is acceptable until the hardest part of the problem is fully solved. That’s historically not how PHP evolves.

To keep this discussion focused:

If someone has concerns about this RFC’s semantics, performance, syntax, implementation, error messaging, interaction with inheritance/traits, or BC impact — that’s absolutely fair and I’d like to address them:

But I’d like to avoid turning this into a thread about defining a package/specification/module system. That’s a valid discussion, and I’d happily participate in another thread, but it’s not one this RFC is trying to solve.

Namespace visibility is intentionally small, intentionally conservative, and intentionally compatible with whatever direction modules eventually take. It’s the smallest useful step the language can take today, without blocking future work, while still being useful.

Now, to reply to your specific points about this RFC:

First, syntax vs. AViz.

Aviz establishes visibility(operation) as the pattern for asymmetric visibility, where the keyword controls the caller set and parentheses restrict the operation (get/set). That’s why private(namespace)(set) follows the same rule: the base visibility is still "private", and the parentheses narrows who may call it.

If we introduced a standalone keyword like internal or nsviz, we’d effectively be adding a new visibility class, not a refinement of private and would bring its own semantics, collision issues, and interactions with any future module work. This RFC aims to minimise surface area, which is why it treats namespace visibility as a refinement.

That said, if the consensus emerges around a new keyword, that’s something I can adjust. The important behaviour is the caller rule, not the exact token spelling.

Second, is exact-match useful enough?

Yes, there are plenty of codebases where internal helpers live side-by-side in one namespace, especially in domain-driven or layered architectures where namespaces are the boundaries. Today, teams either make them public, wrap them in a service class, use @internal, or wire them together via reflection or debug_backtrace.

All of those come with tradeoffs. Exact-match namespace visibility offers a simple enforceable boundary without designing a whole package system or assuming anything about code hierarchy. It’s not the most expressive possible rule, but it’s useful and predictable.

If the community prefers prefix-based visibility or package-level visibility, that could be explored in a follow-up RFC. I’m not opposed to more expressive forms; I’m just not binding this RFC to a package model the language hasn’t defined yet.

And lastly, isn’t namespace visibility easy to bypass?

Yes — but so is private and protected. No PHP visibility is intended as a security boundary. This is a developer-intent boundary: encapsulation, static analysis, and making accidental misuse harder.

If a future module/package system introduces stronger enforcement, this RFC can layer underneath it without a conflict.

Sincerely,

— Rob

Hi

In particular, the syntax is a hard-no. It runs contrary to how the aviz syntax was defined, as others have already noted.

If you don't want to use internal(set) to save internal for some other use, that's fine. Come up with a different keyword. :-) But <allowed scope>(<operation>) is the syntax model that aviz established, and tossing extra parens in there just confuses things for everyone.

I agree with that.

If it really does need to be an entirely separate dimension of scoping, then I would argue it's too complex to capture in just keywords and Rowan's attribute proposal becomes even more compelling.

I disagree that this should be an Attribute for the inverse of the
reasons of why #[\Override] is an attribute:
https://wiki.php.net/rfc/marking_overriden_methods#why_an_attribute_and_not_a_keyword

Visibility is part of the public API and by making this an attribute,
the code will seemingly appear to work in older PHP version that do not
yet know about the attribute, but its behavior will differ.

It would of course also be syntactically / visually inconsistent with
any other visibility definition.

Best regards
Tim Düsterhus

Hi,

Did we take into account prefixed namespaces.

private(namespace \Users\Auth*) function test() {}

And then Auth folder has other classes and folders with child namespaces.

Sent from my iPhone

Hi

class P {
private(namespace) function x() {}
}
class C extends P {
protected function x() {}
}
This behaves the same as overriding a private method with a protected/public one today: the parent’s method is private to its declaring class, so the second example is allowed.

This is unsound. As we have established, neither private(namespace) nor protected is a subset of each other.

Specifically allowing this breaks the following (everything is declared in the same namespace):

class P {
private(namespace) function x() { }
}
class C extends P {
protected function x() { }
}

function f(P $p) {
$p->x(); // legal, because f is in the same namespace as P.
}

f(new C()); // breaks, because C::x() is protected and thus not legal to access from f / the global scope.

Best regards
Tim Düsterhus

Hi

class P {
private(namespace) function x() {}
}

class C extends P {
protected function x() {}
}

This behaves the same as overriding a private method with a protected/public one today: the parent’s method is private to its declaring class, so the second example is allowed.

This is unsound. As we have established, neither private(namespace)
nor protected is a subset of each other.

Specifically allowing this breaks the following (everything is declared
in the same namespace):

 class P {
     private(namespace) function x() { }
 }
 class C extends P {
     protected function x() { }
 }

 function f(P $p) {
     $p->x(); // legal, because f is in the same namespace as P.
 }

 f(new C()); // breaks, because C::x() is protected and thus not 

legal to access from f / the global scope.

Best regards
Tim Düsterhus

Initially, I treated private(namespace) like private for cross-namespace inheritance and overlooked how dynamic dispatch actually works in PHP. This means that a same-named method in a child would simply be a new method. But like you point out, that leads to a subtle problem.

Even though P::x() is a method that’s visible and intended for callers inside namespace A, the runtime dispatch would pick C::x(). That completely and utterly destroys substitutability for namespace internal callers, which is exactly what this visibility is meant to protect.

So ... it seems we need a couple of additional rules here:

1. If a parent has a private(namespace) method, then a subclass in a different namespace simply cannot declare a method with the exact same name. It’d be a compile time error to prevent shadowing and keep dispatch predictable. I’d also be open to other ways as well (such as always calling the namespaced method in the parent), but I’d need to see if that’s even possible in the engine.

2. As you pointed out, protected and private(namespace) aren’t compatible; thus we should only allow the same or a superset. So, it should only allow public or private(namespace) when inheriting in the same namespace.

— Rob