[WIP] Extended Zend Framework Coding Standard

[michalbundyra]

Work in progress

Just want to know what you guys thinks about it.

Basically @weierophinney asked me to add just detection for unused imports. I went "a bit" more far with it and I've added much more rules. I found easy way how we can write custom rules and we don't need to copy them to Standards directory.

List what we have there now:

• Generic.Arrays.DisallowLongArraySyntax,
• Generic.Formatting.SpaceAfterCast (must be one space after cast: (bool) $var),
• Generic.Formatting.SpaceAfterNot,
• Generic.CodeAnalysis.EmptyStatement,
• Generic.CodeAnalysis.ForLoopShouldBeWhileLoop,
• Generic.CodeAnalysis.UnconditionalIfStatement,
• Generic.CodeAnalysis.UnnecessaryFinalModifier,
• Generic.NamingConventions.ConstructorName,
• Generic.PHP.ForbiddenFunctions,
• Generic.Files.OneTraitPerFile,
• Generic.Strings.UnnecessaryStringConcat,
• Squiz.Operators.ValidLogicalOperators,
• Squiz.PHP.LowercasePHPFunctions,
• Squiz.PHP.NonExecutableCode,
• Squiz.Scope.StaticThisUsage,
• Squiz.Strings.ConcatenationSpacing,
• Squiz.Strings.DoubleQuoteUsage,
• Squiz.WhiteSpace.LanguageConstructSpacing,
• Squiz.WhiteSpace.OperatorSpacing,
• Squiz.WhiteSpace.SemicolonSpacing,
• Squiz.WhiteSpace.SuperfluousWhitespace,
• ZendCodingStandard.Arrays.Format (no space after [ and before ], each element in new line for multi-line arrays, no empty lines, correct indents...),
• ZendCodingStandard.Arrays.TrailingArrayComma (requires comma after last element in multiline arrays),
• ZendCodingStandard.Classes.AlphabeticallySortedTraits,
• ZendCodingStandard.Classes.NoNullValues - remove null values for class properties,
• ZendCodingStandard.Classes.TraitUsage,
• ZendCodingStandard.Commenting.DocComment,
• ZendCodingStandard.Commenting.FunctionComment - order of tags and empty lines between tags,
• ZendCodingStandard.Commenting.FunctionDataProviderTag,
• ZendCodingStandard.Commenting.FunctionDisallowedTag - using some tags is disallowed, for example @expectedException* from PHPUnit annotations should be replaced with according function calls just before place, where the exception should be thrown,
• ZendCodingStandard.Commenting.NoInlineCommentAfterCurlyClose,
• ZendCodingStandard.Commenting.TagCase,
• ZendCodingStandard.Commenting.VariableComment,
• ZendCodingStandard.Formatting.DoubleColon - no spaces before and after,
• ZendCodingStandard.Formatting.NewKeyword - one space after,
• ZendCodingStandard.Formatting.NoSpaceAfterSplat - no space after ...,
• ZendCodingStandard.Formatting.Reference - no space after reference operator &$var,
• ZendCodingStandard.Formatting.ReturnType (formating of return type on PHP 7 and 7.1 with nullable types),
• ZendCodingStandard.Formatting.UnnecessaryParentheses (remove unnecessary parentheses where it does not misaligned the readability),
• ZendCodingStandard.Functions.Param - checks method params and tags - required PHPDocs tags only when type hint is not provided or type hint needs specification (array, iterable, \Traversable),
• ZendCodingStandard.Functions.ReturnType - checks method return statement and return type, tag is required only when return type is not declared or needs specification (array, iterable, \Traversable), if function returns void, return tag must be omitted,
• ZendCodingStandard.Functions.Throws - checks throws tags and throw statement in the function - throw tag must be declared for each exception thrown explicitly in the function,
• ZendCodingStandard.Methods.LineAfter (must be exactly one line after method in class, zero after last method in the class),
• ZendCodingStandard.Namespaces.AlphabeticallySortedUses,
• ZendCodingStandard.Namespaces.ConstAndFunctionKeywords - lower case keywords and single space after,
• ZendCodingStandard.Namespaces.UnusedUseStatement (detects unused use statements),
• ZendCodingStandard.Namespaces.UseDoesNotStartWithBackslash,
• ZendCodingStandard.NamingConventions.ValidVariableName (all variables should be camelCase style),
• ZendCodingStandard.Operators.BooleanOperator (boolean operators are not allowed at the end of the line),
• ZendCodingStandard.Operators.TernaryOperator (if multi-line, each part should be in new line starting from operator ? or :),
• ZendCodingStandard.PHP.CorrectClassNameCase (checks case for defined classes),
• ZendCodingStandard.PHP.ImportInternalConstant (import php built-in constants),
• ZendCodingStandard.PHP.ImportInternalFunction (import php built-in functions),
• ZendCodingStandard.PHP.InstantiatingParenthesis (PSR-12 - always parenthesis when instantiating a new class),
• ZendCodingStandard.PHP.LowerCaseKeyword (extends Generic.PHP.LowerCaseKeyword),
• ZendCodingStandard.PHP.RedundantSemicolon (unnecessary semicolons - for example after closing curly bracket of "if" statement),
• ZendCodingStandard.PHP.TypeCasting (disallow !! casting, require (bool) and (int) instead of (boolean) and (integer) accordingly, disallow (unset) cast, always lowercase),
• ZendCodingStandard.Strings.NoConcatenationAtTheEnd,
• ZendCodingStandard.WhiteSpace.BlankLine (only one blank line allowed between parts of the code),
• ZendCodingStandard.WhiteSpace.CommaSpacing (no space before comma, one after, allowed more than one in multidimensional arrays),
• ZendCodingStandard.WhiteSpace.NoBlankLineAtStart (disallow blank line(s) at start of class, closure, function, interface and trait),
• ZendCodingStandard.WhiteSpace.ScopeIndent (experimental, stricter rules of indents).

