Merge pull request #87 from lmc-eu/feature/readme-update

Extend upgrade guidance and readme

Author: OndraM

README.md

@@ -25,18 +25,19 @@ composer require --dev lmc/coding-standard
 use Symplify\EasyCodingStandard\Config\ECSConfig;
 
 return ECSConfig::configure()
+    ->withPaths([__DIR__ . '/src', __DIR__ . '/tests']) // optionally add 'config' or other directories with PHP files
+    ->withRootFiles() // to include ecs.php and all other php files in the root directory
     ->withSets(
         [
             __DIR__ . '/vendor/lmc/coding-standard/ecs.php',
         ]
     );
 
     // Be default only checks compatible with PHP 8.0 are enabled.
-    // Depending on the lowest PHP version your project need to support, you can enable additional checks for
-    // PHP 8.1, 8.2 and 8.3.
+    // Depending on the lowest PHP version your project needs to support, you can enable additional checks.
 
-
-    // Import one of ecs-8.1.php, ecs-8.2.php or ecs-8.3.php. Use only one file (for the highest possible PHP version).
+    // Import one of ecs-8.1.php, ecs-8.2.php or ecs-8.3.php. Use only one additional file (for the highest possible
+    // PHP version), the configs for previous versions are automatically included.
     //->withSets(
     //    [
     //        __DIR__ . '/vendor/lmc/coding-standard/ecs.php',
@@ -45,23 +46,23 @@ return ECSConfig::configure()
     //);
 ```
 
-2. Run the check command (for `src/` and `tests/` directories):
+2. Run the check command
 
 ```bash
