Skip to content

Commit 7dbccc0

Browse files
theofidrytheofidry
authored
feat: Mark all declarations as internal (humbug#882)
This should allow IDEs such as PHPStorm to honour the tag and avoid showing the results in the auto-complete. Closes humbug#861.
1 parent 2713ec1 commit 7dbccc0

14 files changed

+378
-7
lines changed

‎specs/misc/internal-declarations.php

+223
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,223 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
/*
6+
* This file is part of the humbug/php-scoper package.
7+
*
8+
* Copyright (c) 2017 Théo FIDRY <theo.fidry@gmail.com>,
9+
* Pádraic Brady <padraic.brady@gmail.com>
10+
*
11+
* For the full copyright and license information, please view the LICENSE
12+
* file that was distributed with this source code.
13+
*/
14+
15+
return [
16+
'meta' => [
17+
'title' => 'It adds @internal annotations to all declarations',
18+
// Default values. If not specified will be the one used
19+
'prefix' => 'Humbug',
20+
21+
'tag-declarations-as-internal' => true,
22+
23+
'expose-global-constants' => false,
24+
'expose-global-classes' => false,
25+
'expose-global-functions' => false,
26+
'expose-namespaces' => [],
27+
'expose-constants' => [],
28+
'expose-classes' => [],
29+
'expose-functions' => [],
30+
31+
'exclude-namespaces' => [],
32+
'exclude-constants' => [],
33+
'exclude-classes' => [],
34+
'exclude-functions' => [],
35+
36+
'expected-recorded-classes' => [],
37+
'expected-recorded-functions' => [],
38+
],
39+
40+
'Declarations without any comment' => <<<'PHP'
41+
<?php
42+
43+
class RegularClass {
44+
public function aMethod() {}
45+
}
46+
47+
interface RegularInterface {}
48+
49+
abstract class RegularAbstractClass {}
50+
51+
function regular_function () {}
52+
53+
trait RegularTrait {}
54+
55+
const REGULAR_CONSTANT = 'FOO';
56+
57+
enum RegularEnum {}
58+
59+
----
60+
<?php
61+
62+
namespace Humbug;
63+
64+
/** @internal */
65+
class RegularClass
66+
{
67+
public function aMethod()
68+
{
69+
}
70+
}
71+
/** @internal */
72+
interface RegularInterface
73+
{
74+
}
75+
/** @internal */
76+
abstract class RegularAbstractClass
77+
{
78+
}
79+
/** @internal */
80+
function regular_function()
81+
{
82+
}
83+
/** @internal */
84+
trait RegularTrait
85+
{
86+
}
87+
/** @internal */
88+
const REGULAR_CONSTANT = 'FOO';
89+
/** @internal */
90+
enum RegularEnum
91+
{
92+
}
93+
94+
PHP,
95+
96+
'Declarations without with comments' => <<<'PHP'
97+
<?php
98+
99+
// Smth
100+
class RegularClass {
101+
public function aMethod() {}
102+
}
103+
----
104+
<?php
105+
106+
namespace Humbug;
107+
108+
// Smth
109+
/** @internal */
110+
class RegularClass
111+
{
112+
public function aMethod()
113+
{
114+
}
115+
}
116+
117+
PHP,
118+
119+
'Declarations with existing phpDoc' => <<<'PHP'
120+
<?php
121+
122+
/**
123+
* A comment.
124+
*/
125+
class RegularClass {
126+
public function aMethod() {}
127+
}
128+
----
129+
<?php
130+
131+
namespace Humbug;
132+
133+
/**
134+
* A comment.
135+
* @internal
136+
*/
137+
class RegularClass
138+
{
139+
public function aMethod()
140+
{
141+
}
142+
}
143+
144+
PHP,
145+
146+
'Declarations with inlined phpDoc' => <<<'PHP'
147+
<?php
148+
149+
/** A comment. */
150+
class RegularClass {
151+
public function aMethod() {}
152+
}
153+
----
154+
<?php
155+
156+
namespace Humbug;
157+
158+
/** A comment.
159+
* @internal
160+
*/
161+
class RegularClass
162+
{
163+
public function aMethod()
164+
{
165+
}
166+
}
167+
168+
PHP,
169+
170+
'Declarations with inlined phpDoc already containing the @internal tag' => <<<'PHP'
171+
<?php
172+
173+
/** @internal */
174+
class RegularClass {
175+
public function aMethod() {}
176+
}
177+
----
178+
<?php
179+
180+
namespace Humbug;
181+
182+
/** @internal */
183+
class RegularClass
184+
{
185+
public function aMethod()
186+
{
187+
}
188+
}
189+
190+
PHP,
191+
192+
'Declarations with existing phpDoc containing the @internal tag' => <<<'PHP'
193+
<?php
194+
195+
/**
196+
* A comment.
197+
*
198+
* @private
199+
* @internal
200+
*/
201+
class RegularClass {
202+
public function aMethod() {}
203+
}
204+
----
205+
<?php
206+
207+
namespace Humbug;
208+
209+
/**
210+
* A comment.
211+
*
212+
* @private
213+
* @internal
214+
*/
215+
class RegularClass
216+
{
217+
public function aMethod()
218+
{
219+
}
220+
}
221+
222+
PHP,
223+
];

‎src/Configuration/Configuration.php

+11-1
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@ final class Configuration
3838
* @param array<string, array{string, string}> $excludedFilesWithContents Array of tuple
3939
* with the first argument being the file path and
4040
* the second its contents
41+
* @param bool $tagDeclarationsAsInternal Whether a @internal tag should be added to the symbols declarations.
4142
*/
4243
public function __construct(
4344
private ?string $path,
@@ -46,7 +47,8 @@ public function __construct(
4647
private array $filesWithContents,
4748
private array $excludedFilesWithContents,
4849
private Patcher $patcher,
49-
private SymbolsConfiguration $symbolsConfiguration
50+
private SymbolsConfiguration $symbolsConfiguration,
51+
private bool $tagDeclarationsAsInternal,
5052
) {
5153
self::validatePrefix($prefix);
5254

@@ -82,6 +84,7 @@ public function withPrefix(string $prefix): self
8284
$this->excludedFilesWithContents,
8385
$this->patcher,
8486
$this->symbolsConfiguration,
87+
$this->tagDeclarationsAsInternal,
8588
);
8689
}
8790

@@ -106,6 +109,7 @@ public function withFilesWithContents(array $filesWithContents): self
106109
$this->excludedFilesWithContents,
107110
$this->patcher,
108111
$this->symbolsConfiguration,
112+
$this->tagDeclarationsAsInternal,
109113
);
110114
}
111115

