You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Core: add section about namespace declaration rules with select new sniffs
> ### Namespace declarations
>
> Each part of a namespace name should consist of capitalized words separated by underscores.
>
> Namespace declarations should have exactly one blank line before the declaration and at least one blank line after.
>
> There should be only one namespace declaration per file, and it should be at the top of the file. Namespace declarations using curly brace syntax are not allowed. Explicit global namespace declaration (namespace declaration without name) are also not allowed.
Refs:
* https://make.wordpress.org/core/2020/03/20/updating-the-coding-standards-for-modern-php/ - Namespace declarations section
* https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/#namespace-declarations
* WordPress/wpcs-docs 97
* WordPress/WordPress-Coding-Standards 1763
* PHPCSStandards/PHPCSExtra 4
* PHPCSStandards/PHPCSExtra 6
* PHPCSStandards/PHPCSExtra 50
Notes:
* The "Each part of a namespace name should consist of capitalized words separated by underscores" rule needs a new dedicated sniff.
An issue will need to be opened about this in WPCS. The corresponding issue in PHPCSExtra is PHPCSStandards/PHPCSExtra 231
* The "Namespace declarations should have exactly one blank line before the declaration and at least one blank line after" will probably also need a new sniff.
My research shows the following:
- The `PSR2.Namespaces.NamespaceDeclaration` sniff, which is included in `Extra` can _sort of_ cover the "after" part, as in: it check for exactly one blank line after, which is close to, but not exactly what we want.
- The `PSR12.Files.FileHeader` sniff can check both "before" and "after", but will also, again, check for exactly one blank line.
The problem with that sniff is that it currently is "all or nothing", it does not have modular error codes, so we cannot ignore some other things from that sniff (requires blank line between PHP open tag and file docblock), which makes it problematic to include the sniff.
If upstream PR squizlabs/PHP_CodeSniffer 2729 would (finally) be merged, we could reconsider adding that sniff though.
* As for the "... it (the namespace declaration) should be at the top of the file" rule. I do not believe we need to actively check for this.
With the "only one namespace declaration per file" rule being enforced, placing the namespace declaration anywhere else than at the top of the file would be a parse error.
Other notes:
* The "namespace keyword should be lowercase" part, as mentioned in the Make post, is already covered by the `Generic.PHP.LowerCaseKeyword` sniff.
* The "There should be exactly one space between the namespace keyword and the start of the namespace name" part, as mentioned in the Make post, is already covered by the `Generic.WhiteSpace.LanguageConstructSpacing` sniff, which was moved to `Core` in 2097.
* The "namespace names in a namespace declaration should not start with a leading backslash \", as well as the "There should be no whitespace or comments within the name part of the namespace declaration.", as mentioned in the Make post, are things which can (and should) be flagged by PHPCompatibility 10.0.
Closes 1763
0 commit comments