Add support for regexes for excluded symbols (#660)

Author: theofidry

docs/configuration.md

@@ -186,9 +186,9 @@ Symbols can be marked as excluded as follows:
 
 return [
     'exclude-namespaces' => [ 'WP', '/regex/' ],
-    'exclude-classes' => ['Stringeable'],
-    'exclude-functions' => ['str_contains'],
-    'exclude-constants' => ['PHP_EOL'],
+    'exclude-classes' => ['Stringeable', '/regex/'],
+    'exclude-functions' => ['str_contains', '/regex/'],
+    'exclude-constants' => ['PHP_EOL', '/regex/'],
 ];
 ```
 

docs/further-reading.md

@@ -47,11 +47,7 @@ return [
     ],
     'exclude-constants' => [
         // Symfony global constants
-        // TODO: switch to the following regex once regexes are supported here
-        // https://github.com/humbug/php-scoper/issues/634
         '/^SYMFONY\_[\p{L}_]+$/',
-        // Meanwhile:
-        'SYMFONY_GRAPHEME_CLUSTER_RX',
     ],
     'exclude-files' => [
         ...$polyfillsBootstraps,

fixtures/set020-infection/scoper.inc.php

@@ -33,10 +33,7 @@
     ],
     'exclude-constants' => [
         // Symfony global constants
-        // TODO: switch to the following regex once regexes are supported here
-        // https://github.com/humbug/php-scoper/issues/634
         '/^SYMFONY\_[\p{L}_]+$/',
-        'SYMFONY_GRAPHEME_CLUSTER_RX',
     ],
     'exclude-files' => [
         ...$polyfillsBootstraps,

scoper.inc.php

@@ -77,10 +77,7 @@
     ],
     'exclude-constants' => [
         // Symfony global constants
-        // TODO: switch to the following regex once regexes are supported here
-        // https://github.com/humbug/php-scoper/issues/634
         '/^SYMFONY\_[\p{L}_]+$/',
-        'SYMFONY_GRAPHEME_CLUSTER_RX',
     ],
     'exclude-files' => [
         ...$jetBrainStubs,

src/Configuration/SymbolsConfiguration.php

@@ -30,26 +30,10 @@ final class SymbolsConfiguration
     private SymbolRegistry $exposedFunctions;
     private SymbolRegistry $exposedConstants;
 
-    /**
-     * @var string[]
-     */
-    private array $excludedClassNames;
-
-    /**
-     * @var string[]
-     */
-    private array $excludedFunctionNames;
-
-    /**
-     * @var string[]
-     */
-    private array $excludedConstantNames;
-
-    /**
-     * @param string[] $excludedClassNames
-     * @param string[] $excludedFunctionNames
-     * @param string[] $excludedConstantNames
-     */
+    private SymbolRegistry $excludedClasses;
+    private SymbolRegistry $excludedFunctions;
+    private SymbolRegistry $excludedConstants;
+
     public static function create(
         bool $exposeGlobalConstants = false,
         bool $exposeGlobalClasses = false,
@@ -58,12 +42,12 @@ public static function create(
         // Does not contain the list of excluded symbols which go to the
         // Reflector (which has no notion of namespaces)
         ?NamespaceRegistry $exposedNamespaces = null,
-        SymbolRegistry $exposedClasses = null,
-        SymbolRegistry $exposedFunctions = null,
-        SymbolRegistry $exposedConstants = null,
-        array $excludedClassNames = [],
-        array $excludedFunctionNames = [],
-        array $excludedConstantNames = []
+        ?SymbolRegistry $exposedClasses = null,
+        ?SymbolRegistry $exposedFunctions = null,
+        ?SymbolRegistry $exposedConstants = null,
+        ?SymbolRegistry $excludedClasses = null,
+        ?SymbolRegistry $excludedFunctions = null,
+        ?SymbolRegistry $excludedConstants = null
     ): self {
         return new self(
             $exposeGlobalConstants,
@@ -74,17 +58,12 @@ public static function create(
             $exposedClasses ?? SymbolRegistry::create(),
             $exposedFunctions ?? SymbolRegistry::create(),
             $exposedConstants ?? SymbolRegistry::createForConstants(),
-            $excludedClassNames,
-            $excludedFunctionNames,
-            $excludedConstantNames,
+            $excludedClasses ?? SymbolRegistry::create(),
+            $excludedFunctions ?? SymbolRegistry::create(),
+            $excludedConstants ?? SymbolRegistry::createForConstants(),
         );
     }
 
-    /**
-     * @param string[] $excludedClassNames
-     * @param string[] $excludedFunctionNames
-     * @param string[] $excludedConstantNames
-     */
     private function __construct(
         bool $exposeGlobalConstants,
         bool $exposeGlobalClasses,
@@ -94,9 +73,9 @@ private function __construct(
         SymbolRegistry $exposedClasses,
         SymbolRegistry $exposedFunctions,
         SymbolRegistry $exposedConstants,
-        array $excludedClassNames,
-        array $excludedFunctionNames,
-        array $excludedConstantNames
+        SymbolRegistry $excludedClasses,
+        SymbolRegistry $excludedFunctions,
+        SymbolRegistry $excludedConstants
     ) {
         $this->exposeGlobalConstants = $exposeGlobalConstants;
         $this->exposeGlobalClasses = $exposeGlobalClasses;
@@ -106,9 +85,9 @@ private function __construct(
         $this->exposedClasses = $exposedClasses;
         $this->exposedFunctions = $exposedFunctions;
         $this->exposedConstants = $exposedConstants;
-        $this->excludedClassNames = $excludedClassNames;
-        $this->excludedFunctionNames = $excludedFunctionNames;
-        $this->excludedConstantNames = $excludedConstantNames;
+        $this->excludedClasses = $excludedClasses;
+        $this->excludedFunctions = $excludedFunctions;
+        $this->excludedConstants = $excludedConstants;
     }
 
     public function shouldExposeGlobalConstants(): bool
@@ -151,27 +130,18 @@ public function getExposedConstants(): SymbolRegistry
         return $this->exposedConstants;
     }
 
-    /**
-     * @return string[]
-     */
-    public function getExcludedClassNames(): array
+    public function getExcludedClasses(): SymbolRegistry
     {
-        return $this->excludedClassNames;
+        return $this->excludedClasses;
     }
 
-    /**
-     * @return string[]
-     */
-    public function getExcludedFunctionNames(): array
+    public function getExcludedFunctions(): SymbolRegistry
     {
-        return $this->excludedFunctionNames;
+        return $this->excludedFunctions;
     }
 
-    /**
-     * @return string[]
-     */
-    public function getExcludedConstantNames(): array
+    public function getExcludedConstants(): SymbolRegistry
     {
-        return $this->excludedConstantNames;
+        return $this->excludedConstants;
     }
 }

src/Configuration/SymbolsConfigurationFactory.php

@@ -93,6 +93,27 @@ public function createSymbolsConfiguration(array $config): SymbolsConfiguration
             ConfigurationKeys::EXPOSE_CONSTANTS_SYMBOLS_KEYWORD,
         );
 
+        $excludedClasses = SymbolRegistry::create(
+            ...$this->retrieveElements(
+                $config,
+                ConfigurationKeys::CLASSES_INTERNAL_SYMBOLS_KEYWORD,
+            ),
+        );
+
+        $excludedFunctions = SymbolRegistry::create(
+            ...$this->retrieveElements(
+                $config,
+                ConfigurationKeys::FUNCTIONS_INTERNAL_SYMBOLS_KEYWORD,
+            ),
+        );
+
+        $excludedConstants = SymbolRegistry::createForConstants(
+            ...$this->retrieveElements(
+                $config,
+                ConfigurationKeys::CONSTANTS_INTERNAL_SYMBOLS_KEYWORD,
+            ),
+        );
+
         return SymbolsConfiguration::create(
             $exposeGlobalConstants,
             $exposeGlobalClasses,
@@ -135,7 +156,9 @@ public function createSymbolsConfiguration(array $config): SymbolsConfiguration
                     $legacyExposedSymbolsPatterns,
                 ),
             ),
-            ...self::retrieveAllExcludedSymbols($config),
+            $excludedClasses,
+            $excludedFunctions,
+            $excludedConstants,
         );
     }
 
@@ -253,18 +276,6 @@ private function retrieveElements(array $config, string $key): array
         ];
     }
 
-    /**
-     * @return array{string[], string[], string[]}
-     */
-    private static function retrieveAllExcludedSymbols(array $config): array
-    {
-        return [
-            self::retrieveExcludedSymbols($config, ConfigurationKeys::CLASSES_INTERNAL_SYMBOLS_KEYWORD),
-            self::retrieveExcludedSymbols($config, ConfigurationKeys::FUNCTIONS_INTERNAL_SYMBOLS_KEYWORD),
-            self::retrieveExcludedSymbols($config, ConfigurationKeys::CONSTANTS_INTERNAL_SYMBOLS_KEYWORD),
-        ];
-    }
-
     /**
      * @deprecated
      *
@@ -421,20 +432,4 @@ private static function lowerCaseConstantName(string $name): string
 
         return implode('\\', $parts);
     }
-
-    /**
-     * @return string[]
-     */
-    private static function retrieveExcludedSymbols(array $config, string $key): array
-    {
-        if (!array_key_exists($key, $config)) {
-            return [];
-        }
-
-        $symbols = $config[$key];
-
-        self::assertIsArrayOfStrings($symbols, $key);
-
-        return $symbols;
-    }
 }

src/Symbol/EnrichedReflectorFactory.php

@@ -17,10 +17,10 @@ public function __construct(Reflector $reflector)
 
     public function create(SymbolsConfiguration $symbolsConfiguration): EnrichedReflector
     {
-        $configuredReflector = $this->reflector->withSymbols(
-            $symbolsConfiguration->getExcludedClassNames(),
-            $symbolsConfiguration->getExcludedFunctionNames(),
-            $symbolsConfiguration->getExcludedConstantNames(),
+        $configuredReflector = $this->reflector->withAdditionalSymbols(
+            $symbolsConfiguration->getExcludedClasses(),
+            $symbolsConfiguration->getExcludedFunctions(),
+            $symbolsConfiguration->getExcludedConstants(),
         );
 
         return new EnrichedReflector(

src/Symbol/Reflector.php

@@ -633,21 +633,16 @@ private function __construct(
         $this->constants = $constants;
     }
 
-    /**
-     * @param string[] $classNames
-     * @param string[] $functionNames
-     * @param string[] $constantNames
-     */
-    public function withSymbols(
-        array $classNames,
-        array $functionNames,
-        array $constantNames
+    public function withAdditionalSymbols(
+        SymbolRegistry $classNames,
+        SymbolRegistry $functionNames,
+        SymbolRegistry $constantNames
     ): self
     {
         return new self(
-            $this->classes->withAdditionalSymbols($classNames),
-            $this->functions->withAdditionalSymbols($functionNames),
-            $this->constants->withAdditionalSymbols($constantNames),
+            $this->classes->merge($classNames),
+            $this->functions->merge($functionNames),
+            $this->constants->merge($constantNames),
         );
     }
 

src/Symbol/SymbolRegistry.php

@@ -4,6 +4,7 @@
 
 namespace Humbug\PhpScoper\Symbol;
 
+use InvalidArgumentException;
 use function array_key_exists;
 use function array_keys;
 use function array_map;
@@ -107,20 +108,20 @@ public function matches(string $symbol): bool
         return false;
     }
 
-    /**
-     * @param string[] $names
-     * @param string[] $regexes
-     */
-    public function withAdditionalSymbols(array $names = [], array $regexes = []): self
+    public function merge(SymbolRegistry $registry): self
     {
+        if ($this->constants !== $registry->constants) {
+            throw new InvalidArgumentException('Cannot merge registries of different symbol types');
+        }
+
         $args = [
             [
                 ...$this->getNames(),
-                ...$names,
+                ...$registry->getNames(),
             ],
             [
                 ...$this->getRegexes(),
-                ...$regexes,
+                ...$registry->getRegexes(),
             ],
         ];
 

src/scoper.inc.php.tpl

@@ -76,8 +76,6 @@ return [
         // '~^$~',                        // The root namespace only
         // '',                            // Any namespace
     ],
-    // Warning: regexes are not supported there (yet)
-    // See https://github.com/humbug/php-scoper/issues/634
     'exclude-classes' => [
         // 'ReflectionClassConstant',
     ],