====== Request for Comments: Namespaces Encapsulation ======
  * Version: 1.0
  * Date: 2012-08-23
  * Author: Yahav Gindi Bar <g.b.yahav@gmail.com>
  * Status: Under Discussion
  * First Published at: https://wiki.php.net/rfc/namespaces_encapsulation

===== Introduction =====

This RFC introduce and suggest adding encapsulation abilities into classes.
Today, namespaces is a tool used to avoid conflicts with other classes and help improve performance. However, with encapsulation abilities to classes, namespaces can be even better.

==== Why do we need classes encapsulation? ====

Today, when one declare few classes, all of them can be accessed and initialized (though you can disable it using private constructor, which is a different story). from any scope - the global scope and namespace specific.

There are cases which programmer wish, just like when using private class members, to encapsulate and make some of his or her classes available only from the namespace it was created in. This most likely occur when developing a modular site, when one tries to make his or her work simpler for the consumer or end-developer.

===== Use cases =====

<code php>

namespace \Foo;

public class Config {
    public function getOption($key) { ... }
}

internal abstract class ConfigAdapter {
     public abstract function getValue($key);
}

internal class IniConfigAdapter extends ConfigAdapter  {
     public function getValue($key) { ... }
}

internal class XmlConfigAdapter extends ConfigAdapter  {
    public function getValue($key) { ... }
}

internal class YamlConfigAdapter  extends ConfigAdapter {
    public function getValue($key) { ... }
}

</code>

Using the example above, one can encapsulate the many config adapters and use the ''Config'' class in order to retrieve the value requested from the user using the requested adapter.

===== Specification =====

The encapsulation will take place at the class deceleration, by the ability to add the keyword ''internal'' before the class declaration. 

===== Optional features =====

==== Prefix classes with the ''public'' keyword (Vote separately): ====
Even though any class which not declared as internal will be public and available, some developers may wish to prefix their classes with public as well.

For example:
<code php>
namespace \Foo;

public class Foo {
    public function getBar() {
        return (new Bar())->getBar();
    }
}

internal class Bar {
    public function getBar() {
        return "bar";
    }
}

</code>

===== Proposal and Patch =====

The patch for this proposal is not written yet.

===== TODO =====

  * Decide whether to use a new keyword - ''internal'', or use the ''private'' keyword.

===== Further resources =====

Implementation in C#:

* http://msdn.microsoft.com/en-us/library/7c5ka91b%28v=vs.80%29.aspx

Implementation in Java:

* http://docs.oracle.com/javase/tutorial/java/javaOO/innerclasses.html

===== Changelog =====