Merge pull request #477 from phpDocumentor/attribute-reducers

Add reducers to factories to support attributes

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;
     }
 }