Add reducers to factories to support attributes

To make it easier to add reused paths reducers are introduced. These
will allow us to move steps in the production of elements to a separate
class that will make it easier to reuse the logic between factories.

Author: jaapio

src/phpDocumentor/Reflection/Php/Attribute.php

@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types=1);
+
+namespace phpDocumentor\Reflection\Php;
+
+use phpDocumentor\Reflection\Element;
+use phpDocumentor\Reflection\Fqsen;
+
+final class Attribute implements Element
+{
+    private Fqsen $fqsen;
+
+    /** @var CallArgument[] */
+    private array $arguments;
+
+    /** @param CallArgument[] $arguments */
+    public function __construct(Fqsen $fqsen, array $arguments)
+    {
+        $this->fqsen = $fqsen;
+        $this->arguments = $arguments;
+    }
+
+    public function getFqsen(): Fqsen
+    {
+        return $this->fqsen;
+    }
+
+    /** @return CallArgument[] */
+    public function getArguments(): array
+    {
+        return $this->arguments;
+    }
+
+    public function getName(): string
+    {
+        return $this->fqsen->getName();
+    }
+}

src/phpDocumentor/Reflection/Php/AttributeContainer.php

@@ -0,0 +1,10 @@
+<?php
+
+declare(strict_types=1);
+
+namespace phpDocumentor\Reflection\Php;
+
+interface AttributeContainer
+{
+    public function addAttribute(Attribute $attribute): void;
+}

src/phpDocumentor/Reflection/Php/CallArgument.php

@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+namespace phpDocumentor\Reflection\Php;
+
+final class CallArgument
+{
+    private string $value;
+
+    private ?string $name;
+
+    public function __construct(
+        string $value,
+        ?string $name = null
+    ) {
+        $this->value = $value;
+        $this->name = $name;
+    }
+
+    public function getValue(): string
+    {
+        return $this->value;
+    }
+
+    public function getName(): ?string
+    {
+        return $this->name;
+    }
+}

src/phpDocumentor/Reflection/Php/Class_.php

@@ -23,10 +23,11 @@
  * Descriptor representing a Class.
  */
 // @codingStandardsIgnoreStart
