Static analysis with PHPStan

.travis.yml

@@ -54,6 +54,7 @@ install:
   - composer require symfony/yaml:"${YAML}" --prefer-dist --no-interaction
 script:
   - make lint
+  - make stan
   - make test
   - if [[ $TRAVIS_PHP_VERSION = "7.3" || $TRAVIS_PHP_VERSION = "nightly" ]]; then true; else make check-style; fi
   - make coverage

Makefile

@@ -25,6 +25,9 @@ lint:
 	node_modules/.bin/speccy lint tests/spec/data/reference/playlist.json
 	node_modules/.bin/speccy lint tests/spec/data/recursion.json
 
+stan:
+	php $(PHPARGS) vendor/bin/phpstan analyse -l 5 src
+
 # copy openapi3 json schema
 schemas/openapi-v3.0.json: vendor/oai/openapi-specification/schemas/v3.0/schema.json
 	cp $< $@

composer.json

@@ -31,7 +31,8 @@
 		"oai/openapi-specification": "3.0.2",
 		"mermade/openapi3-examples": "1.0.0",
 		"apis-guru/openapi-directory": "1.0.0",
-		"nexmo/api-specification": "1.0.0"
+		"nexmo/api-specification": "1.0.0",
+		"phpstan/phpstan": "^0.12.0"
 	},
 	"autoload": {
 		"psr-4": {

src/ReferenceContext.php

@@ -57,17 +57,11 @@ private function normalizeUri($uri)
         throw new UnresolvableReferenceException('Can not resolve references for a specification given as a relative path.');
     }
 
-    /**
-     * @return mixed
-     */
     public function getBaseSpec(): ?SpecObjectInterface
     {
         return $this->_baseSpec;
     }
 
-    /**
-     * @return mixed
-     */
     public function getUri(): string
     {
         return $this->_uri;

src/Writer.php

@@ -19,7 +19,7 @@ class Writer
 {
     /**
      * Convert OpenAPI spec object to JSON data.
-     * @param SpecObjectInterface|OpenApi the OpenApi object instance.
+     * @param SpecObjectInterface|OpenApi $object the OpenApi object instance.
      * @return string JSON string.
      */
     public static function writeToJson(SpecObjectInterface $object): string
@@ -29,7 +29,7 @@ public static function writeToJson(SpecObjectInterface $object): string
 
     /**
      * Convert OpenAPI spec object to YAML data.
-     * @param SpecObjectInterface|OpenApi the OpenApi object instance.
+     * @param SpecObjectInterface|OpenApi $object the OpenApi object instance.
      * @return string YAML string.
      */
     public static function writeToYaml(SpecObjectInterface $object): string
@@ -39,7 +39,7 @@ public static function writeToYaml(SpecObjectInterface $object): string
 
     /**
      * Write OpenAPI spec object to JSON file.
-     * @param SpecObjectInterface|OpenApi the OpenApi object instance.
+     * @param SpecObjectInterface|OpenApi $object the OpenApi object instance.
      * @param string $fileName file name to write to.
      * @throws IOException when writing the file fails.
      */
@@ -52,7 +52,7 @@ public static function writeToJsonFile(SpecObjectInterface $object, string $file
 
     /**
      * Write OpenAPI spec object to YAML file.
-     * @param SpecObjectInterface|OpenApi the OpenApi object instance.
+     * @param SpecObjectInterface|OpenApi $object the OpenApi object instance.
      * @param string $fileName file name to write to.
      * @throws IOException when writing the file fails.
      */

src/json/JsonReference.php

@@ -90,9 +90,6 @@ public function __clone()
     }
 
 
-    /**
-     * @return string returns the JSON Pointer.
-     */
     public function getJsonPointer(): JsonPointer
     {
         return $this->_pointer;

src/spec/PathItem.php

@@ -66,7 +66,7 @@ protected function attributes(): array
     /**
      * Create an object from spec data.
      * @param array $data spec data read from YAML or JSON
-     * @throws TypeErrorException in case invalid data is supplied.
+     * @throws \cebe\openapi\exceptions\TypeErrorException in case invalid data is supplied.
      */
     public function __construct(array $data)
     {
@@ -142,7 +142,7 @@ public function setReferenceContext(ReferenceContext $context)
 
     /**
      * Resolves all Reference Objects in this object and replaces them with their resolution.
-     * @throws exceptions\UnresolvableReferenceException in case resolving a reference fails.
+     * @throws \cebe\openapi\exceptions\UnresolvableReferenceException in case resolving a reference fails.
      */
     public function resolveReferences(ReferenceContext $context = null)
     {

src/spec/Paths.php

@@ -31,7 +31,7 @@
 class Paths implements SpecObjectInterface, DocumentContextInterface, ArrayAccess, Countable, IteratorAggregate
 {
     /**
-     * @var PathItem[]
+     * @var (PathItem|null)[]
      */
     private $_paths = [];
 
@@ -43,7 +43,7 @@ class Paths implements SpecObjectInterface, DocumentContextInterface, ArrayAcces
 
     /**
      * Create an object from spec data.
-     * @param PathItem[]|array[] $data spec data read from YAML or JSON
+     * @param (PathItem|array|null)[] $data spec data read from YAML or JSON
      * @throws TypeErrorException in case invalid data is supplied.
      */
     public function __construct(array $data)

src/spec/Reference.php

@@ -145,7 +145,7 @@ public function getContext() : ?ReferenceContext
      * @param ReferenceContext $context the reference context to use for resolution.
      * If not specified, `getContext()` will be called to determine the context, if
      * that does not return a context, the UnresolvableReferenceException will be thrown.
-     * @return SpecObjectInterface the resolved spec type.
+     * @return SpecObjectInterface|array|null the resolved spec type.
      * You might want to call resolveReferences() on the resolved object to recursively resolve recursive references.
      * This is not done automatically to avoid recursion to run into the same function again.
      * If you call resolveReferences() make sure to replace the Reference with the resolved object first.
@@ -172,7 +172,7 @@ public function resolve(ReferenceContext $context = null)
                 $baseSpec = $context->getBaseSpec();
                 if ($baseSpec !== null) {
                     // TODO type error if resolved object does not match $this->_to ?
-                    /** @var $referencedObject SpecObjectInterface */
+                    /** @var SpecObjectInterface $referencedObject */
                     $referencedObject = $jsonReference->getJsonPointer()->evaluate($baseSpec);
                     if ($referencedObject instanceof SpecObjectInterface) {
                         $referencedObject->setReferenceContext($context);
@@ -199,7 +199,7 @@ public function resolve(ReferenceContext $context = null)
             if (isset($referencedData['$ref'])) {
                 return (new Reference($referencedData, $this->_to))->resolve(new ReferenceContext(null, $file));
             }
-            /** @var $referencedObject SpecObjectInterface|array */
+            /** @var SpecObjectInterface|array $referencedObject */
             $referencedObject = $this->_to !== null ? new $this->_to($referencedData) : $referencedData;
 
             if ($jsonReference->getJsonPointer()->getPointer() === '') {

src/spec/Responses.php

@@ -27,7 +27,7 @@
 class Responses implements SpecObjectInterface, DocumentContextInterface, ArrayAccess, Countable, IteratorAggregate
 {
     /**
-     * @var Response[]|Reference[]
+     * @var (Response|Reference|null)[]
      */
     private $_responses = [];
     private $_errors = [];
@@ -90,7 +90,7 @@ public function hasResponse($statusCode): bool
 
     /**
      * @param string $statusCode HTTP status code
-     * @return Response|Reference
+     * @return Response|Reference|null
      */
     public function getResponse($statusCode)
     {
@@ -115,7 +115,7 @@ public function removeResponse($statusCode)
     }
 
     /**
-     * @return Response[]|Reference[]
+     * @return (Response|Reference|null)[]
      */
     public function getResponses(): array
     {
@@ -239,6 +239,7 @@ public function resolveReferences(ReferenceContext $context = null)
     {
         foreach ($this->_responses as $key => $response) {
             if ($response instanceof Reference) {
+                /** @var Response|Reference|null $referencedObject */
                 $referencedObject = $response->resolve($context);
                 $this->_responses[$key] = $referencedObject;
                 if (!$referencedObject instanceof Reference && $referencedObject !== null) {