Merge branch 'feature/#41-var-tag-support-in-docblocks' into develop

Close #41

src/Generator/DocBlock/Tag/AbstractTypeableTag.php

@@ -29,8 +29,8 @@ abstract class AbstractTypeableTag extends AbstractGenerator
     protected $types = [];
 
     /**
-     * @param array $types
-     * @param string $description
+     * @param string|string[] $types
+     * @param string          $description
      */
     public function __construct($types = [], $description = null)
     {

src/Generator/DocBlock/Tag/VarTag.php

@@ -0,0 +1,68 @@
+<?php
+/**
+ * Zend Framework (http://framework.zend.com/)
+ *
+ * @link      http://github.com/zendframework/zf2 for the canonical source repository
+ * @copyright Copyright (c) 2005-2016 Zend Technologies USA Inc. (http://www.zend.com)
+ * @license   http://framework.zend.com/license/new-bsd New BSD License
+ */
+
+namespace Zend\Code\Generator\DocBlock\Tag;
+
+class VarTag extends AbstractTypeableTag implements TagInterface
+{
+    /**
+     * @var string|null
+     */
+    private $variableName;
+
+    /**
+     * @param string|null     $variableName
+     * @param string|string[] $types
+     * @param string|null     $description
+     */
+    public function __construct(?string $variableName = null, $types = [], ?string $description = null)
+    {
+        if (null !== $variableName) {
+            $this->variableName = ltrim($variableName, '$');
+        }
+
+        parent::__construct($types, $description);
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function getName() : string
+    {
+        return 'var';
+    }
+
+    /**
+     * @internal this code is only public for compatibility with the
+     *           @see \Zend\Code\Generator\DocBlock\TagManager, which
+     *           uses setters
+     */
+    public function setVariableName(?string $variableName) : void
+    {
+        if (null !== $variableName) {
+            $this->variableName = ltrim($variableName, '$');
+        }
+    }
+
+    public function getVariableName() : ?string
+    {
+        return $this->variableName;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function generate() : string
+    {
+        return '@var'
+            . ((!empty($this->types)) ? ' ' . $this->getTypesAsString() : '')
+            . (null !== $this->variableName ? ' $' . $this->variableName : '')
+            . ((!empty($this->description)) ? ' ' . $this->description : '');
+    }
+}

src/Generator/DocBlock/TagManager.php

@@ -35,6 +35,7 @@ public function initializeDefaultTags()
         $this->addPrototype(new Tag\AuthorTag());
         $this->addPrototype(new Tag\LicenseTag());
         $this->addPrototype(new Tag\ThrowsTag());
+        $this->addPrototype(new Tag\VarTag());
         $this->setGenericPrototype(new Tag\GenericTag());
     }
 

src/Reflection/DocBlock/Tag/VarTag.php

@@ -0,0 +1,83 @@
+<?php
+/**
+ * Zend Framework (http://framework.zend.com/)
+ *
+ * @link      http://github.com/zendframework/zf2 for the canonical source repository
+ * @copyright Copyright (c) 2005-2016 Zend Technologies USA Inc. (http://www.zend.com)
+ * @license   http://framework.zend.com/license/new-bsd New BSD License
+ */
+
+namespace Zend\Code\Reflection\DocBlock\Tag;
+
+class VarTag implements TagInterface, PhpDocTypedTagInterface
+{
+    /**
+     * @var string[]
+     */
+    private $types = [];
+
+    /**
+     * @var string|null
+     */
+    private $variableName;
+
+    /**
+     * @var string|null
+     */
+    private $description;
+
+    /**
+     * {@inheritDoc}
+     */
+    public function getName() : string
+    {
+        return 'var';
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function initialize($tagDocblockLine) : void
+    {
+        $match = [];
+
+        if (!preg_match('#^(.+)?(\$[\S]+)\s*(.*)$#m', $tagDocblockLine, $match)) {
+            return;
+        }
+
+        if ($match[1] !== '') {
+            $this->types = explode('|', rtrim($match[1]));
+        }
+
+        if ($match[2] !== '') {
+            $this->variableName = $match[2];
+        }
+
+        if ($match[3] !== '') {
+            $this->description = $match[3];
+        }
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function getTypes() : array
+    {
+        return $this->types;
+    }
+
+    public function getVariableName() : ?string
+    {
+        return $this->variableName;
+    }
+
+    public function getDescription() : ?string
+    {
+        return $this->description;
+    }
+
+    public function __toString() : string
+    {
+        return 'DocBlock Tag [ * @' . $this->getName() . ' ]' . PHP_EOL;
+    }
+}

src/Reflection/DocBlock/TagManager.php

@@ -26,6 +26,7 @@ public function initializeDefaultTags()
         $this->addPrototype(new Tag\AuthorTag());
         $this->addPrototype(new Tag\LicenseTag());
         $this->addPrototype(new Tag\ThrowsTag());
+        $this->addPrototype(new Tag\VarTag());
         $this->setGenericPrototype(new Tag\GenericTag());
     }
 

test/Generator/DocBlock/Tag/GenericTagTest.php

@@ -69,13 +69,13 @@ public function testConstructorWithOptions()
 
     public function testCreatingTagFromReflection()
     {
-        $docreflection = new DocBlockReflection('/** @var string');
-        $reflectionTag = $docreflection->getTag('var');
+        $docreflection = new DocBlockReflection('/** @global string');
+        $reflectionTag = $docreflection->getTag('global');
 
         /** @var GenericTag $tag */
         $tag = $this->tagmanager->createTagFromReflection($reflectionTag);
         self::assertInstanceOf(GenericTag::class, $tag);
-        self::assertEquals('var', $tag->getName());
+        self::assertEquals('global', $tag->getName());
         self::assertEquals('string', $tag->getContent());
     }
 }

test/Generator/DocBlock/Tag/VarTagTest.php

@@ -0,0 +1,95 @@
+<?php
+/**
+ * Zend Framework (http://framework.zend.com/)
+ *
+ * @link      http://github.com/zendframework/zf2 for the canonical source repository
+ * @copyright Copyright (c) 2005-2016 Zend Technologies USA Inc. (http://www.zend.com)
+ * @license   http://framework.zend.com/license/new-bsd New BSD License
+ */
+
+namespace ZendTest\Code\Generator\DocBlock\Tag;
+
+use PHPUnit\Framework\TestCase;
+use Zend\Code\Generator\DocBlock\Tag\VarTag;
+use Zend\Code\Generator\DocBlock\TagManager;
+use Zend\Code\Reflection\DocBlock\Tag\VarTag as ReflectionVarTag;
+use Zend\Code\Reflection\DocBlockReflection;
+
+/**
+ * @covers \Zend\Code\Generator\DocBlock\Tag\VarTag
+ */
+class VarTagTest extends TestCase
+{
+    /**
+     * @var VarTag
+     */
+    private $tag;
+
+    /**
+     * @var TagManager
+     */
+    private $tagManager;
+
+    protected function setUp() : void
+    {
+        parent::setUp();
+
+        $this->tag        = new VarTag();
+        $this->tagManager = new TagManager();
+
+        $this->tagManager->initializeDefaultTags();
+    }
+
+    public function testGetterAndSetterPersistValue() : void
+    {
+        $tag = new VarTag('variable');
+
+        self::assertSame('variable', $tag->getVariableName());
+    }
+
+    public function testGetterForVariableNameTrimsCorrectly() : void
+    {
+        $this->tag->setVariableName('$variable$');
+        $this->assertEquals('variable$', $this->tag->getVariableName());
+    }
+
+    public function testNameIsCorrect() : void
+    {
+        $this->assertEquals('var', $this->tag->getName());
+    }
+
+    public function testParamProducesCorrectDocBlockLine() : void
+    {
+        $this->tag->setVariableName('variable');
+        $this->tag->setTypes('string[]');
+        $this->tag->setDescription('description');
+        $this->assertEquals('@var string[] $variable description', $this->tag->generate());
+    }
+
+    public function testConstructorWithOptions() : void
+    {
+        $this->tag->setOptions([
+            'variableName' => 'foo',
+            'types'        => ['string'],
+            'description'  => 'description',
+        ]);
+        $tagWithOptionsFromConstructor = new VarTag('foo', ['string'], 'description');
+        $this->assertEquals($this->tag->generate(), $tagWithOptionsFromConstructor->generate());
+    }
+
+    public function testCreatingTagFromReflection() : void
+    {
+        $reflectionTag = (new DocBlockReflection('/** @var int $foo description'))
+            ->getTag('var');
+
+        self::assertInstanceOf(ReflectionVarTag::class, $reflectionTag);
+
+        /** @var VarTag $tag */
+        $tag = $this->tagManager->createTagFromReflection($reflectionTag);
+
+        $this->assertInstanceOf(VarTag::class, $tag);
+        $this->assertEquals('foo', $tag->getVariableName());
+        $this->assertEquals('description', $tag->getDescription());
+        $this->assertEquals('int', $tag->getTypesAsString());
+    }
+}