Skip to content

Commit bb89bb9

Browse files
committed
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
1 parent 3f608b2 commit bb89bb9

File tree

1 file changed

+23
-0
lines changed

1 file changed

+23
-0
lines changed

WordPress-Core/ruleset.xml

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -412,6 +412,29 @@
412412
<!-- Covered by the Squiz.Functions.FunctionDeclarationArgumentSpacing.SpacingAfterReference error code. -->
413413

414414

415+
<!--
416+
#############################################################################
417+
Handbook: Declare Statements, Namespace, and Import Statements - Namespace declarations.
418+
Ref: https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/#namespace-declarations
419+
#############################################################################
420+
-->
421+
<!-- Rule: Each part of a namespace name should consist of capitalized words separated by underscores. -->
422+
423+
<!-- Rule: Namespace declarations should have exactly one blank line before the declaration and at least one blank line after. -->
424+
425+
<!-- Covers rule: There should be only one namespace declaration per file... -->
426+
<rule ref="Universal.Namespaces.OneDeclarationPerFile"/>
427+
428+
<!-- Rule: ... and it should be at the top of the file.
429+
Note: with only one namespace declaration, it not being at the top of the file would be a parse error. -->
430+
431+
<!-- Covers rule: Namespace declarations using curly brace syntax are not allowed. -->
432+
<rule ref="Universal.Namespaces.DisallowCurlyBraceSyntax"/>
433+
434+
<!-- Covers rule: Explicit global namespace declaration (namespace declaration without name) are also not allowed. -->
435+
<rule ref="Universal.Namespaces.DisallowDeclarationWithoutName"/>
436+
437+
415438
<!--
416439
#############################################################################
417440
Handbook: Object-Oriented Programming - Only One Object Structure (Class/Interface/Trait) per File.

0 commit comments

Comments
 (0)