feat: Support external rulesets

dev-tools/phpstan/baseline.php

@@ -871,30 +871,6 @@
 	'count' => 1,
 	'path' => __DIR__ . '/../../src/RuleSet/RuleSet.php',
 ];
-$ignoreErrors[] = [
-	// identifier: method.notFound
-	'message' => '#^Call to an undefined method object\\:\\:getName\\(\\)\\.$#',
-	'count' => 1,
-	'path' => __DIR__ . '/../../src/RuleSet/RuleSets.php',
-];
-$ignoreErrors[] = [
-	// identifier: return.type
-	'message' => '#^Method PhpCsFixer\\\\RuleSet\\\\RuleSets\\:\\:getSetDefinitions\\(\\) should return array\\<string, PhpCsFixer\\\\RuleSet\\\\RuleSetDescriptionInterface\\> but returns array\\<int\\|string, object\\>\\.$#',
-	'count' => 1,
-	'path' => __DIR__ . '/../../src/RuleSet/RuleSets.php',
-];
-$ignoreErrors[] = [
-	// identifier: argument.type
-	'message' => '#^Parameter \\#2 \\$callback of function uksort expects callable\\(int\\|string, int\\|string\\)\\: int, Closure\\(string, string\\)\\: int\\<\\-1, 1\\> given\\.$#',
-	'count' => 1,
-	'path' => __DIR__ . '/../../src/RuleSet/RuleSets.php',
-];
-$ignoreErrors[] = [
-	// identifier: assign.propertyType
-	'message' => '#^Static property PhpCsFixer\\\\RuleSet\\\\RuleSets\\:\\:\\$setDefinitions \\(array\\<string, PhpCsFixer\\\\RuleSet\\\\RuleSetDescriptionInterface\\>\\) does not accept array\\<int\\|string, object\\>\\.$#',
-	'count' => 1,
-	'path' => __DIR__ . '/../../src/RuleSet/RuleSets.php',
-];
 $ignoreErrors[] = [
 	// identifier: return.type
 	'message' => '#^Method PhpCsFixer\\\\Tokenizer\\\\Analyzer\\\\AttributeAnalyzer\\:\\:collectAttributes\\(\\) should return list\\<array\\{start\\: int, end\\: int, name\\: string\\}\\> but returns non\\-empty\\-array\\<int\\<0, max\\>, array\\{start\\: int, end\\: int, name\\: string\\}\\>\\.$#',

doc/config.rst

@@ -141,3 +141,20 @@ configure them in your config file.
         ->setIndent("\t")
         ->setLineEnding("\r\n")
     ;
+
+It's possible to register custom rule sets, which makes it easier to reuse custom configuration between multiple projects. If you have prepared rule set, you can register it, and then enable it in the rules. Custom rule sets (in this example ``\MyNameSpace\MyRuleSetClass``) must implement ``\PhpCsFixer\RuleSet\RuleSetDescriptionInterface``.
+
+.. code-block:: php
+
+    <?php
+
+    return (new PhpCsFixer\Config())
+        ->registerCustomRuleSets([
+            MyNameSpace\MyRuleSetClass::class, // It identifies itself as '@MyRuleSet'
+        ])
+        ->setRules([
+            '@MyRuleSet' => true,
+        ])
+    ;
+
+ℹ️ If you use ``\PhpCsFixer\ConfigInterface`` implementation other than built-in one, make sure it implements ``\PhpCsFixer\CustomRulesetsAwareConfigInterface``.

src/Config.php

@@ -15,6 +15,7 @@
 namespace PhpCsFixer;
 
 use PhpCsFixer\Fixer\FixerInterface;
+use PhpCsFixer\RuleSet\RuleSetDescriptionInterface;
 use PhpCsFixer\Runner\Parallel\ParallelConfig;
 use PhpCsFixer\Runner\Parallel\ParallelConfigFactory;
 
@@ -23,7 +24,7 @@
  * @author Katsuhiro Ogawa <ko.fivestar@gmail.com>
  * @author Dariusz Rumiński <dariusz.ruminski@gmail.com>
  */
-class Config implements ConfigInterface, ParallelAwareConfigInterface
+class Config implements ConfigInterface, ParallelAwareConfigInterface, CustomRulesetsAwareConfigInterface
 {
     private string $cacheFile = '.php-cs-fixer.cache';
 
@@ -32,6 +33,11 @@
      */
     private array $customFixers = [];
 
+    /**
+     * @var list<class-string<RuleSetDescriptionInterface>>
+     */
+    private array $customRuleSets = [];
+
     /**
      * @var null|iterable<\SplFileInfo>
      */
@@ -94,6 +100,11 @@
         return $this->customFixers;
     }
 
+    public function getCustomRuleSets(): array
+    {
+        return $this->customRuleSets;
+    }
+
     /**
      * @return Finder
      */
@@ -163,6 +174,26 @@
         return $this;
     }
 