-vendor/bin/ecs check src/ tests/
+vendor/bin/ecs check
 ```
 
 3. Optionally we recommend adding this to `scripts` section of your `composer.json`:
 
 ```json
     "scripts": {
         "analyze": [
-            "vendor/bin/ecs check src/ tests/ --ansi",
+            "vendor/bin/ecs check --ansi",
             "[... other scripts, like PHPStan etc.]"
         ],
         "fix": [
             "...",
-            "vendor/bin/ecs check ./src/ ./tests/ --ansi --fix"
+            "vendor/bin/ecs check --ansi --fix"
         ],
     }
 ```
@@ -83,6 +84,7 @@ use PhpCsFixer\Fixer\PhpUnit\PhpUnitTestAnnotationFixer;
 use Symplify\EasyCodingStandard\Config\ECSConfig;
 
 return ECSConfig::configure()
+    /* (...) */
     ->withSets(
         [
             __DIR__ . '/vendor/lmc/coding-standard/ecs.php',
@@ -92,6 +94,7 @@ return ECSConfig::configure()
     ->withConfiguredRule(LineLengthSniff::class, ['absoluteLineLimit' => 120])
     // Tests must have @test annotation
     ->withConfiguredRule(PhpUnitTestAnnotationFixer::class, ['style' => 'annotation']);
+    /* (...) */
 ```
 
 See [EasyCodingStandard docs](https://github.com/symplify/easy-coding-standard#configuration) for more configuration options.
@@ -111,6 +114,7 @@ use PHP_CodeSniffer\Standards\Squiz\Sniffs\Arrays\ArrayDeclarationSniff;
 use Symplify\EasyCodingStandard\Config\ECSConfig;
 
 return ECSConfig::configure()
+    /* (...) */
     ->withSkip([
         // Ignore specific check only in specific files
         ForbiddenFunctionsSniff::class => [__DIR__ . '/src-tests/bootstrap.php'],
@@ -126,6 +130,7 @@ return ECSConfig::configure()
             __DIR__ . '/vendor/lmc/coding-standard/ecs.php',
         ]
     );
+    /* (...) */
 ```
 
 See [EasyCodingStandard docs](https://github.com/symplify/easy-coding-standard#configuration) for more configuration options.

UPGRADE-4.0.md

@@ -11,24 +11,34 @@ In require-dev section change the version constraint:
 Then run `composer update`.
 
 ### 2. Configuration updates
+Configuration now uses `ECSConfig` class instead of `ContainerConfigurator`.
 
-Configuration now uses ECSConfig class instead of ContainerConfigurator. Update your `ecs.php` to use the new configuration style:
+Update your `ecs.php` to use the new configuration style:
 
 ```diff
 -use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
--
--return static function (ContainerConfigurator $containerConfigurator): void {
 +use Symplify\EasyCodingStandard\Config\ECSConfig;
-+
+
+-return static function (ContainerConfigurator $containerConfigurator): void {
 +return ECSConfig::configure()
++    ->withSets([
++        __DIR__ . '/vendor/lmc/coding-standard/ecs.php',
++    ]);
+    // ...
 ```
 
-Rules are now set using `ECSConfig::configure()->withRules([])` or `ECSConfig::configure()->withConfiguredRule()` instead of `$services->set()`.
-Skiping tests is now done using `ECSConfig::configure()->withSkip()` instead of `$parameters->set(Option::SKIP, ...)`.
-Imports are now done using `ECSConfig::configure()->withSets()` instead of `$containerConfigurator->import()`.
+Now change the way you set rules, skip tests and import sets:
+
+| Old Method                            | New Method                                                                                |
+|---------------------------------------|-------------------------------------------------------------------------------------------|
+| `$services->set()`                    | `ECSConfig::configure()->withRules([])` or `ECSConfig::configure()->withConfiguredRule()` |
+| `$parameters->set(Option::SKIP, ...)` | `ECSConfig::configure()->withSkip()`                                                      |
+| `$containerConfigurator->import()`    | `ECSConfig::configure()->withSets()`                                                      |
 
-See [ECS documentation](https://github.com/easy-coding-standard/easy-coding-standard/tree/main?tab=readme-ov-file#configure) for more configuration options
-Examples of configurations can be seen [here](https://tomasvotruba.com/blog/new-in-ecs-simpler-config)
+See [examples in Usage section of our README](https://github.com/lmc-eu/php-coding-standard?tab=readme-ov-file#usage)
+or more configuration options in [ECS documentation](https://github.com/easy-coding-standard/easy-coding-standard/tree/main?tab=readme-ov-file#configure).
+
+Some more reasoning and examples of configurations can also be seen [in ECS author blogpost](https://tomasvotruba.com/blog/new-in-ecs-simpler-config).
 
 ### 3. Remove imports of `ecs-7.4.php` and/or `ecs-8.0.php` from your `ecs.php`
 ```diff
@@ -38,7 +48,42 @@ Examples of configurations can be seen [here](https://tomasvotruba.com/blog/new-
     ->withSets(__DIR__ . '/vendor/lmc/coding-standard/ecs-8.1.php')
 ```
 
-### 4. Sanity check
+### 4. Configure paths directly in ecs.php
+
+Paths definition could now be included directly in `ecs.php` instead of repeating them on command line.
+
+In `ecs.php`:
+```php
+// ...
+return ECSConfig::configure()
+    ->withPaths([__DIR__ . '/src', __DIR__ . '/tests']) // optionally add 'config' or other directories with PHP files
+    ->withRootFiles() // to include ecs.php and all other php files in the root directory
+// ...
+```
+
+Now you can remove the explicit paths definition from `composer.json`:
+```diff
+{
+    "scripts": {
+        "analyze": [
+-            "vendor/bin/ecs check --ansi src/ tests/"
++            "vendor/bin/ecs check --ansi"
+        ],
+        "fix": [
+-            "vendor/bin/ecs check --ansi --fix src/ tests/"
++            "vendor/bin/ecs check --ansi --fix"
+        ]
+    }
+}
+```
+
+Or run directly from command line without a need of specifying them:
+```bash
+$ vendor/bin/ecs check --ansi src/ tests/ # old
+$ vendor/bin/ecs check --ansi # new
+```
+
+### 5. Sanity check
 Besides running your code style checks, you can ensure all predefined LMC checks are loaded as well, by running:
 
 ```sh