feat: Mark all declarations as internal (#882)

This should allow IDEs such as PHPStorm to honour the tag and avoid
showing the results in the auto-complete.

Closes #861.

specs/misc/internal-declarations.php

@@ -0,0 +1,223 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the humbug/php-scoper package.
+ *
+ * Copyright (c) 2017 Théo FIDRY <[email protected]>,
+ *                    Pádraic Brady <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+return [
+    'meta' => [
+        'title' => 'It adds @internal annotations to all declarations',
+        // Default values. If not specified will be the one used
+        'prefix' => 'Humbug',
+
+        'tag-declarations-as-internal' => true,
+
+        'expose-global-constants' => false,
+        'expose-global-classes' => false,
+        'expose-global-functions' => false,
+        'expose-namespaces' => [],
+        'expose-constants' => [],
+        'expose-classes' => [],
+        'expose-functions' => [],
+
+        'exclude-namespaces' => [],
+        'exclude-constants' => [],
+        'exclude-classes' => [],
+        'exclude-functions' => [],
+
+        'expected-recorded-classes' => [],
+        'expected-recorded-functions' => [],
+    ],
+
+    'Declarations without any comment' => <<<'PHP'
+    <?php
+    
+    class RegularClass {
+        public function aMethod() {}
+    }
+    
+    interface RegularInterface {}
+    
+    abstract class RegularAbstractClass {}
+    
+    function regular_function () {}
+    
+    trait RegularTrait {}
+    
+    const REGULAR_CONSTANT = 'FOO';
+    
+    enum RegularEnum {}
+    
+    ----
+    <?php
+    
+    namespace Humbug;
+
+    /** @internal */
+    class RegularClass
+    {
+        public function aMethod()
+        {
+        }
+    }
+    /** @internal */
+    interface RegularInterface
+    {
+    }
+    /** @internal */
+    abstract class RegularAbstractClass
+    {
+    }
+    /** @internal */
+    function regular_function()
+    {
+    }
+    /** @internal */
+    trait RegularTrait
+    {
+    }
+    /** @internal */
+    const REGULAR_CONSTANT = 'FOO';
+    /** @internal */
+    enum RegularEnum
+    {
+    }
+
+    PHP,
+
+    'Declarations without with comments' => <<<'PHP'
+    <?php
+    
+    // Smth
+    class RegularClass {
+        public function aMethod() {}
+    }
+    ----
+    <?php
+    
+    namespace Humbug;
+
+    // Smth
+    /** @internal */
+    class RegularClass
+    {
+        public function aMethod()
+        {
+        }
+    }
+
+    PHP,
+
+    'Declarations with existing phpDoc' => <<<'PHP'
+    <?php
+    
+    /**
+     * A comment.
+     */
+    class RegularClass {
+        public function aMethod() {}
+    }
+    ----
+    <?php
+    
+    namespace Humbug;
+
+    /**
+     * A comment.
+     * @internal
+     */
+    class RegularClass
+    {
+        public function aMethod()
+        {
+        }
+    }
+
+    PHP,
+
+    'Declarations with inlined phpDoc' => <<<'PHP'
+    <?php
+    
+    /** A comment. */
+    class RegularClass {
+        public function aMethod() {}
+    }
+    ----
+    <?php
+    
+    namespace Humbug;
+
+    /** A comment.
+     * @internal
+     */
+    class RegularClass
+    {
+        public function aMethod()
+        {
+        }
+    }
+
+    PHP,
+
+    'Declarations with inlined phpDoc already containing the @internal tag' => <<<'PHP'
+    <?php
+    
+    /** @internal */
+    class RegularClass {
+        public function aMethod() {}
+    }
+    ----
+    <?php
+    
+    namespace Humbug;
+
+    /** @internal */
+    class RegularClass
+    {
+        public function aMethod()
+        {
+        }
+    }
+
+    PHP,
+
+    'Declarations with existing phpDoc containing the @internal tag' => <<<'PHP'
+    <?php
+    
+    /**
+     * A comment.
+     * 
+     * @private
+     * @internal
+     */
+    class RegularClass {
+        public function aMethod() {}
+    }
+    ----
+    <?php
+    
+    namespace Humbug;
+
+    /**
+     * A comment.
+     * 
+     * @private
+     * @internal
+     */
+    class RegularClass
+    {
+        public function aMethod()
+        {
+        }
+    }
+
+    PHP,
+];

src/Configuration/Configuration.php

@@ -38,6 +38,7 @@ final class Configuration
      * @param array<string, array{string, string}> $excludedFilesWithContents Array of tuple
      *                                                                        with the first argument being the file path and
      *                                                                        the second its contents
+     * @param bool                                 $tagDeclarationsAsInternal Whether a @internal tag should be added to the symbols declarations.
      */
     public function __construct(
         private ?string $path,
@@ -46,7 +47,8 @@ public function __construct(
         private array $filesWithContents,
         private array $excludedFilesWithContents,
         private Patcher $patcher,
-        private SymbolsConfiguration $symbolsConfiguration
+        private SymbolsConfiguration $symbolsConfiguration,
+        private bool $tagDeclarationsAsInternal,
     ) {
         self::validatePrefix($prefix);
 
@@ -82,6 +84,7 @@ public function withPrefix(string $prefix): self
             $this->excludedFilesWithContents,
             $this->patcher,
             $this->symbolsConfiguration,
+            $this->tagDeclarationsAsInternal,
         );
     }
 
@@ -106,6 +109,7 @@ public function withFilesWithContents(array $filesWithContents): self
             $this->excludedFilesWithContents,
             $this->patcher,
             $this->symbolsConfiguration,
+            $this->tagDeclarationsAsInternal,
         );
     }
 
