diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index 07da68c..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,184 +0,0 @@ -# Changelog - -## Not released -- Fix regression in line-length sniff -- Improvements and cleanup of various sniff and `PhpcsHelpers` -- Added tests for `PhpcsHelpers` -- Improvements and increased consistency in CS and doc blocks -- Improved line length calculation for inline HTML -- Added Psalm -- Added CI checks via GitHub workflows - -## 1.0.0-beta.7 -- Allow `iterable` as return type for generators -- Replace merge conflict sniff removed from upstream VIP cs -- Do not trigger warnings for long `use` statements - -## 1.0.0-beta.6 -- Add "js" to allowed 2-chars words for "ElementMinimalLength" sniff -- Improvements to closure doc-bloc recognition - -## 1.0.0-beta.5 -- Introduce "StaticClosure" sniff -- CS adjustments - -## 1.0.0-beta.4 -- Replace "NestingLevel" from Generics with custom sniff (to relax checks for try / catch) -- Improved documentation - -## 1.0.0-beta.3 -### Changed -- Extended list of allowed 2-chars words for "ElementMinimalLength" sniff -- README adjustments -- Increase configuration flexibility for "NoAccessors" sniff -- Improved documentation -- CS adjustments - -## 1.0.0-beta.2 -### Changed -- Move PHPCS requirement to 3.5.0+ - -## 1.0.0-beta.1 -### Added -- PHPCompatibility checks -- External VIP rules -- Possibility to filter execution of tests -### Changed -- Move to PSR-12 -- Move to WPCS v2 -- Move to PHPCS v3.3 -- Upgrade `dealerdirect/phpcodesniffer-composer-installer` to `^0.5` -- Extend type declaration exclusion for hooks static closures -- Simplify customization of `ElementNameMinimalLength` -- Allow blank line after method with single line declaration -- Ignore in return type declaration check all methods that start with `__` -- Remove `PHPCSAliases` class -- Remove configuration values in provided `ruleset.xml` -- Improved README and documentation - -## 0.13.4 -- Fix function with nullable type return and returning null (and nothing else) considered invalid. -- Replace abandoned wimg/php-compatibility with phpcompatibility/php-compatibility. - -## 0.13.3 -- Fixed false positive "missing argument type declaration" when param are passed by-reference. -- Make `ReturnTypeDeclarationSniff` compatible with PHPCS 3.3 - -## 0.13.2 -- Changed "squizlabs/php_codesniffer" in composer.json to "~3.2.3" - -## 0.13.1 -- Revert WordPress security rules names changed in `0.13.0` - -## 0.13.0 -- Whitelist PHP core methods for not having return or argument type declaration. -- Fix WordPress security rules names. - -## 0.12.0 -- Fix bug in `Psr4Sniff` when class has not namespace. -- Allow @wp-hook ignore of return type for private and protected methods. -- Only check public accessors (by default). -- Fix bug in checking return type. -- Allow filters callbacks to return `null` on purpose. - -## 0.11.0 -- Fix false positive in `ReturnTypeDeclarationSniff` with nullable types. -- Relax check for missing return type when `{aType}|null` doc bloc is present. -- Add `is` to the list of allowed short names. -- Added `FunctionBodyStartSniff` to deal with blank lines on top of functions body. -- Added `VariablesNameSniff`. -- Improved `PhpcsHelpers::variableIsProperty()`. -- Improved failure handling in FixturesTest. -- Use NeutronStandard by opting-in rules instead of opting-out. -- Properly handle Generators and return types. - -## 0.10.0 -- Renamed sniffs namespace (**breaking change**). - Sniff are now referenced via `Inpsyde.CodeQuality...` instead of `InpsydeCodingStandard.CodeQuality...` -- Add `Psr4Sniff` to check PSR-4 compliance of files that contain classes auto-loadable entities. -- Minor tweaks to sniff. -- Improved documentation for custom sniffs and their configuration. - -## 0.9.0 -- `ReturnTypeDeclarationSniff` do no warn for missing return type when a docbloc like: - `@return {aType}|null` exists for the function. - -## 0.8.0 -- Fix bug in `NoAccessorsSniff` and allow for a few method names related to PHP core interfaces. -- Exclude `ArrayAccess` methods from `ReturnTypeDeclarationSniff` and `ArgumentTypeDeclarationSniff`. -- Fix bug in `LineLengthSniff` which affected edge cases. -- Changed default `LineLengthSniff` max length to 100, excluding leading indent. -- Remove Variable Analysis, too much false positives - -## 0.7.2 -- Fix bug in `ReturnTypeDeclarationSniff` which caused wrong return type detection. - -## 0.7.1 -- Exclude `NeutronStandard.MagicMethods.RiskyMagicMethod` -- Add `.gitattributes` -- Update own styles in `phpcs` - -## 0.7.0 -- Removed `NeutronStandard.Conditions.DisallowConditionAssignWithoutConditional`. -- Removed `NeutronStandard.MagicMethods.DisallowMagicGet`. -- Removed `NeutronStandard.MagicMethods.DisallowMagicSet`. -- Made `NeutronStandard.Whitespace.DisallowMultipleNewlines.MultipleNewlines` a warning not error. -- Added custom `AssignmentInsideConditionSniff` sniff. -- Added custom `NoTopLevelDefineSniff` sniff. - -## 0.6.0 -- Missing return type waring from `ReturnTypeDeclarationSniff` skipped for hook callbacks. -- Fixed a bug in return counting in helper class that affected few sniffs. -- Add several "Generic" and "Squiz" rules. -- Add `DisallowShortOpenTagSniff` that extends the generic sniff allowing short echo. -- Remove `NeutronStandard.Constants.DisallowDefine` because of github.com/Automattic/phpcs-neutron-standard/issues/44 -- Renamed configuration properties for `FunctionLengthSniff`. -- Add integration tests for custom sniffs. -- Rename `NoASetterSniff` to `NoAccessorsSniff` and also warn for getters. - -## 0.5.1 -- `ArgumentTypeDeclarationSniff` also skip function and methods that declare `@wp-hook` doc param. - -## 0.5.0 -* Disabled `NeutronStandard.Functions.TypeHint` and replaced with custom sniffs -* Added `ArgumentTypeDeclarationSniff` to replace `NeutronStandard.Functions.TypeHint` sniff for - missing argument types. - It does not check closures used as hook callbacks (because WP cannot be trusted on types). -* Added `ReturnTypeDeclarationSniff` to replace `NeutronStandard.Functions.TypeHint` sniff for - missing or wrong return type. -* Added `HookClosureReturnSniff` to sniff closures added to filters and missing return values and - closures added to action and having return values. - -## 0.4.2 -* Fix a bug in `FunctionLengthSniff` which only excludes first doc block -* `FunctionLengthSniff` also excludes (by default) blank lines and single line comments -* Introduce `phpcs.xml` -* Small improvements to ruleset -* Use own styles - -## 0.4.1 -* `FunctionLengthSniff` now excludes doc blocks lines from counting -* New `LineLengthSniff` (that replaces "Generic" sniff included by "PSR2") and - ignores long lines coming from translation functions first argument - -## 0.4.0 -* Rename custom rules namespace from `CodingStandard` to `InpsydeCodingStandard` - -## 0.3.0 -* Usage of PSR 1/2 as base -* Test for PHP 7+ -* Introduction of [phpcs-variable-analysis](https://github.com/sirbrillig/phpcs-variable-analysis) -* Introduction of [Automattic NeutronStandard](https://github.com/Automattic/phpcs-neutron-standard) -* Only use few WordPress rules from [wpcs](https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards) -* Make package compatible with `phpcodesniffer-composer-installer` -* Add lot of info to README - -## 0.2.0 -* Removed `Generic.PHP.LowerCaseConstant`, because we're going to use PSR standards. -* Updated to newer version of `wp-coding-standards/wpcs`. -* Updated to newer version of `squizlabs/php_codesniffer`. -* Added support for PHP7+. -* Added new excludes which are too WordPressy. - -## 0.1.0 -* First release. diff --git a/README.md b/README.md index 7cede78..646d8c6 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ the coding standards can be checked via: vendor/bin/phpcs --standard="Inpsyde" ``` -Where `` is at least one file or directory to check, e.g.: +Here, `` is at least one file or directory to check, for example: ```shell vendor/bin/phpcs --standard="Inpsyde" ./src/ ./my-plugin.php @@ -30,7 +30,7 @@ vendor/bin/phpcs --help ## Configuration File -A `phpcs.xml.dist` can be used to avoid passing many arguments via command line. +A `phpcs.xml.dist` file can be used to avoid passing many arguments via the command line. For example: ```xml @@ -47,11 +47,11 @@ For example: - + - + - + ``` -Such a configuration allows to run the code style check with only: +Such a configuration allows to run the code style check like so: ```shell vendor/bin/phpcs ``` -Moreover, thanks to the `text_domain` setting, Code Sniffer will also check that all WP +Moreover, thanks to the `text_domain` setting, PHP_CodeSniffer will also check that all WordPress internationalization functions are called with the proper text domain. --- # Included rules -For the detailed lists of included rules refers to [`ruleset.xml](./Inpsyde/ruleset.xml). +For the detailed lists of included rules, refer to [`ruleset.xml`](./Inpsyde/ruleset.xml). ## PSR-1, PSR-2, PSR-12 -See https://www.php-fig.org/psr/psr-1, https://www.php-fig.org/psr/psr-2, -https://www.php-fig.org/psr/psr-12 +For more information about included rules from PHP Standards Recommendations (PSR), refer to the +official documentation: + +- [PSR-1](https://www.php-fig.org/psr/psr-1) +- [PSR-2](https://www.php-fig.org/psr/psr-2) +- [PSR-12](https://www.php-fig.org/psr/psr-12) -## WordPress Coding Standard +## WordPress Coding Standards -To ensure code quality, and compatibility with wp.com VIP, several WordPress Coding Standard rules -have been"cherry-picked" from -[WP coding standards](https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards) and -[VIP coding standard](https://github.com/Automattic/VIP-Coding-Standards/) +To ensure code quality, and compatibility with WordPress VIP, some rules have been included from: + +- [WordPress Coding Standards](https://github.com/WordPress/WordPress-Coding-Standards) +- [VIP Coding Standards](https://github.com/Automattic/VIP-Coding-Standards) ## Slevomat -A few rules are cherry-picked from ["Slevomat" coding standard](https://github.com/slevomat/coding-standard). +A few rules have been included from the [Slevomat Coding Standard](https://github.com/slevomat/coding-standard). ## PHPCompatibility -See https://github.com/wimg/PHPCompatibility. - -It allows to analyse code for compatibility with higher and lower versions of PHP. -The default target version is PHP 7.0+. +For PHP cross-version compatibility checks, the full [PHP Compatibility Coding Standard for PHP CodeSniffer](https://github.com/PHPCompatibility/PHPCompatibility) +standard has been included. -Target version can be changed via custom `phpcs.xml`. +The target PHP version (range) can be changed via a [custom `phpcs.xml` file](https://github.com/PHPCompatibility/PHPCompatibility/blob/9.3.5/README.md#using-a-custom-ruleset). ## Generic Rules -Some rules are also included from PHPCS itself and [PHPCS Extra](https://github.com/PHPCSStandards/PHPCSExtra). +Some rules are also included from PHP_CodeSniffer itself, as well as [PHPCSExtra](https://github.com/PHPCSStandards/PHPCSExtra). ## Custom Rules -Some custom rules are also in use. They are: +The following custom rules are in use: -| Sniff name | Description | Has Config | Auto-Fixable | +| Sniff Name | Description | Has Config | Auto-Fixable | |:---------------------------|:-----------------------------------------------------------------------------------------------|:----------:|:------------:| | `ArgumentTypeDeclaration` | Enforce argument type declaration. | | | | `DisableCallUserFunc` | Disable usage of `call_user_func`. | | | @@ -140,7 +142,8 @@ Some custom rules are also in use. They are: | `StaticClosure` | Points closures that can be `static`. | | ✓ | | `VariablesName` | Check variable (and properties) names | ✓ | | -For **notes and configuration** see [`/inpsyde-custom-sniffs.md`](/inpsyde-custom-sniffs.md) file in this repo. +For **notes and configuration**, refer to the [`inpsyde-custom-sniffs.md`](/inpsyde-custom-sniffs.md) +file in this repository. --- @@ -153,12 +156,12 @@ The recommended way to use the `InpsydeTemplates` ruleset is as follows: ```xml - ./src/ - ./tests + ./src ./templates + ./tests ./views - + */templates/* @@ -167,9 +170,9 @@ The recommended way to use the `InpsydeTemplates` ruleset is as follows: ``` -The following templates-specific rules are available: +The following template-specific rules are available: -| Sniff name | Description | Has Config | Auto-Fixable | +| Sniff Name | Description | Has Config | Auto-Fixable | |:--------------------|:--------------------------------------------------|:----------:|:------------:| | `TrailingSemicolon` | Remove trailing semicolon before closing PHP tag. | | ✓ | @@ -177,127 +180,104 @@ The following templates-specific rules are available: ## Rules Tree -Sometimes it is necessary to don't follow some rules. To avoid error reporting it is possible to: +Sometimes it is necessary not to follow some rules. To avoid error reporting, it is possible to: -- Removing rules for an entire project via configuration -- Disabling rules from code, only is specific places +- remove rules for an entire project via configuration; +- disable rules from code, only is specific places. -In both cases it is possible to remove or disable: +In both cases, it is possible to remove or disable: -- a whole standard -- a standard subset -- a single sniff -- a single rules +- a complete standard; +- a standard subset; +- a single sniff; +- a single rule. -The for things above are in hierarchical relationship: a _standard_ is made of one or more _subset_, -each subset contains one or more _sniff_ and each sniff contains one or more rule. +These things are in a hierarchical relationship: _standards_ are made of one or more _subsets_, +which contain one or more _sniffs_, which in turn contain one or more _rules_. -## Remove rules via configuration file +## Removing Rules via Configuration File -Rules can be removed for the entire project by using a custom `phpcs.xml`, with a syntax like this: +Rules can be removed for the entire project by using a custom `phpcs.xml` file, like this: ```xml - - - + + + ``` -In the example above, the _sniff_ `PSR1.Classes.ClassDeclaration` (and all the rules it contains) +In the example above, the `PSR1.Classes.ClassDeclaration` sniff (and all the rules it contains) has been removed. -Replacing `PSR1.Classes.ClassDeclaration` with just `PSR1` had been possible to -remove the whole standard, while replacing it with `PSR1.Classes.ClassDeclaration.MultipleClasses` -only the single rule is removed. - -## Remove rules via code comments - -If it is necessary to remove a rule/sniff/standard subset/standard only in specific place in the -code, it is possible to use special comments that starts with `// phpcs:disable` followed by the -name of the sniff to disable. - -For example: `// phpcs:disable PSR1.Classes.ClassDeclaration`. +By using `PSR1` instead of `PSR1.Classes.ClassDeclaration`, one would remove the entire `PSR1` +standard, whereas using `PSR1.Classes.ClassDeclaration.MultipleClasses` would remove this one rule +only, but no other rules in the `PSR1.Classes.ClassDeclaration` sniff. -From the point the comment is encountered to the end of the file, the requested rule/sniff/standard -subset/standard is not checked anymore. +## Removing Rules via Code Comments -To re-enable it is necessary to use a similar syntax, but this time using `phpcs:enable` instead of -`phpcs:disable`. +Removing a rule/sniff/subset/standard only for a specific file or a part of it can be done by using +special `phpcs` annotations/comments, for example, `// phpcs:disable` followed by an optional name +of a standard/subset/sniff/rule. Like so: -It is worth noting: - -- `phpcs:disable` and `phpcs:enable` can be used without specifying the rule name, in this case the - check for *all* rules are disabled/enabled. -- Disabling / enabling comments could be embedded in doc block comments at file/class/method level. - For example: - ```php -class Foo -{ - /** - * @param mixed $a - * @param mixed $b - * - * phpcs:disable NeutronStandard.Functions.TypeHint.NoArgumentType - */ - public function test($a, $b) - { - // phpcs:enable - } -} +// phpcs:disable PSR1.Classes.ClassDeclaration ``` +For more information about ignoring files, please refer to the official [PHP_CodeSniffer Wiki](https://github.com/PHPCSStandards/PHP_CodeSniffer/wiki/Advanced-Usage#ignoring-parts-of-a-file). + --- -# IDE integration +# IDE Integration ## PhpStorm -After having installed the package as explained above in the _"Installation"_ section, -open PhpStorm settings, and navigate to +After installing the package as explained above, open PhpStorm settings, and navigate to `Language & Frameworks` -> `PHP` -> `Quality Tools` -> `PHP_CodeSniffer` Choose _"Local"_ in the _"Configuration"_ dropdown. -Click the _"..."_ button next to the dropdown, it will show a dialog -where you need to specify the path for the Code Sniffer executable. +Click the _"..."_ button next to the dropdown. It will show a dialog where you need to specify +the path for the PHP_CodeSniffer executable. -Open the file selection dialog, navigate to `vendor/bin/` in your project and select `phpcs` -(`phpcs.bat` on Windows). +Open the file selection dialog, navigate to `vendor/bin/` in your project, and select `phpcs`. +On Windows, choose `phpcs.bat`. -Click the _"Validate"_ button next to the path input field, if everything is fine -a success message will be shown at the bottom of the window. +Click the _"Validate"_ button next to the path input field. If everything is working fine, a +success message will be shown at the bottom of the window. -Navigate PhpStorm settings to: +Still in the PhpStorm settings, navigate to: `Editor` -> `Inspections` -Type `codesniffer` in the search field before the list of inspections, -select `PHP` -> `Quality Tools` -> `PHP_CodeSniffer validation` and enable it using the checkbox in -the list, press _"Apply"_. +Type `codesniffer` in the search field before the list of inspections, then select: + +`PHP` -> `Quality Tools` -> `PHP_CodeSniffer validation` + +Enable it using the checkbox in the list, press _"Apply"_. -Select _"PHP_CodeSniffer validation"_, press the refresh icon next to the _"Coding standard"_ -dropdown on the right and choose `Inpsyde`. +Select _"PHP_CodeSniffer validation"_, click the refresh icon next to the _"Coding standard"_ +dropdown on the right, and choose `Inpsyde`. -If you do not see `Inpsyde` here, you may need to specify `phpcs.xml` file by selecting _"Custom"_ -as standard and using the _"..."_ button next to the dropdown. +If you don't see `Inpsyde` here, you may need to specify the `phpcs.xml` file by selecting +_"Custom"_ as standard and then use the _"..."_ button next to the dropdown. -Now PhpStorm integration is complete, and errors in the code style will be shown in the IDE editor -allowing to detect them without running any commands at all. +Once the PhpStorm integration is complete, warnings and errors in your code will automatically be +shown in your IDE editor. --- # Installation -Via Composer, require as dev-dependency: +Via Composer, require as development dependency: ```shell composer require "inpsyde/php-coding-standards:^2@dev" --dev ``` -_(the `@dev` can be removed as soon as the stable 2.0.0 will be released, or if root package minimum stability is "dev")._ +_(Please note that `@dev` can be removed as soon as a stable 2.0.0 version has been released, or if +your root package minimum stability is `dev`)._ diff --git a/composer.json b/composer.json index 0c9dd94..a3b00fa 100644 --- a/composer.json +++ b/composer.json @@ -1,6 +1,6 @@ { "name": "inpsyde/php-coding-standards", - "description": "PHP 7+ coding standards for Inpsyde WordPress projects.", + "description": "PHP 7.4+ coding standards for Syde WordPress projects.", "type": "phpcodesniffer-standard", "keywords": [ "phpcs", @@ -16,14 +16,15 @@ "PHP standards", "WordPress", "WordPress standards", - "Inpsyde" + "Inpsyde", + "Syde" ], "license": "MIT", "authors": [ { - "name": "Inpsyde GmbH", - "email": "hello@inpsyde.com", - "homepage": "https://inpsyde.com", + "name": "Syde GmbH", + "email": "hello@syde.com", + "homepage": "https://syde.com", "role": "Company" } ], diff --git a/phpcs.xml b/phpcs.xml index 24d74b0..37c2693 100644 --- a/phpcs.xml +++ b/phpcs.xml @@ -4,6 +4,7 @@ PHP 7.4+ coding standards for Syde WordPress projects. Inpsyde + InpsydeTemplates ./tests/src ./tests/unit/cases ./tests/e2e/cases @@ -29,6 +30,7 @@ ./Inpsyde/Sniffs/ + ./InpsydeTemplates/Sniffs/ diff --git a/phpunit.xml.dist b/phpunit.xml.dist index 2e160a3..a3fb553 100644 --- a/phpunit.xml.dist +++ b/phpunit.xml.dist @@ -7,6 +7,7 @@ ./Inpsyde + ./InpsydeTemplates diff --git a/psalm.xml b/psalm.xml index f296c48..d6771a0 100644 --- a/psalm.xml +++ b/psalm.xml @@ -17,6 +17,7 @@ > +