First implementation of hooks

Author: jaapio

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

@@ -30,7 +30,7 @@ abstract class AbstractFactory implements ProjectFactoryStrategy
 {
     /** @param iterable<Reducer> $reducers */
     public function __construct(
-        private readonly DocBlockFactoryInterface $docBlockFactory,
+        protected readonly DocBlockFactoryInterface $docBlockFactory,
         protected readonly iterable $reducers = [],
     ) {
     }

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

@@ -66,16 +66,20 @@ private function promoteParameterToProperty(ContextStack $context, StrategyConta
 
         $property = PropertyBuilder::create(
             $this->valueConverter,
+            $this->docBlockFactory,
+            $strategies,
+            $this->reducers,
         )->fqsen(new Fqsen($methodContainer->getFqsen() . '::$' . (string) $param->var->name))
             ->visibility($param)
             ->type($param->type)
-            ->docblock($this->createDocBlock($param->getDocComment(), $context->getTypeContext()))
+            ->docblock($param->getDocComment())
             ->default($param->default)
             ->readOnly($this->readOnly($param->flags))
             ->static(false)
             ->startLocation(new Location($param->getLine(), $param->getStartFilePos()))
             ->endLocation(new Location($param->getEndLine(), $param->getEndFilePos()))
-            ->build();
+            ->hooks($param->hooks)
+            ->build($context);
 
         foreach ($this->reducers as $reducer) {
             $property = $reducer->reduce($context, $param, $strategies, $property);

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

@@ -8,14 +8,15 @@
 use phpDocumentor\Reflection\Element;
 use phpDocumentor\Reflection\Php\File as FileElement;
 use phpDocumentor\Reflection\Php\Project;
+use phpDocumentor\Reflection\Php\PropertyHook;
 use phpDocumentor\Reflection\Types\Context as TypeContext;
 
 use function array_reverse;
 use function end;
 
 final class ContextStack
 {
-    /** @var (Element|FileElement)[] */
+    /** @var (Element|FileElement|PropertyHook)[] */
     private array $elements = [];
 
     public function __construct(private readonly Project $project, private readonly TypeContext|null $typeContext = null)
@@ -31,7 +32,7 @@ private static function createFromSelf(Project $project, TypeContext|null $typeC
         return $self;
     }
 
-    public function push(Element|FileElement $element): self
+    public function push(Element|FileElement|PropertyHook $element): self
     {
         $elements = $this->elements;
         $elements[] = $element;
@@ -54,7 +55,7 @@ public function getProject(): Project
         return $this->project;
     }
 
-    public function peek(): Element|FileElement
+    public function peek(): Element|FileElement|PropertyHook
     {
         $element = end($this->elements);
         if ($element === false) {

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

@@ -73,17 +73,20 @@ protected function doCreate(
         foreach ($iterator as $stmt) {
             $property = PropertyBuilder::create(
                 $this->valueConverter,
+                $this->docBlockFactory,
+                $strategies,
+                $this->reducers,
             )
                 ->fqsen($stmt->getFqsen())
                 ->visibility($stmt)
                 ->type($stmt->getType())
-                ->docblock($this->createDocBlock($stmt->getDocComment(), $context->getTypeContext()))
+                ->docblock($stmt->getDocComment())
                 ->default($iterator->getDefault())
                 ->static($stmt->isStatic())
                 ->startLocation(new Location($stmt->getLine()))
                 ->endLocation(new Location($stmt->getEndLine()))
                 ->readOnly($stmt->isReadonly())
-                ->build();
+                ->build($context);
 
             foreach ($this->reducers as $reducer) {
                 $property = $reducer->reduce($context, $object, $strategies, $property);

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

@@ -4,20 +4,27 @@
 
 namespace phpDocumentor\Reflection\Php\Factory;
 
-use phpDocumentor\Reflection\DocBlock;
+use phpDocumentor\Reflection\DocBlockFactoryInterface;
 use phpDocumentor\Reflection\Fqsen;
 use phpDocumentor\Reflection\Location;
 use phpDocumentor\Reflection\Php\AsyncVisibility;
+use phpDocumentor\Reflection\Php\Factory\Reducer\Reducer;
 use phpDocumentor\Reflection\Php\Property as PropertyElement;
+use phpDocumentor\Reflection\Php\PropertyHook;
+use phpDocumentor\Reflection\Php\StrategyContainer;
 use phpDocumentor\Reflection\Php\Visibility;
+use PhpParser\Comment\Doc;
 use PhpParser\Modifiers;
 use PhpParser\Node\ComplexType;
 use PhpParser\Node\Expr;
 use PhpParser\Node\Identifier;
 use PhpParser\Node\Name;
 use PhpParser\Node\Param;
+use phpParser\Node\PropertyHook as PropertyHookNode;
 use PhpParser\PrettyPrinter\Standard as PrettyPrinter;
 
+use function array_filter;
+use function array_map;
 use function method_exists;
 
 /**
@@ -31,23 +38,33 @@ final class PropertyBuilder
     private Visibility $visibility;
     private bool $readOnly = false;
     private Identifier|Name|ComplexType|null $type;
-    private DocBlock|null $docblock;
-    private PrettyPrinter $valueConverter;
-    private Expr|null $default;
-    private bool $static;
+    private Doc|null $docblock = null;
+
+    private Expr|null $default = null;
+    private bool $static = false;
     private Location $startLocation;
     private Location $endLocation;
 
-    private function __construct()
-    {
+    /** @var PropertyHookNode */
+    private array $hooks = [];
+
+    /** @param Reducer[] $reducers */
+    private function __construct(
+        private PrettyPrinter $valueConverter,
+        private DocBlockFactoryInterface $docBlockFactory,
+        private StrategyContainer $strategies,
+        private array $reducers,
+    ) {
+        $this->visibility = new Visibility(Visibility::PUBLIC_);
     }
 
-    public static function create(PrettyPrinter $valueConverter): self
-    {
-        $instance = new self();
-        $instance->valueConverter = $valueConverter;
-
-        return $instance;
+    public static function create(
+        PrettyPrinter $valueConverter,
+        DocBlockFactoryInterface $docBlockFactory,
+        StrategyContainer $strategies,
+        array $reducers,
+    ): self {
+        return new self($valueConverter, $docBlockFactory, $strategies, $reducers);
     }
 
     public function fqsen(Fqsen $fqsen): self
@@ -78,7 +95,7 @@ public function readOnly(bool $readOnly): self
         return $this;
     }
 
-    public function docblock(DocBlock|null $docblock): self
+    public function docblock(Doc|null $docblock): self
     {
         $this->docblock = $docblock;
 
@@ -113,18 +130,30 @@ public function endLocation(Location $endLocation): self
         return $this;
     }
 
-    public function build(): PropertyElement
+    /** @param PropertyHookNode[] $hooks */
+    public function hooks(array $hooks): self
+    {
+        $this->hooks = $hooks;
+
+        return $this;
+    }
+
+    public function build(ContextStack|null $context): PropertyElement
     {
         return new PropertyElement(
             $this->fqsen,
             $this->visibility,
-            $this->docblock,
+            $this->docblock !== null ? $this->docBlockFactory->create($this->docblock->getText(), $context?->getTypeContext()) : null,
             $this->default !== null ? $this->valueConverter->prettyPrintExpr($this->default) : null,
             $this->static,
             $this->startLocation,
             $this->endLocation,
             (new Type())->fromPhpParser($this->type),
             $this->readOnly,
+            array_filter(array_map(
+                fn (PropertyHookNode $hook) => $this->buildHook($hook, $context),
+                $this->hooks,
+            )),
         );
     }
 
@@ -160,7 +189,7 @@ private function buildVisibility(Param|PropertyIterator $node): Visibility
     private function buildReadVisibility(Param|PropertyIterator $node): Visibility
     {
         if ($node instanceof Param && method_exists($node, 'isPublic') === false) {
-            return $this->buildPromotedPropertyReadVisibility($node->flags);
+            return $this->buildVisibilityFromFlags($node->flags);
         }
 
         if ($node->isPrivate()) {
@@ -174,7 +203,7 @@ private function buildReadVisibility(Param|PropertyIterator $node): Visibility
         return new Visibility(Visibility::PUBLIC_);
     }
 
-    private function buildPromotedPropertyReadVisibility(int $flags): Visibility
+    private function buildVisibilityFromFlags(int $flags): Visibility
     {
         if ((bool) ($flags & Modifiers::PRIVATE) === true) {
             return new Visibility(Visibility::PRIVATE_);
@@ -199,4 +228,30 @@ private function buildWriteVisibility(Param|PropertyIterator $node): Visibility
 
         return new Visibility(Visibility::PUBLIC_);
     }
+
+    private function buildHook(PropertyHookNode $hook, ContextStack $context): PropertyHook
+    {
+        $doc = $hook->getDocComment();
+
+        $result = new PropertyHook(
+            $hook->name->toString(),
+            $this->buildVisibilityFromFlags($hook->flags),
+            $doc !== null ? $this->docBlockFactory->create($doc->getText(), $context->getTypeContext()) : null,
+            $hook->isFinal(),
+            new Location($hook->getStartLine(), $hook->getStartFilePos()),
+            new Location($hook->getEndLine(), $hook->getEndFilePos()),
+        );
+
+        foreach ($this->reducers as $reducer) {
+            $result = $reducer->reduce($context, $hook, $this->strategies, $result);
+        }
+
+        $thisContext = $context->push($result);
+        foreach ($hook->getStmts() as $stmt) {
+            $strategy = $this->strategies->findMatching($thisContext, $stmt);
+            $strategy->create($thisContext, $stmt, $this->strategies);
+        }
+
+        return $result;
+    }
 }

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

@@ -20,9 +20,11 @@
 use PhpParser\Node\Expr;
 use PhpParser\Node\Identifier;
 use PhpParser\Node\Name;
+use PhpParser\Node\PropertyHook;
 use PhpParser\Node\Stmt\Property as PropertyNode;
 
 use function method_exists;
+use function property_exists;
 
 /**
  * This class acts like a combination of a PropertyNode and PropertyProperty to
@@ -201,6 +203,16 @@ public function getFqsen(): Fqsen
         return $this->property->props[$this->index]->getAttribute('fqsen');
     }
 
+    /** @return PropertyHook[] */
+    public function getHooks(): array
+    {
+        if (property_exists($this->property, 'hooks') === false) {
+            return [];
+        }
+
+        return $this->property->hooks;
+    }
+
     /** @link http://php.net/manual/en/iterator.current.php */
     public function current(): self
     {

src/phpDocumentor/Reflection/Php/Factory/Reducer/Parameter.php

@@ -9,6 +9,7 @@
 use phpDocumentor\Reflection\Php\Factory\Type;
 use phpDocumentor\Reflection\Php\Function_;
 use phpDocumentor\Reflection\Php\Method;
+use phpDocumentor\Reflection\Php\PropertyHook;
 use phpDocumentor\Reflection\Php\StrategyContainer;
 use PhpParser\Node\Expr\Variable;
 use PhpParser\Node\FunctionLike;
@@ -33,7 +34,7 @@ public function reduce(
             return $carry;
         }
 
-        if ($carry instanceof Method === false && $carry instanceof Function_ === false) {
+        if ($carry instanceof Method === false && $carry instanceof Function_ === false && $carry instanceof PropertyHook === false) {
             return null;
         }
 

src/phpDocumentor/Reflection/Php/ProjectFactory.php

@@ -85,7 +85,7 @@ public static function createInstance(): self
                 new Function_($docblockFactory, [$attributeReducer, $parameterReducer]),
                 new Interface_($docblockFactory, [$attributeReducer]),
                 $methodStrategy,
-                new Property($docblockFactory, new PrettyPrinter(), [$attributeReducer]),
+                new Property($docblockFactory, new PrettyPrinter(), [$attributeReducer, $parameterReducer]),
                 new Trait_($docblockFactory, [$attributeReducer]),
 
                 new IfStatement(),
@@ -94,7 +94,7 @@ public static function createInstance(): self
         );
 
         $strategies->addStrategy(
-            new ConstructorPromotion($methodStrategy, $docblockFactory, new PrettyPrinter(), [$attributeReducer]),
+            new ConstructorPromotion($methodStrategy, $docblockFactory, new PrettyPrinter(), [$attributeReducer, $parameterReducer]),
             1100,
         );
         $strategies->addStrategy(new Noop(), -PHP_INT_MAX);

src/phpDocumentor/Reflection/Php/Property.php

@@ -37,7 +37,10 @@ final class Property implements Element, MetaDataContainerInterface, AttributeCo
 
     private readonly Location $endLocation;
 
-    /** @param Visibility|null $visibility when null is provided a default 'public' is set. */
+    /**
+     * @param Visibility|null $visibility when null is provided a default 'public' is set.
+     * @param PropertyHook[] $hooks
+     */
     public function __construct(
         private readonly Fqsen $fqsen,
         Visibility|null $visibility = null,
@@ -48,6 +51,7 @@ public function __construct(
         Location|null $endLocation = null,
         private readonly Type|null $type = null,
         private readonly bool $readOnly = false,
+        private readonly array $hooks = [],
     ) {
         $this->visibility = $visibility ?: new Visibility('public');
         $this->location = $location ?: new Location(-1);