@@ -135,6 +139,7 @@ public function withPatcher(Patcher $patcher): self
             $this->excludedFilesWithContents,
             $patcher,
             $this->symbolsConfiguration,
+            $this->tagDeclarationsAsInternal,
         );
     }
 
@@ -148,6 +153,11 @@ public function getSymbolsConfiguration(): SymbolsConfiguration
         return $this->symbolsConfiguration;
     }
 
+    public function shouldTagDeclarationsAsInternal(): bool
+    {
+        return $this->tagDeclarationsAsInternal;
+    }
+
     private static function validatePrefix(string $prefix): void
     {
         if (1 !== preg_match(self::PREFIX_PATTERN, $prefix)) {

src/Configuration/ConfigurationFactory.php

@@ -96,6 +96,7 @@ public function create(?string $path = null, array $paths = []): Configuration
         $finders = self::retrieveFinders($config);
         $filesFromPaths = self::retrieveFilesFromPaths($paths);
         $filesWithContents = self::retrieveFilesWithContents(chain($filesFromPaths, ...$finders));
+        $tagDeclarationsAsInternal = $config[ConfigurationKeys::TAG_DECLARATIONS_AS_INTERNAL] ?? true;
 
         return new Configuration(
             $path,
@@ -105,6 +106,7 @@ public function create(?string $path = null, array $paths = []): Configuration
             self::retrieveFilesWithContents($excludedFiles),
             new PatcherChain($patchers),
             $symbolsConfiguration,
+            $tagDeclarationsAsInternal,
         );
     }
 

src/Configuration/ConfigurationKeys.php

@@ -25,6 +25,7 @@ final class ConfigurationKeys
     public const EXCLUDED_FILES_KEYWORD = 'exclude-files';
     public const FINDER_KEYWORD = 'finders';
     public const PATCHERS_KEYWORD = 'patchers';
+    public const TAG_DECLARATIONS_AS_INTERNAL = 'tag-declarations-as-internal';
 
     public const EXPOSE_GLOBAL_CONSTANTS_KEYWORD = 'expose-global-constants';
     public const EXPOSE_GLOBAL_CLASSES_KEYWORD = 'expose-global-classes';
@@ -46,6 +47,7 @@ final class ConfigurationKeys
         self::EXCLUDED_FILES_KEYWORD,
         self::FINDER_KEYWORD,
         self::PATCHERS_KEYWORD,
+        self::TAG_DECLARATIONS_AS_INTERNAL,
         self::EXPOSE_GLOBAL_CONSTANTS_KEYWORD,
         self::EXPOSE_GLOBAL_CLASSES_KEYWORD,
         self::EXPOSE_GLOBAL_FUNCTIONS_KEYWORD,