Merge pull request #3486 from phpDocumentor/collect-files-and-indexes…

…-in-api-set Collect files and indexes in API Documentation Set
phpDocumentor · Mar 22, 2023 · 7068b5c · 7068b5c
2 parents 2597b8a + 9a251a4
commit 7068b5c
Show file tree

Hide file tree

Showing 13 changed files with 58 additions and 70 deletions.
diff --git a/src/phpDocumentor/Descriptor/Builder/Reflector/ClassAssembler.php b/src/phpDocumentor/Descriptor/Builder/Reflector/ClassAssembler.php
@@ -48,7 +48,7 @@ public function create(object $data): ClassInterface
         $classDescriptor->setFullyQualifiedStructuralElementName($data->getFqsen());
         $classDescriptor->setName($data->getName());
         $classDescriptor->setPackage(
-            $this->extractPackageFromDocBlock($data->getDocBlock()) ?? $this->getBuilder()->getDefaultPackage()
+            $this->extractPackageFromDocBlock($data->getDocBlock()) ?? $this->getBuilder()->getDefaultPackageName()
         );
         $classDescriptor->setStartLocation($data->getLocation());
         $classDescriptor->setEndLocation($data->getEndLocation());

diff --git a/src/phpDocumentor/Descriptor/Builder/Reflector/EnumAssembler.php b/src/phpDocumentor/Descriptor/Builder/Reflector/EnumAssembler.php
@@ -44,7 +44,7 @@ protected function buildDescriptor(object $data): EnumInterface
         $descriptor->setFullyQualifiedStructuralElementName($data->getFqsen());
         $descriptor->setName($data->getName());
         $descriptor->setPackage(
-            $this->extractPackageFromDocBlock($data->getDocBlock()) ?? $this->getBuilder()->getDefaultPackage()
+            $this->extractPackageFromDocBlock($data->getDocBlock()) ?? $this->getBuilder()->getDefaultPackageName()
         );
         $descriptor->setStartLocation($data->getLocation());
         $descriptor->setEndLocation($data->getEndLocation());

