Implement metadata support in all level elements

Author: jaapio

Diff for: Makefile

@@ -32,6 +32,10 @@ test:
 	docker run -it --rm -v${CURDIR}:/github/workspace phpdoc/phpunit-ga
 	docker run -it --rm -v${CURDIR}:/data -w /data php:7.2 -f ./tests/coverage-checker.php 94
 
+.PHONY: benchmark
+benchmark:
+	docker run -it --rm -v${CURDIR}:/opt/project -w /opt/project php:7.4-cli tools/phpbench run
+
 .PHONY: pre-commit-test
 pre-commit-test: test phpcs phpstan
 

Diff for: docs/index.rst

@@ -0,0 +1,7 @@
+Reflection
+==========
+
+.. toctree::
+   :hidden:
+
+   meta-data

Diff for: docs/meta-data.rst

@@ -0,0 +1,77 @@
+Metadata
+=====
+
+The model of this library is as closed as possible.
+Main reason is because consumers of the library should rely on cache.
+A mutable and flexible interface of the model would most likely break the caching.
+However after some time the users to this library started requesting for a more flexible format.
+This is why metadata was introduced.
+
+Create your first metadata
+--------------------------
+
+First step is to create your own metadata implementation.
+
+.. code:: php
+   final class Hook implements \phpDocumentor\Reflection\Metadata\Metadata
+   {
+      private string $hook;
+
+      public function __construct(string $hook)
+      {
+          $this->hook = $hook;
+      }
+
+      public function key(): string
+      {
+         return "project-metadata";
+      }
+
+      public function hook(): string
+      {
+          return $this->hook;
+      }
+   }
+
+.. note::
+    We do highly recommend to keep your metadata objects small.
+    When reflecting a large project the number of objects will grow fast.
+
+Now we have an class that can be used it is time to create a :php:class:`\phpDocumentor\Reflection\Php\ProjectFactoryStrategy`.
+Strategies are used to reflect nodes in the AST of `phpparser`_.
+
+In the example below we are adding the Hook metadata to any functions containing a function call.
+
+.. code:: php
+
+   use \phpDocumentor\Reflection\Php\Function;
+
+   final class HookStrategy implements \phpDocumentor\Reflection\Php\ProjectFactoryStrategy
+   {
+        public function matches(ContextStack $context, object $object): bool
+        {
+             return $this->context->peek() instanceof Function_ &&
+                    $object instanceof \PhpParser\Node\Expr\FuncCall &&
+                    ((string)$object->name) === 'hook'
+        }
+
+        public function create(ContextStack $context, object $object, StrategyContainer $strategies): void
+        {
+            $method = $context->peek();
+            $method->addMetadata(new Hook($object->args[0]->value));
+        }
+   }
+
+.. note::
+    To speed up the reflection of your project the default factory instance has a Noop strategy. This strategy will
+    ignore all statements that are not handled by any strategy. Keep this in mind when implementing your own strategies
+    especially the statements you are looking for are nested in other statements like a ``while`` loop.
+
+Finally add your new strategy to the project factory.
+
+.. code:: php
+
+    $factory = \phpDocumentor\Reflection\Php\ProjectFactory::createInstance();
+    $factory->addStrategy(new HookStrategy());
+
+.. _phpparser: https://github.com/nikic/PHP-Parser/

Diff for: src/phpDocumentor/Reflection/Metadata/MetaDataContainer.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of phpDocumentor.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ *
+ * @link http://phpdoc.org
+ */
+
+namespace phpDocumentor\Reflection\Metadata;
+
+interface MetaDataContainer
+{
+    public function addMetadata(Metadata $metadata): void;
+
+    /** @return Metadata[] */
+    public function getMetadata(): array;
+}

Diff for: src/phpDocumentor/Reflection/Metadata/Metadata.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of phpDocumentor.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ *
+ * @link http://phpdoc.org
+ */
+
+namespace phpDocumentor\Reflection\Metadata;
+
+interface Metadata
+{
+    public function key(): string;
+}

