# I would like to write an RFC for the addition of an internal keyword - Thread: https://externals.io/message/66260 - Original archive: https://news-web.php.net/php.internals/66260 - Started by Jens Riisom Schultz on 2013-02-27T07:07:06+00:00 - Messages: 13 - Reply by email to internals@lists.php.net - More for agents: search with https://externals.io/search.md?q={query} · JSON API at https://externals.io/api · documentation at https://externals.io/llms.txt --- ## #66260 — Jens Riisom Schultz — 2013-02-27T07:07:06+00:00 URL: https://externals.io/message/66260#66260 Hi, I just want to get a feel for whether the following idea would be instantly rejected (for example I get the feeling that adding keywords is a big deal): Often, when writing frameworks, you need to make public or protected functionality or classes which should only be called from inside the framework. You CAN ensure this with a lot of ninja tricks and debug_backtrace, but it is very cumbersome and often hides your methods and properties from class signatures. Therefore I would propose adding a C# style "internal" keyword. ( http://msdn.microsoft.com/en-us/library/7c5ka91b(v=vs.80).aspx ) The idea is, simply, that functions, methods and classes marked as "internal" would only be accessible from within the namespace in which they are defined. For example the following class, "namespace Framework; internal class Something {}", would only be visible from within the "Framework" namespace. I have a hunch that this would be relatively easy to implement. If noone objects I would attempt to create a patch and an RFC. What do you think? -Jens Riisom Schultz --- ## #66262 — Nikita Nefedov — 2013-02-27T08:18:34+00:00 URL: https://externals.io/message/66260#66262 · In reply to: #66260 On Wed, 27 Feb 2013 11:07:06 +0400, Jens Riisom Schultz wrote: > Hi, > > I just want to get a feel for whether the following idea would be > instantly rejected (for example I get the feeling that adding keywords > is a big deal): > > Often, when writing frameworks, you need to make public or protected > functionality or classes which should only be called from inside the > framework. You CAN ensure this with a lot of ninja tricks and > debug_backtrace, but it is very cumbersome and often hides your methods > and properties from class signatures. > > Therefore I would propose adding a C# style "internal" keyword. ( > http://msdn.microsoft.com/en-us/library/7c5ka91b(v=vs.80).aspx ) > > The idea is, simply, that functions, methods and classes marked as > "internal" would only be accessible from within the namespace in which > they are defined. > > For example the following class, "namespace Framework; internal class > Something {}", would only be visible from within the "Framework" > namespace. > > I have a hunch that this would be relatively easy to implement. > > If noone objects I would attempt to create a patch and an RFC. > > What do you think? > > > -Jens Riisom Schultz > -- > > > Hi, I, for one, think it should be solved on the IDE side. I used a lot of Doctrine's internal methods lately and if they would be not accessible I wouldn't be able to do a lot of things. Of course internal methods/classes shouldn't be exposed as a part of API, but if they exist, I would want to call them *if I know what I'm doing*. I think it would be useful if phpdoc had an @internal tag so that IDEs could highlight places where you use internal parts of library. --- ## #66263 — Sebastian Krebs — 2013-02-27T08:40:19+00:00 URL: https://externals.io/message/66260#66263 · In reply to: #66260 2013/2/27 Jens Riisom Schultz > Hi, > > I just want to get a feel for whether the following idea would be > instantly rejected (for example I get the feeling that adding keywords is a > big deal): > > Often, when writing frameworks, you need to make public or protected > functionality or classes which should only be called from inside the > framework. You CAN ensure this with a lot of ninja tricks and > debug_backtrace, but it is very cumbersome and often hides your methods and > properties from class signatures. > Just my 2 cent, but whats about just trust other developers, that when they call a method/function marked with @internal they know, what they are doing? > > Therefore I would propose adding a C# style "internal" keyword. ( > http://msdn.microsoft.com/en-us/library/7c5ka91b(v=vs.80).aspx ) > > The idea is, simply, that functions, methods and classes marked as > "internal" would only be accessible from within the namespace in which they > are defined. > I don't think it makes sense for methods as public/protected/private is enough. For know I don't see reasonable use-cases for an additional visibility-modifier for "public as long as in the same namespace", or "namespace-protected" for methods. But maybe it's interesting to extend public/private/protected to classes and functions like protected function anInternalFunction() { /* Restricted to this and subnamespaces */ } private class { /* Restricted to this namespace */ } Worth the mention, that I rarely miss something like this, but at least I can imagine some use-cases. > > For example the following class, "namespace Framework; internal class > Something {}", would only be visible from within the "Framework" namespace. > > I have a hunch that this would be relatively easy to implement. > > If noone objects I would attempt to create a patch and an RFC. > > What do you think? > > > -Jens Riisom Schultz > -- > > > > -- github.com/KingCrunch --- ## #66265 — Lazare Inepologlou — 2013-02-27T09:11:53+00:00 URL: https://externals.io/message/66260#66265 · In reply to: #66260 Hello, 2013/2/27 Jens Riisom Schultz > Hi, > > I just want to get a feel for whether the following idea would be > instantly rejected (for example I get the feeling that adding keywords is a > big deal): > > Often, when writing frameworks, you need to make public or protected > functionality or classes which should only be called from inside the > framework. You CAN ensure this with a lot of ninja tricks and > debug_backtrace, but it is very cumbersome and often hides your methods and > properties from class signatures. > > Therefore I would propose adding a C# style "internal" keyword. ( > http://msdn.microsoft.com/en-us/library/7c5ka91b(v=vs.80).aspx ) > > The idea is, simply, that functions, methods and classes marked as > "internal" would only be accessible from within the namespace in which they > are defined. > > The "internal" keyword in C# restricts access to the same *assembly*. An assebly in .NET jargon is a .dll or a .exe, ie a package of code compiled by the same developper at once. As packages in PHP do not exist, or exist in some vague form (.phar, composer etc), I do not see how this keyword, with its original meaning, could find a place here. Namespaces are not restricted to the same develloper and anyone can add to them. Therefore, the meaning of the keyword would be totally different from that of C#. > For example the following class, "namespace Framework; internal class > Something {}", would only be visible from within the "Framework" namespace. > > I have a hunch that this would be relatively easy to implement. > > If noone objects I would attempt to create a patch and an RFC. > > What do you think? > > > -Jens Riisom Schultz --- ## #66271 — Steve Clay — 2013-02-27T15:08:17+00:00 URL: https://externals.io/message/66260#66271 · In reply to: #66262 > I, for one, think it should be solved on the IDE side. I used a lot of Doctrine's internal > methods lately and if they would be not accessible I wouldn't be able to do a lot of things. > Of course internal methods/classes shouldn't be exposed as a part of API, but if they > exist, I would want to call them *if I know what I'm doing*. I think it would be useful if > phpdoc had an @internal tag so that IDEs could highlight places where you use internal > parts of library. Agreed, IDE/phpDoc is the place for a solution (and I do recognize that there is some need here). phpDoc already supports "@access private" for items to be left out of public documentation. An IDE could be configured to have these items appear greyed or not to appear in autocomplete lists. There's already a way to tightly control access: embrace OOP and eliminate statically accessible APIs (global vars/funcs and static props/methods) that you don't want people calling. You don't actually need them. Although closures helped too, PHP gained true information hiding in 5.0 with "private". Steve Clay -- http://www.mrclay.org/ --- ## #66275 — Sebastian Krebs — 2013-02-27T15:22:35+00:00 URL: https://externals.io/message/66260#66275 · In reply to: #66271 2013/2/27 Steve Clay > > > > […] > > Agreed, IDE/phpDoc is the place for a solution (and I do recognize that > there is some need here). > > phpDoc already supports "@access private" for items to be left out of > public documentation. An IDE could be configured to have these items appear > greyed or not to appear in autocomplete lists. > a) You misuse the "private visibility" here: "@access private" comes from old PHP4-days, where the DocComment must know the visibility, because the method itself didn't b) Most doc-tools are able to generate developer-docs, which usually contain all protected and private elements. This "hidden element" will appear as regular private method there. Can be confusing I think :) > > There's already a way to tightly control access: embrace OOP and eliminate > statically accessible APIs (global vars/funcs and static props/methods) > that you don't want people calling. You don't actually need them. Although > closures helped too, PHP gained true information hiding in 5.0 with > "private". I agree > > > Steve Clay > -- > http://www.mrclay.org/ > > > -- > > > > -- github.com/KingCrunch --- ## #66282 — Steve Clay — 2013-02-27T17:37:05+00:00 URL: https://externals.io/message/66260#66282 · In reply to: #66275 > 2013/2/27 Steve Clay > > […] > a) You misuse the "private visibility" here: "@access private" comes from > old PHP4-days, where the DocComment must know the visibility, because the > method itself didn't Sure, but phpDocumentor1 currently uses @access to control documentation output (the description doesn't mention access/visibility at all and "protected" does nothing). http://manual.phpdoc.org/HTMLSmartyConverter/default/phpDocumentor/tutorial_tags.access.pkg.html For phpDoc2 the OP should also check out these: http://www.phpdoc.org/docs/latest/for-users/phpdoc/tags/internal.html http://www.phpdoc.org/docs/latest/for-users/phpdoc/tags/api.html http://www.phpdoc.org/docs/latest/for-users/phpdoc/tags/ignore.html Steve Clay -- http://www.mrclay.org/ --- ## #66313 — Jens Riisom Schultz — 2013-02-28T06:56:54+00:00 URL: https://externals.io/message/66260#66313 · In reply to: #66265 Hi everyone, (I got "hooked off" this discussion, so I have tried to keep up by reading the digest... This makes it impossible for me to correctly interleave my comments, so I'll just "top post" or whatever the term is) (I'm sure this has been mentioned before but a forum would be so much more accesible than this mailing list concept...) * In response to the argument that you want to be able to modify a framework or use it in an unintended manner: This would be possible by explicitly stating "namespace Framework;" in a given php file. * In response to the argument that php has no assembly concept: I know this, but namespaces are as close as we get, and would effectively solve this. * In response to the argument that php already has accessibility restrictions with private and protected: This is true, but it does not solve all problems. Often you need classes to interoperate in a way that can only be facilitated by making functionality public. Also, there is no way to make a private or protected class (since php has no assembly concept), though what I propose would likely birth the concept of private and protected classes as well. * In response to the argument that PHP does not restrict anyone from adding to a namespace: That is true, but say you were using Doctrine2. Would you ever make a php file with "namespace Doctrine2;" in it, unless you wanted to modify Doctrine2, and hence you knew what you were doing, or accepted the risks? * In response to the concept of solving this through documentation: First off, this is not possible with the current phpdoc and phpdoc2 standards. Second off, problems like these should not be solved by documentation, imho, or of course I would not propose this. The C# designers seem to agree with me. And the Java designers, too (though they have no internal keyword they do have a way of hiding framework specific classes). Information hiding is one of the staples of good OOP, and the internal keyword would facilitate further information hiding in a way which is extremely hard to do as php is now. I would like to finish off with an example - I can tell there is a huge resistance to this but I do not agree with your arguments, so I'll give it another shot. doInternalStuff(); } internal public static function internalStuffHelper() {} } internal class InternalClass { public function doInternalStuff() { return PublicAPIClass::internalStuffHelper(); } } namespace NotTheFramework; $instance = new \Framework\PublicAPIClass(); $instance->doStuff(); // You would not be able to do the following things: use Framework\InternalClass; $instance = new \Framework\InternalClass(); \FrameWork\PublicAPIClass::internalStuffHelper(); ?> Please read my example carefully, before simply writing it off. ...And a question: Am I wrong when I assume that this should be "relatively" easy to implement? -Jens Riisom Schultz > Hello, > > 2013/2/27 Jens Riisom Schultz > Hi, > > I just want to get a feel for whether the following idea would be instantly rejected (for example I get the feeling that adding keywords is a big deal): > > Often, when writing frameworks, you need to make public or protected functionality or classes which should only be called from inside the framework. You CAN ensure this with a lot of ninja tricks and debug_backtrace, but it is very cumbersome and often hides your methods and properties from class signatures. > > Therefore I would propose adding a C# style "internal" keyword. ( http://msdn.microsoft.com/en-us/library/7c5ka91b(v=vs.80).aspx ) > > The idea is, simply, that functions, methods and classes marked as "internal" would only be accessible from within the namespace in which they are defined. > > > The "internal" keyword in C# restricts access to the same *assembly*. An assebly in .NET jargon is a .dll or a .exe, ie a package of code compiled by the same developper at once. As packages in PHP do not exist, or exist in some vague form (.phar, composer etc), I do not see how this keyword, with its original meaning, could find a place here. > > Namespaces are not restricted to the same develloper and anyone can add to them. Therefore, the meaning of the keyword would be totally different from that of C#. > > > > > For example the following class, "namespace Framework; internal class Something {}", would only be visible from within the "Framework" namespace. > > I have a hunch that this would be relatively easy to implement. > > If noone objects I would attempt to create a patch and an RFC. > > What do you think? > > > -Jens Riisom Schultz --- ## #66317 — Sebastian Krebs — 2013-02-28T08:14:42+00:00 URL: https://externals.io/message/66260#66317 · In reply to: #66313 2013/2/28 Jens Riisom Schultz > Hi everyone, > > (I got "hooked off" this discussion, so I have tried to keep up by reading > the digest... This makes it impossible for me to correctly interleave my > comments, so I'll just "top post" or whatever the term is) (I'm sure this > has been mentioned before but a forum would be so much more accesible than > this mailing list concept...) > > > * In response to the argument that you want to be able to modify a > framework or use it in an unintended manner: > This would be possible by explicitly stating "namespace Framework;" in a > given php file. > > * In response to the argument that php has no assembly concept: > I know this, but namespaces are as close as we get, and would effectively > solve this. > No. A namespace is in fact more or less just a prefix, that groups the containing elements together. Beside the semantic meaning of grouping they don't have any further abilities, or meaning. Without knowing exact details I guess, that "internal" in C# is primary a technical thing, that allows a compiler further optimizations, because he definitely knows, that the function/method is only used within the assembly and is not required to do anything to expose it to the outside? > > * In response to the argument that php already has accessibility > restrictions with private and protected: > This is true, but it does not solve all problems. Often you need classes > to interoperate in a way that can only be facilitated by making > functionality public. Also, there is no way to make a private or protected > class (since php has no assembly concept), though what I propose would > likely birth the concept of private and protected classes as well. > Maybe it's just me, but no: I've never had the need of what you describe and where a public method wasn't apropriate anway... At least for a very long time :D > > * In response to the argument that PHP does not restrict anyone from > adding to a namespace: > That is true, but say you were using Doctrine2. Would you ever make a php > file with "namespace Doctrine2;" in it, unless you wanted to modify > Doctrine2, and hence you knew what you were doing, or accepted the risks? > Well, yes. But extending/overriding a components method _always_ requires, that you know what you do, so why enforcing/encouraging hacks, instead of the good old "protected"? > > * In response to the concept of solving this through documentation: > First off, this is not possible with the current phpdoc and phpdoc2 > standards. Second off, problems like these should not be solved by > documentation, imho, or of course I would not propose this. The C# > designers seem to agree with me. And the Java designers, too (though they > have no internal keyword they do have a way of hiding framework specific > classes). > > Information hiding is one of the staples of good OOP, and the internal > keyword would facilitate further information hiding in a way which is > extremely hard to do as php is now. > > I would like to finish off with an example - I can tell there is a huge > resistance to this but I do not agree with your arguments, so I'll give it > another shot. > > > namespace Framework; > > class PublicAPIClass { > public function doStuff() { > $instance = new InternalClass(); > return $instance->doInternalStuff(); > } > > internal public static function internalStuffHelper() {} > } > > internal class InternalClass { > public function doInternalStuff() { > return PublicAPIClass::internalStuffHelper(); > } > } > This doesn't explain, why the "InternalClass" should be hidden? Additional the "new" in "doStuff()" and the cyclic calls let me believe, that you'll have a "tight coupling"-problem anyway. abstract class APIAbstract { protected function doInternalStuff() { return PublicAPIClass::internalStuffHelper(); } protected static function internalStuffHelper(); } > > namespace NotTheFramework; > > $instance = new \Framework\PublicAPIClass(); > $instance->doStuff(); > > // You would not be able to do the following things: > use Framework\InternalClass; > > $instance = new \Framework\InternalClass(); > > \FrameWork\PublicAPIClass::internalStuffHelper(); > And the question remains: Why _should_ I not be able to do this? If it is that specific to the "PublicAPIClass" maybe it should be an abstract parent instead? Or a trait? If it is _not_ that specific to "PublicAPIClass" ... well, ehm, this can't be, because it calls "internalStuffHelper()", thus it is bound to the class in any case. :) > > ?> > > Please read my example carefully, before simply writing it off. > > ...And a question: Am I wrong when I assume that this should be > "relatively" easy to implement? > > -Jens Riisom Schultz > > > On Feb 27, 2013, at 10:11 AM, Lazare Inepologlou > wrote: > > > […] > instantly rejected (for example I get the feeling that adding keywords is a > big deal): > > […] > functionality or classes which should only be called from inside the > framework. You CAN ensure this with a lot of ninja tricks and > debug_backtrace, but it is very cumbersome and often hides your methods and > properties from class signatures. > > […] > http://msdn.microsoft.com/en-us/library/7c5ka91b(v=vs.80).aspx ) > > […] > "internal" would only be accessible from within the namespace in which they > are defined. > > […] > assebly in .NET jargon is a .dll or a .exe, ie a package of code compiled > by the same developper at once. As packages in PHP do not exist, or exist > in some vague form (.phar, composer etc), I do not see how this keyword, > with its original meaning, could find a place here. > > […] > to them. Therefore, the meaning of the keyword would be totally different > from that of C#. > > […] > Something {}", would only be visible from within the "Framework" namespace. > > […] > > -- github.com/KingCrunch --- ## #66321 — Lazare Inepologlou — 2013-02-28T11:40:08+00:00 URL: https://externals.io/message/66260#66321 · In reply to: #66317 Hello, please read my comment inline... 2013/2/28 Sebastian Krebs > 2013/2/28 Jens Riisom Schultz > > > […] > reading > > […] > than > > […] > > No. A namespace is in fact more or less just a prefix, that groups the > containing elements together. Beside the semantic meaning of grouping they > don't have any further abilities, or meaning. > Without knowing exact details I guess, that "internal" in C# is primary a > technical thing, that allows a compiler further optimizations, because he > definitely knows, that the function/method is only used within the assembly > and is not required to do anything to expose it to the outside? > > Regardless of the technical details, it is still a fine way of applying encaptulation so you can't say that it is only a technical thing. > > > […] > protected > > […] > > Maybe it's just me, but no: I've never had the need of what you describe > and where a public method wasn't apropriate anway... At least for a very > long time :D > > > > […] > > Well, yes. But extending/overriding a components method _always_ requires, > that you know what you do, so why enforcing/encouraging hacks, instead of > the good old "protected"? > > "Protected" is used for extending classes. There is no mechanism to inherit and extend a namespace so "protected" is irrelevant here. > > > […] > Actually Java has a concept that is identical to your proposal. The default access modifier (when no access modifier is written) is the "package" modifier (=accessible from within the same package). > > […] > it > > […] > > "internal public" is too much here, unless you want also to have "internal protected" like C#. I have extensivelly used "internal" and "package" in C# and Java, and I can tell you that "internal protected" is so rare that is not worh it. > > This doesn't explain, why the "InternalClass" should be hidden? Additional > the "new" in "doStuff()" and the cyclic calls let me believe, that you'll > have a "tight coupling"-problem anyway. > > abstract class APIAbstract { > protected function doInternalStuff() { > return PublicAPIClass::internalStuffHelper(); > } > protected static function internalStuffHelper(); > } > > > > […] > > And the question remains: Why _should_ I not be able to do this? If it is > that specific to the "PublicAPIClass" maybe it should be an abstract parent > instead? Or a trait? > If it is _not_ that specific to "PublicAPIClass" ... well, ehm, this can't > be, because it calls "internalStuffHelper()", thus it is bound to the class > in any case. :) > > > > […] > Relatively is the right word here. It might be easy for class members as the mechanism already exists. However, for direct namespace members there is no such concept. Can you make a proof-of-concept patch? > > […] > is a > > […] > and > > […] > they > > […] > An > > […] > namespace. > > […] > > > -- > github.com/KingCrunch > Lazare Inepologlou Ingénieur Logiciel --- ## #66362 — Steve Clay — 2013-02-28T20:37:18+00:00 URL: https://externals.io/message/66260#66362 · In reply to: #66313 Setting aside difficulty of implementation, I'm coming around to the idea, though I think you could simplify it by cordoning off an entire namespace. E.g.: A namespace at least two deep (e.g. \A\B\) may be marked 'protected' (by some method TBD). Classes and functions declared in a protected namespace can only be accessed from methods or functions inside the same namespace, or in ancestor namespaces. E.g., if \Foo\Internal\ is protected, access of its classes/functions must originate from classes/functions defined in \Foo\, \Foo\Internal\, or \Foo\Internal\*. This would allow something like nested classes, but obviously with a lot more flexibility. In practice, plugin code sitting in, say, \MyPlugin\ could freely access \Framework\SomeClass, but not \Framework\Internal\SomeClass. I see some value there, but there's tons of questions remaining and how to to implement the damn thing... Steve Clay -- http://www.mrclay.org/ > * In response to the argument that php has no assembly concept: > I know this, but namespaces are as close as we get, and would effectively solve this. --- ## #66391 — Julien Pauli — 2013-03-01T11:11:57+00:00 URL: https://externals.io/message/66260#66391 · In reply to: #66321 On Thu, Feb 28, 2013 at 12:40 PM, Lazare Inepologlou wrote: > Hello, > > please read my comment inline... > > 2013/2/28 Sebastian Krebs > > > […] > my > > […] > this > > […] > a > > […] > effectively > > […] > they > > […] > assembly > > […] > Regardless of the technical details, it is still a fine way of applying > encaptulation so you can't say that it is only a technical thing. > > > > […] > classes > > […] > php > > […] > risks? > > […] > requires, > > […] > "Protected" is used for extending classes. There is no mechanism to inherit > and extend a namespace so "protected" is irrelevant here. > > > > […] > they > > […] > specific > > […] > > > Actually Java has a concept that is identical to your proposal. The default > access modifier (when no access modifier is written) is the "package" > modifier (=accessible from within the same package). > > Ha, it's been years since I'm asking for such a feature to come to PHP. I would love to see a package visibility in PHP, restricting access to 'package'ed members (methods or attributes) to an object born from a class of the same namespace. Would really help some cases in frameworks or so :-) Just my2cents Julien --- ## #66398 — Michael Morris — 2013-03-01T19:44:10+00:00 URL: https://externals.io/message/66260#66398 · In reply to: #66391 My thoughts are that no additional keyword is necessary - allow protected and private to be used in this scopes. A protected element of a namespace can be accessed within that namespace or any sub-namespaces, and a private element would only be visible by code in the same namespace. Hence namespace A { protected class Bar(){} } namespace B { new \A\Bar(); // fails, protected. } namespace A\C { new \A\Bar(); // works, C is A's child. private class Foo(); } namespace A\C\D { new \A\C\Foo(); // fails, private and only reachable from \A\C } This accomplishes the same as the proposed keyword, and then some, and doesn't introduce the BC break of a new keyword. > On Thu, Feb 28, 2013 at 12:40 PM, Lazare Inepologlou > […] > > > […] > in > > […] > primary a > > […] > he > > […] > would > > […] > describe > > […] > very > > […] > of > > […] > inherit > > […] > default > > […] > > I would love to see a package visibility in PHP, restricting access to > 'package'ed members (methods or attributes) to an object born from a class > of the same namespace. > Would really help some cases in frameworks or so :-) > > Just my2cents > > Julien