Update README.md

* Added advanced PHPDoc type keyworks

* Fixed typed keywords

.github/workflows/run-tests.yml

@@ -19,14 +19,14 @@ jobs:
 
     strategy:
       matrix:
-        php: [8.1, 8.0, 7.4, 7.3, 7.2]
+        php: [8.4, 8.3, 8.2, 8.1, 8.0, 7.4, 7.3, 7.2]
         dependency-version: [prefer-lowest, prefer-stable]
 
     name: P${{ matrix.php }} - ${{ matrix.dependency-version }}
 
     steps:
     - name: Checkout code
-      uses: actions/checkout@v2
+      uses: actions/checkout@v4
 
     - name: Setup PHP
       uses: shivammathur/setup-php@v2

.gitignore

@@ -1,3 +1,4 @@
 .idea
+.phpunit.result.cache
 composer.lock
 vendor

README.md

@@ -1,6 +1,9 @@
-The ReflectionDocBlock Component [![Build Status](https://secure.travis-ci.org/phpDocumentor/ReflectionDocBlock.png)](https://travis-ci.org/phpDocumentor/ReflectionDocBlock)
+The ReflectionDocBlock Component 
 ================================
 
+> This is a fork of [phpDocumentor/ReflectionDocBlock 2.x](https://github.com/phpDocumentor/ReflectionDocBlock/tree/release/2.x) combined with bits of [phpDocumentor/TypeResolver](https://github.com/phpDocumentor/TypeResolver) and various tweaks. The main reason for this fork is to add functionality for https://github.com/barryvdh/laravel-ide-helper
+> Any other use of this library is discouraged. You are probably better of using https://github.com/phpDocumentor/ReflectionDocBlock directly.
+
 Introduction
 ------------
 

composer.json

@@ -6,7 +6,7 @@
         {"name": "Mike van Riel", "email": "[email protected]"}
     ],
     "require": {
-        "php": ">=5.3.3"
+        "php": ">=7.1"
     },
     "autoload": {
         "psr-0": {"Barryvdh": ["src/"]}
@@ -20,7 +20,7 @@
     },
     "extra": {
         "branch-alias": {
-            "dev-master": "2.0.x-dev"
+            "dev-master": "2.3.x-dev"
         }
     }
 }

src/Barryvdh/Reflection/DocBlock.php

@@ -15,6 +15,7 @@ namespace Barryvdh\Reflection;
 use Barryvdh\Reflection\DocBlock\Tag;
 use Barryvdh\Reflection\DocBlock\Context;
 use Barryvdh\Reflection\DocBlock\Location;
+use Barryvdh\Reflection\DocBlock\Tag\TemplateTag;
 
 /**
  * Parses the DocBlock for any structure.
@@ -40,6 +41,9 @@ class DocBlock implements \Reflector
      */
     protected $tags = array();
 
+    /** @var string[] An array containing all the generics in this docblock. */
+    protected $generics = array();
+
     /** @var Context Information about the context of this DocBlock. */
     protected $context = null;
 
@@ -71,8 +75,8 @@ class DocBlock implements \Reflector
      */
     public function __construct(
         $docblock,
-        Context $context = null,
-        Location $location = null
+        ?Context $context = null,
+        ?Location $location = null
     ) {
         if (is_object($docblock)) {
             if (!method_exists($docblock, 'getDocComment')) {
@@ -238,7 +242,11 @@ class DocBlock implements \Reflector
 
             // create proper Tag objects
             foreach ($result as $key => $tag_line) {
-                $result[$key] = Tag::createInstance(trim($tag_line), $this);
+                $tag = Tag::createInstance(trim($tag_line), $this);
+                if ($tag instanceof TemplateTag) {
+                    $this->generics[] = $tag->getTemplateName();
+                }
+                $result[$key] = $tag;
             }
         }
 
@@ -457,6 +465,16 @@ class DocBlock implements \Reflector
         return false;
     }
 
+    /**
+     * Returns the generics for this DocBlock.
+     *
+     * @return string[]
+     */
+    public function getGenerics()
+    {
+        return $this->generics;
+    }
+
     /**
      * Builds a string representation of this object.
      *

src/Barryvdh/Reflection/DocBlock/Context.php

@@ -30,6 +30,9 @@ class Context
     /** @var string Name of the structural element, within the namespace. */
     protected $lsen = '';
 
+    /** @var string[] List of generics */
+    protected $generics = array();
+
     /**
      * Cteates a new context.
      * @param string $namespace         The namespace where this DocBlock
@@ -42,13 +45,15 @@ class Context
     public function __construct(
         $namespace = '',
         array $namespace_aliases = array(),
-        $lsen = ''
+        $lsen = '',
+        array $generics = array()
     ) {
         if (!empty($namespace)) {
             $this->setNamespace($namespace);
         }
         $this->setNamespaceAliases($namespace_aliases);
         $this->setLSEN($lsen);
+        $this->setGenerics($generics);
     }
 
     /**
@@ -77,6 +82,16 @@ class Context
         return $this->lsen;
     }
 
+    /**
+     * Returns the list of generics.
+     *
+     * @return string[] List of generics
+     */
+    public function getGenerics()
+    {
+        return $this->generics;
+    }
+    
     /**
      * Sets a new namespace.
      * 
@@ -151,4 +166,17 @@ class Context
         $this->lsen = (string)$lsen;
         return $this;
     }
+
+    /**
+     * Sets a new list of generics.
+     *
+     * @param string[] $generics The new list of generics.
+     *
+     * @return $this
+     */
+    public function setGenerics(array $generics)
+    {
+        $this->generics = $generics;
+        return $this;
+    }
 }

src/Barryvdh/Reflection/DocBlock/ContextFactory.php

@@ -0,0 +1,422 @@
+<?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 Barryvdh\Reflection\DocBlock;
+
+use ArrayIterator;
+use InvalidArgumentException;
+use ReflectionClass;
+use ReflectionClassConstant;
+use ReflectionMethod;
+use ReflectionParameter;
+use ReflectionProperty;
+use Reflector;
+use RuntimeException;
+use UnexpectedValueException;
+
+use function define;
+use function defined;
+use function file_exists;
+use function file_get_contents;
+use function get_class;
+use function in_array;
+use function is_string;
+use function strrpos;
+use function substr;
+use function token_get_all;
+use function trim;
+
+use const T_AS;
+use const T_CLASS;
+use const T_CURLY_OPEN;
+use const T_DOLLAR_OPEN_CURLY_BRACES;
+use const T_NAME_FULLY_QUALIFIED;
+use const T_NAME_QUALIFIED;
+use const T_NAMESPACE;
+use const T_NS_SEPARATOR;
+use const T_STRING;
+use const T_TRAIT;
+use const T_USE;
+
+if (!defined('T_NAME_QUALIFIED')) {
+    define('T_NAME_QUALIFIED', 10001);
+}
+
+if (!defined('T_NAME_FULLY_QUALIFIED')) {
+    define('T_NAME_FULLY_QUALIFIED', 10002);
+}
+
+/**
+ * Convenience class to create a Context for DocBlocks when not using the Reflection Component of phpDocumentor.
+ *
+ * For a DocBlock to be able to resolve types that use partial namespace names or rely on namespace imports we need to
+ * provide a bit of context so that the DocBlock can read that and based on it decide how to resolve the types to
+ * Fully Qualified names.
+ *
+ * @see Context for more information.
+ */
+final class ContextFactory
+{
+    /** The literal used at the end of a use statement. */
+    private const T_LITERAL_END_OF_USE = ';';
+
+    /** The literal used between sets of use statements */
+    private const T_LITERAL_USE_SEPARATOR = ',';
+
+    /**
+     * Build a Context given a Class Reflection.
+     *
+     * @see Context for more information on Contexts.
+     */
+    public function createFromReflector(Reflector $reflector): Context
+    {
+        if ($reflector instanceof ReflectionClass) {
+            //phpcs:ignore SlevomatCodingStandard.Commenting.InlineDocCommentDeclaration.MissingVariable
+            /** @var ReflectionClass<object> $reflector */
+
+            return $this->createFromReflectionClass($reflector);
+        }
+
+        if ($reflector instanceof ReflectionParameter) {
+            return $this->createFromReflectionParameter($reflector);
+        }
+
+        if ($reflector instanceof ReflectionMethod) {
+            return $this->createFromReflectionMethod($reflector);
+        }
+
+        if ($reflector instanceof ReflectionProperty) {
+            return $this->createFromReflectionProperty($reflector);
+        }
+
+        if ($reflector instanceof ReflectionClassConstant) {
+            return $this->createFromReflectionClassConstant($reflector);
+        }
+
+        throw new UnexpectedValueException('Unhandled \Reflector instance given:  ' . get_class($reflector));
+    }
+
+    private function createFromReflectionParameter(ReflectionParameter $parameter): Context
+    {
+        $class = $parameter->getDeclaringClass();
+        if (!$class) {
+            throw new InvalidArgumentException('Unable to get class of ' . $parameter->getName());
+        }
+
+        return $this->createFromReflectionClass($class);
+    }
+
+    private function createFromReflectionMethod(ReflectionMethod $method): Context
+    {
+        $class = $method->getDeclaringClass();
+
+        return $this->createFromReflectionClass($class);
+    }
+
+    private function createFromReflectionProperty(ReflectionProperty $property): Context
+    {
+        $class = $property->getDeclaringClass();
+
+        return $this->createFromReflectionClass($class);
+    }
+
+    private function createFromReflectionClassConstant(ReflectionClassConstant $constant): Context
+    {
+        //phpcs:ignore SlevomatCodingStandard.Commenting.InlineDocCommentDeclaration.MissingVariable
+        /** @phpstan-var ReflectionClass<object> $class */
+        $class = $constant->getDeclaringClass();
+
+        return $this->createFromReflectionClass($class);
+    }
+
+    /**
+     * @phpstan-param ReflectionClass<object> $class
+     */
+    private function createFromReflectionClass(ReflectionClass $class): Context
+    {
+        $fileName  = $class->getFileName();
+        $namespace = $class->getNamespaceName();
+
+        if (is_string($fileName) && file_exists($fileName)) {
+            $contents = file_get_contents($fileName);
+            if ($contents === false) {
+                throw new RuntimeException('Unable to read file "' . $fileName . '"');
+            }
+
+            return $this->createForNamespace($namespace, $contents);
+        }
+
+        return new Context($namespace, []);
+    }
+
+    /**
+     * Build a Context for a namespace in the provided file contents.
+     *
+     * @see Context for more information on Contexts.
+     *
+     * @param string $namespace    It does not matter if a `\` precedes the namespace name,
+     * this method first normalizes.
+     * @param string $fileContents The file's contents to retrieve the aliases from with the given namespace.
+     */
+    public function createForNamespace(string $namespace, string $fileContents): Context
+    {
+        $namespace        = trim($namespace, '\\');
+        $useStatements    = [];
+        $currentNamespace = '';
+        $tokens           = new ArrayIterator(token_get_all($fileContents));
+
+        while ($tokens->valid()) {
+            $currentToken = $tokens->current();
+            switch ($currentToken[0]) {
+                case T_NAMESPACE:
+                    $currentNamespace = $this->parseNamespace($tokens);
+                    break;
+                case T_CLASS:
+                case T_TRAIT:
+                    // Fast-forward the iterator through the class so that any
+                    // T_USE tokens found within are skipped - these are not
+                    // valid namespace use statements so should be ignored.
+                    $braceLevel      = 0;
+                    $firstBraceFound = false;
+                    while ($tokens->valid() && ($braceLevel > 0 || !$firstBraceFound)) {
+                        $currentToken = $tokens->current();
+                        if (
+                            $currentToken === '{'
+                            || in_array($currentToken[0], [T_CURLY_OPEN, T_DOLLAR_OPEN_CURLY_BRACES], true)
+                        ) {
+                            if (!$firstBraceFound) {
+                                $firstBraceFound = true;
+                            }
+
+                            ++$braceLevel;
+                        }
+
+                        if ($currentToken === '}') {
+                            --$braceLevel;
+                        }
+
+                        $tokens->next();
+                    }
+
+                    break;
+                case T_USE:
+                    if ($currentNamespace === $namespace) {
+                        $useStatements += $this->parseUseStatement($tokens);
+                    }
+
+                    break;
+            }
+
+            $tokens->next();
+        }
+
+        return new Context($namespace, $useStatements);
+    }
+
+    /**
+     * Deduce the name from tokens when we are at the T_NAMESPACE token.
+     *
+     * @param ArrayIterator<int, string|array{0:int,1:string,2:int}> $tokens
+     */
+    private function parseNamespace(ArrayIterator $tokens): string
+    {
+        // skip to the first string or namespace separator
+        $this->skipToNextStringOrNamespaceSeparator($tokens);
+
+        $name = '';
+        $acceptedTokens = [T_STRING, T_NS_SEPARATOR, T_NAME_QUALIFIED];
+        while ($tokens->valid() && in_array($tokens->current()[0], $acceptedTokens, true)) {
+            $name .= $tokens->current()[1];
+            $tokens->next();
+        }
+
+        return $name;
+    }
+
+    /**
+     * Deduce the names of all imports when we are at the T_USE token.
+     *
+     * @param ArrayIterator<int, string|array{0:int,1:string,2:int}> $tokens
+     *
+     * @return string[]
+     * @psalm-return array<string, string>
+     */
+    private function parseUseStatement(ArrayIterator $tokens): array
+    {
+        $uses = [];
+
+        while ($tokens->valid()) {
+            $this->skipToNextStringOrNamespaceSeparator($tokens);
+
+            $uses += $this->extractUseStatements($tokens);
+            $currentToken = $tokens->current();
+            if ($currentToken[0] === self::T_LITERAL_END_OF_USE) {
+                return $uses;
+            }
+        }
+
+        return $uses;
+    }
+
+    /**
+     * Fast-forwards the iterator as longs as we don't encounter a T_STRING or T_NS_SEPARATOR token.
+     *
+     * @param ArrayIterator<int, string|array{0:int,1:string,2:int}> $tokens
+     */
+    private function skipToNextStringOrNamespaceSeparator(ArrayIterator $tokens): void
+    {
+        while ($tokens->valid()) {
+            $currentToken = $tokens->current();
+            if (in_array($currentToken[0], [T_STRING, T_NS_SEPARATOR], true)) {
+                break;
+            }
+
+            if ($currentToken[0] === T_NAME_QUALIFIED) {
+                break;
+            }
+
+            if (defined('T_NAME_FULLY_QUALIFIED') && $currentToken[0] === T_NAME_FULLY_QUALIFIED) {
+                break;
+            }
+
+            $tokens->next();
+        }
+    }
+
+    /**
+     * Deduce the namespace name and alias of an import when we are at the T_USE token or have not reached the end of
+     * a USE statement yet. This will return a key/value array of the alias => namespace.
+     *
+     * @param ArrayIterator<int, string|array{0:int,1:string,2:int}> $tokens
+     *
+     * @return string[]
+     * @psalm-return array<string, string>
+     *
+     * @psalm-suppress TypeDoesNotContainType
+     */
+    private function extractUseStatements(ArrayIterator $tokens): array
+    {
+        $extractedUseStatements = [];
+        $groupedNs              = '';
+        $currentNs              = '';
+        $currentAlias           = '';
+        $state                  = 'start';
+
+        while ($tokens->valid()) {
+            $currentToken = $tokens->current();
+            $tokenId      = is_string($currentToken) ? $currentToken : $currentToken[0];
+            $tokenValue   = is_string($currentToken) ? null : $currentToken[1];
+            switch ($state) {
+                case 'start':
+                    switch ($tokenId) {
+                        case T_STRING:
+                        case T_NS_SEPARATOR:
+                            $currentNs   .= (string) $tokenValue;
+                            $currentAlias =  $tokenValue;
+                            break;
+                        case T_NAME_QUALIFIED:
+                        case T_NAME_FULLY_QUALIFIED:
+                            $currentNs   .= (string) $tokenValue;
+                            $currentAlias = substr(
+                                (string) $tokenValue,
+                                (int) (strrpos((string) $tokenValue, '\\')) + 1
+                            );
+                            break;
+                        case T_CURLY_OPEN:
+                        case '{':
+                            $state     = 'grouped';
+                            $groupedNs = $currentNs;
+                            break;
+                        case T_AS:
+                            $state = 'start-alias';
+                            break;
+                        case self::T_LITERAL_USE_SEPARATOR:
+                        case self::T_LITERAL_END_OF_USE:
+                            $state = 'end';
+                            break;
+                        default:
+                            break;
+                    }
+
+                    break;
+                case 'start-alias':
+                    switch ($tokenId) {
+                        case T_STRING:
+                            $currentAlias = $tokenValue;
+                            break;
+                        case self::T_LITERAL_USE_SEPARATOR:
+                        case self::T_LITERAL_END_OF_USE:
+                            $state = 'end';
+                            break;
+                        default:
+                            break;
+                    }
+
+                    break;
+                case 'grouped':
+                    switch ($tokenId) {
+                        case T_STRING:
+                        case T_NS_SEPARATOR:
+                            $currentNs   .= (string) $tokenValue;
+                            $currentAlias = $tokenValue;
+                            break;
+                        case T_AS:
+                            $state = 'grouped-alias';
+                            break;
+                        case self::T_LITERAL_USE_SEPARATOR:
+                            $state                                          = 'grouped';
+                            $extractedUseStatements[(string) $currentAlias] = $currentNs;
+                            $currentNs                                      = $groupedNs;
+                            $currentAlias                                   = '';
+                            break;
+                        case self::T_LITERAL_END_OF_USE:
+                            $state = 'end';
+                            break;
+                        default:
+                            break;
+                    }
+
+                    break;
+                case 'grouped-alias':
+                    switch ($tokenId) {
+                        case T_STRING:
+                            $currentAlias = $tokenValue;
+                            break;
+                        case self::T_LITERAL_USE_SEPARATOR:
+                            $state                                          = 'grouped';
+                            $extractedUseStatements[(string) $currentAlias] = $currentNs;
+                            $currentNs                                      = $groupedNs;
+                            $currentAlias                                   = '';
+                            break;
+                        case self::T_LITERAL_END_OF_USE:
+                            $state = 'end';
+                            break;
+                        default:
+                            break;
+                    }
+            }
+
+            if ($state === 'end') {
+                break;
+            }
+
+            $tokens->next();
+        }
+
+        if ($groupedNs !== $currentNs) {
+            $extractedUseStatements[(string) $currentAlias] = $currentNs;
+        }
+
+        return $extractedUseStatements;
+    }
+}

src/Barryvdh/Reflection/DocBlock/Description.php

@@ -35,10 +35,10 @@ class Description implements \Reflector
     /**
      * Populates the fields of a description.
      *
-     * @param string   $content  The description's conetnts.
+     * @param string   $content  The description's contents.
      * @param DocBlock $docblock The DocBlock which this description belongs to.
      */
-    public function __construct($content, DocBlock $docblock = null)
+    public function __construct($content, ?DocBlock $docblock = null)
     {
         $this->setContent($content)->setDocBlock($docblock);
     }
@@ -190,7 +190,7 @@ class Description implements \Reflector
      *
      * @return $this
      */
-    public function setDocBlock(DocBlock $docblock = null)
+    public function setDocBlock(?DocBlock $docblock = null)
     {
         $this->docblock = $docblock;
 

src/Barryvdh/Reflection/DocBlock/Tag.php

@@ -97,7 +97,9 @@ class Tag implements \Reflector
         'version'
             => '\Barryvdh\Reflection\DocBlock\Tag\VersionTag',
         'SuppressWarnings'
-            => '\Barryvdh\Reflection\DocBlock\Tag\SuppressWarningsTag'
+            => '\Barryvdh\Reflection\DocBlock\Tag\SuppressWarningsTag',
+        'template'
+            => '\Barryvdh\Reflection\DocBlock\Tag\TemplateTag'
     );
 
     /**
@@ -113,8 +115,8 @@ class Tag implements \Reflector
      */
     final public static function createInstance(
         $tag_line,
-        DocBlock $docblock = null,
-        Location $location = null
+        ?DocBlock $docblock = null,
+        ?Location $location = null
     ) {
         if (!preg_match(
             '/^@(' . self::REGEX_TAGNAME . ')(?:\s*([^\s].*)|$)?/us',
@@ -194,8 +196,8 @@ class Tag implements \Reflector
     public function __construct(
         $name,
         $content,
-        DocBlock $docblock = null,
-        Location $location = null
+        ?DocBlock $docblock = null,
+        ?Location $location = null
     ) {
         $this
             ->setName($name)
@@ -323,7 +325,7 @@ class Tag implements \Reflector
      * 
      * @return $this
      */
-    public function setDocBlock(DocBlock $docblock = null)
+    public function setDocBlock(?DocBlock $docblock = null)
     {
         $this->docblock = $docblock;
 
@@ -347,7 +349,7 @@ class Tag implements \Reflector
      * 
      * @return $this
      */
-    public function setLocation(Location $location = null)
+    public function setLocation(?Location $location = null)
     {
         $this->location = $location;
 

src/Barryvdh/Reflection/DocBlock/Tag/MethodTag.php

@@ -80,10 +80,12 @@ class MethodTag extends ReturnTag
                         (?:[\w\|_\\\\]*\$this[\w\|_\\\\]*)
                         |
                         (?:
-                            (?:[\w\|_\\\\]+)
+                            (?:[\w\|_\\\\]+(?:<[\s\S]*>)?)
                             # array notation
                             (?:\[\])*
                         )*
+                        |
+                        (?:\([\s\S]*\))?
                     )
                     \s+
                 )?

src/Barryvdh/Reflection/DocBlock/Tag/ParamTag.php

@@ -46,20 +46,37 @@ class ParamTag extends ReturnTag
     public function setContent($content)
     {
         Tag::setContent($content);
-        $parts = preg_split(
-            '/(\s+)/Su',
-            $this->description,
-            3,
-            PREG_SPLIT_DELIM_CAPTURE
-        );
 
-        // detect generic type
-        if (isset($parts[0]) && isset($parts[2]) && strpos($parts[0], '<') !== false && strpos($parts[2], '>') !== false) {
-            $parts[0] .= ' ' . $parts[2];
-            unset($parts[1]);
-            unset($parts[2]);
-            $parts = array_values($parts);
+        $parts = [];
+        $rest = $this->description;
+
+        // parsing generics and closures to detect types
+        for($pos = 0, $stacks = []; $pos < strlen($rest); $pos++) {
+            $char = $rest[$pos];
+
+            if($char === '<') {
+                array_unshift($stacks, $char);
             }
+            if($char === '(') {
+                array_unshift($stacks, $char);
+            }
+            if($char === '>' && isset($stacks[0]) && $stacks[0] === '<') {
+                array_shift($stacks);
+            }
+            if($char === ')' && isset($stacks[0]) && $stacks[0] === '(') {
+                array_shift($stacks);
+            }
+
+            if(!$stacks && preg_match('/\A(\s+)(.*)/su', substr($rest, $pos), $matches)) {
+                $parts[0] = substr($rest, 0, $pos);
+                $parts[1] = $matches[1];
+                $rest = $matches[2];
+
+                break;
+            }
+        }
+
+        array_push($parts, ...preg_split('/(\s+)/u', $rest, 2, PREG_SPLIT_DELIM_CAPTURE));
 
         // if the first item that is encountered is not a variable; it is a type
         if (isset($parts[0])

src/Barryvdh/Reflection/DocBlock/Tag/ReturnTag.php

@@ -120,7 +120,8 @@ class ReturnTag extends Tag
         if (null === $this->types) {
             $this->types = new Collection(
                 array($this->type),
-                $this->docblock ? $this->docblock->getContext() : null
+                $this->docblock ? $this->docblock->getContext() : null,
+                $this->docblock ? $this->docblock->getGenerics() : array()
             );
         }
         return $this->types;

src/Barryvdh/Reflection/DocBlock/Tag/TemplateTag.php

@@ -0,0 +1,104 @@
+<?php
+
+/**
+ * phpDocumentor
+ *
+ * PHP Version 5.3
+ *
+ * @author    Mike van Riel <[email protected]>
+ * @copyright 2010-2011 Mike van Riel / Naenius (http://www.naenius.com)
+ * @license   http://www.opensource.org/licenses/mit-license.php MIT
+ * @link      http://phpdoc.org
+ */
+
+namespace Barryvdh\Reflection\DocBlock\Tag;
+
+/**
+ * Reflection class for a @template tag in a Docblock.
+ *
+ * @author  chack1172 <[email protected]>
+ * @license http://www.opensource.org/licenses/mit-license.php MIT
+ * @link    http://phpdoc.org
+ */
+class TemplateTag extends ParamTag
+{
+    /** @var string */
+    protected $templateName = null;
+
+    /** @var string|null */
+    protected $bound = null;
+
+    public function getContent()
+    {
+        if (null === $this->content) {
+            $this->content = $this->templateName;
+            if (null !== $this->bound) {
+                $this->content .= ' of ' . $this->bound;
+            }
+        }
+
+        return $this->content;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function setContent($content)
+    {
+        $parts = explode(' of ', $content);
+        $this->templateName = $parts[0];
+        if (isset($parts[1])) {
+            $this->bound = $parts[1];
+        }
+
+        $this->setDescription('');
+        $this->content = $content;
+        return $this;
+    }
+
+    /**
+     * Gets the template name
+     *
+     * @return string
+     */
+    public function getTemplateName()
+    {
+        return $this->templateName;
+    }
+
+    /**
+     * Sets the template name
+     *
+     * @param string $templateName
+     *
+     * @return $this
+     */
+    public function setTemplateName($templateName)
+    {
+        $this->templateName = $templateName;
+        $this->content = null;
+        return $this;
+    }
+
+    /**
+     * Gets the bound type
+     *
+     * @return string|null
+     */
+    public function getBound()
+    {
+        return $this->bound;
+    }
+
+    /**
+     * Sets the bound type
+     * @param string|null $bound
+     * @return $this
+     */
+    public function setBound($bound)
+    {
+        $this->bound = $bound;
+        $this->content = null;
+        return $this;
+    }
+}

src/Barryvdh/Reflection/DocBlock/Type/Collection.php

@@ -37,7 +37,14 @@ class Collection extends \ArrayObject
     protected static $keywords = array(
         'string', 'int', 'integer', 'bool', 'boolean', 'float', 'double',
         'object', 'mixed', 'array', 'resource', 'void', 'null', 'scalar',
-        'callback', 'callable', 'false', 'true', 'self', '$this', 'static'
+        'callback', 'callable', 'false', 'true', 'self', '$this', 'static',
+        'array-key', 'number', 'iterable', 'pure-callable', 'closed-resource',
+        'open-resource', 'positive-int', 'negative-int', 'non-positive-int',
+        'non-negative-int', 'non-zero-int', 'non-empty-array', 'list',
+        'non-empty-list', 'key-of', 'value-of', 'template-type', 'class-string',
+        'callable-string', 'numeric-string', 'non-empty-string',
+        'non-falsy-string', 'literal-string', 'lowercase-string', 'never',
+        'never-return', 'never-returns', 'no-return', 'int-mask', 'int-mask-of'
     );
 
     /**
@@ -50,6 +57,13 @@ class Collection extends \ArrayObject
      */
     protected $context = null;
 
+    /**
+     * List of generics types
+     *
+     * @var string[]
+     */
+    protected $generics = array();
+
     /**
      * Registers the namespace and aliases; uses that to add and expand the
      * given types.
@@ -60,9 +74,11 @@ class Collection extends \ArrayObject
      */
     public function __construct(
         array $types = array(),
-        Context $context = null
+        ?Context $context = null,
+        array $generics = array()
     ) {
         $this->context = null === $context ? new Context() : $context;
+        $this->generics = array_merge($this->context->getGenerics(), $generics);
 
         foreach ($types as $type) {
             $this->add($type);
@@ -145,9 +161,9 @@ class Collection extends \ArrayObject
                 $type_parts[] = $curr_type;
                 $curr_type = '';
             } else {
-                if ($char === '<') {
+                if ($char === '<' || $char === '(') {
                     $nest_level++;
-                } else if ($char === '>') {
+                } else if ($char === '>' || $char === ')') {
                     $nest_level--;
                 }
 
@@ -185,7 +201,11 @@ class Collection extends \ArrayObject
             return '';
         }
 
-        if (substr($type, 0, 6) === 'array<' && substr($type, -1) === '>') {
+        if (preg_match('/^[\w-]+<.*>$/', $type)) {
+            return $type;
+        }
+
+        if($type[0] === '(') {
             return $type;
         }
 
@@ -193,7 +213,7 @@ class Collection extends \ArrayObject
             return $this->expand(substr($type, 0, -2)) . self::OPERATOR_ARRAY;
         }
 
-        if ($this->isRelativeType($type) && !$this->isTypeAKeyword($type)) {
+        if ($this->isRelativeType($type) && !$this->isTypeAKeyword($type) && !$this->isTypeAGeneric($type)) {
 
             if($this->shouldBeAbsolute($type)){
                 return self::OPERATOR_NAMESPACE . $type;
@@ -269,6 +289,19 @@ class Collection extends \ArrayObject
             || $this->isTypeAKeyword($type);
     }
 
+    /**
+     * Detects whether the given type represents a generic.
+     *
+     * @param string $type A relative or absolute type as defined in the
+     *     phpDocumentor documentation.
+     *
+     * @return bool
+     */
+    protected function isTypeAGeneric($type)
+    {
+        return in_array($type, $this->generics, true);
+    }
+
     /**
      * Detects if the type should actually be absolute, by checking if it exists.
      *

tests/Barryvdh/Reflection/DocBlock/ContextFactoryTest.php

@@ -0,0 +1,227 @@
+<?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 Barryvdh\Reflection\DocBlock;
+
+// Added imports on purpose as mock for the unit tests, please do not remove.
+use Barryvdh\Reflection\DocBlock\Tag as m, Barryvdh;
+use Barryvdh\Reflection\DocBlock;
+use Barryvdh\Reflection\DocBlock\Tag;
+use PHPUnit\Framework\TestCase;
+
+// yes, the slash is part of the test
+use PHPUnit\Framework\{
+    Assert,
+    Exception as e
+};
+use \ReflectionClass;
+use stdClass;
+
+/**
+ * @coversDefaultClass \phpDocumentor\Reflection\Types\ContextFactory
+ * @covers ::<private>
+ */
+class ContextFactoryTest extends TestCase
+{
+    /**
+     * @covers ::createFromReflector
+     * @covers ::createForNamespace
+     * @uses Barryvdh\Reflection\DocBlock\Context
+     */
+    public function testReadsNamespaceFromClassReflection(): void
+    {
+        $fixture = new ContextFactory();
+        $context = $fixture->createFromReflector(new ReflectionClass($this));
+
+        $this->assertSame(__NAMESPACE__, $context->getNamespace());
+    }
+
+    /**
+     * @covers ::createFromReflector
+     * @covers ::createForNamespace
+     * @uses Barryvdh\Reflection\DocBlock\Context
+     */
+    public function testReadsAliasesFromClassReflection(): void
+    {
+        $fixture = new ContextFactory();
+        $context = $fixture->createFromReflector(new ReflectionClass($this));
+
+        $this->assertNamespaceAliasesFrom($context);
+    }
+
+    /**
+     * @covers ::createForNamespace
+     * @uses Barryvdh\Reflection\DocBlock\Context
+     */
+    public function testReadsNamespaceFromProvidedNamespaceAndContent(): void
+    {
+        $fixture = new ContextFactory();
+        $context = $fixture->createForNamespace(__NAMESPACE__, file_get_contents(__FILE__));
+
+        $this->assertSame(__NAMESPACE__, $context->getNamespace());
+    }
+
+    /**
+     * @covers ::createForNamespace
+     * @uses Barryvdh\Reflection\DocBlock\Context
+     */
+    public function testReadsAliasesFromProvidedNamespaceAndContent(): void
+    {
+        $fixture = new ContextFactory();
+        $context = $fixture->createForNamespace(__NAMESPACE__, file_get_contents(__FILE__));
+
+        $this->assertNamespaceAliasesFrom($context);
+    }
+
+    /**
+     * @covers ::createForNamespace
+     * @uses Barryvdh\Reflection\DocBlock\Context
+     */
+    public function testTraitUseIsNotDetectedAsNamespaceUse(): void
+    {
+        $php = '<?php declare(strict_types=1);
+                namespace Foo;
+
+                trait FooTrait {}
+
+                class FooClass {
+                    use FooTrait;
+                }
+            ';
+
+        $fixture = new ContextFactory();
+        $context = $fixture->createForNamespace('Foo', $php);
+
+        $this->assertSame([], $context->getNamespaceAliases());
+    }
+
+    /**
+     * @covers ::createForNamespace
+     * @uses Barryvdh\Reflection\DocBlock\Context
+     */
+    public function testAllOpeningBracesAreCheckedWhenSearchingForEndOfClass(): void
+    {
+        $php = '<?php declare(strict_types=1);
+                namespace Foo;
+
+                trait FooTrait {}
+                trait BarTrait {}
+
+                class FooClass {
+                    use FooTrait;
+
+                    public function bar()
+                    {
+                        echo "{$baz}";
+                        echo "${baz}";
+                    }
+                }
+
+                class BarClass {
+                    use BarTrait;
+
+                    public function bar()
+                    {
+                        echo "{$baz}";
+                        echo "${baz}";
+                    }
+                }
+            ';
+
+        $fixture = new ContextFactory();
+        $context = $fixture->createForNamespace('Foo', $php);
+
+        $this->assertSame([], $context->getNamespaceAliases());
+    }
+
+    /**
+     * @covers ::createForNamespace
+     * @uses Barryvdh\Reflection\DocBlock\Context
+     */
+    public function testTraitContainsClosureWithUseStatement(): void
+    {
+        $php = '<?php declare(strict_types=1);
+                namespace Foo;
+
+                trait FooTrait {
+                    protected function check(array $data, string $key) : void
+                    {
+                        array_walk($data, function(&$item) use ($key) {
+                            // update item based on the key
+                        });
+                    }
+                }
+
+                class FooClass {
+                    use FooTrait;
+                }
+            ';
+
+        $fixture = new ContextFactory();
+        $context = $fixture->createForNamespace('Foo', $php);
+
+        $this->assertSame([], $context->getNamespaceAliases());
+    }
+
+    /**
+     * @covers ::createFromReflector
+     */
+    public function testEmptyFileName(): void
+    {
+        $fixture = new ContextFactory();
+        $context = $fixture->createFromReflector(new ReflectionClass(stdClass::class));
+
+        $this->assertSame([], $context->getNamespaceAliases());
+    }
+
+    /**
+     * @covers ::createFromReflector
+     */
+    public function testEvalDClass(): void
+    {
+        eval(
+        <<<PHP
+namespace Foo;
+
+class Bar
+{
+}
+PHP
+        );
+        $fixture = new ContextFactory();
+        $context = $fixture->createFromReflector(new ReflectionClass('Foo\Bar'));
+
+        $this->assertSame([], $context->getNamespaceAliases());
+    }
+
+    public function assertNamespaceAliasesFrom(Context $context)
+    {
+        $expected = [
+            'm' => '\\' . m::class,
+            'DocBlock' => '\\' . DocBlock::class,
+            'Tag' => '\\' . Tag::class,
+            'Barryvdh' => '\\' . 'Barryvdh',
+            'TestCase' => '\\' . TestCase::class,
+            'Assert' => '\\' . Assert::class,
+            'e' => '\\' . e::class,
+            ReflectionClass::class => '\\' . ReflectionClass::class,
+            \stdClass::class => '\\' . \stdClass::class,
+        ];
+
+        $actual = $context->getNamespaceAliases();
+
+        // sort so that order differences don't break it
+        asort($expected);
+        asort($actual);
+
+        $this->assertSame($expected, $actual);
+    }
+}

tests/Barryvdh/Reflection/DocBlock/Tag/MethodTagTest.php

@@ -142,7 +142,25 @@ class MethodTagTest extends TestCase
             array(
                 'static static foo()',
                 true, 'foo', 'static', true, 0, ''
-            )
+            ),
+
+            // generic array
+            array(
+                'array<int, string> foo()',
+                true, 'foo', 'array<int, string>', false, 0, ''
+            ),
+
+            // nested generics
+            array(
+                'array<int, array<string, mixed>> foo()',
+                true, 'foo', 'array<int, array<string, mixed>>', false, 0, ''
+            ),
+
+            // closure
+            array(
+                '(\Closure(int, string): bool) foo()',
+                true, 'foo', '(\Closure(int, string): bool)', false, 0, ''
+            ),
         );
     }
 }

tests/Barryvdh/Reflection/DocBlock/Tag/ParamTagTest.php

@@ -114,7 +114,75 @@ class ParamTagTest extends TestCase
                 array('int'),
                 '$bob',
                 "Type on a new line"
-            )
+            ),
+
+            // generic array
+            array(
+                'param',
+                'array<int, string> $names',
+                'array<int, string>',
+                array('array<int, string>'),
+                '$names',
+                ''
+            ),
+
+            // nested generics
+            array(
+                'param',
+                'array<int, array<string, mixed>> $arrays',
+                'array<int, array<string, mixed>>',
+                array('array<int, array<string, mixed>>'),
+                '$arrays',
+                ''
+            ),
+
+            // closure
+            array(
+                'param',
+                '(\Closure(int, string): bool) $callback',
+                '(\Closure(int, string): bool)',
+                array('(\Closure(int, string): bool)'),
+                '$callback',
+                ''
+            ),
+
+            // generic array in closure
+            array(
+                'param',
+                '(\Closure(array<int, string>): bool) $callback',
+                '(\Closure(array<int, string>): bool)',
+                array('(\Closure(array<int, string>): bool)'),
+                '$callback',
+                ''
+            ),
+
+            // union types in closure
+            array(
+                'param',
+                '(\Closure(int|string): bool)|bool $callback',
+                '(\Closure(int|string): bool)|bool',
+                array('(\Closure(int|string): bool)', 'bool'),
+                '$callback',
+                ''
+            ),
+
+            // example from Laravel Framework - Eloquent Builder)
+            array(
+                'param',
+                'array<array-key, array|(\Closure(\Illuminate\Database\Eloquent\Relations\Relation<*,*,*>): mixed)|string>|string  $relations',
+                'array<array-key, array|(\Closure(\Illuminate\Database\Eloquent\Relations\Relation<*,*,*>): mixed)|string>|string',
+                array('array<array-key, array|(\Closure(\Illuminate\Database\Eloquent\Relations\Relation<*,*,*>): mixed)|string>', 'string'),
+                '$relations',
+                ''
+            ),
+            array(
+                'param',
+                '(\Closure(\Illuminate\Database\Eloquent\Relations\Relation<*,*,*>): mixed)|string|null  $callback',
+                '(\Closure(\Illuminate\Database\Eloquent\Relations\Relation<*,*,*>): mixed)|string|null',
+                array('(\Closure(\Illuminate\Database\Eloquent\Relations\Relation<*,*,*>): mixed)', 'string', 'null'),
+                '$callback',
+                ''
+            ),
         );
     }
 }

tests/Barryvdh/Reflection/DocBlock/Tag/TemplateTagTest.php

@@ -0,0 +1,86 @@
+<?php
+
+/**
+ * phpDocumentor Template Tag Test
+ *
+ * PHP version 5.3
+ *
+ * @author    Daniel O'Connor <[email protected]>
+ * @copyright 2010-2011 Mike van Riel / Naenius. (http://www.naenius.com)
+ * @license   http://www.opensource.org/licenses/mit-license.php MIT
+ * @link      http://phpdoc.org
+ */
+
+namespace Barryvdh\Reflection\DocBlock\Tag;
+
+use PHPUnit\Framework\TestCase;
+
+/**
+ * Test class for \Barryvdh\Reflection\DocBlock\Tag\TemplateTag
+ *
+ * @author    Daniel O'Connor <[email protected]>
+ * @copyright 2010-2011 Mike van Riel / Naenius. (http://www.naenius.com)
+ * @license   http://www.opensource.org/licenses/mit-license.php MIT
+ * @link      http://phpdoc.org
+ */
+class TemplateTagTest extends TestCase
+{
+    /**
+     * Test that the phpDocumentor_Reflection_DocBlock_Tag_See can create a link
+     * for the @see doc block.
+     *
+     * @param string $type
+     * @param string $content
+     * @param string $exContent
+     * @param string $exReference
+     *
+     * @covers \Barryvdh\Reflection\DocBlock\Tag\SeeTag
+     * @dataProvider provideDataForConstuctor
+     *
+     * @return void
+     */
+    public function testConstructorParesInputsIntoCorrectFields(
+        $type,
+        $content,
+        $exContent,
+        $exDescription,
+        $exTemplateName,
+        $exBound
+    ) {
+        $tag = new TemplateTag($type, $content);
+
+        $this->assertEquals($type, $tag->getName());
+        $this->assertEquals($exContent, $tag->getContent());
+        $this->assertEquals($exDescription, $tag->getDescription());
+        $this->assertEquals($exTemplateName, $tag->getTemplateName());
+        $this->assertEquals($exBound, $tag->getBound());
+    }
+
+    /**
+     * Data provider for testConstructorParesInputsIntoCorrectFields
+     *
+     * @return array
+     */
+    public function provideDataForConstuctor()
+    {
+        // $type, $content, $exContent, $exDescription, $exTemplateName, $exBound
+        return array(
+            array(
+                'template',
+                'TValue',
+                'TValue',
+                '',
+                'TValue',
+                null,
+            ),
+            array(
+                'template',
+                'TValue of string',
+                'TValue of string',
+                '',
+                'TValue',
+                'string',
+            ),
+        );
+    }
+}

tests/Barryvdh/Reflection/DocBlock/Type/CollectionTest.php

@@ -144,6 +144,27 @@ class CollectionTest extends TestCase
         $this->assertSame($expected, $collection->getArrayCopy());
     }
 
+    /**
+     * @param string $fixture
+     * @param array  $expected
+     *
+     * @dataProvider provideTypesToExpandWithGenerics
+     * @covers Barryvdh\Reflection\DocBlock\Type\Collection::add
+     *
+     * @return void
+     */
+    public function testAddWithGenerics($fixture, $expected)
+    {
+        $collection = new Collection(
+            array(),
+            new Context('\My\Space', array('Alias' => '\My\Space\Aliasing'), '', array('TParent')),
+            array('TValue')
+        );
+        $collection->add($fixture);
+
+        $this->assertSame($expected, $collection->getArrayCopy());
+    }
+
     /**
      * @covers Barryvdh\Reflection\DocBlock\Type\Collection::add
      *
@@ -198,6 +219,10 @@ class CollectionTest extends TestCase
                 'DocBlock[]|int[]',
                 array($namespace.'DocBlock[]', 'int[]')
             ),
+            array(
+                'array<string>',
+                array('array<string>')
+            ),
             array(
                 'array<int, string>',
                 array('array<int, string>')
@@ -222,6 +247,42 @@ class CollectionTest extends TestCase
                 'Alias\LinkDescriptor::setLink()',
                 array('\My\Space\Aliasing\LinkDescriptor::setLink()')
             ),
+            array(
+                'int<0, 100>',
+                array('int<0, 100>')
+            ),
+            array(
+                'non-empty-array<string>',
+                array('non-empty-array<string>')
+            ),
+            array(
+                'non-empty-array<int, string>',
+                array('non-empty-array<int, string>')
+            ),
+            array(
+                'list<string>',
+                array('list<string>')
+            ),
+            array(
+                'non-empty-list<string>',
+                array('non-empty-list<string>')
+            ),
+            array(
+                'key-of<MyClass::ARRAY_CONST>',
+                array('key-of<MyClass::ARRAY_CONST>')
+            ),
+            array(
+                'value-of<MyClass::ARRAY_CONST>',
+                array('value-of<MyClass::ARRAY_CONST>')
+            ),
+            array(
+                'value-of<MyBackedEnum>',
+                array('value-of<MyBackedEnum>')
+            ),
+            array(
+                'iterable<string>',
+                array('iterable<string>')
+            ),
         );
     }
 
@@ -267,4 +328,23 @@ class CollectionTest extends TestCase
             ),
         );
     }
+
+    /**
+     * Returns the types and their expected values to test the retrieval of
+     * types including generics.
+     *
+     * @param string $method    Name of the method consuming this data provider.
+     * @param string $namespace Name of the namespace to user as basis.
+     *
+     * @return string[]
+     */
+    public function provideTypesToExpandWithGenerics($method, $namespace = '\My\Space\\')
+    {
+        return array(
+            array('TValue', array('TValue')),
+            array('TValue[]', array('TValue[]')),
+            array('TValue|DocBlock', array('TValue', $namespace . 'DocBlock')),
+            array('TParent', array('TParent')),
+        );
+    }
 }

tests/Barryvdh/Reflection/DocBlockTest.php

@@ -336,4 +336,22 @@ DOCBLOCK;
         $this->assertCount(1, $object->getTagsByName('return'));
         $this->assertCount(2, $object->getTagsByName('param'));
     }
+
+    /**
+     * @covers \Barryvdh\Reflection\DocBlock::parseTags
+     *
+     * @return void
+     */
+    public function testGenericsAreParsed()
+    {
+        $fixture = <<<DOCBLOCK
+/**
+ * @template TValue
+ * @param TValue
+ * @return TValue
+ */
+DOCBLOCK;
+        $object = new DocBlock($fixture);
+        $this->assertSame(array('TValue'), $object->getGenerics());
+    }
 }