Enhancement: Add Config\RuleSet::withRules() to allow overriding Config\Rules

CHANGELOG.md

@@ -14,6 +14,7 @@ For a full diff see [`5.16.0...main`][5.16.0...main].
 - Extracted `Config\PhpVersion` as a value object ([#871]), by [@localheinz]
 - 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]
 
 ### Changed
 
@@ -1202,6 +1203,7 @@ For a full diff see [`d899e77...1.0.0`][d899e77...1.0.0].
 [#886]: https://github.com/ergebnis/php-cs-fixer-config/pull/886
 [#887]: https://github.com/ergebnis/php-cs-fixer-config/pull/887
 [#888]: https://github.com/ergebnis/php-cs-fixer-config/pull/888
+[#891]: https://github.com/ergebnis/php-cs-fixer-config/pull/891
 
 [@dependabot]: https://github.com/apps/dependabot
 [@linuxjuggler]: https://github.com/linuxjuggler

README.md

@@ -128,13 +128,13 @@ This will enable and configure the [`HeaderCommentFixer`](https://github.com/Fri
 
  use Ergebnis\PhpCsFixer\Config;
 
- $ruleSet = Config\RuleSet\Php82::create();
-
--$config = Config\Factory::fromRuleSet($ruleSet);
-+$config = Config\Factory::fromRuleSet($ruleSet, Config\Rules::fromArray([
+-$ruleSet = Config\RuleSet\Php82::create();
++$ruleSet = Config\RuleSet\Php82::create()->withRules(Config\Rules::fromArray([
 +    'mb_str_functions' => false,
 +    'strict_comparison' => false,
-+]));
++]);
+
+ $config = Config\Factory::fromRuleSet($ruleSet);
 
  $config->getFinder()->in(__DIR__);
  $config->setCacheFile(__DIR__ . '/.build/php-cs-fixer/.php-cs-fixer.cache');

src/RuleSet.php

@@ -69,6 +69,19 @@ public function rules(): Rules
         return $this->rules;
     }
 
+    /**
+     * Returns a new rule set with merged rules.
+     */
+    public function withRules(Rules $rules): self
+    {
+        return new self(
+            $this->customFixers,
+            $this->name,
+            $this->phpVersion,
+            $this->rules->merge($rules),
+        );
+    }
+
     /**
      * Returns a new rule set with rules where the header_comment fixer is enabled to add a header.
      *

test/Unit/RuleSetTest.php

@@ -64,6 +64,46 @@ public function testCreateReturnsRuleSet(): void
         self::assertSame($rules, $ruleSet->rules());
     }
 
+    public function testWithRulesReturnsRuleSetWithMergedRules(): void
+    {
+        $faker = self::faker();
+
+        $rules = Rules::fromArray([
+            'foo' => true,
+            'bar' => false,
+        ]);
+
+        $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->withRules($rules);
+
+        self::assertNotSame($ruleSet, $mutated);
+
+        self::assertEquals($ruleSet->customFixers(), $mutated->customFixers());
+        self::assertEquals($ruleSet->name(), $mutated->name());
+        self::assertEquals($ruleSet->phpVersion(), $mutated->phpVersion());
+
+        $expected = $ruleSet->rules()->merge($rules);
+
+        self::assertEquals($expected, $mutated->rules());
+    }
+
     #[Framework\Attributes\DataProvider('provideValidHeader')]
     public function testWithHeaderReturnsRuleSetWithEnabledHeaderCommentFixer(string $header): void
     {