Merge pull request #207 from orklah/static-analysis

More static analysis fixes

phpcs.xml.dist

@@ -8,6 +8,7 @@
     <arg value="p"/>
 
     <rule ref="phpDocumentor">
+        <exclude name="SlevomatCodingStandard.Exceptions.ReferenceThrowableOnly.ReferencedGeneralException" />
     </rule>
 
     <rule ref="SlevomatCodingStandard.Classes.SuperfluousAbstractClassNaming.SuperfluousPrefix">

psalm.xml

@@ -13,13 +13,18 @@
     </projectFiles>
 
     <issueHandlers>
-        <LessSpecificReturnType errorLevel="info" />
-        
         <RedundantConditionGivenDocblockType>
             <errorLevel type="info">
                 <!-- Psalm is very strict and believe that because we documented a type, it is redundant to assert it -->
                 <file name="src/DocBlock/StandardTagFactory.php"/>
             </errorLevel>
         </RedundantConditionGivenDocblockType>
+
+        <PossiblyNullArrayOffset>
+            <errorLevel type="info">
+                <!-- Psalm forbid accessing an array with a null offset but it's still working code without notice -->
+                <file name="src/DocBlock/StandardTagFactory.php"/>
+            </errorLevel>
+        </PossiblyNullArrayOffset>
     </issueHandlers>
 </psalm>

src/DocBlock.php

@@ -19,7 +19,7 @@ use Webmozart\Assert\Assert;
 final class DocBlock
 {
     /** @var string The opening line for this docblock. */
-    private $summary = '';
+    private $summary;
 
     /** @var DocBlock\Description The actual description for this docblock. */
     private $description;
@@ -34,10 +34,10 @@ final class DocBlock
     private $location;
 
     /** @var bool Is this DocBlock (the start of) a template? */
-    private $isTemplateStart = false;
+    private $isTemplateStart;
 
     /** @var bool Does this DocBlock signify the end of a DocBlock template? */
-    private $isTemplateEnd = false;
+    private $isTemplateEnd;
 
     /**
      * @param DocBlock\Tag[] $tags

src/DocBlock/DescriptionFactory.php

@@ -158,7 +158,7 @@ class DescriptionFactory
 
         // determine how many whitespace characters need to be stripped
         $startingSpaceCount = 9999999;
-        for ($i = 1; $i < count($lines); ++$i) {
+        for ($i = 1, $iMax = count($lines); $i < $iMax; ++$i) {
             // lines with a no length do not count as they are not indented at all
             if (strlen(trim($lines[$i])) === 0) {
                 continue;
@@ -171,7 +171,7 @@ class DescriptionFactory
 
         // strip the number of spaces from each line
         if ($startingSpaceCount > 0) {
-            for ($i = 1; $i < count($lines); ++$i) {
+            for ($i = 1, $iMax = count($lines); $i < $iMax; ++$i) {
                 $lines[$i] = substr($lines[$i], $startingSpaceCount);
             }
         }

src/DocBlock/Serializer.php

@@ -98,10 +98,7 @@ class Serializer
         return $comment . $indent . ' */';
     }
 
-    /**
-     * @return mixed
-     */
-    private function removeTrailingSpaces(string $indent, string $text)
+    private function removeTrailingSpaces(string $indent, string $text) : string
     {
         return str_replace(
             sprintf("\n%s * \n", $indent),
@@ -110,10 +107,7 @@ class Serializer
         );
     }
 
