Merge pull request #67 from Art4/improve-typed-properties

Improve for typed properties and return types

Author: Art4

.github/workflows/phpstan.yml

@@ -49,6 +49,6 @@ jobs:
         run: composer install --no-progress --prefer-dist --optimize-autoloader
 
       - name: Run PHPStan
-        run: vendor/bin/phpstan.phar analyze src --level 6
+        run: vendor/bin/phpstan.phar analyze src --level 8
 
       - run: echo "🍏 This job's status is ${{ job.status }}."

CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ## [Unreleased](https://github.com/Art4/json-api-client/compare/1.0.0...v1.x)
 
+### Added
+
+- Added type hints for parameters and return types in internal and final classes
+- New tests for improving backward compatibility in interfaces
+
+### Changed
+
+- Switched from Travis-CI to Github Actions
+
 ## [1.0.0 - 2021-03-05](https://github.com/Art4/json-api-client/compare/0.10.2...1.0.0)
 
 ### Added

phpunit.xml

@@ -9,6 +9,7 @@
     <testsuite name="all">
       <directory suffix="Test.php">tests/Unit/</directory>
       <directory suffix="Test.php">tests/Functional/</directory>
+      <directory suffix="Test.php">tests/BC/</directory>
     </testsuite>
     <testsuite name="unit">
       <directory suffix="Test.php">tests/Unit/</directory>

src/Element.php

@@ -27,9 +27,7 @@ interface Element
     /**
      * Sets the manager and parent
      *
-     * @param mixed                          $data    The data for this Element
-     * @param \Art4\JsonApiClient\Manager    $manager The manager
-     * @param \Art4\JsonApiClient\Accessable $parent  The parent
+     * @param mixed $data The data for this Element
      */
     public function __construct($data, Manager $manager, Accessable $parent);
 }

src/Helper/AbstractElement.php