I would like to add also some more rules/sniffs:

• [x] trait sniff
  • [x] must be one use keyword per declaration - ZendCodingStandard.Classes.TraitUsage,
  • [x] exactly one blank line after traits and before methods in class - ZendCodingStandard.Classes.TraitUsage,
  • [x] alphabetical order - ZendCodingStandard.Classes.AlphabeticallySortedTraits,
  • [x] checking everything inside curly brackets,
• [x] global use statements sniffs
  • [x] alphabetical order - ZendCodingStandard.Namespaces.AlphabeticallySortedUses,
  • [x] unused uses - ZendCodingStandard.Namespaces.UnusedUseStatement,
  • [x] lower case const and function keywords - ZendCodingStandard.Namespaces.ConstAndFunctionKeywords,
  • [x] one space after const and function keywords - ZendCodingStandard.Namespaces.ConstAndFunctionKeywords,
  • [x] use does not start with backslash - ZendCodingStandard.Namespaces.UseDoesNotStartWithBackslash,
• [x] no empty line on top of the body class/method - ZendCodingStandard.WhiteSpace.NoBlankLineAtStart,
• [x] more than one blank line is not allowed - ZendCodingStandard.WhiteSpace.BlankLine,
• [x] correct camelCase names of internal PHP class (for example DateTime instead of Datetime) - ZendCodingStandard.PHP.CorrectClassNameCase,
• [x] concatenation character shouldn't be at the end of the line ZendCodingStandard.Strings.NoConcatenationAtTheEndSniff,
• [x] logical operator shouldn't be at the end of the line - ZendCodingStandard.Operators.BooleanOperator,
• [x] PHPDocs with @dataProvider:
  • [x] only allowed for test... methods,
  • [x] data provider name doesn't have "Provider" suffix,
  • [x] should be always above @param tags,
  • [x] should be one empty line after and before @dataProvider ...,
• [x] disallow or and and for logical operators (use || and && accordingly) - Squiz.Operators.ValidLogicalOperators,
• [x] disallow method names the same as their class (deprecated error in PHP 7.0: Methods with the same name as their class will not be constructors in a future version) - Generic.NamingConventions.ConstructorName,
• [x] arrays formatting - ZendCodingStandard.Arrays.Format:
  • [x] no white space after array opening bracket and before closing (disallow [ 1, 2, 3 ]),
  • [x] each element in new line for multi-line arrays
  • [x] correct indents,
  • [x] disallow empty lines in arrays,
• [x] no space after splat operator (...$var) - ZendCodingStandard.Formatting.NoSpaceAfterSplat,
• [x] no space before and after double colon operator (ClassName::class) - ZendCodingStandard.Formatting.DoubleColon,
• [x] only one space after new - ZendCodingStandard.Formatting.NewKeyword,
• [x] "When instantiating a new class, parenthesis MUST always be present even when there are no arguments passed to the constructor." (PSR-12),
• [x] unnecessary semicolons (for example after if curly closing bracket) - ZendCodingStandard.PHP.RedundantSemicolon,
• [x] no space after reference operator & - ZendCodingStandard.Formatting.Reference.

Of course would be nice to have also tests for all of our custom sniffs...

So as you can see it's quite long list. Can you think about anything else what will be worth to add?

Let me know what do you think. Thanks!

/cc @weierophinney @Koopzington @xtreamwayz

[mrVrAlex]

Allowed, but not required.

Exactly, I agree

Why you think what space between parentheses and colon makes more sense (even in RFC no spaces in examples))? Awaiting PSR12 & ZCS ;)

[Ocramius]

Why you think what space between parentheses and colon makes more sense (even in RFC no spaces in examples))?

Mostly for readability purposes. It's a heated topic, like most CS rules, but doctrine/coding-standard also enforces the ) : foo { style

[mrVrAlex]

Well, if such expert "mastodon" like Ocramius for space, then I am fully convinced. ))

[grizzm0]

You would never see a space before ":" while writing which makes it feels really "unnatural" to do so. Atleast for me. That's why my vote is for function(Foo $bar): Baz {}.

There's also no space before ":" in a switch case, before ":" in if (): (short syntax) nor before a scope resolution operator (::).

If you would describe the function in writing you would type The function Foo should return: Bar not The function Foo should return : Bar

[weierophinney]

You would never see a space before ":" while writing which makes it feels really "unnatural" to do so. Atleast for me. That's why my vote is for function(Foo $bar): Baz {}.

You do see it with ternary statements, however: $x ? $y : $z.

Personally, I find the whitespace surrounding it makes it harder to accidentally omit when adding your return type, leading to fewer mistakes.

Regardless of either of our own personal preferences, we will follow the guidelines of PSR-12 once it's finalized. (Interestingly, this is one of the very topics that forced it back into draft status, as quite a number of people prefer spaces surrounding the : when defining return types; the WG for the spec is debating that, and several other items, currently.)

[tux-rampage]

Is this still a thing since #5 (that seems to fulfill the same purpose) was merged?

[michalbundyra]

It's not. All work done here has been moved to https://github.com/webimpress/coding-standard