Improving Our Use of PHP Namespaces

We were right to do PHP Namespaces wrong

Let's step back and think about why we use namespaces, and how to realize their real advantages. I suspect there's a lingering hesitance to embrace their usefulness. For years we've built the appropriate habit of naming our symbols with appropriate specificity to avoid naming collisions. I'm talking about naming your class something like MyCompany_Loader, or something similarly specific to your context. This informal namespacing was a great stop-gap. But once we make the switch to formal namespacing, we should reconsider what impact this should have on our symbol names.

How to properly use PHP namespaces

The specific notion on my mind is that I'm seeing a redundant mix of formal and informal namespacing. Let's start a conversation about this, while it's still somewhat early in the game. At this point (I'm *always* willing to be convinced otherwise), I contend that we should completely eradicate the informal namespacing conventions if we are going to adopt formal namespacing in our apps. Here's a simple example that illustrates the general direction I think we should move in (derived from the Drupal Extension project, a Behat Mink component).

Example (Let's move away from this):

    namespace MyCompany;
    use Drupal\DrupalExtension\Context\DrupalContext;
    class MyCompanyContext extends DrupalContext {}

Proposal (Let's move toward this):

    namespace MyCompany;
    class Context extends \Drupal\Extension\Context {}

Notice a few specific things:

1. In the first example's use statement, the word Drupal occurs 3 times; 2 can be removed
2. In the first example's use statement, the word Context occurs twice; 1 can be removed.
3. In the first example, both "localized" class names had redundant occurrences of the company name. This is specifically what formal namespaces exist to eliminate.

These are essentially equivalent, but the latter removes several redundant components and delivers what namespaces are supposed to bring us. Notice also that I removed a `use` statement and instead used the fully-qualified class name in the code. This is an important part of what I'm proposing. I think it's too simple to advocate for moving all use of namespaces to the top of a file and only use "short names" for symbols in other namespaces. This is particularly important when you are extending a symbol. Code readability is inversely related to how often I need to scroll to the top of the file to figure out which specific version of a symbol is being used.

To Summarize

1. Don't use redundant name components
2. Don't be afraid to use fully-qualified names in-context, if appropriate.

The cases where it's not really necessary to use fully-qualified names in-context are when you are only "consuming" a symbol, and not extending it. For example, if you are going to use a Widgetizer library, but not extend it, feel free to use the `use` statement and simplify the use of the symbol throughout the file. The important distinction is that you don't have potentially ambiguous names if you are only pulling in one namespace with that symbol.