Is your feature request related to a problem?

PHP 5.3 introduced namespaces into PHP.

Refs:

• https://www.php.net/manual/en/migration53.new-features.php
• https://www.php.net/manual/en/language.namespaces.php

At this moment WPCS has no formatting rules for namespace declarations or the usage of namespaced constructs.

This issue, however, is purely about namespace declarations.

Describe the solution you'd like

I would like to propose adding the following rules regarding namespace declarations to the WP Coding Standards handbook:

1. There should be exactly one space between the namespace keyword and the start of the namespace name in a namespace declaration.
2. Each "leaf" of a namespace name should be in Camel_Caps, i.e. each word should start with a capital and words should be separated by an underscore.
   Consecutive caps, like for acronyms, will be allowed.
   This is in line with other WP naming conventions.
3. There should be no whitespace or comments within the name part of the namespace declaration.
4. There should be exactly one blank line before a namespace declaration.
5. There should be at least one blank line after a namespace declaration.
   The "at least" bit prevent potential fixer conflicts with sniffs which check for a fixed amount of blank lines above function/class declarations.
6. There should be only one namespace declaration per file.
7. Scoped namespace declarations are not allowed.
8. Namespace declarations without name (= explicit global namespace) are not allowed.

Valid code example

<?php
/**
 * File docblock.
 */

namespace Prefix\Admin\Domain_URL\Sub_Domain\Event;

use ...

Invalid code examples

<?php
/**
 * File docblock.
 */
namespace Prefix \
	/* Here comes the real namespace */ Admin\DomainURL\SubDomain\Event;
use ...

<?php
/**
 * File docblock.
 */
namespace Foo {
    // Code.
}

namespace {
    // Code.
}

If this proposal is accepted, we can then add sniff(s) to WPCS to check these rules automatically and - except for issues with comments - auto-fix them.

Already covered

• The namespace keyword should be lowercase.
  This is already covered by the Generic.PHP.LowerCaseKeyword.Found sniff which is included in the WordPress-Core ruleset.

Open question:

• Should we - at this time - define rules about the allowed compound depth of namespace names ? Or should we leave this open for now ?

Additional context

Explicitly not covered by this proposal:

• The name of a namespace should not start with a (superfluous) namespace separator.
  This would be a parse error in nearly all cases as PHP will in that case interpret the namespace name as the name of a global (namespaced) constant.
  Parse errors should be detected by linters and/or by the Generic.PHP.Syntax sniff.
• The order of various statements which can be at the start of a document.
  This will be covered in a separate proposal.
• Any relation between namespace declarations and autoloading / the path to the file.

Comparison with PSR-12:

The only rule in the above proposal which is included in PSR-12 is rule 4 (one blank line before) and in a way rule 5 (at least one blank line after).
PSR-12 has no opinion on any of the other rules proposed here.

PSR-12 does have an opinion on the allowed compound namespace depth, but what with plugins and themes needing to use prefixing of namespaces, the PSR-12 rule for this may ultimately not be suitable for use in the context of WordPress.

Comparison with PSR-1:

While PSR-1 (included in PSR-12) demands StudlyCaps/PascalCase for class names, it does not do so explicitly for namespace names.

PSR-1 does demand implementing PSR-0 or PSR-4 for autoloading, but as autoloading is explicitly not covered in this proposal, this is not something we currently need to take into account.

Notes for the WPCS Implementation:

• Rule 1 can be covered by the upstream Generic.WhiteSpace.LanguageConstructSpacing.IncorrectSingle sniff. Also see issue PHPCS 3.4.1: Use the Generic.WhiteSpace.LanguageConstructSpacing sniff #1616
• Rule 2 would need a dedicated WP sniff in the NamingConventions category.
• Rule 3 can be covered by an upstream sniff once it is pulled & merged. See: Sniff to check whitespace around namespace separators squizlabs/PHP_CodeSniffer#2150
• Rule 4 can possibly be covered by the upstream PSR-12 sniff for the same, once it is created, pulled & merged.
• Rule 5 is already covered in WordPress-Extra by the upstream PSR2.Namespaces.NamespaceDeclaration.BlankLineAfter sniff. This sniff could be moved to WordPress-Core.
• Rule 6, 7 and 8 can be covered by upstream sniffs once pulled & merged. See: Interest in a namespace declaration sniff to check scoped/no name usage ? squizlabs/PHP_CodeSniffer#2324

/cc @pento