@@ -135,6 +139,7 @@ public function withPatcher(Patcher $patcher): self
135139
$this->excludedFilesWithContents,
136140
$patcher,
137141
$this->symbolsConfiguration,
142+
$this->tagDeclarationsAsInternal,
138143
);
139144
}
140145

@@ -148,6 +153,11 @@ public function getSymbolsConfiguration(): SymbolsConfiguration
148153
return $this->symbolsConfiguration;
149154
}
150155

156+
public function shouldTagDeclarationsAsInternal(): bool
157+
{
158+
return $this->tagDeclarationsAsInternal;
159+
}
160+
151161
private static function validatePrefix(string $prefix): void
152162
{
153163
if (1 !== preg_match(self::PREFIX_PATTERN, $prefix)) {

‎src/Configuration/ConfigurationFactory.php

+2
Original file line numberDiff line numberDiff line change
@@ -96,6 +96,7 @@ public function create(?string $path = null, array $paths = []): Configuration
9696
$finders = self::retrieveFinders($config);
9797
$filesFromPaths = self::retrieveFilesFromPaths($paths);
9898
$filesWithContents = self::retrieveFilesWithContents(chain($filesFromPaths, ...$finders));
99+
$tagDeclarationsAsInternal = $config[ConfigurationKeys::TAG_DECLARATIONS_AS_INTERNAL] ?? true;
99100

100101
return new Configuration(
101102
$path,
@@ -105,6 +106,7 @@ public function create(?string $path = null, array $paths = []): Configuration
105106
self::retrieveFilesWithContents($excludedFiles),
106107
new PatcherChain($patchers),
107108
$symbolsConfiguration,
109+
$tagDeclarationsAsInternal,
108110
);
109111
}
110112

‎src/Configuration/ConfigurationKeys.php

+2
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ final class ConfigurationKeys
2525
public const EXCLUDED_FILES_KEYWORD = 'exclude-files';
2626
public const FINDER_KEYWORD = 'finders';
2727
public const PATCHERS_KEYWORD = 'patchers';
28+
public const TAG_DECLARATIONS_AS_INTERNAL = 'tag-declarations-as-internal';
2829

2930
public const EXPOSE_GLOBAL_CONSTANTS_KEYWORD = 'expose-global-constants';
3031
public const EXPOSE_GLOBAL_CLASSES_KEYWORD = 'expose-global-classes';
@@ -46,6 +47,7 @@ final class ConfigurationKeys
4647
self::EXCLUDED_FILES_KEYWORD,
4748
self::FINDER_KEYWORD,
4849
self::PATCHERS_KEYWORD,
50+
self::TAG_DECLARATIONS_AS_INTERNAL,
4951
self::EXPOSE_GLOBAL_CONSTANTS_KEYWORD,
5052
self::EXPOSE_GLOBAL_CLASSES_KEYWORD,
5153
self::EXPOSE_GLOBAL_FUNCTIONS_KEYWORD,

0 commit comments

Comments
 (0)