From bb89bb9839831417629b5e9fa81a5c293485962a Mon Sep 17 00:00:00 2001 From: jrfnl Date: Tue, 13 Jun 2023 14:26:32 +0200 Subject: [PATCH] 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 --- WordPress-Core/ruleset.xml | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/WordPress-Core/ruleset.xml b/WordPress-Core/ruleset.xml index bf8b6938d4..ee3bad0504 100644 --- a/WordPress-Core/ruleset.xml +++ b/WordPress-Core/ruleset.xml @@ -412,6 +412,29 @@ + + + + + + + + + + + + + + + + +