Diff for: src/phpDocumentor/Reflection/Php/Class_.php

@@ -17,14 +17,17 @@
 use phpDocumentor\Reflection\Element;
 use phpDocumentor\Reflection\Fqsen;
 use phpDocumentor\Reflection\Location;
+use phpDocumentor\Reflection\Metadata\MetaDataContainer as MetaDataContainerInterface;
 
 /**
  * Descriptor representing a Class.
  */
 // @codingStandardsIgnoreStart
-final class Class_ implements Element
+final class Class_ implements Element, MetaDataContainerInterface
 // @codingStandardsIgnoreEnd
 {
+    use MetadataContainer;
+
     /** @var Fqsen Full Qualified Structural Element Name */
     private $fqsen;
 

Diff for: src/phpDocumentor/Reflection/Php/Constant.php

@@ -17,12 +17,15 @@
 use phpDocumentor\Reflection\Element;
 use phpDocumentor\Reflection\Fqsen;
 use phpDocumentor\Reflection\Location;
+use phpDocumentor\Reflection\Metadata\MetaDataContainer as MetaDataContainerInterface;
 
 /**
  * Descriptor representing a constant
  */
-final class Constant implements Element
+final class Constant implements Element, MetaDataContainerInterface
 {
+    use MetadataContainer;
+
     /** @var Fqsen */
     private $fqsen;
 

Diff for: src/phpDocumentor/Reflection/Php/EnumCase.php

@@ -8,9 +8,12 @@
 use phpDocumentor\Reflection\Element;
 use phpDocumentor\Reflection\Fqsen;
 use phpDocumentor\Reflection\Location;
+use phpDocumentor\Reflection\Metadata\MetaDataContainer as MetaDataContainerInterface;
 
-final class EnumCase implements Element
+final class EnumCase implements Element, MetaDataContainerInterface
 {
+    use MetadataContainer;
+
     /** @var Fqsen */
     private $fqsen;
 
@@ -24,6 +27,10 @@ final class EnumCase implements Element
 
     public function __construct(Fqsen $fqsen, ?DocBlock $docBlock, ?Location $location = null, ?string $value = null)
     {
+        if ($location === null) {
+            $location = new Location(-1);
+        }
+
         $this->fqsen    = $fqsen;
         $this->docBlock = $docBlock;
         $this->location = $location;
@@ -45,7 +52,7 @@ public function getDocBlock(): ?DocBlock
         return $this->docBlock;
     }
 
-    public function getLocation(): ?Location
+    public function getLocation(): Location
     {
         return $this->location;
     }

Diff for: src/phpDocumentor/Reflection/Php/Enum_.php

@@ -17,17 +17,20 @@
 use phpDocumentor\Reflection\Element;
 use phpDocumentor\Reflection\Fqsen;
 use phpDocumentor\Reflection\Location;
+use phpDocumentor\Reflection\Metadata\MetaDataContainer as MetaDataContainerInterface;
 use phpDocumentor\Reflection\Type;
 
-final class Enum_ implements Element
+final class Enum_ implements Element, MetaDataContainerInterface
 {
+    use MetadataContainer;
+
     /** @var Fqsen Full Qualified Structural Element Name */
     private $fqsen;
 
     /** @var DocBlock|null */
     private $docBlock;
 
-    /** @var Location|null */
+    /** @var Location */
     private $location;
 
     /** @var EnumCase[] */
@@ -76,7 +79,7 @@ public function getDocBlock(): ?DocBlock
         return $this->docBlock;
     }
 
-    public function getLocation(): ?Location
+    public function getLocation(): Location
     {
         return $this->location;
     }

Diff for: src/phpDocumentor/Reflection/Php/Factory/AbstractFactory.php

@@ -2,6 +2,15 @@
 
 declare(strict_types=1);
 
+/**
+ * This file is part of phpDocumentor.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ *
+ * @link http://phpdoc.org
+ */
+
 namespace phpDocumentor\Reflection\Php\Factory;
 
 use InvalidArgumentException;

Diff for: src/phpDocumentor/Reflection/Php/Factory/Function_.php

@@ -21,6 +21,8 @@
 use PhpParser\Node\Stmt\Function_ as FunctionNode;
 use Webmozart\Assert\Assert;
 
+use function is_array;
+
 /**
  * Strategy to convert Function_ to FunctionDescriptor
  *
@@ -57,10 +59,19 @@ protected function doCreate(
 
         $file->addFunction($function);
 
+        $thisContext = $context->push($function);
         foreach ($object->params as $param) {
-            $thisContext = $context->push($function);
             $strategy = $strategies->findMatching($thisContext, $param);
             $strategy->create($thisContext, $param, $strategies);
         }
+
+        if (!is_array($object->stmts)) {
+            return;
+        }
+
+        foreach ($object->stmts as $stmt) {
+            $strategy = $strategies->findMatching($thisContext, $stmt);
+            $strategy->create($thisContext, $stmt, $strategies);
+        }
     }
 }

Diff for: src/phpDocumentor/Reflection/Php/Factory/Method.php

@@ -24,6 +24,8 @@
 use PhpParser\Node\Stmt\ClassMethod;
 use Webmozart\Assert\Assert;
 
+use function is_array;
+
 /**
  * Strategy to create MethodDescriptor and arguments when applicable.
  */
@@ -67,11 +69,20 @@ protected function doCreate(
         );
         $methodContainer->addMethod($method);
 
+        $thisContext = $context->push($method);
         foreach ($object->params as $param) {
-            $thisContext = $context->push($method);
             $strategy = $strategies->findMatching($thisContext, $param);
             $strategy->create($thisContext, $param, $strategies);
         }
+
+        if (!is_array($object->stmts)) {
+            return;
+        }
+
+        foreach ($object->stmts as $stmt) {
+            $strategy = $strategies->findMatching($thisContext, $stmt);
+            $strategy->create($thisContext, $stmt, $strategies);
+        }
     }
 
     /**

Diff for: src/phpDocumentor/Reflection/Php/File.php

@@ -15,14 +15,17 @@
 
 use phpDocumentor\Reflection\DocBlock;
 use phpDocumentor\Reflection\Fqsen;
+use phpDocumentor\Reflection\Metadata\MetaDataContainer as MetaDataContainerInterface;
 
 use function basename;
 
 /**
  * Represents a file in the project.
  */
-final class File
+final class File implements MetaDataContainerInterface
 {
+    use MetadataContainer;
+
     /** @var DocBlock|null */
     private $docBlock = null;
 

Diff for: src/phpDocumentor/Reflection/Php/Function_.php

@@ -17,16 +17,19 @@
 use phpDocumentor\Reflection\Element;
 use phpDocumentor\Reflection\Fqsen;
 use phpDocumentor\Reflection\Location;
+use phpDocumentor\Reflection\Metadata\MetaDataContainer as MetaDataContainerInterface;
 use phpDocumentor\Reflection\Type;
 use phpDocumentor\Reflection\Types\Mixed_;
 
 /**
  * Descriptor representing a function
  */
 // @codingStandardsIgnoreStart
-final class Function_ implements Element
+final class Function_ implements Element, MetaDataContainerInterface
 // // @codingStandardsIgnoreEnd
 {
+    use MetadataContainer;
+
     /** @var Fqsen Full Qualified Structural Element Name */
     private $fqsen;
 

Diff for: src/phpDocumentor/Reflection/Php/Interface_.php

@@ -17,13 +17,16 @@
 use phpDocumentor\Reflection\Element;
 use phpDocumentor\Reflection\Fqsen;
 use phpDocumentor\Reflection\Location;
+use phpDocumentor\Reflection\Metadata\MetaDataContainer as MetaDataContainerInterface;
 use Webmozart\Assert\Assert;
 
 /**
  * Descriptor representing an Interface.
  */
-final class Interface_ implements Element
+final class Interface_ implements Element, MetaDataContainerInterface
 {
+    use MetadataContainer;
+
     /** @var Fqsen Full Qualified Structural Element Name */
     private $fqsen;