-    /**
-     * @return mixed
-     */
-    private function addAsterisksForEachLine(string $indent, string $text)
+    private function addAsterisksForEachLine(string $indent, string $text) : string
     {
         return str_replace(
             "\n",

src/DocBlock/StandardTagFactory.php

@@ -212,6 +212,7 @@ final class StandardTagFactory implements TagFactory
         try {
             $callable = [$handlerClassName, 'create'];
             Assert::isCallable($callable);
+            /** @phpstan-var callable(string): ?Tag $callable */
             $tag = call_user_func_array($callable, $arguments);
 
             return $tag ?? InvalidTag::create($body, $name);
@@ -222,6 +223,8 @@ final class StandardTagFactory implements TagFactory
 
     /**
      * Determines the Fully Qualified Class Name of the Factory or Tag (containing a Factory Method `create`).
+     *
+     * @return class-string<StaticMethod>
      */
     private function findHandlerClassName(string $tagName, TypeContext $context) : string
     {

src/DocBlock/Tag.php

@@ -21,6 +21,8 @@ interface Tag
 
     /**
      * @return Tag|mixed Class that implements Tag
+     *
+     * @phpstan-return ?Tag
      */
     public static function create(string $body);
 

src/DocBlock/Tags/Author.php

@@ -29,10 +29,10 @@ final class Author extends BaseTag implements Factory\StaticMethod
     protected $name = 'author';
 
     /** @var string The name of the author */
-    private $authorName = '';
+    private $authorName;
 
     /** @var string The email of the author */
-    private $authorEmail = '';
+    private $authorEmail;
 
     /**
      * Initializes this tag with the author name and e-mail.

src/DocBlock/Tags/Deprecated.php

@@ -44,7 +44,7 @@ final class Deprecated extends BaseTag implements Factory\StaticMethod
     )';
 
     /** @var string|null The version vector. */
-    private $version = '';
+    private $version;
 
     public function __construct(?string $version = null, ?Description $description = null)
     {

src/DocBlock/Tags/Example.php

@@ -34,7 +34,7 @@ final class Example implements Tag, Factory\StaticMethod
      * @var bool Whether the file path component represents an URI. This determines how the file portion
      *     appears at {@link getContent()}.
      */
-    private $isURI = false;
+    private $isURI;
 
     /** @var int */
     private $startingLine;
@@ -55,7 +55,7 @@ final class Example implements Tag, Factory\StaticMethod
         $this->startingLine = $startingLine;
         $this->lineCount    = $lineCount;
         if ($content !== null) {
-            $this->content = trim((string) $content);
+            $this->content = trim($content);
         }
 
         $this->isURI = $isURI;

src/DocBlock/Tags/InvalidTag.php

@@ -5,6 +5,7 @@ declare(strict_types=1);
 namespace phpDocumentor\Reflection\DocBlock\Tags;
 
 use Closure;
+use Exception;
 use phpDocumentor\Reflection\DocBlock\Tag;
 use ReflectionClass;
 use ReflectionFunction;
@@ -54,12 +55,7 @@ final class InvalidTag implements Tag
         return $this->name;
     }
 
-    /**
-     * @return self
-     *
-     * @inheritDoc
-     */
-    public static function create(string $body, string $name = '')
+    public static function create(string $body, string $name = '') : self
     {
         return new self($name, $body);
     }
@@ -81,7 +77,7 @@ final class InvalidTag implements Tag
      */
     private function flattenExceptionBacktrace(Throwable $exception) : void
     {
-        $traceProperty = (new ReflectionClass('Exception'))->getProperty('trace');
+        $traceProperty = (new ReflectionClass(Exception::class))->getProperty('trace');
         $traceProperty->setAccessible(true);
 
         $flatten =

src/DocBlock/Tags/Method.php

@@ -42,16 +42,16 @@ final class Method extends BaseTag implements Factory\StaticMethod
     protected $name = 'method';
 
     /** @var string */
-    private $methodName = '';
+    private $methodName;
 
     /**
      * @phpstan-var array<int, array{name: string, type: Type}>
      * @var array<int, array<string, Type|string>>
      */
-    private $arguments = [];
+    private $arguments;
 
     /** @var bool */
-    private $isStatic = false;
+    private $isStatic;
 
     /** @var Type */
     private $returnType;

src/DocBlock/Tags/Param.php

@@ -81,17 +81,19 @@ final class Param extends TagWithType implements Factory\StaticMethod
         // if the next item starts with a $ or ...$ it must be the variable name
         if (isset($parts[0])
             && (strlen($parts[0]) > 0)
-            && ($parts[0][0] === '$' || substr($parts[0], 0, 4) === '...$')
+            && (strpos($parts[0], '$') === 0 || strpos($parts[0], '...$') === 0)
         ) {
             $variableName = array_shift($parts);
             array_shift($parts);
 
-            if ($variableName !== null && strpos($variableName, '...') === 0) {
+            Assert::notNull($variableName);
+
+            if (strpos($variableName, '...') === 0) {
                 $isVariadic   = true;
                 $variableName = substr($variableName, 3);
             }
 
-            if ($variableName !== null && strpos($variableName, '$') === 0) {
+            if (strpos($variableName, '$') === 0) {
                 $variableName = substr($variableName, 1);
             }
         }

src/DocBlock/Tags/Property.php

@@ -34,7 +34,7 @@ use const PREG_SPLIT_DELIM_CAPTURE;
 final class Property extends TagWithType implements Factory\StaticMethod
 {
     /** @var string|null */
-    protected $variableName = '';
+    protected $variableName;
 
     public function __construct(?string $variableName, ?Type $type = null, ?Description $description = null)
     {
@@ -71,13 +71,13 @@ final class Property extends TagWithType implements Factory\StaticMethod
         }
 
         // if the next item starts with a $ or ...$ it must be the variable name
-        if (isset($parts[0]) && ($parts[0] !== '') && (strpos($parts[0], '$') === 0)) {
+        if (isset($parts[0]) && strpos($parts[0], '$') === 0) {
             $variableName = array_shift($parts);
             array_shift($parts);
 
-            if ($variableName !== null && strpos($variableName, '$') === 0) {
-                $variableName = substr($variableName, 1);
-            }
+            Assert::notNull($variableName);
+
+            $variableName = substr($variableName, 1);
         }
 
         $description = $descriptionFactory->create(implode('', $parts), $context);

src/DocBlock/Tags/PropertyRead.php

@@ -34,7 +34,7 @@ use const PREG_SPLIT_DELIM_CAPTURE;
 final class PropertyRead extends TagWithType implements Factory\StaticMethod
 {
     /** @var string|null */
-    protected $variableName = '';
+    protected $variableName;
 
     public function __construct(?string $variableName, ?Type $type = null, ?Description $description = null)
     {
@@ -71,13 +71,13 @@ final class PropertyRead extends TagWithType implements Factory\StaticMethod
         }
 
         // if the next item starts with a $ or ...$ it must be the variable name
-        if (isset($parts[0]) && ($parts[0] !== '') && (strpos($parts[0], '$') === 0)) {
+        if (isset($parts[0]) && strpos($parts[0], '$') === 0) {
             $variableName = array_shift($parts);
             array_shift($parts);
 
-            if ($variableName !== null && strpos($variableName, '$') === 0) {
-                $variableName = substr($variableName, 1);
-            }
+            Assert::notNull($variableName);
+
+            $variableName = substr($variableName, 1);
         }
 
         $description = $descriptionFactory->create(implode('', $parts), $context);

src/DocBlock/Tags/PropertyWrite.php

@@ -34,7 +34,7 @@ use const PREG_SPLIT_DELIM_CAPTURE;
 final class PropertyWrite extends TagWithType implements Factory\StaticMethod
 {
     /** @var string */
-    protected $variableName = '';
+    protected $variableName;
 
     public function __construct(?string $variableName, ?Type $type = null, ?Description $description = null)
     {
@@ -71,13 +71,13 @@ final class PropertyWrite extends TagWithType implements Factory\StaticMethod
         }
 
         // if the next item starts with a $ or ...$ it must be the variable name
-        if (isset($parts[0]) && (strlen($parts[0]) > 0) && ($parts[0][0] === '$')) {
+        if (isset($parts[0]) && strpos($parts[0], '$') === 0) {
             $variableName = array_shift($parts);
             array_shift($parts);
 
-            if ($variableName !== null && strpos($variableName, '$') === 0) {
-                $variableName = substr($variableName, 1);
-            }
+            Assert::notNull($variableName);
+
+            $variableName = substr($variableName, 1);
         }
 
         $description = $descriptionFactory->create(implode('', $parts), $context);

src/DocBlock/Tags/Since.php

@@ -44,7 +44,7 @@ final class Since extends BaseTag implements Factory\StaticMethod
     )';
 
     /** @var string|null The version vector. */
-    private $version = '';
+    private $version;
 
     public function __construct(?string $version = null, ?Description $description = null)
     {

src/DocBlock/Tags/Source.php

@@ -28,7 +28,7 @@ final class Source extends BaseTag implements Factory\StaticMethod
     protected $name = 'source';
 
     /** @var int The starting line, relative to the structural element's location. */
-    private $startingLine = 1;
+    private $startingLine;
 
     /** @var int|null The number of lines, relative to the starting line. NULL means "to the end". */
     private $lineCount;

src/DocBlock/Tags/TagWithType.php

@@ -39,7 +39,7 @@ abstract class TagWithType extends BaseTag
     {
         $type         = '';
         $nestingLevel = 0;
-        for ($i = 0; $i < strlen($body); $i++) {
+        for ($i = 0, $iMax = strlen($body); $i < $iMax; $i++) {
             $character = $body[$i];
 
             if (trim($character) === '' && $nestingLevel === 0) {

src/DocBlock/Tags/Var_.php

@@ -72,13 +72,13 @@ final class Var_ extends TagWithType implements Factory\StaticMethod
         }
 
         // if the next item starts with a $ or ...$ it must be the variable name
-        if (isset($parts[0]) && ($parts[0] !== '') && (strpos($parts[0], '$') === 0)) {
+        if (isset($parts[0]) && strpos($parts[0], '$') === 0) {
             $variableName = array_shift($parts);
             array_shift($parts);
 
-            if ($variableName !== null && strpos($variableName, '$') === 0) {
-                $variableName = substr($variableName, 1);
-            }
+            Assert::notNull($variableName);
+
+            $variableName = substr($variableName, 1);
         }
 
         $description = $descriptionFactory->create(implode('', $parts), $context);

src/DocBlock/Tags/Version.php

@@ -44,7 +44,7 @@ final class Version extends BaseTag implements Factory\StaticMethod
     )';
 
     /** @var string|null The version vector. */
-    private $version = '';
+    private $version;
 
     public function __construct(?string $version = null, ?Description $description = null)
     {

src/DocBlockFactory.php

@@ -52,7 +52,7 @@ final class DocBlockFactory implements DocBlockFactoryInterface
     /**
      * Factory method for easy instantiation.
      *
-     * @param array<class-string<StaticMethod>> $additionalTags
+     * @param array<string, class-string<StaticMethod>> $additionalTags
      */
     public static function createInstance(array $additionalTags = []) : self
     {
@@ -85,6 +85,7 @@ final class DocBlockFactory implements DocBlockFactoryInterface
             }
 
             $docblock = $docblock->getDocComment();
+            Assert::string($docblock);
         }
 
         Assert::stringNotEmpty($docblock);

src/DocBlockFactoryInterface.php

@@ -12,7 +12,7 @@ interface DocBlockFactoryInterface
     /**
      * Factory method for easy instantiation.
      *
-     * @param array<class-string<StaticMethod>> $additionalTags
+     * @param array<string, class-string<StaticMethod>> $additionalTags
      */
     public static function createInstance(array $additionalTags = []) : DocBlockFactory;