[Code] Add support for @throws, multiple types and typed arrays

zendframework · Oct 31, 2012 · d166256 · d166256
1 parent 7e8a5db
commit d166256
Show file tree

Hide file tree

Showing 10 changed files with 212 additions and 26 deletions.
diff --git a/library/Zend/Code/Reflection/DocBlock/Tag/MethodTag.php b/library/Zend/Code/Reflection/DocBlock/Tag/MethodTag.php
@@ -14,14 +14,14 @@
  * @category   Zend
  * @package    Zend_Reflection
  */
-class MethodTag implements TagInterface
+class MethodTag implements TagInterface, PhpDocTypedTagInterface
 {
     /**
      * Return value type
      *
-     * @var string
+     * @var array
      */
-    protected $returnType = null;
+    protected $types = array();
 
     /**
      * Method name
@@ -67,7 +67,7 @@ public function initialize($tagDocblockLine)
             }
 
             if ($match[2] !== '') {
-                $this->returnType = rtrim($match[2]);
+                $this->types = explode('|', rtrim($match[2]));
             }
 
             $this->methodName = $match[3];
@@ -81,11 +81,21 @@ public function initialize($tagDocblockLine)
     /**
      * Get return value type
      *
-     * @return string
+     * @return null|string
+     * @deprecated 2.0.4 use getTypes instead
      */
     public function getReturnType()
     {
-        return $this->returnType;
+        if (empty($this->types)) {
+            return null;
+        }
+
+        return $this->types[0];
+    }
+
+    public function getTypes()
+    {
+        return $this->types;
     }
 
     /**

diff --git a/library/Zend/Code/Reflection/DocBlock/Tag/ParamTag.php b/library/Zend/Code/Reflection/DocBlock/Tag/ParamTag.php
@@ -14,12 +14,12 @@
  * @category   Zend
  * @package    Zend_Reflection
  */
-class ParamTag implements TagInterface
+class ParamTag implements TagInterface, PhpDocTypedTagInterface
 {
     /**
-     * @var string
+     * @var array
      */
-    protected $type = null;
+    protected $types = array();
 
     /**
      * @var string
@@ -47,9 +47,9 @@ public function getName()
     public function initialize($tagDocBlockLine)
     {
         $matches = array();
-        preg_match('#([\w|\\\]+)(?:\s+(\$\S+)){0,1}(?:\s+(.*))?#s', $tagDocBlockLine, $matches);
+        preg_match('#((?:[\w|\\\]+(?:\[\])*\|?)+)(?:\s+(\$\S+))?(?:\s+(.*))?#s', $tagDocBlockLine, $matches);
 
-        $this->type = $matches[1];
+        $this->types = explode('|', $matches[1]);
 
         if (isset($matches[2])) {
             $this->variableName = $matches[2];
@@ -64,10 +64,20 @@ public function initialize($tagDocBlockLine)
      * Get parameter variable type
      *
      * @return string
+     * @deprecated 2.0.4 use getTypes instead
      */
     public function getType()
     {
-        return $this->type;
+        if (empty($this->types)) {
+            return '';
+        }
+
+        return $this->types[0];
+    }
+
+    public function getTypes()
+    {
+        return $this->types;
     }
 
     /**

diff --git a/library/Zend/Code/Reflection/DocBlock/Tag/PhpDocTypedTagInterface.php b/library/Zend/Code/Reflection/DocBlock/Tag/PhpDocTypedTagInterface.php
@@ -0,0 +1,21 @@
+<?php
+/**
+ * Zend Framework (http://framework.zend.com/)
+ *
+ * @link      http://github.com/zendframework/zf2 for the canonical source repository
+ * @copyright Copyright (c) 2005-2012 Zend Technologies USA Inc. (http://www.zend.com)
+ * @license   http://framework.zend.com/license/new-bsd New BSD License
+ * @package   Zend_Code
+ */
+
+namespace Zend\Code\Reflection\DocBlock\Tag;
+
+interface PhpDocTypedTagInterface
+{
+    /**
+     * Return all types supported by the tag definition
+     *
+     * @return string[]
+     */
+    public function getTypes();
+}
diff --git a/library/Zend/Code/Reflection/DocBlock/Tag/PropertyTag.php b/library/Zend/Code/Reflection/DocBlock/Tag/PropertyTag.php
@@ -14,12 +14,12 @@
  * @category   Zend
  * @package    Zend_Reflection
  */
-class PropertyTag implements TagInterface
+class PropertyTag implements TagInterface, PhpDocTypedTagInterface
 {
     /**
-     * @var string
+     * @var array
      */
-    protected $type = null;
+    protected $types = array();
 
     /**
      * @var string
@@ -48,7 +48,7 @@ public function initialize($tagDocblockLine)
     {
         if (preg_match('#^(.+)?(\$[\S]+)[\s]*(.*)$#m', $tagDocblockLine, $match)) {
             if ($match[1] !== '') {
-                $this->type = rtrim($match[1]);
+                $this->types = explode('|', rtrim($match[1]));
             }
 
             if ($match[2] !== '') {
@@ -65,10 +65,20 @@ public function initialize($tagDocblockLine)
      * Get property variable type
      *
      * @return null|string
+     * @deprecated 2.0.4 use getTypes instead
      */
     public function getType()
     {
-        return $this->type;
+        if (empty($this->types)) {
+            return null;
+        }
+
+        return $this->types[0];
+    }
+
+    public function getTypes()
+    {
+        return $this->types;
     }
 
     /**

diff --git a/library/Zend/Code/Reflection/DocBlock/Tag/ReturnTag.php b/library/Zend/Code/Reflection/DocBlock/Tag/ReturnTag.php
@@ -14,12 +14,12 @@
  * @category   Zend
  * @package    Zend_Reflection
  */
-class ReturnTag implements TagInterface
+class ReturnTag implements TagInterface, PhpDocTypedTagInterface
 {
     /**
-     * @var string
+     * @var array
      */
-    protected $type = null;
+    protected $types = array();
 
     /**
      * @var string
@@ -41,23 +41,33 @@ public function getName()
     public function initialize($tagDocBlockLine)
     {
         $matches = array();
-        preg_match('#([\w|\\\]+)(?:\s+(.*))?#', $tagDocBlockLine, $matches);
+        preg_match('#((?:[\w|\\\]+(?:\[\])*\|?)+)(?:\s+(.*))?#s', $tagDocBlockLine, $matches);
 
-        $this->type = $matches[1];
+        $this->types = explode('|', $matches[1]);
 
         if (isset($matches[2])) {
-            $this->description = $matches[2];
+            $this->description = trim(preg_replace('#\s+#', ' ', $matches[2]));
         }
     }
 
     /**
      * Get return variable type
      *
      * @return string
+     * @deprecated 2.0.4 use getTypes instead
      */
     public function getType()
     {
-        return $this->type;
+        if (empty($this->types)) {
+            return '';
+        }
+
+        return $this->types[0];
+    }
+
+    public function getTypes()
+    {
+        return $this->types;
     }
 
     public function getDescription()

diff --git a/library/Zend/Code/Reflection/DocBlock/Tag/ThrowsTag.php b/library/Zend/Code/Reflection/DocBlock/Tag/ThrowsTag.php
@@ -0,0 +1,73 @@
+<?php
+/**
+ * Zend Framework (http://framework.zend.com/)
+ *
+ * @link      http://github.com/zendframework/zf2 for the canonical source repository
+ * @copyright Copyright (c) 2005-2012 Zend Technologies USA Inc. (http://www.zend.com)
+ * @license   http://framework.zend.com/license/new-bsd New BSD License
+ * @package   Zend_Code
+ */
+
+namespace Zend\Code\Reflection\DocBlock\Tag;
+
+/**
+ * @category   Zend
+ * @package    Zend_Reflection
+ */
+class ThrowsTag implements TagInterface, PhpDocTypedTagInterface
+{
+    /**
+     * @var string
+     */
+    protected $type = null;
+
+    /**
+     * @var string
+     */
+    protected $description = null;
+
+    /**
+     * @return string
+     */
+    public function getName()
+    {
+        return 'throws';
+    }
+
+    /**
+     * @param  string $tagDocBlockLine
+     * @return void
+     */
+    public function initialize($tagDocBlockLine)
+    {
+        $matches = array();
+        preg_match('#([\w|\\\]+)(?:\s+(.*))?#', $tagDocBlockLine, $matches);
+
+        $this->type = $matches[1];
+
+        if (isset($matches[2])) {
+            $this->description = $matches[2];
+        }
+    }
+
+    /**
+     * Get return variable type
+     *
+     * @return string
+     * @deprecated 2.0.4 use getTypes instead
+     */
+    public function getType()
+    {
+        return $this->type;
+    }
+
+    public function getTypes()
+    {
+        return array($this->type);
+    }
+
+    public function getDescription()
+    {
+        return $this->description;
+    }
+}
diff --git a/library/Zend/Code/Reflection/DocBlock/TagManager.php b/library/Zend/Code/Reflection/DocBlock/TagManager.php
@@ -37,6 +37,7 @@ public function useDefaultPrototypes()
         $this->addTagPrototype(new Tag\ReturnTag());
         $this->addTagPrototype(new Tag\MethodTag());
         $this->addTagPrototype(new Tag\PropertyTag());
+        $this->addTagPrototype(new Tag\ThrowsTag());
         $this->addTagPrototype(new Tag\GenericTag());
     }
 

diff --git a/tests/ZendTest/Code/Reflection/DocBlock/Tag/MethodTagTest.php b/tests/ZendTest/Code/Reflection/DocBlock/Tag/MethodTagTest.php
@@ -35,11 +35,12 @@ public function testParseName()
     public function testParseNameAndType()
     {
         $tag = new MethodTag();
-        $tag->initialize('string test()');
+        $tag->initialize('string|null test()');
         $this->assertEquals('method', $tag->getName());
         $this->assertEquals('test()', $tag->getMethodName());
         $this->assertFalse($tag->isStatic());
         $this->assertEquals('string', $tag->getReturnType());
+        $this->assertEquals(array('string', 'null'), $tag->getTypes());
         $this->assertNull($tag->getDescription());
     }
 

diff --git a/tests/ZendTest/Code/Reflection/DocBlock/Tag/PropertyTagTest.php b/tests/ZendTest/Code/Reflection/DocBlock/Tag/PropertyTagTest.php
@@ -34,10 +34,11 @@ public function testParseName()
     public function testParseTypeAndName()
     {
         $tag = new PropertyTag();
-        $tag->initialize('string $test');
+        $tag->initialize('string|null $test');
         $this->assertEquals('$test', $tag->getPropertyName());
         $this->assertNull($tag->getDescription());
         $this->assertEquals('string', $tag->getType());
+        $this->assertEquals(array('string', 'null'), $tag->getTypes());
     }
 
     public function testParseNameAndDescription()

diff --git a/tests/ZendTest/Code/Reflection/DocBlockReflectionTest.php b/tests/ZendTest/Code/Reflection/DocBlockReflectionTest.php
@@ -11,6 +11,7 @@
 namespace ZendTest\Code\Reflection;
 
 use Zend\Code\Reflection\ClassReflection;
+use Zend\Code\Reflection\DocBlockReflection;
 
 /**
  * @category   Zend
@@ -120,4 +121,52 @@ public function testToString()
 
         $this->assertEquals($expectedString, (string)$classDocBlock);
     }
+
+    public function testFunctionDocBlockTags()
+    {
+        $docblock = '
+    /**
+     * Method ShortDescription
+     *
+     * @param int $one Description for one
+     * @param int[] Description for two
+     * @param string|null $three Description for three
+     *                      which spans multiple lines
+     * @return int[]|null Description
+     * @throws Exception
+     */
+';
+
+        $docblockReflection = new DocBlockReflection($docblock);
+
+        $paramTags = $docblockReflection->getTags('param');
+
+        $this->assertEquals(5, count($docblockReflection->getTags()));
+        $this->assertEquals(3, count($paramTags));
+        $this->assertEquals(1, count($docblockReflection->getTags('return')));
+        $this->assertEquals(1, count($docblockReflection->getTags('throws')));
+
+        $returnTag = $docblockReflection->getTag('return');
+        $this->assertInstanceOf('Zend\Code\Reflection\DocBlock\Tag\ReturnTag', $returnTag);
+        $this->assertEquals('int[]', $returnTag->getType());
+        $this->assertEquals(array('int[]', 'null'), $returnTag->getTypes());
+        $this->assertEquals('Description', $returnTag->getDescription());
+
+        $throwsTag = $docblockReflection->getTag('throws');
+        $this->assertInstanceOf('Zend\Code\Reflection\DocBlock\Tag\ThrowsTag', $throwsTag);
+        $this->assertEquals('Exception', $throwsTag->getType());
+
+        $paramTag = $paramTags[0];
+        $this->assertInstanceOf('Zend\Code\Reflection\DocBlock\Tag\ParamTag', $paramTag);
+        $this->assertEquals('int', $paramTag->getType());
+
+        $paramTag = $paramTags[1];
+        $this->assertInstanceOf('Zend\Code\Reflection\DocBlock\Tag\ParamTag', $paramTag);
+        $this->assertEquals('int[]', $paramTag->getType());
+
+        $paramTag = $paramTags[2];
+        $this->assertInstanceOf('Zend\Code\Reflection\DocBlock\Tag\ParamTag', $paramTag);
+        $this->assertEquals('string', $paramTag->getType());
+        $this->assertEquals(array('string', 'null'), $paramTag->getTypes());
+    }
 }