More cleanup of tag creation

TagWithType need to be created via a factory now.

src/DocBlock/StandardTagFactory.php

@@ -17,26 +17,34 @@ use InvalidArgumentException;
 use phpDocumentor\Reflection\DocBlock\Tags\Author;
 use phpDocumentor\Reflection\DocBlock\Tags\Covers;
 use phpDocumentor\Reflection\DocBlock\Tags\Deprecated;
+use phpDocumentor\Reflection\DocBlock\Tags\Factory\AbstractPHPStanFactory;
+use phpDocumentor\Reflection\DocBlock\Tags\Factory\ExtendsFactory;
 use phpDocumentor\Reflection\DocBlock\Tags\Factory\Factory;
+use phpDocumentor\Reflection\DocBlock\Tags\Factory\ImplementsFactory;
+use phpDocumentor\Reflection\DocBlock\Tags\Factory\MethodFactory;
+use phpDocumentor\Reflection\DocBlock\Tags\Factory\ParamFactory;
+use phpDocumentor\Reflection\DocBlock\Tags\Factory\PropertyFactory;
+use phpDocumentor\Reflection\DocBlock\Tags\Factory\PropertyReadFactory;
+use phpDocumentor\Reflection\DocBlock\Tags\Factory\PropertyWriteFactory;
+use phpDocumentor\Reflection\DocBlock\Tags\Factory\ReturnFactory;
+use phpDocumentor\Reflection\DocBlock\Tags\Factory\TemplateExtendsFactory;
+use phpDocumentor\Reflection\DocBlock\Tags\Factory\TemplateFactory;
+use phpDocumentor\Reflection\DocBlock\Tags\Factory\TemplateImplementsFactory;
+use phpDocumentor\Reflection\DocBlock\Tags\Factory\ThrowsFactory;
+use phpDocumentor\Reflection\DocBlock\Tags\Factory\VarFactory;
 use phpDocumentor\Reflection\DocBlock\Tags\Generic;
 use phpDocumentor\Reflection\DocBlock\Tags\InvalidTag;
 use phpDocumentor\Reflection\DocBlock\Tags\Link as LinkTag;
 use phpDocumentor\Reflection\DocBlock\Tags\Method;
-use phpDocumentor\Reflection\DocBlock\Tags\Mixin;
-use phpDocumentor\Reflection\DocBlock\Tags\Param;
-use phpDocumentor\Reflection\DocBlock\Tags\Property;
-use phpDocumentor\Reflection\DocBlock\Tags\PropertyRead;
-use phpDocumentor\Reflection\DocBlock\Tags\PropertyWrite;
-use phpDocumentor\Reflection\DocBlock\Tags\Return_;
 use phpDocumentor\Reflection\DocBlock\Tags\See as SeeTag;
 use phpDocumentor\Reflection\DocBlock\Tags\Since;
 use phpDocumentor\Reflection\DocBlock\Tags\Source;
 use phpDocumentor\Reflection\DocBlock\Tags\TemplateCovariant;
 use phpDocumentor\Reflection\DocBlock\Tags\Throws;
 use phpDocumentor\Reflection\DocBlock\Tags\Uses;
-use phpDocumentor\Reflection\DocBlock\Tags\Var_;
 use phpDocumentor\Reflection\DocBlock\Tags\Version;
 use phpDocumentor\Reflection\FqsenResolver;
+use phpDocumentor\Reflection\TypeResolver;
 use phpDocumentor\Reflection\Types\Context as TypeContext;
 use ReflectionMethod;
 use ReflectionNamedType;