-final class Class_ implements Element, MetaDataContainerInterface
+final class Class_ implements Element, MetaDataContainerInterface, AttributeContainer
 // @codingStandardsIgnoreEnd
 {
     use MetadataContainer;
+    use HasAttributes;
 
     /** @var Fqsen Full Qualified Structural Element Name */
     private Fqsen $fqsen;

src/phpDocumentor/Reflection/Php/Constant.php

@@ -22,9 +22,10 @@
 /**
  * Descriptor representing a constant
  */
-final class Constant implements Element, MetaDataContainerInterface
+final class Constant implements Element, MetaDataContainerInterface, AttributeContainer
 {
     use MetadataContainer;
+    use HasAttributes;
 
     private Fqsen $fqsen;
 

src/phpDocumentor/Reflection/Php/EnumCase.php

@@ -10,9 +10,10 @@
 use phpDocumentor\Reflection\Location;
 use phpDocumentor\Reflection\Metadata\MetaDataContainer as MetaDataContainerInterface;
 
-final class EnumCase implements Element, MetaDataContainerInterface
+final class EnumCase implements Element, MetaDataContainerInterface, AttributeContainer
 {
     use MetadataContainer;
+    use HasAttributes;
 
     private Fqsen $fqsen;
 

src/phpDocumentor/Reflection/Php/Enum_.php

@@ -20,9 +20,10 @@
 use phpDocumentor\Reflection\Metadata\MetaDataContainer as MetaDataContainerInterface;
 use phpDocumentor\Reflection\Type;
 
-final class Enum_ implements Element, MetaDataContainerInterface
+final class Enum_ implements Element, MetaDataContainerInterface, AttributeContainer
 {
     use MetadataContainer;
+    use HasAttributes;
 
     /** @var Fqsen Full Qualified Structural Element Name */
     private Fqsen $fqsen;

src/phpDocumentor/Reflection/Php/Factory/AbstractFactory.php

@@ -16,6 +16,7 @@
 use InvalidArgumentException;
 use phpDocumentor\Reflection\DocBlock;
 use phpDocumentor\Reflection\DocBlockFactoryInterface;
+use phpDocumentor\Reflection\Php\Factory\Reducer\Reducer;
 use phpDocumentor\Reflection\Php\ProjectFactoryStrategy;
 use phpDocumentor\Reflection\Php\StrategyContainer;
 use phpDocumentor\Reflection\Types\Context;
@@ -31,9 +32,14 @@ abstract class AbstractFactory implements ProjectFactoryStrategy
 {
     private DocBlockFactoryInterface $docBlockFactory;
 
-    public function __construct(DocBlockFactoryInterface $docBlockFactory)
+    /** @var iterable<Reducer> */
+    private iterable $reducers;
+
+    /** @param iterable<Reducer> $recuders */
+    public function __construct(DocBlockFactoryInterface $docBlockFactory, iterable $recuders = [])
     {
         $this->docBlockFactory = $docBlockFactory;
+        $this->reducers = $recuders;
     }
 
     /**
@@ -55,7 +61,10 @@ public function create(ContextStack $context, object $object, StrategyContainer
             );
         }
 
-        $this->doCreate($context, $object, $strategies);
+        $element = $this->doCreate($context, $object, $strategies);
+        foreach ($this->reducers as $reducer) {
+            $element = $reducer->reduce($context, $object, $strategies, $element);
+        }
     }
 
     /**
@@ -66,7 +75,7 @@ public function create(ContextStack $context, object $object, StrategyContainer
      *
      * @param NodeAbstract|object $object object to convert to an Element
      */
-    abstract protected function doCreate(ContextStack $context, object $object, StrategyContainer $strategies): void;
+    abstract protected function doCreate(ContextStack $context, object $object, StrategyContainer $strategies): ?object;
 
     protected function createDocBlock(?Doc $docBlock = null, ?Context $context = null): ?DocBlock
     {

src/phpDocumentor/Reflection/Php/Factory/Argument.php

@@ -29,7 +29,7 @@
  * @see ArgumentDescriptor
  * @see \PhpParser\Node\Arg
  */
-final class Argument extends AbstractFactory implements ProjectFactoryStrategy
+final class Argument implements ProjectFactoryStrategy
 {
     private PrettyPrinter $valueConverter;
 
@@ -56,7 +56,7 @@ public function matches(ContextStack $context, object $object): bool
      * @param Param $object object to convert to an Element
      * @param StrategyContainer $strategies used to convert nested objects.
      */
-    protected function doCreate(
+    public function create(
         ContextStack $context,
         object $object,
         StrategyContainer $strategies

src/phpDocumentor/Reflection/Php/Factory/ClassConstant.php

@@ -61,7 +61,7 @@ protected function doCreate(
         ContextStack $context,
         object $object,
         StrategyContainer $strategies
-    ): void {
+    ): ?object {
         $constantContainer = $context->peek();
         Assert::isInstanceOfAny(
             $constantContainer,
@@ -86,6 +86,8 @@ protected function doCreate(
                 $const->isFinal()
             ));
         }
+
+        return null;
     }
 
     /**

src/phpDocumentor/Reflection/Php/Factory/Class_.php

@@ -17,7 +17,6 @@
 use phpDocumentor\Reflection\Location;
 use phpDocumentor\Reflection\Php\Class_ as ClassElement;
 use phpDocumentor\Reflection\Php\File as FileElement;
-use phpDocumentor\Reflection\Php\ProjectFactoryStrategy;
 use phpDocumentor\Reflection\Php\StrategyContainer;
 use PhpParser\Node\Stmt\Class_ as ClassNode;
 
@@ -26,7 +25,7 @@
 /**
  * Strategy to create a ClassElement including all sub elements.
  */
-final class Class_ extends AbstractFactory implements ProjectFactoryStrategy
+final class Class_ extends AbstractFactory
 {
     public function matches(ContextStack $context, object $object): bool
     {
@@ -42,7 +41,7 @@ public function matches(ContextStack $context, object $object): bool
      * @param ContextStack $context of the created object
      * @param ClassNode $object
      */
-    protected function doCreate(ContextStack $context, object $object, StrategyContainer $strategies): void
+    protected function doCreate(ContextStack $context, object $object, StrategyContainer $strategies): ?object
     {
         $docBlock = $this->createDocBlock($object->getDocComment(), $context->getTypeContext());
 
@@ -72,5 +71,7 @@ protected function doCreate(ContextStack $context, object $object, StrategyConta
             $strategy = $strategies->findMatching($thisContext, $stmt);
             $strategy->create($thisContext, $stmt, $strategies);
         }
+
+        return $classElement;
     }
 }

src/phpDocumentor/Reflection/Php/Factory/ConstructorPromotion.php

@@ -49,7 +49,7 @@ public function matches(ContextStack $context, object $object): bool
     /**
      * @param ClassMethod $object
      */
-    protected function doCreate(ContextStack $context, object $object, StrategyContainer $strategies): void
+    protected function doCreate(ContextStack $context, object $object, StrategyContainer $strategies): ?object
     {
         $this->methodStrategy->create($context, $object, $strategies);
 
@@ -60,6 +60,8 @@ protected function doCreate(ContextStack $context, object $object, StrategyConta
 
             $this->promoteParameterToProperty($context, $param);
         }
+
+        return $context->peek();
     }
 
     private function promoteParameterToProperty(ContextStack $context, Param $param): void

src/phpDocumentor/Reflection/Php/Factory/Define.php

@@ -88,23 +88,23 @@ protected function doCreate(
         ContextStack $context,
         object $object,
         StrategyContainer $strategies
-    ): void {
+    ): ?object {
         $expression = $object->expr;
         assert($expression instanceof FuncCall);
 
         [$name, $value] = $expression->args;
 
         //We cannot calculate the name of a variadic consuming define.
         if ($name instanceof VariadicPlaceholder || $value instanceof VariadicPlaceholder) {
-            return;
+            return null;
         }
 
         $file = $context->search(FileElement::class);
         assert($file instanceof FileElement);
 
         $fqsen = $this->determineFqsen($name, $context);
         if ($fqsen === null) {
-            return;
+            return null;
         }
 
         $constant = new ConstantElement(
@@ -116,6 +116,8 @@ protected function doCreate(
         );
 
         $file->addConstant($constant);
+
+        return $constant;
     }
 
     private function determineValue(?Arg $value): ?string

src/phpDocumentor/Reflection/Php/Factory/EnumCase.php

@@ -32,17 +32,22 @@ public function matches(ContextStack $context, object $object): bool
     /**
      * @param EnumCaseNode $object
      */
-    protected function doCreate(ContextStack $context, object $object, StrategyContainer $strategies): void
+    protected function doCreate(ContextStack $context, object $object, StrategyContainer $strategies): ?object
     {
         $docBlock = $this->createDocBlock($object->getDocComment(), $context->getTypeContext());
         $enum = $context->peek();
         assert($enum instanceof EnumElement);
-        $enum->addCase(new EnumCaseElement(
+
+        $case = new EnumCaseElement(
             $object->getAttribute('fqsen'),
             $docBlock,
             new Location($object->getLine()),
             new Location($object->getEndLine()),
             $object->expr !== null ? $this->prettyPrinter->prettyPrintExpr($object->expr) : null
-        ));
+        );
+
+        $enum->addCase($case);
+
+        return $case;
     }
 }

src/phpDocumentor/Reflection/Php/Factory/Enum_.php

@@ -29,7 +29,7 @@ public function matches(ContextStack $context, object $object): bool
     }
 
     /** @param EnumNode $object */
-    protected function doCreate(ContextStack $context, object $object, StrategyContainer $strategies): void
+    protected function doCreate(ContextStack $context, object $object, StrategyContainer $strategies): ?object
     {
         $docBlock = $this->createDocBlock($object->getDocComment(), $context->getTypeContext());
 
@@ -56,5 +56,7 @@ protected function doCreate(ContextStack $context, object $object, StrategyConta
             $strategy = $strategies->findMatching($thisContext, $stmt);
             $strategy->create($thisContext, $stmt, $strategies);
         }
+
+        return $enum;
     }
 }

src/phpDocumentor/Reflection/Php/Factory/File.php

@@ -86,17 +86,19 @@ public function matches(ContextStack $context, object $object): bool
      * @param FileSystemFile $object path to the file to convert to an File object.
      * @param StrategyContainer $strategies used to convert nested objects.
      */
-    protected function doCreate(ContextStack $context, object $object, StrategyContainer $strategies): void
+    protected function doCreate(ContextStack $context, object $object, StrategyContainer $strategies): ?object
     {
         $command = new CreateCommand($context, $object, $strategies);
         $middlewareChain = $this->middlewareChain;
 
         $file = $middlewareChain($command);
         if ($file === null) {
-            return;
+            return null;
         }
 
         $context->getProject()->addFile($file);
+
+        return $file;
     }
 
     private function createFile(CreateCommand $command): FileElement

src/phpDocumentor/Reflection/Php/Factory/Function_.php

@@ -46,7 +46,7 @@ protected function doCreate(
         ContextStack $context,
         object $object,
         StrategyContainer $strategies
-    ): void {
+    ): ?object {
         $file = $context->peek();
         Assert::isInstanceOf($file, FileElement::class);
 
@@ -68,12 +68,14 @@ protected function doCreate(
         }
 
         if (!is_array($object->stmts)) {
-            return;
+            return null;
         }
 
         foreach ($object->stmts as $stmt) {
             $strategy = $strategies->findMatching($thisContext, $stmt);
             $strategy->create($thisContext, $stmt, $strategies);
         }
+
+        return $function;
     }
 }