Core: add section about import use statement rules with select new sniffs

[jrfnl]

Using import use statements

Using import use statements allows you to refer to constants, functions, classes, interfaces, namespaces, enums and traits that live outside of the current namespace.

Import use statements should be at the top of the file and follow the (optional) namespace declaration. They should follow a specific order based on the type of the import:

1. use statements for namespaces, classes, interfaces, traits and enums
2. use statements for functions
3. use statements for constants

Aliases can be used to prevent name collisions (two classes in different namespaces using the same class name).
When using aliases, make sure the aliases follow the WordPress naming convention and are unique.

The following examples showcase the correct and incorrect usage of import use statements regarding things like spacing, groupings, leading backslashes, etc.

Refs:

• https://make.wordpress.org/core/2020/03/20/updating-the-coding-standards-for-modern-php/ - Import use statement section
• https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/#using-import-use-statements
• Add import use statements section wpcs-docs#98
• New Universal.UseStatements.NoLeadingBackslash sniff PHPCSStandards/PHPCSExtra#46
• New Universal.UseStatements.LowercaseFunctionConst sniff PHPCSStandards/PHPCSExtra#58

Notes:

• The "Import use statements should be at the top of a file and should directly follow the (optional) namespace declaration." rule is sort of covered by the PSR12.Files.FileHeader.IncorrectOrder sniff.
  This sniff will flag incorrect order when a use statement is part of the file header, but will not pick up on use statements which are not at the top of the file.
• The "There should be exactly one blank line before the first import use statement of each type and at least one blank line after the last import use statement." will probably need a new sniff.
  My research shows the following:
  • The PSR12.Files.FileHeader sniff can check both "before" and "after", but will 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 for the various file headers sections for the blank line check, 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 PSR12/FileHeader: make "SpacingAfter" and "SpacingInside" errorcodes modular squizlabs/PHP_CodeSniffer#2729 would (finally) be merged, we could reconsider adding that sniff though.
• The "There should be exactly one space after each keyword." rule is currently only checked for the use keyword via the Generic.WhiteSpace.LanguageConstructSpacing sniff, which was moved to Core in Core: move rules related to include/require statements from Extra to Core #2097.
  PHPCSExtra 1.1.0 will contain a new Universal.UseStatements.KeywordSpacing sniff which can check the spacing around the function, const and as keywords.
• The "Alias names should comply with the existing WordPress naming conventions for class/function/constant names." rule will need a new dedicated sniff.
  An issue will need to be opened about this in WPCS. The corresponding issue in PHPCSExtra is Sniff to enforce naming conventions for class/function/const aliases PHPCSStandards/PHPCSExtra#232
• The "Only set an alias when using a different name." rule as mentioned in the Make post is currently not checked.
  PHPCSExtra 1.1.0 will contain a new Universal.UseStatements.NoUselessAliases sniff which will be able to check this.
• The "When using group use statements ... There should be one statement for each type – OO constructs (classes/interfaces/traits), functions, constants. The various types should not be combined in one group use statement." rule as mentioned in the Make post is currently not checked.
  PHPCSExtra 1.1.0 will contain a new Universal.UseStatements.DisallowMixedGroupUse sniff which will be able to check this.
• As for the formatting rules for group use statements: there are currently no sniffs available for this, so a new sniff is needed to check this.

Other notes:

• The "There should be no whitespace or comments within the name part of a use declaration.", as mentioned in the Make post, can (and should) be flagged by PHPCompatibility 10.0.

[GaryJones]

✅