@@ -77,7 +85,7 @@ final class StandardTagFactory implements TagFactory
     public const REGEX_TAGNAME = '[\w\-\_\\\\:]+';
 
     /**
-     * @var array<class-string<Tag>|Factory> An array with a tag as a key, and an
+     * @var array<string, class-string<Tag>|Tag|Factory> An array with a tag as a key, and an
      *                               FQCN to a class that handles it as an array value.
      */
     private array $tagHandlerMappings = [
@@ -86,21 +94,13 @@ final class StandardTagFactory implements TagFactory
         'deprecated'         => Deprecated::class,
         // 'example'         => '\phpDocumentor\Reflection\DocBlock\Tags\Example',
         'link'               => LinkTag::class,
-        'mixin'              => Mixin::class,
         'method'             => Method::class,
-        'param'              => Param::class,
-        'property-read'      => PropertyRead::class,
-        'property'           => Property::class,
-        'property-write'     => PropertyWrite::class,
-        'return'             => Return_::class,
         'see'                => SeeTag::class,
         'since'              => Since::class,
         'source'             => Source::class,
         'template-covariant' => TemplateCovariant::class,
         'throw'              => Throws::class,
-        'throws'             => Throws::class,
         'uses'               => Uses::class,
-        'var'                => Var_::class,
         'version'            => Version::class,
     ];
 
@@ -124,26 +124,60 @@ final class StandardTagFactory implements TagFactory
      */
     private array $serviceLocator = [];
 
-    /**
-     * Initialize this tag factory with the means to resolve an FQSEN and optionally a list of tag handlers.
-     *
-     * If no tag handlers are provided than the default list in the {@see self::$tagHandlerMappings} property
-     * is used.
-     *
-     * @see self::registerTagHandler() to add a new tag handler to the existing default list.
-     *
-     * @param array<class-string<Tag>> $tagHandlers
-     */
-    public function __construct(FqsenResolver $fqsenResolver, ?array $tagHandlers = null)
+    private function __construct(FqsenResolver $fqsenResolver)
     {
         $this->fqsenResolver = $fqsenResolver;
-        if ($tagHandlers !== null) {
-            $this->tagHandlerMappings = $tagHandlers;
-        }
 
         $this->addService($fqsenResolver, FqsenResolver::class);
     }
 
