Skip to content

3.2.0

Compare
Choose a tag to compare
@gsherwood gsherwood released this 12 Dec 22:06
· 2452 commits to master since this release
3.2.0
ba816f2

Comment Syntax Changes

This release deprecates the @codingStandards comment syntax used for sending commands to PHP_CodeSniffer. The existing syntax will continue to work in all version 3 releases, but will be removed in version 4

The comment formats have been replaced by a shorter syntax:

  • @codingStandardsIgnoreFile becomes phpcs:ignoreFile
  • @codingStandardsIgnoreStart becomes phpcs:disable
  • @codingStandardsIgnoreEnd becomes phpcs:enable
  • @codingStandardsIgnoreLine becomes phpcs:ignore
  • @codingStandardsChangeSetting becomes phpcs:set

The new syntax allows for additional developer comments to be added after a -- separator. This is useful for describing why a code block is being ignored, or why a setting is being changed. E.g., // phpcs:disable -- This code block must be left as-is.

Comments using the new syntax are assigned new comment token types to allow them to be detected:

  • phpcs:ignoreFile has the token T_PHPCS_IGNORE_FILE
  • phpcs:disable has the token T_PHPCS_DISABLE
  • phpcs:enable has the token T_PHPCS_ENABLE
  • phpcs:ignore has the token T_PHPCS_IGNORE
  • phpcs:set has the token T_PHPCS_SET

