Enhancement: Add Config\RuleSet::withCustomFixers() to allow merging …

…Config\Fixers

CHANGELOG.md

@@ -15,6 +15,7 @@ For a full diff see [`5.16.0...main`][5.16.0...main].
 - Extracted `Config\Rules` as a value object ([#874]), by [@localheinz]
 - Extracted `Config\Fixers` as a value object ([#883]), by [@localheinz]
 - Added `Config\RuleSet::withRules()` to allow overriding `Config\Rules` ([#891]), by [@localheinz]
+- Added `Config\RuleSet::withCustomFixers()` to allow registering additional `Config\Fixers` ([#893]), by [@localheinz]
 
 ### Changed
 
@@ -1206,6 +1207,7 @@ For a full diff see [`d899e77...1.0.0`][d899e77...1.0.0].
 [#888]: https://github.com/ergebnis/php-cs-fixer-config/pull/888
 [#891]: https://github.com/ergebnis/php-cs-fixer-config/pull/891
 [#892]: https://github.com/ergebnis/php-cs-fixer-config/pull/892
+[#893]: https://github.com/ergebnis/php-cs-fixer-config/pull/893
 
 [@dependabot]: https://github.com/apps/dependabot
 [@linuxjuggler]: https://github.com/linuxjuggler

README.md

@@ -142,6 +142,40 @@ This will enable and configure the [`HeaderCommentFixer`](https://github.com/Fri
  return $config;
 ```
 
+### Configuring a rule set that registers and configures rules for custom fixers
+
+:bulb: Optionally register and configure rules for custom fixers:
+
+```diff
+ <?php
+
+ declare(strict_types=1);
+
+ use Ergebnis\PhpCsFixer\Config;
+ use FooBar\Fixer;
+
+-$ruleSet = Config\RuleSet\Php82::create();
++$ruleSet = Config\RuleSet\Php82::create()
++    ->withCustomFixers(Config\Fixers::fromFixers(
++        new Fixer\BarBazFixer(),
++        new Fixer\QuzFixer(),
++    ))
++    ->withRules(Config\Rules::fromArray([
++        'FooBar/bar_baz' => true,
++        'FooBar/quz' => [
++            'qux => false,
++        ],
++    ]))
++]);
+
+ $config = Config\Factory::fromRuleSet($ruleSet);
+
+ $config->getFinder()->in(__DIR__);
+ $config->setCacheFile(__DIR__ . '/.build/php-cs-fixer/.php-cs-fixer.cache');
+
+ return $config;
+```
+
 ### Makefile
 
 If you like [`Makefile`](https://www.gnu.org/software/make/manual/make.html#Introduction)s, create a `Makefile` with a `coding-standards` target:

src/Fixers.php

@@ -68,4 +68,12 @@ public function toArray(): array
     {
         return $this->value;
     }
+
+    public function merge(self $customFixers): self
+    {
+        return new self(...\array_merge(
+            $this->value,
+            $customFixers->value,
+        ));
+    }
 }

src/RuleSet.php

@@ -69,6 +69,19 @@ public function rules(): Rules
         return $this->rules;
     }
 
+    /**
+     * Returns a new rule set with custom fixers.
+     */
+    public function withCustomFixers(Fixers $customFixers): self
+    {
+        return new self(
+            $this->customFixers->merge($customFixers),
+            $this->name,
+            $this->phpVersion,
+            $this->rules,
+        );
+    }
+
     /**
      * Returns a new rule set with merged rules.
      */

test/Unit/FixersTest.php

@@ -85,4 +85,30 @@ public function testFromIterableReturnsFixersWhenValueIsTraversable(): void
 
         self::assertSame($value, $fixers->toArray());
     }
+
+    public function testMergeReturnsFixersMergedWithFixers(): void
+    {
+        $one = Fixers::fromFixers(
+            $this->createStub(Fixer\FixerInterface::class),
+            $this->createStub(Fixer\FixerInterface::class),
+            $this->createStub(Fixer\FixerInterface::class),
+        );
+
+        $two = Fixers::fromFixers(
+            $this->createStub(Fixer\FixerInterface::class),
+            $this->createStub(Fixer\FixerInterface::class),
+        );
+
+        $mutated = $one->merge($two);
+
+        self::assertNotSame($one, $mutated);
+        self::assertNotSame($two, $mutated);
+
+        $expected = Fixers::fromFixers(...\array_merge(
+            $one->toArray(),
+            $two->toArray(),
+        ));
+
+        self::assertEquals($expected, $mutated);
+    }
 }

test/Unit/RuleSetTest.php

@@ -64,6 +64,45 @@ public function testCreateReturnsRuleSet(): void
         self::assertSame($rules, $ruleSet->rules());
     }
 
+    public function testWithCustomFixersReturnsRuleSetWithMergedCustomFixers(): void
+    {
+        $faker = self::faker();
+
+        $customFixers = Fixers::fromFixers(
+            $this->createStub(Fixer\FixerInterface::class),
+            $this->createStub(Fixer\FixerInterface::class),
+        );
+
+        $ruleSet = RuleSet::create(
+            Fixers::fromFixers(
+                $this->createStub(Fixer\FixerInterface::class),
+                $this->createStub(Fixer\FixerInterface::class),
+                $this->createStub(Fixer\FixerInterface::class),
+            ),
+            Name::fromString($faker->word()),
+            PhpVersion::create(
+                PhpVersion\Major::fromInt($faker->numberBetween(0)),
+                PhpVersion\Minor::fromInt($faker->numberBetween(0, 99)),
+                PhpVersion\Patch::fromInt($faker->numberBetween(0, 99)),
+            ),
+            Rules::fromArray([
+                'foo' => false,
+                'quz' => true,
+            ]),
+        );
+
+        $mutated = $ruleSet->withCustomFixers($customFixers);
+
+        self::assertNotSame($ruleSet, $mutated);
+
+        $expected = $ruleSet->customFixers()->merge($customFixers);
+
+        self::assertEquals($expected, $mutated->customFixers());
+        self::assertEquals($ruleSet->name(), $mutated->name());
+        self::assertEquals($ruleSet->phpVersion(), $mutated->phpVersion());
+        self::assertEquals($ruleSet->rules(), $mutated->rules());
+    }
+
     public function testWithRulesReturnsRuleSetWithMergedRules(): void
     {
         $faker = self::faker();