Add new tags

src/DocBlock/StandardTagFactory.php

@@ -13,45 +13,47 @@
 
 namespace phpDocumentor\Reflection\DocBlock;
 
+use function trim;
+use function count;
+use function strpos;
+use function sprintf;
+use ReflectionMethod;
+use function get_class;
+use function is_object;
+use function preg_match;
+use ReflectionNamedType;
+use ReflectionParameter;
+use function array_merge;
+use function array_slice;
+use Webmozart\Assert\Assert;
 use InvalidArgumentException;
+use function array_key_exists;
+use function call_user_func_array;
+use phpDocumentor\Reflection\FqsenResolver;
+use phpDocumentor\Reflection\DocBlock\Tags\Uses;
+use phpDocumentor\Reflection\DocBlock\Tags\Var_;
+use phpDocumentor\Reflection\DocBlock\Tags\Mixin;
+use phpDocumentor\Reflection\DocBlock\Tags\Param;
+use phpDocumentor\Reflection\DocBlock\Tags\Since;
 use phpDocumentor\Reflection\DocBlock\Tags\Author;
 use phpDocumentor\Reflection\DocBlock\Tags\Covers;
-use phpDocumentor\Reflection\DocBlock\Tags\Deprecated;
-use phpDocumentor\Reflection\DocBlock\Tags\Factory\Factory;
-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\Param;
+use phpDocumentor\Reflection\DocBlock\Tags\Source;
+use phpDocumentor\Reflection\DocBlock\Tags\Throws;
+use phpDocumentor\Reflection\DocBlock\Tags\Generic;
+
+use phpDocumentor\Reflection\DocBlock\Tags\Return_;
+use phpDocumentor\Reflection\DocBlock\Tags\Version;
 use phpDocumentor\Reflection\DocBlock\Tags\Property;
+use phpDocumentor\Reflection\DocBlock\Tags\Deprecated;
+use phpDocumentor\Reflection\DocBlock\Tags\InvalidTag;
 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\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\Types\Context as TypeContext;
-use ReflectionMethod;
-use ReflectionNamedType;
-use ReflectionParameter;
-use Webmozart\Assert\Assert;
-
-use function array_key_exists;
-use function array_merge;
-use function array_slice;
-use function call_user_func_array;
-use function count;
-use function get_class;
-use function is_object;
-use function preg_match;
-use function sprintf;
-use function strpos;
-use function trim;
+use phpDocumentor\Reflection\DocBlock\Tags\Factory\Factory;
+use phpDocumentor\Reflection\DocBlock\Tags\Link as LinkTag;
+use phpDocumentor\Reflection\DocBlock\Tags\TemplateCovariant;
 
 /**
  * Creates a Tag object given the contents of a tag.
@@ -80,25 +82,27 @@ final class StandardTagFactory implements TagFactory
      *                               FQCN to a class that handles it as an array value.
      */
     private array $tagHandlerMappings = [
-        'author' => Author::class,
-        'covers' => Covers::class,
-        'deprecated' => Deprecated::class,
-        // 'example'        => '\phpDocumentor\Reflection\DocBlock\Tags\Example',
-        'link' => LinkTag::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,
-        'throw' => Throws::class,
-        'throws' => Throws::class,
-        'uses' => Uses::class,
-        'var' => Var_::class,
-        'version' => Version::class,
+        'author'             => Author::class,
+        'covers'             => Covers::class,
+        '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,
     ];
 
     /**

src/DocBlock/Tags/Extends_.php

@@ -0,0 +1,47 @@
+<?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\DocBlock\Tags;
+
+use Doctrine\Deprecations\Deprecation;
+use phpDocumentor\Reflection\Type;
+use phpDocumentor\Reflection\DocBlock\Description;
+use phpDocumentor\Reflection\DocBlock\Tags\TagWithType;
+
+/**
+ * Reflection class for a {@}extends tag in a Docblock.
+ */
+class Extends_ extends TagWithType 
+{
+    public function __construct(Type $type, ?Description $description = null)
+    {
+        $this->name        = 'extends';
+        $this->type        = $type;
+        $this->description = $description;
+    }
+
+    /**
+     * @deprecated Create using static factory is deprecated,
+     *  this method should not be called directly by library consumers
+     */
+    public static function create(string $body)
+    {
+        Deprecation::trigger(
+            'phpdocumentor/reflection-docblock',
+            'https://github.com/phpDocumentor/ReflectionDocBlock/issues/361',
+            'Create using static factory is deprecated, this method should not be called directly
+             by library consumers',
+        );
+        return null;
+    }
+}

src/DocBlock/Tags/Factory/ExtendsFactory.php