diff --git a/src/phpDocumentor/Descriptor/Builder/Reflector/FileAssembler.php b/src/phpDocumentor/Descriptor/Builder/Reflector/FileAssembler.php
@@ -53,7 +53,7 @@ public function create(object $data): FileInterface
     {
         $fileDescriptor = new FileDescriptor($data->getHash());
         $fileDescriptor->setPackage(
-            $this->extractPackageFromDocBlock($data->getDocBlock()) ?? $this->getBuilder()->getDefaultPackage()
+            $this->extractPackageFromDocBlock($data->getDocBlock()) ?? $this->getBuilder()->getDefaultPackageName()
         );
 
         $fileDescriptor->setName($data->getName());
@@ -245,7 +245,7 @@ protected function overridePackageTag(File $data, FileInterface $fileDescriptor)
         $packages = Collection::fromClassString(TagDescriptor::class);
         $package  = $this->extractPackageFromDocBlock($data->getDocBlock());
         if (!$package) {
-            $package = $this->getBuilder()->getDefaultPackage();
+            $package = $this->getBuilder()->getDefaultPackageName();
         }
 
         $tag = new TagDescriptor('package');

diff --git a/src/phpDocumentor/Descriptor/ProjectDescriptorBuilder.php b/src/phpDocumentor/Descriptor/ProjectDescriptorBuilder.php
@@ -46,8 +46,9 @@ class ProjectDescriptorBuilder
     /** @var iterable<WithCustomSettings> */
     private $servicesWithCustomSettings;
 
-    /** @var ApiSpecification */
-    private $apiSpecification;
+    private ApiSpecification $apiSpecification;
+
+    private string $defaultPackageName;
 
     /**
      * @param iterable<WithCustomSettings> $servicesWithCustomSettings
@@ -65,6 +66,10 @@ public function __construct(
     public function createProjectDescriptor(): void
     {
         $this->project = new ProjectDescriptor(self::DEFAULT_PROJECT_NAME);
+
+        // Ensure all custom settings from other services are loaded, even if no other custom settings will
+        // be set later on.
+        $this->setCustomSettings([]);
     }
 
     /**
@@ -125,20 +130,6 @@ public function getAssembler(object $data, string $type): ?AssemblerInterface
         return $this->assemblerFactory->get($data, $type);
     }
 
-    /**
-     * Analyzes a Descriptor and alters its state based on its state or even removes the descriptor.
-     *
-     * @param TDescriptor $descriptor
-     *
-     * @return TDescriptor|null
-     *
-     * @template TDescriptor as Filterable
-     */
-    public function filter(Filterable $descriptor): ?Filterable
-    {
-        return $this->filter->filter($descriptor, $this->apiSpecification);
-    }
-
     /**
      * Filters a descriptor, validates it, stores the validation results and returns the transmuted object or null
      * if it is supposed to be removed.
@@ -156,43 +147,28 @@ protected function filterDescriptor(Descriptor $descriptor): ?Descriptor
         }
 
         // filter the descriptor; this may result in the descriptor being removed!
-        $descriptor = $this->filter($descriptor);
+        $descriptor = $this->filter->filter($descriptor, $this->apiSpecification);
 
         return $descriptor;
     }
 
-    public function setApiSpecification(ApiSpecification $apiSpecification): void
+    public function usingApiSpecification(ApiSpecification $apiSpecification): void
     {
-        // TODO: Any change in the API Specification compared to a previous (cached) run should invalidate that cache.
         $this->apiSpecification = $apiSpecification;
-
-        // TODO: The setVisibility call should purge the cache; but once we are here, cache has already been loaded..
-        $this->setVisibility($apiSpecification->calculateVisiblity());
     }
 
-    public function createApiDocumentationSet(Project $project): void
+    public function populateApiDocumentationSet(ApiSetDescriptor $apiSet, Project $project): void
     {
-        $customSettings = $this->getProjectDescriptor()->getSettings()->getCustom();
-        foreach ($this->servicesWithCustomSettings as $service) {
-            // We assume that the custom settings have the non-default settings and we should not override those;
-            // that is why we merge the custom settings on top of the default settings; this will cause the overrides
-            // to remain in place.
-            $customSettings = array_merge($service->getDefaultSettings(), $customSettings);
-        }
-
-        // TODO: This call should purge the cache; but once we are here, cache has already been loaded..
-        $this->getProjectDescriptor()->getSettings()->setCustom($customSettings);
-
         foreach ($project->getFiles() as $file) {
             $descriptor = $this->buildDescriptor($file, FileDescriptor::class);
             if ($descriptor === null) {
                 continue;
             }
 
-            $this->getProjectDescriptor()->getFiles()->set($descriptor->getPath(), $descriptor);
+            $apiSet->getFiles()->set($descriptor->getPath(), $descriptor);
         }
 
-        $namespaces = $this->getProjectDescriptor()->getIndexes()->fetch('namespaces', new Collection());
+        $namespaces = $apiSet->getIndexes()->fetch('namespaces', new Collection());
 
         foreach ($project->getNamespaces() as $namespace) {
             $namespaces->set(
@@ -202,19 +178,19 @@ public function createApiDocumentationSet(Project $project): void
         }
     }
 
-    public function getDefaultPackage(): string
+    public function usingDefaultPackageName(string $name): void
     {
-        return $this->apiSpecification['default-package-name'];
+        $this->defaultPackageName = $name;
     }
 
-    public function setVisibility(int $visibility): void
+    public function getDefaultPackageName(): string
     {
-        $this->project->getSettings()->setVisibility($visibility);
+        return $this->defaultPackageName;
     }
 
-    public function shouldIncludeSource(): bool
+    public function setVisibility(int $visibility): void
     {
-        return $this->apiSpecification['include-source'];
+        $this->project->getSettings()->setVisibility($visibility);
     }
 
     public function setName(string $title): void
@@ -235,6 +211,13 @@ public function setPartials(Collection $partials): void
      */
     public function setCustomSettings(array $customSettings): void
     {
+        foreach ($this->servicesWithCustomSettings as $service) {
+            // We assume that the custom settings have the non-default settings and we should not override those;
+            // that is why we merge the custom settings on top of the default settings; this will cause the overrides
+            // to remain in place.
+            $customSettings = array_merge($service->getDefaultSettings(), $customSettings);
+        }
+
         $this->project->getSettings()->setCustom($customSettings);
     }
 

diff --git a/src/phpDocumentor/Pipeline/Stage/ParseApiDocumentationSets.php b/src/phpDocumentor/Pipeline/Stage/ParseApiDocumentationSets.php
@@ -14,7 +14,7 @@
 namespace phpDocumentor\Pipeline\Stage;
 
 use League\Pipeline\Pipeline;
-use phpDocumentor\Configuration\VersionSpecification;
+use phpDocumentor\Descriptor\ApiSetDescriptor;
 
 final class ParseApiDocumentationSets
 {
@@ -27,13 +27,12 @@ public function __construct(Pipeline $parseApiDocumentationSetPipeline)
 
     public function __invoke(Payload $payload): Payload
     {
-        /** @var VersionSpecification[] $versions */
-        $versions = $payload->getConfig()['phpdocumentor']['versions'];
+        $versions = $payload->getBuilder()->getProjectDescriptor()->getVersions();
 
         foreach ($versions as $version) {
-            foreach ($version->getApi() as $apiSpecification) {
+            foreach ($version->getDocumentationSets()->filter(ApiSetDescriptor::class) as $apiSet) {
                 $this->parseApiDocumentationSetPipeline->process(
-                    new Parser\ApiSetPayload($payload->getConfig(), $payload->getBuilder(), $apiSpecification)
+                    new Parser\ApiSetPayload($payload->getConfig(), $payload->getBuilder(), $apiSet)
                 );
             }
         }

diff --git a/src/phpDocumentor/Pipeline/Stage/Parser/ApiSetPayload.php b/src/phpDocumentor/Pipeline/Stage/Parser/ApiSetPayload.php
@@ -13,8 +13,8 @@
 
 namespace phpDocumentor\Pipeline\Stage\Parser;
 
-use phpDocumentor\Configuration\ApiSpecification;
 use phpDocumentor\Configuration\Configuration;
+use phpDocumentor\Descriptor\ApiSetDescriptor;
 use phpDocumentor\Descriptor\ProjectDescriptorBuilder;
 use phpDocumentor\Reflection\File;
 
@@ -28,7 +28,7 @@ final class ApiSetPayload
     /** @var ConfigurationMap */
     private array $configuration;
     private ProjectDescriptorBuilder $builder;
-    private ApiSpecification $specification;
+    private ApiSetDescriptor $apiSet;
 
     /** @var File[] */
     private array $files;
@@ -40,12 +40,12 @@ final class ApiSetPayload
     public function __construct(
         array $configuration,
         ProjectDescriptorBuilder $builder,
-        ApiSpecification $specification,
+        ApiSetDescriptor $apiSet,
         array $files = []
     ) {
         $this->configuration = $configuration;
         $this->builder = $builder;
-        $this->specification = $specification;
+        $this->apiSet = $apiSet;
 
         $this->files = $files;
     }
@@ -63,9 +63,9 @@ public function getBuilder(): ProjectDescriptorBuilder
         return $this->builder;
     }
 
-    public function getSpecification(): ApiSpecification
+    public function getApiSet(): ApiSetDescriptor
     {
-        return $this->specification;
+        return $this->apiSet;
     }
 
     /**
@@ -76,7 +76,7 @@ public function withFiles(array $files): self
         return new static(
             $this->getConfiguration(),
             $this->getBuilder(),
-            $this->getSpecification(),
+            $this->getApiSet(),
             array_merge($this->getFiles(), $files)
         );
     }

diff --git a/src/phpDocumentor/Pipeline/Stage/Parser/CollectFiles.php b/src/phpDocumentor/Pipeline/Stage/Parser/CollectFiles.php
@@ -31,7 +31,7 @@ public function __construct(FileCollector $fileCollector, LoggerInterface $logge
 
     public function __invoke(ApiSetPayload $payload): ApiSetPayload
     {
-        $apiConfig = $payload->getSpecification();
+        $apiConfig = $payload->getApiSet()->getSettings();
         $this->logger->info('Collecting files from ' . $apiConfig->source()->dsn());
 
         $files = $this->fileCollector->getFiles(

diff --git a/src/phpDocumentor/Pipeline/Stage/Parser/ParseFiles.php b/src/phpDocumentor/Pipeline/Stage/Parser/ParseFiles.php
@@ -35,10 +35,15 @@ public function __construct(
 
     public function __invoke(ApiSetPayload $payload): ApiSetPayload
     {
-        $apiConfig = $payload->getSpecification();
+        $apiConfig = $payload->getApiSet()->getSettings();
 
         $builder = $payload->getBuilder();
-        $builder->setApiSpecification($apiConfig);
+        $builder->usingApiSpecification($apiConfig);
+        $builder->usingDefaultPackageName($apiConfig['default-package-name'] ?? '');
+
+        // TODO: The setVisibility call should purge the cache if it differs; but once we are here, cache has already
+        //       been loaded..
+        $payload->getBuilder()->setVisibility($apiConfig->calculateVisiblity());
 
         $encoding = $apiConfig['encoding'] ?? '';
         if ($encoding) {
@@ -47,12 +52,13 @@ public function __invoke(ApiSetPayload $payload): ApiSetPayload
 
         $this->parser->setMarkers($apiConfig['markers'] ?? []);
         $this->parser->setValidate(($apiConfig['validate'] ?? 'false') === 'true');
-        $this->parser->setDefaultPackageName($apiConfig['default-package-name'] ?? '');
+        $this->parser->setDefaultPackageName($builder->getDefaultPackageName());
 
         $this->logger->notice('Parsing files');
-        $project = $this->parser->parse($payload->getFiles());
-
-        $payload->getBuilder()->createApiDocumentationSet($project);
+        $payload->getBuilder()->populateApiDocumentationSet(
+            $payload->getApiSet(),
+            $this->parser->parse($payload->getFiles())
+        );
 
         return $payload;
     }

diff --git a/tests/unit/phpDocumentor/Descriptor/Builder/Reflector/ClassAssemblerTest.php b/tests/unit/phpDocumentor/Descriptor/Builder/Reflector/ClassAssemblerTest.php
@@ -146,7 +146,7 @@ protected function getClassReflectorDescriptor(?Fqsen $classFqsen = null, ?Fqsen
     protected function getProjectDescriptorBuilderMock(): ObjectProphecy
     {
         $projectDescriptorBuilderMock = $this->prophesize(ProjectDescriptorBuilder::class);
-        $projectDescriptorBuilderMock->getDefaultPackage()->shouldBeCalled()->willReturn('\\');
+        $projectDescriptorBuilderMock->getDefaultPackageName()->shouldBeCalled()->willReturn('\\');
         $projectDescriptorBuilderMock->buildDescriptor(Argument::any(), Argument::any())->will(function ($param) {
             switch ($param) {
                 case 'Method':

diff --git a/tests/unit/phpDocumentor/Descriptor/Builder/Reflector/EnumAssemblerTest.php b/tests/unit/phpDocumentor/Descriptor/Builder/Reflector/EnumAssemblerTest.php
@@ -34,7 +34,7 @@ public function setUp(): void
     {
         $this->assembler = new EnumAssembler();
         $this->builder = $this->prophesize(ProjectDescriptorBuilder::class);
-        $this->builder->getDefaultPackage()->willReturn('test');
+        $this->builder->getDefaultPackageName()->willReturn('test');
         $this->assembler->setBuilder($this->builder->reveal());
     }
 

diff --git a/tests/unit/phpDocumentor/Descriptor/Builder/Reflector/FileAssemblerTest.php b/tests/unit/phpDocumentor/Descriptor/Builder/Reflector/FileAssemblerTest.php
@@ -92,7 +92,7 @@ protected function getProjectDescriptorBuilderMock(): ObjectProphecy
         $settings->includeSource();
 
         $projectDescriptorBuilderMock = $this->prophesize(ProjectDescriptorBuilder::class);
-        $projectDescriptorBuilderMock->getDefaultPackage()->shouldBeCalled()->willReturn($this->defaultPackage);
+        $projectDescriptorBuilderMock->getDefaultPackageName()->shouldBeCalled()->willReturn($this->defaultPackage);
 
         $projectDescriptorBuilderMock->buildDescriptor(Argument::any(), Argument::any())->will(function () {
             $mock = $this->prophesize(DescriptorAbstract::class);

diff --git a/tests/unit/phpDocumentor/Pipeline/Stage/Cache/GarbageCollectCacheTest.php b/tests/unit/phpDocumentor/Pipeline/Stage/Cache/GarbageCollectCacheTest.php
@@ -46,7 +46,7 @@ public function testItWillInstructTheDescriptorMapperToCollectGarbage(): void
             new ApiSetPayload(
                 [],
                 $this->prophesize(ProjectDescriptorBuilder::class)->reveal(),
-                $this->faker()->apiSpecification(),
+                $this->faker()->apiSetDescriptor(),
                 $files
             )
         );

diff --git a/tests/unit/phpDocumentor/Pipeline/Stage/Parser/CollectFilesTest.php b/tests/unit/phpDocumentor/Pipeline/Stage/Parser/CollectFilesTest.php
@@ -59,7 +59,7 @@ public function testFilesAreCollectedAndAddedToPayload(): void
         $payload = new ApiSetPayload(
             ['phpdocumentor' => ['versions' => ['1.0.0' => $version]]],
             $this->prophesize(ProjectDescriptorBuilder::class)->reveal(),
-            $this->faker()->apiSpecification()
+            $this->faker()->apiSetDescriptor()
         );
 
         $result = $fixture($payload);