+    /**
+     * @param list<class-string<RuleSetDescriptionInterface>> $ruleSets
+     */
+    public function registerCustomRuleSets(array $ruleSets): ConfigInterface
+    {
+        foreach ($ruleSets as $class) {
+            if (!class_exists($class)) {
+                throw new \UnexpectedValueException(sprintf('Rule set "%s" does not exist.', $class));
+            }
+
+            if (!\in_array(RuleSetDescriptionInterface::class, class_implements($class), true)) {
+                throw new \UnexpectedValueException(sprintf('Rule set "%s" does not implement "%s".', $class, RuleSetDescriptionInterface::class));
+            }
+        }
+
+        $this->customRuleSets = array_values(array_unique(array_merge($this->customRuleSets, $ruleSets)));
+
+        return $this;
+    }
+
     public function setCacheFile(string $cacheFile): ConfigInterface
     {
         $this->cacheFile = $cacheFile;

src/Console/Command/DocumentationCommand.php

@@ -60,7 +60,7 @@ protected function execute(InputInterface $input, OutputInterface $output): int
         $fixerFactory->registerBuiltInFixers();
         $fixers = $fixerFactory->getFixers();
 
-        $setDefinitions = RuleSets::getSetDefinitions();
+        $setDefinitions = RuleSets::getBuiltInSetDefinitions();
 
         $fixerDocumentGenerator = new FixerDocumentGenerator($locator);
         $ruleSetDocumentationGenerator = new RuleSetDocumentationGenerator($locator);

src/Console/ConfigurationResolver.php

@@ -26,6 +26,7 @@
 use PhpCsFixer\Console\Output\Progress\ProgressOutputType;
 use PhpCsFixer\Console\Report\FixReport\ReporterFactory;
 use PhpCsFixer\Console\Report\FixReport\ReporterInterface;
+use PhpCsFixer\CustomRulesetsAwareConfigInterface;
 use PhpCsFixer\Differ\DifferInterface;
 use PhpCsFixer\Differ\NullDiffer;
 use PhpCsFixer\Differ\UnifiedDiffer;
@@ -38,6 +39,7 @@
 use PhpCsFixer\ParallelAwareConfigInterface;
 use PhpCsFixer\RuleSet\RuleSet;
 use PhpCsFixer\RuleSet\RuleSetInterface;
+use PhpCsFixer\RuleSet\RuleSets;
 use PhpCsFixer\Runner\Parallel\ParallelConfig;
 use PhpCsFixer\Runner\Parallel\ParallelConfigFactory;
 use PhpCsFixer\StdinFileInfo;
@@ -273,6 +275,12 @@
             if (null === $this->config) {
                 $this->config = $this->defaultConfig;
             }
+
+            if ($this->config instanceof CustomRulesetsAwareConfigInterface) {
+                foreach ($this->config->getCustomRuleSets() as $ruleSet) {
+                    RuleSets::registerCustomRuleSet($ruleSet);
+                }
+            }
         }
 
         return $this->config;

src/CustomRulesetsAwareConfigInterface.php

@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of PHP CS Fixer.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *     Dariusz Rumiński <dariusz.ruminski@gmail.com>
+ *
+ * This source file is subject to the MIT license that is bundled
+ * with this source code in the file LICENSE.
+ */
+
+namespace PhpCsFixer;
+
+use PhpCsFixer\RuleSet\RuleSetDescriptionInterface;
+
+/**
+ * @author Greg Korba <greg@codito.dev>
+ *
+ * @TODO 4.0 Include support for custom rulesets in main ConfigInterface
+ */
+interface CustomRulesetsAwareConfigInterface extends ConfigInterface
+{
+    /**
+     * Registers custom rule sets to be used the same way as built-in rule sets.
+     *
+     * @param list<class-string<RuleSetDescriptionInterface>> $ruleSets
+     *
+     * @todo v4 Introduce it in main ConfigInterface
+     */
+    public function registerCustomRuleSets(array $ruleSets): ConfigInterface;
+
+    /**
+     * @return list<class-string<RuleSetDescriptionInterface>>
+     */
+    public function getCustomRuleSets(): array;
+}

src/RuleSet/RuleSets.php

@@ -14,6 +14,7 @@
 
 namespace PhpCsFixer\RuleSet;
 
+use PhpCsFixer\RuleSetNameValidator;
 use Symfony\Component\Finder\Finder;
 
 /**
@@ -26,27 +27,52 @@
     /**
      * @var array<string, RuleSetDescriptionInterface>
      */