@@ -0,0 +1,53 @@
+<?php
+
+declare(strict_types=1);
+
+namespace phpDocumentor\Reflection\DocBlock\Tags\Factory;
+
+use Webmozart\Assert\Assert;
+use phpDocumentor\Reflection\DocBlock\Tag;
+use phpDocumentor\Reflection\TypeResolver;
+use phpDocumentor\Reflection\Types\Context;
+use PHPStan\PhpDocParser\Ast\PhpDoc\PhpDocTagNode;
+use phpDocumentor\Reflection\DocBlock\Tags\Extends_;
+use PHPStan\PhpDocParser\Ast\PhpDoc\ExtendsTagValueNode;
+use phpDocumentor\Reflection\DocBlock\DescriptionFactory;
+use phpDocumentor\Reflection\DocBlock\Tags\TemplateExtends;
+
+/**
+ * @internal This class is not part of the BC promise of this library.
+ */
+class ExtendsFactory 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, ExtendsTagValueNode::class);
+
+        $description = $tagValue->getAttribute('description');
+        if (is_string($description) === false) {
+            $description = $tagValue->description;
+        }
+
+        $class = $node->name === '@extends' ? Extends_::class : TemplateExtends::class;
+
+        return new $class(
+            $this->typeResolver->createType($tagValue->type, $context),
+            $this->descriptionFactory->create($tagValue->description, $context) 
+        );
+    }
+
+    public function supports(PhpDocTagNode $node, Context $context): bool
+    {
+        return $node->value instanceof ExtendsTagValueNode && ($node->name === '@extends' || $node->name === '@template-extends');
+    }
+}

src/DocBlock/Tags/Factory/ImplementsFactory.php

@@ -0,0 +1,53 @@
+<?php
+
+declare(strict_types=1);
+
+namespace phpDocumentor\Reflection\DocBlock\Tags\Factory;
+
+use Webmozart\Assert\Assert;
+use phpDocumentor\Reflection\DocBlock\Tag;
+use phpDocumentor\Reflection\TypeResolver;
+use phpDocumentor\Reflection\Types\Context;
+use PHPStan\PhpDocParser\Ast\PhpDoc\PhpDocTagNode;
+use phpDocumentor\Reflection\DocBlock\Tags\Implements_;
+use phpDocumentor\Reflection\DocBlock\DescriptionFactory;
+use PHPStan\PhpDocParser\Ast\PhpDoc\ImplementsTagValueNode;
+use phpDocumentor\Reflection\DocBlock\Tags\TemplateImplements;
+
+/**
+ * @internal This class is not part of the BC promise of this library.
+ */
+class ImplementsFactory 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, ImplementsTagValueNode::class);
+
+        $description = $tagValue->getAttribute('description');
+        if (is_string($description) === false) {
+            $description = $tagValue->description;
+        }
+
+        $class = $node->name === '@implements' ? Implements_::class : TemplateImplements::class;
+
+        return new $class(
+            $this->typeResolver->createType($tagValue->type, $context),
+            $this->descriptionFactory->create($tagValue->description, $context) 
+        );
+    }
+
+    public function supports(PhpDocTagNode $node, Context $context): bool
+    {
+        return $node->value instanceof ImplementsTagValueNode && ($node->name === '@implements' || $node->name === '@template-implements');
+    }
+}

src/DocBlock/Tags/Factory/TemplateFactory.php

@@ -0,0 +1,52 @@
+<?php
+
+declare(strict_types=1);
+
+namespace phpDocumentor\Reflection\DocBlock\Tags\Factory;
+
+use Webmozart\Assert\Assert;
+use phpDocumentor\Reflection\DocBlock\Tag;
+use phpDocumentor\Reflection\TypeResolver;
+use phpDocumentor\Reflection\Types\Context;
+use PHPStan\PhpDocParser\Ast\PhpDoc\PhpDocTagNode;
+use phpDocumentor\Reflection\DocBlock\Tags\Template;
+use phpDocumentor\Reflection\DocBlock\DescriptionFactory;
+use PHPStan\PhpDocParser\Ast\PhpDoc\TemplateTagValueNode;
+
+/**
+ * @internal This class is not part of the BC promise of this library.
+ */
+final class TemplateFactory 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, TemplateTagValueNode::class);
+
+        $description = $tagValue->getAttribute('description');
+        if (is_string($description) === false) {
+            $description = $tagValue->description;
+        }
+
+        return new Template(
+            $tagValue->name,
+            $this->typeResolver->createType($tagValue->bound, $context),
+            $this->typeResolver->createType($tagValue->default, $context),
+            $this->descriptionFactory->create($tagValue->description, $context) 
+        );
+    }
+
+    public function supports(PhpDocTagNode $node, Context $context): bool
+    {
+        return $node->value instanceof TemplateTagValueNode && $node->name === '@template';
+    }
+}

src/DocBlock/Tags/Implements_.php

@@ -0,0 +1,47 @@
+<?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\DocBlock\Tags;
+
+use Doctrine\Deprecations\Deprecation;
+use phpDocumentor\Reflection\Type;
+use phpDocumentor\Reflection\DocBlock\Description;
+use phpDocumentor\Reflection\DocBlock\Tags\TagWithType;
+
+/**
+ * Reflection class for a {@}implements tag in a Docblock.
+ */
+class Implements_ extends TagWithType 
+{
+    public function __construct(Type $type, ?Description $description = null)
+    {
+        $this->name        = 'implements';
+        $this->type        = $type;
+        $this->description = $description;
+    }
+
+    /**
+     * @deprecated Create using static factory is deprecated,
+     *  this method should not be called directly by library consumers
+     */
+    public static function create(string $body)
+    {
+        Deprecation::trigger(
+            'phpdocumentor/reflection-docblock',
+            'https://github.com/phpDocumentor/ReflectionDocBlock/issues/361',
+            'Create using static factory is deprecated, this method should not be called directly
+             by library consumers',
+        );
+        return null;
+    }
+}