+    /**
+     * Initialize this tag factory with the means to resolve an FQSEN.
+     *
+     * @see self::registerTagHandler() to add a new tag handler to the existing default list.
+     */
+    public static function createInstance(FqsenResolver $fqsenResolver): self
+    {
+        $tagFactory = new self($fqsenResolver);
+        $descriptionFactory = new DescriptionFactory($tagFactory);
+
+        $typeResolver = new TypeResolver($fqsenResolver);
+
+        $phpstanTagFactory = new AbstractPHPStanFactory(
+            new ParamFactory($typeResolver, $descriptionFactory),
+            new VarFactory($typeResolver, $descriptionFactory),
+            new ReturnFactory($typeResolver, $descriptionFactory),
+            new PropertyFactory($typeResolver, $descriptionFactory),
+            new PropertyReadFactory($typeResolver, $descriptionFactory),
+            new PropertyWriteFactory($typeResolver, $descriptionFactory),
+            new MethodFactory($typeResolver, $descriptionFactory),
+            new ImplementsFactory($typeResolver, $descriptionFactory),
+            new ExtendsFactory($typeResolver, $descriptionFactory),
+            new TemplateFactory($typeResolver, $descriptionFactory),
+            new TemplateImplementsFactory($typeResolver, $descriptionFactory),
+            new TemplateExtendsFactory($typeResolver, $descriptionFactory),
+            new ThrowsFactory($typeResolver, $descriptionFactory),
+        );
+
+        $tagFactory->addService($descriptionFactory);
+        $tagFactory->addService($typeResolver);
+        $tagFactory->registerTagHandler('param', $phpstanTagFactory);
+        $tagFactory->registerTagHandler('var', $phpstanTagFactory);
+        $tagFactory->registerTagHandler('return', $phpstanTagFactory);
+        $tagFactory->registerTagHandler('property', $phpstanTagFactory);
+        $tagFactory->registerTagHandler('property-read', $phpstanTagFactory);
+        $tagFactory->registerTagHandler('property-write', $phpstanTagFactory);
+        $tagFactory->registerTagHandler('method', $phpstanTagFactory);
+        $tagFactory->registerTagHandler('extends', $phpstanTagFactory);
+        $tagFactory->registerTagHandler('implements', $phpstanTagFactory);
+        $tagFactory->registerTagHandler('template', $phpstanTagFactory);
+        $tagFactory->registerTagHandler('template-extends', $phpstanTagFactory);
+        $tagFactory->registerTagHandler('template-implements', $phpstanTagFactory);
+        $tagFactory->registerTagHandler('throws', $phpstanTagFactory);
+
+        return $tagFactory;
+    }
+
     public function create(string $tagLine, ?TypeContext $context = null): Tag
     {
         if (!$context) {
@@ -238,7 +272,7 @@ final class StandardTagFactory implements TagFactory
     /**
      * Determines the Fully Qualified Class Name of the Factory or Tag (containing a Factory Method `create`).
      *
-     * @return class-string<Tag>|Factory
+     * @return class-string<Tag>|Tag|Factory
      */
     private function findHandlerClassName(string $tagName, TypeContext $context)
     {
@@ -302,7 +336,7 @@ final class StandardTagFactory implements TagFactory
      * Retrieves a series of ReflectionParameter objects for the static 'create' method of the given
      * tag handler class name.
      *
-     * @param class-string|Factory $handler
+     * @param class-string<Tag>|Tag|Factory $handler
      *
      * @return ReflectionParameter[]
      */

src/DocBlock/Tags/Factory/MixinFactory.php

@@ -0,0 +1,52 @@
+<?php
+
+declare(strict_types=1);
+
+namespace phpDocumentor\Reflection\DocBlock\Tags\Factory;
+
+use phpDocumentor\Reflection\DocBlock\DescriptionFactory;
+use phpDocumentor\Reflection\DocBlock\Tag;
+use phpDocumentor\Reflection\DocBlock\Tags\Mixin;
+use phpDocumentor\Reflection\TypeResolver;
+use phpDocumentor\Reflection\Types\Context;
+use PHPStan\PhpDocParser\Ast\PhpDoc\MixinTagValueNode;
+use PHPStan\PhpDocParser\Ast\PhpDoc\PhpDocTagNode;
+use Webmozart\Assert\Assert;
+
+use function is_string;
+
+/**
+ * @internal This class is not part of the BC promise of this library.
+ */
+final class MixinFactory implements PHPStanFactory
+{
+    private DescriptionFactory $descriptionFactory;
+    private TypeResolver $typeResolver;
+
+    public function __construct(TypeResolver $typeResolver, DescriptionFactory $descriptionFactory)
+    {
+        $this->descriptionFactory = $descriptionFactory;
+        $this->typeResolver = $typeResolver;
+    }
+
+    public function create(PhpDocTagNode $node, Context $context): Tag
+    {
+        $tagValue = $node->value;
+        Assert::isInstanceOf($tagValue, MixinTagValueNode::class);
+
+        $description = $tagValue->getAttribute('description');
+        if (is_string($description) === false) {
+            $description = $tagValue->description;
+        }
+
+        return new Mixin(
+            $this->typeResolver->createType($tagValue->type, $context),
+            $this->descriptionFactory->create($description, $context)
+        );
+    }
+
+    public function supports(PhpDocTagNode $node, Context $context): bool
+    {
+        return $node->value instanceof MixinTagValueNode;
+    }
+}

src/DocBlock/Tags/Factory/ParamFactory.php

@@ -8,6 +8,7 @@ use phpDocumentor\Reflection\DocBlock\DescriptionFactory;
 use phpDocumentor\Reflection\DocBlock\Tag;
 use phpDocumentor\Reflection\DocBlock\Tags\InvalidTag;
 use phpDocumentor\Reflection\DocBlock\Tags\Param;
+use phpDocumentor\Reflection\Exception\ParserException;
 use phpDocumentor\Reflection\TypeResolver;
 use phpDocumentor\Reflection\Types\Context;
 use PHPStan\PhpDocParser\Ast\PhpDoc\InvalidTagValueNode;
@@ -40,7 +41,9 @@ final class ParamFactory implements PHPStanFactory
         $tagValue = $node->value;
 
         if ($tagValue instanceof InvalidTagValueNode) {
-            return InvalidTag::create($tagValue->value, 'param')->withError($tagValue->exception);
+            return InvalidTag::create($tagValue->value, 'param')->withError(
+                ParserException::from($tagValue->exception)
+            );
         }
 
         Assert::isInstanceOfAny(

src/DocBlock/Tags/Factory/ThrowsFactory.php

@@ -0,0 +1,52 @@
+<?php
+
+declare(strict_types=1);
+
+namespace phpDocumentor\Reflection\DocBlock\Tags\Factory;
+
+use phpDocumentor\Reflection\DocBlock\DescriptionFactory;
+use phpDocumentor\Reflection\DocBlock\Tag;
+use phpDocumentor\Reflection\DocBlock\Tags\Throws;
+use phpDocumentor\Reflection\TypeResolver;
+use phpDocumentor\Reflection\Types\Context;
+use PHPStan\PhpDocParser\Ast\PhpDoc\PhpDocTagNode;
+use PHPStan\PhpDocParser\Ast\PhpDoc\ThrowsTagValueNode;
+use Webmozart\Assert\Assert;
+
+use function is_string;
+
+/**
+ * @internal This class is not part of the BC promise of this library.
+ */
+final class ThrowsFactory implements PHPStanFactory
+{
+    private DescriptionFactory $descriptionFactory;
+    private TypeResolver $typeResolver;
+
+    public function __construct(TypeResolver $typeResolver, DescriptionFactory $descriptionFactory)
+    {
+        $this->descriptionFactory = $descriptionFactory;
+        $this->typeResolver = $typeResolver;
+    }
+
+    public function create(PhpDocTagNode $node, Context $context): Tag
+    {
+        $tagValue = $node->value;
+        Assert::isInstanceOf($tagValue, ThrowsTagValueNode::class);
+
+        $description = $tagValue->getAttribute('description');
+        if (is_string($description) === false) {
+            $description = $tagValue->description;
+        }
+
+        return new Throws(
+            $this->typeResolver->createType($tagValue->type, $context),
+            $this->descriptionFactory->create($description, $context)
+        );
+    }
+
+    public function supports(PhpDocTagNode $node, Context $context): bool
+    {
+        return $node->value instanceof ThrowsTagValueNode;
+    }
+}

src/DocBlock/Tags/Mixin.php

@@ -14,11 +14,7 @@ declare(strict_types=1);
 namespace phpDocumentor\Reflection\DocBlock\Tags;
 
 use phpDocumentor\Reflection\DocBlock\Description;
-use phpDocumentor\Reflection\DocBlock\DescriptionFactory;
 use phpDocumentor\Reflection\Type;
-use phpDocumentor\Reflection\TypeResolver;
-use phpDocumentor\Reflection\Types\Context as TypeContext;
-use Webmozart\Assert\Assert;
 
 /**
  * Reflection class for a {@}mixin tag in a Docblock.
@@ -31,21 +27,4 @@ final class Mixin extends TagWithType
         $this->type        = $type;
         $this->description = $description;
     }
-
-    public static function create(
-        string $body,
-        ?TypeResolver $typeResolver = null,
-        ?DescriptionFactory $descriptionFactory = null,
-        ?TypeContext $context = null
-    ): self {
-        Assert::notNull($typeResolver);
-        Assert::notNull($descriptionFactory);
-
-        [$type, $description] = self::extractTypeFromBody($body);
-
-        $type        = $typeResolver->resolve($type, $context);
-        $description = $descriptionFactory->create($description, $context);
-
-        return new static($type, $description);
-    }
 }

src/DocBlock/Tags/Param.php

@@ -16,8 +16,6 @@ namespace phpDocumentor\Reflection\DocBlock\Tags;
 use phpDocumentor\Reflection\DocBlock\Description;
 use phpDocumentor\Reflection\Type;
 
-use function strpos;
-
 /**
  * Reflection class for the {@}param tag in a Docblock.
  */

src/DocBlock/Tags/TagWithType.php

@@ -37,7 +37,7 @@ abstract class TagWithType extends BaseTag
         return $this->type;
     }
 
-    public static function create(string $body): Tag
+    final public static function create(string $body): Tag
     {
         throw new CannotCreateTag('Typed tag cannot be created');
     }

src/DocBlock/Tags/TemplateCovariant.php

@@ -14,11 +14,7 @@ declare(strict_types=1);
 namespace phpDocumentor\Reflection\DocBlock\Tags;
 
 use phpDocumentor\Reflection\DocBlock\Description;
-use phpDocumentor\Reflection\DocBlock\DescriptionFactory;
 use phpDocumentor\Reflection\Type;
-use phpDocumentor\Reflection\TypeResolver;
-use phpDocumentor\Reflection\Types\Context as TypeContext;
-use Webmozart\Assert\Assert;
 
 /**
  * Reflection class for a {@}template-covariant tag in a Docblock.
@@ -31,21 +27,4 @@ final class TemplateCovariant extends TagWithType
         $this->type        = $type;
         $this->description = $description;
     }
-
-    public static function create(
-        string $body,
-        ?TypeResolver $typeResolver = null,
-        ?DescriptionFactory $descriptionFactory = null,
-        ?TypeContext $context = null
-    ): self {
-        Assert::notNull($typeResolver);
-        Assert::notNull($descriptionFactory);
-
-        [$type, $description] = self::extractTypeFromBody($body);
-
-        $type        = $typeResolver->resolve($type, $context);
-        $description = $descriptionFactory->create($description, $context);
-
-        return new static($type, $description);
-    }
 }

src/DocBlock/Tags/Throws.php

@@ -14,11 +14,7 @@ declare(strict_types=1);
 namespace phpDocumentor\Reflection\DocBlock\Tags;
 
 use phpDocumentor\Reflection\DocBlock\Description;
-use phpDocumentor\Reflection\DocBlock\DescriptionFactory;
 use phpDocumentor\Reflection\Type;
-use phpDocumentor\Reflection\TypeResolver;
-use phpDocumentor\Reflection\Types\Context as TypeContext;
-use Webmozart\Assert\Assert;
 
 /**
  * Reflection class for a {@}throws tag in a Docblock.
@@ -31,21 +27,4 @@ final class Throws extends TagWithType
         $this->type        = $type;
         $this->description = $description;
     }
-
-    public static function create(
-        string $body,
-        ?TypeResolver $typeResolver = null,
-        ?DescriptionFactory $descriptionFactory = null,
-        ?TypeContext $context = null
-    ): self {
-        Assert::notNull($typeResolver);
-        Assert::notNull($descriptionFactory);
-
-        [$type, $description] = self::extractTypeFromBody($body);
-
-        $type        = $typeResolver->resolve($type, $context);
-        $description = $descriptionFactory->create($description, $context);
-
-        return new static($type, $description);
-    }
 }

src/DocBlockFactory.php

@@ -19,20 +19,7 @@ use phpDocumentor\Reflection\DocBlock\DescriptionFactory;
 use phpDocumentor\Reflection\DocBlock\StandardTagFactory;
 use phpDocumentor\Reflection\DocBlock\Tag;
 use phpDocumentor\Reflection\DocBlock\TagFactory;
-use phpDocumentor\Reflection\DocBlock\Tags\Factory\AbstractPHPStanFactory;
-use phpDocumentor\Reflection\DocBlock\Tags\Factory\ExtendsFactory;
 use phpDocumentor\Reflection\DocBlock\Tags\Factory\Factory;
-use phpDocumentor\Reflection\DocBlock\Tags\Factory\ImplementsFactory;
-use phpDocumentor\Reflection\DocBlock\Tags\Factory\MethodFactory;
-use phpDocumentor\Reflection\DocBlock\Tags\Factory\ParamFactory;
-use phpDocumentor\Reflection\DocBlock\Tags\Factory\PropertyFactory;
-use phpDocumentor\Reflection\DocBlock\Tags\Factory\PropertyReadFactory;
-use phpDocumentor\Reflection\DocBlock\Tags\Factory\PropertyWriteFactory;
-use phpDocumentor\Reflection\DocBlock\Tags\Factory\ReturnFactory;
-use phpDocumentor\Reflection\DocBlock\Tags\Factory\TemplateExtendsFactory;
-use phpDocumentor\Reflection\DocBlock\Tags\Factory\TemplateFactory;
-use phpDocumentor\Reflection\DocBlock\Tags\Factory\TemplateImplementsFactory;
-use phpDocumentor\Reflection\DocBlock\Tags\Factory\VarFactory;
 use Webmozart\Assert\Assert;
 
 use function array_shift;
@@ -70,39 +57,8 @@ final class DocBlockFactory implements DocBlockFactoryInterface
     public static function createInstance(array $additionalTags = []): DocBlockFactoryInterface
     {
         $fqsenResolver = new FqsenResolver();
-        $tagFactory = new StandardTagFactory($fqsenResolver);
+        $tagFactory = StandardTagFactory::createInstance($fqsenResolver);
         $descriptionFactory = new DescriptionFactory($tagFactory);
-        $typeResolver = new TypeResolver($fqsenResolver);
-
-        $phpstanTagFactory = new AbstractPHPStanFactory(
-            new ParamFactory($typeResolver, $descriptionFactory),
-            new VarFactory($typeResolver, $descriptionFactory),
-            new ReturnFactory($typeResolver, $descriptionFactory),
-            new PropertyFactory($typeResolver, $descriptionFactory),
-            new PropertyReadFactory($typeResolver, $descriptionFactory),
-            new PropertyWriteFactory($typeResolver, $descriptionFactory),
-            new MethodFactory($typeResolver, $descriptionFactory),
-            new ImplementsFactory($typeResolver, $descriptionFactory),
-            new ExtendsFactory($typeResolver, $descriptionFactory),
-            new TemplateFactory($typeResolver, $descriptionFactory),
-            new TemplateImplementsFactory($typeResolver, $descriptionFactory),
-            new TemplateExtendsFactory($typeResolver, $descriptionFactory),
-        );
-
-        $tagFactory->addService($descriptionFactory);
-        $tagFactory->addService($typeResolver);
-        $tagFactory->registerTagHandler('param', $phpstanTagFactory);
-        $tagFactory->registerTagHandler('var', $phpstanTagFactory);
-        $tagFactory->registerTagHandler('return', $phpstanTagFactory);
-        $tagFactory->registerTagHandler('property', $phpstanTagFactory);
-        $tagFactory->registerTagHandler('property-read', $phpstanTagFactory);
-        $tagFactory->registerTagHandler('property-write', $phpstanTagFactory);
-        $tagFactory->registerTagHandler('method', $phpstanTagFactory);
-        $tagFactory->registerTagHandler('extends', $phpstanTagFactory);
-        $tagFactory->registerTagHandler('implements', $phpstanTagFactory);
-        $tagFactory->registerTagHandler('template', $phpstanTagFactory);
-        $tagFactory->registerTagHandler('template-extends', $phpstanTagFactory);
-        $tagFactory->registerTagHandler('template-implements', $phpstanTagFactory);
 
         $docBlockFactory = new self($descriptionFactory, $tagFactory);
         foreach ($additionalTags as $tagName => $tagHandler) {

src/Exception/ParserException.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace phpDocumentor\Reflection\Exception;
+
+use InvalidArgumentException;
+
+final class ParserException extends InvalidArgumentException implements ReflectionDocblockException
+{
+    public static function from(\PHPStan\PhpDocParser\Parser\ParserException $exception): self
+    {
+        return new self(
+            'Failed to parse docblock: ' . $exception->getMessage(),
+            0,
+            $exception
+        );
+    }
+}

src/Exception/ReflectionDocblockException.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace phpDocumentor\Reflection\Exception;
+
+use Throwable;
+
+interface ReflectionDocblockException extends Throwable
+{
+}