From 26ec573ea58029204aafa913d27d4495c3687482 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ond=C5=99ej=20Machulda?= Date: Mon, 13 May 2024 17:11:42 +0200 Subject: [PATCH 1/3] Feat: Remove the most risky fixers from the next version (will be readded in the next release) --- ecs.php | 32 ------------------- .../Fixtures/NewPhpFeatures.correct.php.inc | 5 ++- .../Fixtures/NewPhpFeatures.wrong.php.inc | 2 +- 3 files changed, 5 insertions(+), 34 deletions(-) diff --git a/ecs.php b/ecs.php index a9e3236..5d49511 100644 --- a/ecs.php +++ b/ecs.php @@ -69,9 +69,6 @@ use PhpCsFixer\Fixer\FunctionNotation\LambdaNotUsedImportFixer; use PhpCsFixer\Fixer\FunctionNotation\NoUnreachableDefaultArgumentValueFixer; use PhpCsFixer\Fixer\FunctionNotation\NoUselessSprintfFixer; -use PhpCsFixer\Fixer\FunctionNotation\PhpdocToParamTypeFixer; -use PhpCsFixer\Fixer\FunctionNotation\PhpdocToPropertyTypeFixer; -use PhpCsFixer\Fixer\FunctionNotation\PhpdocToReturnTypeFixer; use PhpCsFixer\Fixer\FunctionNotation\ReturnTypeDeclarationFixer; use PhpCsFixer\Fixer\FunctionNotation\VoidReturnFixer; use PhpCsFixer\Fixer\Import\NoLeadingImportSlashFixer; @@ -133,14 +130,10 @@ use PhpCsFixer\Fixer\Whitespace\NoExtraBlankLinesFixer; use PhpCsFixer\Fixer\Whitespace\NoWhitespaceInBlankLineFixer; use PhpCsFixer\Fixer\Whitespace\TypeDeclarationSpacesFixer; -use SlevomatCodingStandard\Sniffs\Classes\RequireConstructorPropertyPromotionSniff; use SlevomatCodingStandard\Sniffs\ControlStructures\RequireNullSafeObjectOperatorSniff; use SlevomatCodingStandard\Sniffs\Exceptions\ReferenceThrowableOnlySniff; use SlevomatCodingStandard\Sniffs\Functions\RequireTrailingCommaInCallSniff; use SlevomatCodingStandard\Sniffs\Functions\RequireTrailingCommaInDeclarationSniff; -use SlevomatCodingStandard\Sniffs\TypeHints\ParameterTypeHintSniff; -use SlevomatCodingStandard\Sniffs\TypeHints\PropertyTypeHintSniff; -use SlevomatCodingStandard\Sniffs\TypeHints\ReturnTypeHintSniff; use SlevomatCodingStandard\Sniffs\TypeHints\UnionTypeHintFormatSniff; use Symplify\CodingStandard\Fixer\Commenting\ParamReturnAndVarTagMalformsFixer; use Symplify\EasyCodingStandard\Config\ECSConfig; @@ -377,15 +370,6 @@ ReferenceThrowableOnlySniff::class, // The @param, @return, @var and inline @var annotations should keep standard format ParamReturnAndVarTagMalformsFixer::class, - // Takes `@var` annotation of non-mixed types and adjusts accordingly the property signature. - PhpdocToPropertyTypeFixer::class, - // Takes `@param` annotations of non-mixed types and adjusts accordingly the function signature. - PhpdocToParamTypeFixer::class, - // Takes `@return` annotation of non-mixed types and adjusts accordingly the function signature. - PhpdocToReturnTypeFixer::class, - // Promote constructor properties - // @see https://github.com/FriendsOfPHP/PHP-CS-Fixer/issues/5956 - RequireConstructorPropertyPromotionSniff::class, // switch -> match // @see https://github.com/FriendsOfPHP/PHP-CS-Fixer/issues/5894 @@ -393,10 +377,6 @@ // Require \Stringable interface in classes implementing __toString() method // > it may probably be a phpstan rule, more than cs rule - since it needs a class hierarchy to solve this // @see https://github.com/FriendsOfPHP/PHP-CS-Fixer/issues/6235 - PropertyTypeHintSniff::class, - - ParameterTypeHintSniff::class, - ReturnTypeHintSniff::class, // Multi-line arguments list in function/method declaration must have a trailing comma RequireTrailingCommaInDeclarationSniff::class, @@ -531,18 +511,6 @@ // Allow single line closures ScopeClosingBraceSniff::class . '.ContentBefore' => null, - // Skip unwanted rules from PropertyTypeHintSniff - PropertyTypeHintSniff::class . '.' . PropertyTypeHintSniff::CODE_MISSING_TRAVERSABLE_TYPE_HINT_SPECIFICATION => null, - PropertyTypeHintSniff::class . '.' . PropertyTypeHintSniff::CODE_MISSING_ANY_TYPE_HINT => null, - - // Skip unwanted rules from ParameterTypeHintSniff - ParameterTypeHintSniff::class . '.' . ParameterTypeHintSniff::CODE_MISSING_TRAVERSABLE_TYPE_HINT_SPECIFICATION => null, - ParameterTypeHintSniff::class . '.' . ParameterTypeHintSniff::CODE_MISSING_ANY_TYPE_HINT => null, - - // Skip unwanted rules from ReturnTypeHintSniff - ReturnTypeHintSniff::class . '.' . ReturnTypeHintSniff::CODE_MISSING_TRAVERSABLE_TYPE_HINT_SPECIFICATION => null, - ReturnTypeHintSniff::class . '.' . ReturnTypeHintSniff::CODE_MISSING_ANY_TYPE_HINT => null, - // We use declare(strict_types=1); after opening tag BlankLineAfterOpeningTagFixer::class => null, ]); diff --git a/tests/Integration/Fixtures/NewPhpFeatures.correct.php.inc b/tests/Integration/Fixtures/NewPhpFeatures.correct.php.inc index c6e2726..f2962dd 100644 --- a/tests/Integration/Fixtures/NewPhpFeatures.correct.php.inc +++ b/tests/Integration/Fixtures/NewPhpFeatures.correct.php.inc @@ -4,8 +4,11 @@ namespace Lmc\CodingStandard\Integration\Fixtures; class NewPhpFeatures { - public function __construct(private string $someString) // RequireConstructorPropertyPromotionSniff + private string $someString; + + public function __construct(string $someString) { + $this->someString = $someString; } public function php80features( diff --git a/tests/Integration/Fixtures/NewPhpFeatures.wrong.php.inc b/tests/Integration/Fixtures/NewPhpFeatures.wrong.php.inc index 49d1d08..3435f7e 100644 --- a/tests/Integration/Fixtures/NewPhpFeatures.wrong.php.inc +++ b/tests/Integration/Fixtures/NewPhpFeatures.wrong.php.inc @@ -6,7 +6,7 @@ class NewPhpFeatures { private string $someString; - public function __construct(string $someString) // RequireConstructorPropertyPromotionSniff + public function __construct(string $someString) { $this->someString = $someString; } From b2e17f75fe5d2e04f2f82fdb3993e2be50175f8a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ond=C5=99ej=20Machulda?= Date: Tue, 14 May 2024 10:46:02 +0200 Subject: [PATCH 2/3] Docs: Warn about thoughtless approving of risky changes --- UPGRADE-4.0.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/UPGRADE-4.0.md b/UPGRADE-4.0.md index 48b1a87..82dec8f 100644 --- a/UPGRADE-4.0.md +++ b/UPGRADE-4.0.md @@ -85,7 +85,20 @@ $ vendor/bin/ecs check --ansi src/ tests/ # old $ vendor/bin/ecs check --ansi # new ``` -### 5. Sanity check +### 5. BE CAREFUL WITH SUGGESTED CHANGES! ⚠️ + +Some of the new default fixers introduced in php-coding-standard 4.0 and 4.1 suggest changes, which - if not +thoughtfully reviewed - can change the code behavior. Especially changes introduced by (but not limited to!): + +- PhpdocToPropertyTypeFixer + PropertyTypeHintSniff +- PhpdocToParamTypeFixer + ParameterTypeHintSniff +- PhpdocToReturnTypeFixer + ReturnTypeHintSniff + +**Always carefully review the changes suggested by all fixers!** You may want to skip some of the checks +(using `withSkip()`) in the first phase of upgrading to the new version of the coding standard +or you can introduce some of the rules gradually or on a file-by-file basis. + +### 6. Sanity check Besides running your code style checks, you can ensure all predefined checks are loaded as well, by running: ```sh From 93f588d08b7a6bca3723759f3f4816641089fdbe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ond=C5=99ej=20Machulda?= Date: Tue, 14 May 2024 11:05:46 +0200 Subject: [PATCH 3/3] Docs: Make grammar and structure improvements in readme and upgrade guide --- README.md | 27 ++++++++++++++++----------- UPGRADE-4.0.md | 10 +++++----- 2 files changed, 21 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 5b57997..62e17be 100644 --- a/README.md +++ b/README.md @@ -2,12 +2,12 @@ [![Latest Stable Version](https://img.shields.io/packagist/v/lmc/coding-standard.svg?style=flat-square)](https://packagist.org/packages/lmc/coding-standard) -PHP coding standard used in [Alma Career Czechia](https://www.almacareer.com/) (formerly LMC) products. +PHP coding standard used in [Alma Career Czechia][Alma Career] (formerly LMC) products. -Standard is based on [PSR-12](https://www.php-fig.org/psr/psr-12/) and adds +The standard is based on [PSR-12][psr-12] and partially [PER 2.0][per-2] and adds various checks to make sure the code is readable, follows the same conventions, and does not contain common mistakes. -We use [EasyCodingStandard] to define and execute checks created for both [PHP-CS-Fixer] and [PHP_CodeSniffer]. +We use [EasyCodingStandard][ecs] to define and execute checks created for both [PHP-CS-Fixer] and [PHP_CodeSniffer]. ## Installation @@ -59,7 +59,7 @@ Now you will be able to run the fix using `composer analyze` and execute automat ### Add custom checks or override default settings -On top of default code-style rules you are free to add any rules from [PHP-CS-Fixer] or [PHP_CodeSniffer]. +On top of the default code-style rules, you are free to add any rules from [PHP-CS-Fixer] or [PHP_CodeSniffer]. If needed, you can also override some default settings. ```php @@ -83,12 +83,12 @@ return ECSConfig::configure() /* (...) */ ``` -See [EasyCodingStandard docs](https://github.com/symplify/easy-coding-standard#configuration) for more configuration options. +See [EasyCodingStandard docs][ecs-docs] for more configuration options. ### Exclude (skip) checks or files -You can configure your `ecs.php` to entirely skip some files, disable specific checks or suppress specific errors. +You can configure your `ecs.php` file to entirely skip some files, disable specific checks, or suppress specific errors. ```php