-    private static $setDefinitions;
+    private static ?array $builtInSetDefinitions = null;
+
+    /**
+     * @var array<string, RuleSetDescriptionInterface>
+     */
+    private static array $customRuleSetDefinitions = [];
 
     /**
      * @return array<string, RuleSetDescriptionInterface>
      */
     public static function getSetDefinitions(): array
     {
-        if (null === self::$setDefinitions) {
-            self::$setDefinitions = [];
+        $allRuleSets = array_merge(
+            self::getBuiltInSetDefinitions(),
+            self::$customRuleSetDefinitions
+        );
+
+        uksort($allRuleSets, static fn (string $x, string $y): int => strnatcmp($x, $y));
+
+        return $allRuleSets;
+    }
+
+    /**
+     * @return array<string, RuleSetDescriptionInterface>
+     */
+    public static function getBuiltInSetDefinitions(): array
+    {
+        if (null === self::$builtInSetDefinitions) {
+            self::$builtInSetDefinitions = [];
 
             foreach (Finder::create()->files()->in(__DIR__.'/Sets') as $file) {
+                /** @var class-string<RuleSetDescriptionInterface> $class */
                 $class = 'PhpCsFixer\RuleSet\Sets\\'.$file->getBasename('.php');
                 $set = new $class();
 
-                self::$setDefinitions[$set->getName()] = $set;
+                if (!RuleSetNameValidator::isValid($set->getName(), false)) {
+                    throw new \InvalidArgumentException(sprintf('Rule set name invalid: %s', $set->getName()));
+                }
+
+                self::$builtInSetDefinitions[$set->getName()] = $set;
             }
 
-            uksort(self::$setDefinitions, static fn (string $x, string $y): int => strnatcmp($x, $y));
+            uksort(self::$builtInSetDefinitions, static fn (string $x, string $y): int => strnatcmp($x, $y));
         }
 
-        return self::$setDefinitions;
+        return self::$builtInSetDefinitions;
     }
 
     /**
@@ -67,4 +93,39 @@
 
         return $definitions[$name];
     }
+
+    /**
+     * @param class-string<RuleSetDescriptionInterface> $class
+     */
+    public static function registerCustomRuleSet(string $class): void
+    {
+        if (!class_exists($class)
+            || !\in_array(RuleSetDescriptionInterface::class, class_implements($class), true)
+        ) {
+            throw new \InvalidArgumentException(
+                sprintf(
+                    'Class "%s" must be an instance of "%s".',
+                    $class,
+                    RuleSetDescriptionInterface::class
+                )
+            );
+        }
+
+        $ruleset = new $class();
+        $name = $ruleset->getName();
+
+        if (!RuleSetNameValidator::isValid($name, true)) {
+            throw new \InvalidArgumentException('RuleSet name must begin with "@" and a letter (a-z, A-Z), and can contain only letters (a-z, A-Z), numbers, underscores, slashes, colons, dots and hyphens.');
+        }
+
+        if (!class_exists($class, true)) {
+            throw new \InvalidArgumentException(sprintf('Class "%s" does not exist.', $class));
+        }
+
+        if (\array_key_exists($name, self::getSetDefinitions())) {
+            throw new \InvalidArgumentException(sprintf('Set "%s" is already defined.', $name));
+        }
+
+        self::$customRuleSetDefinitions[$name] = $ruleset;
+    }
 }

src/RuleSetNameValidator.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of PHP CS Fixer.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *     Dariusz Rumiński <dariusz.ruminski@gmail.com>
+ *
+ * This source file is subject to the MIT license that is bundled
+ * with this source code in the file LICENSE.
+ */
+
+namespace PhpCsFixer;
+
+final class RuleSetNameValidator
+{
+    public static function isValid(string $name, bool $isCustom): bool
+    {
+        if (!$isCustom) {
+            return Preg::match('/^@[a-zA-Z][a-zA-Z0-9:_\/\.-]*$/', $name);
+        }
+
+        return Preg::match('/^@[a-zA-Z][a-zA-Z0-9:_\/\.-]*$/', $name);
+    }
+}

tests/AutoReview/DescribeCommandTest.php

@@ -64,6 +64,7 @@ public function testDescribeCommand(FixerFactory $factory, string $fixerName, ?a
         $commandTester->execute([
             'command' => $command->getName(),
             'name' => $fixerName,
+            '--config' => realpath(__DIR__.'/../../.php-cs-fixer.dist.php'),
         ]);
 
         self::assertSame(0, $commandTester->getStatusCode());

tests/AutoReview/DocumentationTest.php

@@ -132,7 +132,7 @@ public function testRuleSetsDocumentationIsUpToDate(): void
         $fixers = self::getFixers();
         $paths = [];
 
-        foreach (RuleSets::getSetDefinitions() as $name => $definition) {
+        foreach (RuleSets::getBuiltInSetDefinitions() as $name => $definition) {
             $path = $locator->getRuleSetsDocumentationFilePath($name);
             $paths[$path] = $definition;
 
@@ -157,7 +157,7 @@ public function testRuleSetsDocumentationDirectoryHasNoExtraFiles(): void
         $generator = new DocumentationLocator();
 
         self::assertCount(
-            \count(RuleSets::getSetDefinitions()) + 1,
+            \count(RuleSets::getBuiltInSetDefinitions()) + 1,
             (new Finder())->files()->in($generator->getRuleSetsDocumentationDirectoryPath())
         );
     }