Other Changes

  • The phpcs:disable and phpcs:ignore comments can now selectively ignore specific sniffs (request #604)
    • E.g., // phpcs:disable Generic.Commenting.Todo.Found for a specific message
    • E.g., // phpcs:disable Generic.Commenting.Todo for a whole sniff
    • E.g., // phpcs:disable Generic.Commenting for a whole category of sniffs
    • E.g., // phpcs:disable Generic for a whole standard
    • Multiple sniff codes can be specified by comma separating them
      • E.g., // phpcs:disable Generic.Commenting.Todo,PSR1.Files
  • @codingStandardsIgnoreLine comments now only ignore the following line if they are on a line by themselves
    • If they are at the end of an existing line, they will only ignore the line they are on
    • Stops some lines from accidentally being ignored
    • Same rule applies for the new phpcs:ignore comment syntax
  • PSR1.Files.SideEffects now respects the new phpcs:disable comment syntax
    • The sniff will no longer check any code that is between phpcs:disable and phpcs:enable comments
    • The sniff does not support phpcs:ignore; you must wrap code structures with disable/enable comments
    • Previously, there was no way to have this sniff ignore parts of a file
  • Fixed a problem where PHPCS would sometimes hang waiting for STDIN, or read incomplete versions of large files
    • Thanks to Arne Jørgensen for the patch
  • Array properties specified in ruleset files now have their keys and values trimmed
    • This saves having to do this in individual sniffs and stops errors introduced by whitespace in rulesets
    • Thanks to Juliette Reinders Folmer for the patch
  • Added phpcs.xsd to allow validation of ruleset XML files
    • Thanks to Renaat De Muynck for the contribution
  • File paths specified using --stdin-path can now point to fake file locations (request #1488)
    • Previously, STDIN files using fake file paths were excluded from checking
  • Setting an empty basepath (--basepath=) on the CLI will now clear a basepath set directly in a ruleset
    • Thanks to Xaver Loppenstedt for the patch
  • Ignore patterns are now checked on symlink target paths instead of symlink source paths
    • Restores previous behaviour of this feature
  • Metrics were being double counted when multiple sniffs were recording the same metric
  • Added support for bash process substitution
    • Thanks to Scott Dutton for the contribution
  • Files included in the cache file code hash are now sorted to aid in cache file reuse across servers
  • Windows BAT files can now be used outside a PEAR install
    • You must have the path to PHP set in your PATH environment variable
    • Thanks to Joris Debonnet for the patch
  • The JS unsigned right shift assignment operator is now properly classified as an assignment operator
    • Thanks to Juliette Reinders Folmer for the patch
  • The AbstractVariableSniff abstract sniff now supports anonymous classes and nested functions
    • Also fixes an issue with Squiz.Scope.MemberVarScope where member vars of anonymous classes were not being checked
  • Added AbstractArraySniff to make it easier to create sniffs that check array formatting
    • Allows for checking of single and multi line arrays easily
    • Provides a parsed structure of the array including positions of keys, values, and double arrows
  • Added Generic.Arrays.ArrayIndent to enforce a single tab stop indent for array keys in multi-line arrays
    • Also ensures the close brace is on a new line and indented to the same level as the original statement
    • Allows for the indent size to be set using an indent property of the sniff
  • Added Generic.PHP.DiscourageGoto to warn about the use of the GOTO language construct
    • Thanks to Juliette Reinders Folmer for the contribution
  • Generic.Debug.ClosureLinter was not running the gjslint command
    • Thanks to Michał Bundyra for the patch
  • Generic.WhiteSpace.DisallowSpaceIndent now fixes space indents in multi-line block comments
    • Thanks to Juliette Reinders Folmer for the patch
  • Generic.WhiteSpace.DisallowSpaceIndent now fixes mixed space/tab indents more accurately
    • Thanks to Juliette Reinders Folmer for the patch
  • Generic.WhiteSpace.DisallowTabIndent now fixes tab indents in multi-line block comments
    • Thanks to Juliette Reinders Folmer for the patch
  • PEAR.Functions.FunctionDeclaration no longer errors when a function declaration is the first content in a JS file
    • Thanks to Juliette Reinders Folmer for the patch
  • PEAR.Functions.FunctionCallSignature now requires the function name to be indented to an exact tab stop
    • If the function name is not the start of the statement, the opening statement must be indented correctly instead
    • Added a new fixable error code PEAR.Functions.FunctionCallSignature.OpeningIndent for this error
  • Squiz.Functions.FunctionDeclarationArgumentSpacing is no longer confused about comments in function declarations
    • Thanks to Juliette Reinders Folmer for the patch
  • Squiz.PHP.NonExecutableCode error messages now indicate which line the code block ending is on
    • Makes it easier to identify where the code block exited or returned
    • Thanks to Juliette Reinders Folmer for the patch
  • Squiz.Commenting.FunctionComment now supports nullable type hints
  • Squiz.Commenting.FunctionCommentThrowTag no longer assigns throw tags inside anon classes to the enclosing function
  • Squiz.WhiteSpace.SemicolonSpacing now ignores semicolons used for empty statements inside FOR conditions
    • Thanks to Juliette Reinders Folmer for the patch
  • Squiz.ControlStructures.ControlSignature now allows configuring the number of spaces before the colon in alternative syntax
    • Override the requiredSpacesBeforeColon setting in a ruleset.xml file to change
    • Default remains at 1
    • Thanks to Nikola Kovacs for the patch
  • The Squiz standard now ensures array keys are indented 4 spaces from the main statement
    • Previously, this standard aligned keys 1 space from the start of the array keyword
  • The Squiz standard now ensures array end braces are aligned with the main statement
    • Previously, this standard aligned the close brace with the start of the array keyword
  • The standard for PHP_CodeSniffer itself now enforces short array syntax
  • The standard for PHP_CodeSniffer itself now uses the Generic.Arrays/ArrayIndent sniff rules
  • Improved fixer conflicts and syntax error handling for a number of sniffs
    • Thanks to Juliette Reinders Folmer for the patch
  • Fixed bug #1462 : Error processing cyrillic strings in Tokenizer
  • Fixed bug #1573 : Squiz.WhiteSpace.LanguageConstructSpacing does not properly check for tabs and newlines
    • Thanks to Michał Bundyra for the patch
  • Fixed bug #1590 : InlineControlStructure CBF issue while adding braces to an if thats returning a nested function
  • Fixed bug #1718 : Unclosed strings at EOF sometimes tokenized as T_WHITESPACE by the JS tokenizer
  • Fixed bug #1731 : Directory exclusions do not work as expected when a single file name is passed to phpcs
  • Fixed bug #1737 : Squiz.CSS.EmptyStyleDefinition sees comment as style definition and fails to report error
  • Fixed bug #1746 : Very large reports can sometimes become garbled when using the parallel option
  • Fixed bug #1747 : Squiz.Scope.StaticThisUsage incorrectly looking inside closures
  • Fixed bug #1757 : Unknown type hint "object" in Squiz.Commenting.FunctionComment
  • Fixed bug #1758 : PHPCS gets stuck creating file list when processing circular symlinks
  • Fixed bug #1761 : Generic.WhiteSpace.ScopeIndent error on multi-line function call with static closure argument
  • Fixed bug #1762 : Generic.WhiteSpace.Disallow[Space/Tab]Indent not inspecting content before open tag
    • Thanks to Juliette Reinders Folmer for the patch
  • Fixed bug #1769 : Custom "define" function triggers a warning about declaring new symbols
  • Fixed bug #1776 : Squiz.Scope.StaticThisUsage incorrectly looking inside anon classes
  • Fixed bug #1777 : Generic.WhiteSpace.ScopeIndent incorrect indent errors when self called function proceeded by comme