Skip to content

Commit 24f1f0c

Browse files
jaapiojaapio
authored
Merge pull request #1334 from lacatoire/deprecate/specification-interface-file-collector
Deprecate SpecificationInterface in FileCollector and ParseDirectoryCommand
2 parents a233106 + 3ef741c commit 24f1f0c

6 files changed

Lines changed: 303 additions & 9 deletions

File tree

‎packages/guides/src/FileCollector.php‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@
1313

1414
namespace phpDocumentor\Guides;
1515

16+
use Doctrine\Deprecations\Deprecation;
1617
use Flyfinder\Specification\AndSpecification;
1718
use Flyfinder\Specification\HasExtension;
1819
use Flyfinder\Specification\InPath;
@@ -49,10 +50,22 @@ public function __construct(SpecificationFactoryInterface|null $specificationFac
4950
* objects, and avoids adding files to the parse queue that have
5051
* not changed and whose direct dependencies have not changed.
5152
*
52-
* @param SpecificationInterface|Exclude|null $excludedSpecification specification that is used to exclude specific files/directories
53+
* @param SpecificationInterface|Exclude|null $excludedSpecification specification that is used to exclude specific files/directories.
54+
* Passing a {@see SpecificationInterface} is deprecated, use {@see Exclude} instead.
5355
*/
5456
public function collect(FilesystemInterface|FileSystem $filesystem, string $directory, string $extension, SpecificationInterface|Exclude|null $excludedSpecification = null): Files
5557
{
58+
if ($excludedSpecification instanceof SpecificationInterface) {
59+
Deprecation::triggerIfCalledFromOutside(
60+
'phpdocumentor/guides',
61+
'https://github.com/phpDocumentor/guides/issues/1209',
62+
'Passing %s to %s::collect() is deprecated, use %s instead.',
63+
$excludedSpecification::class,
64+
self::class,
65+
Exclude::class,
66+
);
67+
}
68+
5669
$directory = trim($directory, '/');
5770
$specification = $this->getSpecification($excludedSpecification, $directory, $extension);
5871

‎packages/guides/src/Handlers/ParseDirectoryCommand.php‎

Lines changed: 15 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -34,10 +34,12 @@ public function __construct(
3434
) {
3535
if ($excludedSpecification instanceof SpecificationInterface) {
3636
Deprecation::trigger(
37-
'phpDocumentor/guides',
37+
'phpdocumentor/guides',
3838
'https://github.com/phpDocumentor/guides/issues/1209',
39-
'Passing ' . $excludedSpecification::class . ' to ' . self::class . 'will be deprecated,'
40-
. 'use phpDocumentor\FileSystem\Finder\Exclude instead.',
39+
'Passing %s to %s is deprecated, use %s instead.',
40+
$excludedSpecification::class,
41+
self::class,
42+
Exclude::class,
4143
);
4244
$this->excludedSpecification = $excludedSpecification;
4345
$this->exclude = null;
@@ -67,16 +69,16 @@ public function getProjectNode(): ProjectNode
6769
return $this->projectNode;
6870
}
6971

70-
/** @deprecated Specification definition on parse directory is deprecated. Use @{see self::getExclude()} instead.*/
72+
/** @deprecated Specification definition on parse directory is deprecated. Use {@see self::getExclude()} instead. */
7173
public function getExcludedSpecification(): SpecificationInterface|null
7274
{
73-
Deprecation::trigger(
74-
'phpDocumentor/guides',
75+
Deprecation::triggerIfCalledFromOutside(
76+
'phpdocumentor/guides',
7577
'https://github.com/phpDocumentor/guides/issues/1209',
7678
'Specification definition on parse directory is deprecated. Use getExclude() instead.',
7779
);
7880

79-
return $this->excludedSpecification ?? null;
81+
return $this->excludedSpecification;
8082
}
8183

8284
public function getExclude(): Exclude
@@ -88,4 +90,10 @@ public function hasExclude(): bool
8890
{
8991
return isset($this->exclude);
9092
}
93+
94+
/** @internal Used by {@see ParseDirectoryHandler} to dispatch without triggering the deprecation on {@see self::getExcludedSpecification()}. */
95+
public function hasExcludedSpecification(): bool
96+
{
97+
return isset($this->excludedSpecification);
98+
}
9199
}

‎packages/guides/src/Handlers/ParseDirectoryHandler.php‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -69,7 +69,11 @@ public function handle(ParseDirectoryCommand $command): array
6969
$origin,
7070
$currentDirectory,
7171
$extension,
72-
$command->hasExclude() ? $command->getExclude() : $command->getExcludedSpecification(),
72+
match (true) {
73+
$command->hasExclude() => $command->getExclude(),
74+
$command->hasExcludedSpecification() => $command->getExcludedSpecification(),
75+
default => null,
76+
},
7377
);
7478

7579
$postCollectFilesForParsingEvent = $this->eventDispatcher->dispatch(

‎packages/guides/tests/unit/FileCollectorTest.php‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
/**
6+
* This file is part of phpDocumentor.
7+
*
8+
* For the full copyright and license information, please view the LICENSE
9+
* file that was distributed with this source code.
10+
*
11+
* @link https://phpdoc.org
12+
*/
13+
14+
namespace phpDocumentor\Guides;
15+
16+
use Doctrine\Deprecations\Deprecation;
17+
use Flyfinder\Path;
18+
use Flyfinder\Specification\InPath;
19+
use phpDocumentor\FileSystem\FileSystem;
20+
use phpDocumentor\FileSystem\Finder\Exclude;
21+
use PHPUnit\Framework\TestCase;
22+
23+
final class FileCollectorTest extends TestCase
24+
{
25+
public function testCollectDoesNotTriggerDeprecationWhenNoExclusionIsPassed(): void
26+
{
27+
$filesystem = $this->createMock(FileSystem::class);
28+
$filesystem->method('find')->willReturn([]);
29+
30+
$before = Deprecation::getUniqueTriggeredDeprecationsCount();
31+
32+
(new FileCollector())->collect($filesystem, 'docs', 'rst');
33+
34+
self::assertSame($before, Deprecation::getUniqueTriggeredDeprecationsCount());
35+
}
36+
37+
public function testCollectDoesNotTriggerDeprecationWhenExcludeIsPassed(): void
38+
{
39+
$filesystem = $this->createMock(FileSystem::class);
40+
$filesystem->method('find')->willReturn([]);
41+
42+
$before = Deprecation::getUniqueTriggeredDeprecationsCount();
43+
44+
(new FileCollector())->collect($filesystem, '', 'rst', new Exclude());
45+
46+
self::assertSame($before, Deprecation::getUniqueTriggeredDeprecationsCount());
47+
}
48+
49+
public function testCollectTriggersDeprecationWhenSpecificationInterfaceIsPassed(): void
50+
{
51+
$filesystem = $this->createMock(FileSystem::class);
52+
$filesystem->method('find')->willReturn([]);
53+
54+
$before = Deprecation::getUniqueTriggeredDeprecationsCount();
55+
56+
(new FileCollector())->collect(
57+
$filesystem,
58+
'docs',
59+
'rst',
60+
new InPath(new Path('docs')),
61+
);
62+
63+
self::assertSame(
64+
$before + 1,
65+
Deprecation::getUniqueTriggeredDeprecationsCount(),
66+
);
67+
}
68+
}

‎packages/guides/tests/unit/Handlers/ParseDirectoryCommandTest.php‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
/**
6+
* This file is part of phpDocumentor.
7+
*
8+
* For the full copyright and license information, please view the LICENSE
9+
* file that was distributed with this source code.
10+
*
11+
* @link https://phpdoc.org
12+
*/
13+
14+
namespace phpDocumentor\Guides\Handlers;
15+
16+
use Doctrine\Deprecations\Deprecation;
17+
use Flyfinder\Path;
18+
use Flyfinder\Specification\InPath;
19+
use League\Flysystem\FilesystemInterface;
20+
use phpDocumentor\FileSystem\Finder\Exclude;
21+
use phpDocumentor\Guides\Nodes\ProjectNode;
22+
use PHPUnit\Framework\TestCase;
23+
24+
final class ParseDirectoryCommandTest extends TestCase
25+
{
26+
public function testNoDeprecationIsTriggeredWhenNoExclusionIsPassed(): void
27+
{
28+
$before = Deprecation::getUniqueTriggeredDeprecationsCount();
29+
30+
$command = new ParseDirectoryCommand(
31+
$this->createMock(FilesystemInterface::class),
32+
'docs',
33+
'rst',
34+
new ProjectNode(),
35+
);
36+
37+
self::assertSame($before, Deprecation::getUniqueTriggeredDeprecationsCount());
38+
self::assertFalse($command->hasExclude());
39+
self::assertFalse($command->hasExcludedSpecification());
40+
}
41+
42+
public function testNoDeprecationIsTriggeredWhenExcludeIsPassed(): void
43+
{
44+
$before = Deprecation::getUniqueTriggeredDeprecationsCount();
45+
46+
$command = new ParseDirectoryCommand(
47+
$this->createMock(FilesystemInterface::class),
48+
'docs',
49+
'rst',
50+
new ProjectNode(),
51+
new Exclude(),
52+
);
53+
54+
self::assertSame($before, Deprecation::getUniqueTriggeredDeprecationsCount());
55+
self::assertTrue($command->hasExclude());
56+
self::assertFalse($command->hasExcludedSpecification());
57+
}
58+
59+
public function testDeprecationIsTriggeredWhenSpecificationInterfaceIsPassed(): void
60+
{
61+
$before = Deprecation::getUniqueTriggeredDeprecationsCount();
62+
63+
$command = new ParseDirectoryCommand(
64+
$this->createMock(FilesystemInterface::class),
65+
'docs',
66+
'rst',
67+
new ProjectNode(),
68+
new InPath(new Path('docs')),
69+
);
70+
71+
self::assertSame(
72+
$before + 1,
73+
Deprecation::getUniqueTriggeredDeprecationsCount(),
74+
);
75+
self::assertFalse($command->hasExclude());
76+
self::assertTrue($command->hasExcludedSpecification());
77+
}
78+
79+
public function testGetExcludeReturnsEmptyExcludeWhenNoneWasPassed(): void
80+
{
81+
$command = new ParseDirectoryCommand(
82+
$this->createMock(FilesystemInterface::class),
83+
'docs',
84+
'rst',
85+
new ProjectNode(),
86+
);
87+
88+
self::assertEquals(new Exclude(), $command->getExclude());
89+
}
90+
91+
public function testGetExcludedSpecificationReturnsTheStoredSpecification(): void
92+
{
93+
$specification = new InPath(new Path('docs'));
94+
$command = new ParseDirectoryCommand(
95+
$this->createMock(FilesystemInterface::class),
96+
'docs',
97+
'rst',
98+
new ProjectNode(),
99+
$specification,
100+
);
101+
102+
self::assertSame($specification, $command->getExcludedSpecification());
103+
}
104+
}

‎packages/guides/tests/unit/Handlers/ParseDirectoryHandlerTest.php‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
/**
6+
* This file is part of phpDocumentor.
7+
*
8+
* For the full copyright and license information, please view the LICENSE
9+
* file that was distributed with this source code.
10+
*
11+
* @link https://phpdoc.org
12+
*/
13+
14+
namespace phpDocumentor\Guides\Handlers;
15+
16+
use Doctrine\Deprecations\Deprecation;
17+
use Flyfinder\Path;
18+
use Flyfinder\Specification\InPath;
19+
use League\Tactician\CommandBus;
20+
use phpDocumentor\FileSystem\FileSystem;
21+
use phpDocumentor\FileSystem\Finder\Exclude;
22+
use phpDocumentor\Guides\FileCollector;
23+
use phpDocumentor\Guides\Nodes\ProjectNode;
24+
use PHPUnit\Framework\TestCase;
25+
use Psr\EventDispatcher\EventDispatcherInterface;
26+
27+
final class ParseDirectoryHandlerTest extends TestCase
28+
{
29+
public function testHandlerForwardsExcludeToCollectorWithoutTriggeringSpecificationDeprecation(): void
30+
{
31+
$command = $this->createCommand(new Exclude(['/excluded']));
32+
$handler = $this->createHandler();
33+
34+
$before = Deprecation::getUniqueTriggeredDeprecationsCount();
35+
36+
$handler->handle($command);
37+
38+
self::assertSame($before, Deprecation::getUniqueTriggeredDeprecationsCount());
39+
}
40+
41+
public function testHandlerDoesNotTriggerDeprecationWhenNoExclusionIsConfigured(): void
42+
{
43+
$command = $this->createCommand();
44+
$handler = $this->createHandler();
45+
46+
$before = Deprecation::getUniqueTriggeredDeprecationsCount();
47+
48+
$handler->handle($command);
49+
50+
self::assertSame($before, Deprecation::getUniqueTriggeredDeprecationsCount());
51+
}
52+
53+
public function testHandlerForwardsLegacySpecificationWithoutFiringExtraDeprecation(): void
54+
{
55+
$command = $this->createCommand(new InPath(new Path('docs')));
56+
$handler = $this->createHandler();
57+
58+
$before = Deprecation::getUniqueTriggeredDeprecationsCount();
59+
60+
$handler->handle($command);
61+
62+
self::assertSame(
63+
$before,
64+
Deprecation::getUniqueTriggeredDeprecationsCount(),
65+
'Internal handler dispatch must not re-fire the deprecation already raised at construction.',
66+
);
67+
}
68+
69+
private function createCommand(Exclude|InPath|null $exclusion = null): ParseDirectoryCommand
70+
{
71+
$filesystem = $this->createMock(FileSystem::class);
72+
$filesystem->method('listContents')->willReturn([['basename' => 'index.rst']]);
73+
$filesystem->method('find')->willReturn([]);
74+
75+
return new ParseDirectoryCommand(
76+
$filesystem,
77+
'',
78+
'rst',
79+
new ProjectNode(),
80+
$exclusion,
81+
);
82+
}
83+
84+
private function createHandler(): ParseDirectoryHandler
85+
{
86+
$eventDispatcher = $this->createMock(EventDispatcherInterface::class);
87+
$eventDispatcher->method('dispatch')->willReturnCallback(
88+
static fn (object $event): object => $event,
89+
);
90+
91+
return new ParseDirectoryHandler(
92+
new FileCollector(),
93+
$this->createMock(CommandBus::class),
94+
$eventDispatcher,
95+
);
96+
}
97+
}

0 commit comments

Comments
 (0)