@@ -32,22 +32,14 @@ abstract class AbstractElement implements Accessable, Element
 {
     use AccessableTrait;
 
-    /**
-     * @var \Art4\JsonApiClient\Manager
-     */
-    private $manager;
+    private Manager $manager;
 
-    /**
-     * @var \Art4\JsonApiClient\Accessable
-     */
-    private $parent;
+    private Accessable $parent;
 
     /**
      * Sets the manager and parent
      *
-     * @param mixed                          $data    The data for this Element
-     * @param \Art4\JsonApiClient\Manager    $manager The manager
-     * @param \Art4\JsonApiClient\Accessable $parent  The parent
+     * @param mixed $data The data for this Element
      */
     public function __construct($data, Manager $manager, Accessable $parent)
     {
@@ -59,33 +51,26 @@ public function __construct($data, Manager $manager, Accessable $parent)
 
     /**
      * Returns the Manager
-     *
-     * @return \Art4\JsonApiClient\Manager
      */
-    protected function getManager()
+    protected function getManager(): Manager
     {
         return $this->manager;
     }
 
     /**
      * Get the parent
-     *
-     * @return \Art4\JsonApiClient\Accessable
      */
-    protected function getParent()
+    protected function getParent(): Accessable
     {
         return $this->parent;
     }
 
     /**
      * Create an element
      *
-     * @param mixed $name
      * @param mixed $data
-     *
-     * @return \Art4\JsonApiClient\Accessable
      */
-    protected function create($name, $data)
+    protected function create(string $name, $data): Accessable
     {
         return $this->getManager()->getFactory()->make(
             $name,
@@ -97,8 +82,6 @@ protected function create($name, $data)
      * Parse the data
      *
      * @param mixed $data
-     *
-     * @return void
      */
-    abstract protected function parse($data);
+    abstract protected function parse($data): void;
 }

src/Helper/AccessKey.php

@@ -35,7 +35,7 @@ final class AccessKey extends SplStack
      *
      * @return AccessKey<string>
      */
-    public static function create($key)
+    public static function create($key): AccessKey
     {
         // Ignore arrays and objects
         if (is_object($key) or is_array($key)) {
@@ -61,14 +61,12 @@ public static function create($key)
     /**
      * @var string Raw key
      */
-    public $raw = '';
+    public string $raw = '';
 
     /**
      * Transforms the Key to a string
-     *
-     * @return string
      */
-    public function __toString()
+    public function __toString(): string
     {
         return $this->raw;
     }

src/Helper/AccessableTrait.php

@@ -37,29 +37,24 @@ trait AccessableTrait
     /**
      * Set a value
      *
-     * @param string $key   The Key
      * @param mixed  $value The Value
-     *
-     * @return self
      */
-    protected function set($key, $value)
+    final protected function set(string $key, $value): void
     {
         // Allow non-associative array for collections
         if ($key === '') {
             $this->data[] = $value;
         } else {
             $this->data[$key] = $value;
         }
-
-        return $this;
     }
 
     /**
      * Returns the keys of all setted values
      *
      * @return array<string> Keys of all setted values
      */
-    public function getKeys()
+    final public function getKeys()
     {
         return array_keys($this->data);
     }
@@ -71,7 +66,7 @@ public function getKeys()
      *
      * @return bool
      */
-    public function has($key)
+    final public function has($key)
     {
         $key = $this->parseKey($key);
 
@@ -90,7 +85,7 @@ public function has($key)
 
         // #TODO Handle other objects and arrays
         if (! $value instanceof Accessable) {
-            //throw new AccessException('The existance for the key "' . $key->raw . '" could\'nt be checked.');
+            // throw new AccessException('The existance for the key "' . $key->raw . '" could\'nt be checked.');
             return false;
         }
 
@@ -128,11 +123,11 @@ public function get($key)
     /**
      * Get a value by the key
      *
-     * @param string $key The key of the value
+     * @throws AccessException
      *
      * @return mixed The value
      */
-    private function getValue($key)
+    private function getValue(string $key)
     {
         if (array_key_exists($key, $this->data)) {
             return $this->data[$key];
@@ -148,7 +143,7 @@ private function getValue($key)
      *
      * @return AccessKey<string> The parsed key
      */
-    private function parseKey($key)
+    private function parseKey($key): AccessKey
     {
         if (is_object($key) and $key instanceof AccessKey) {
             return $key;

src/Helper/Parser.php

@@ -19,6 +19,7 @@
 
 namespace Art4\JsonApiClient\Helper;
 
+use Art4\JsonApiClient\Accessable;
 use Art4\JsonApiClient\Exception\Exception;
 use Art4\JsonApiClient\Input\RequestStringInput;
 use Art4\JsonApiClient\Input\ResponseStringInput;
@@ -31,29 +32,21 @@
 final class Parser
 {
     /**
-     * @param string $jsonString
-     *
-     * @throws \Art4\JsonApiClient\Exception\ValidationException If $jsonString contains invalid JSON API
      * @throws \Art4\JsonApiClient\Exception\InputException if something went wrong with the input
-     *
-     * @return \Art4\JsonApiClient\Accessable
+     * @throws \Art4\JsonApiClient\Exception\ValidationException If $jsonString contains invalid JSON API
      */
-    public static function parseResponseString($jsonString)
+    public static function parseResponseString(string $jsonString): Accessable
     {
         $manager = new ErrorAbortManager(new Factory());
 
         return $manager->parse(new ResponseStringInput($jsonString));
     }
 
     /**
-     * @param string $jsonString
-     *
-     * @throws \Art4\JsonApiClient\Exception\ValidationException If $jsonString contains invalid JSON API
      * @throws \Art4\JsonApiClient\Exception\InputException if something went wrong with the input
-     *
-     * @return \Art4\JsonApiClient\Accessable
+     * @throws \Art4\JsonApiClient\Exception\ValidationException If $jsonString contains invalid JSON API
      */
-    public static function parseRequestString($jsonString)
+    public static function parseRequestString(string $jsonString): Accessable
     {
         $manager = new ErrorAbortManager(new Factory());
 
@@ -62,12 +55,8 @@ public static function parseRequestString($jsonString)
 
     /**
      * Checks if a string is a valid JSON API response body
-     *
-     * @param string $jsonString
-     *
-     * @return bool true, if $jsonString contains valid JSON API, else false
      */
-    public static function isValidResponseString($jsonString)
+    public static function isValidResponseString(string $jsonString): bool
     {
         try {
             static::parseResponseString($jsonString);
@@ -80,12 +69,8 @@ public static function isValidResponseString($jsonString)
 
     /**
      * Checks if a string is a valid JSON API request body
-     *
-     * @param string $jsonString
-     *
-     * @return bool true, if $jsonString contains valid JSON API, else false
      */
-    public static function isValidRequestString($jsonString)
+    public static function isValidRequestString(string $jsonString): bool
     {
         try {
             static::parseRequestString($jsonString);

src/Input/RequestInput.php

@@ -20,7 +20,7 @@
 namespace Art4\JsonApiClient\Input;
 
 /**
- * Input Interface
+ * Request Input Interface
  */
 interface RequestInput
 {

src/Input/RequestStringInput.php

@@ -19,6 +19,8 @@
 
 namespace Art4\JsonApiClient\Input;
 
+use Art4\JsonApiClient\Exception\InputException;
+
 /**
  * Handles a http Request body as string
  */
@@ -33,7 +35,7 @@ final class RequestStringInput implements Input, RequestInput
      *
      * @param string $string
      *
-     * @throws \Art4\JsonApiClient\Exception\InputException if $string is not a string
+     * @throws InputException if $string is not a string
      */
     public function __construct($string)
     {
@@ -43,15 +45,19 @@ public function __construct($string)
     /**
      * Get the input as simple object
      *
-     * This should be a native PH stdClass object, so Manager could
+     * This should be a native PHP stdClass object, so Manager could
      * iterate over all public attributes
      *
-     * @throws \Art4\JsonApiClient\Exception\InputException if something went wrong with the input
-     *
-     * @return \stdClass
+     * @throws InputException if something went wrong with the input
      */
-    public function getAsObject()
+    public function getAsObject(): \stdClass
     {
-        return $this->decodeJson($this->rawString);
+        $data = $this->decodeJson($this->rawString);
+
+        if (! $data instanceof \stdClass) {
+            throw new InputException('JSON must contain an object (e.g. `{}`).');
+        }
+
+        return $data;
     }
 }