Merge pull request #87 from Art4/86-add-return-types-in-final-classes

Add return types in final classes

.phpstan.neon

@@ -76,3 +76,15 @@ parameters:
 			count: 1
 			path: tests/Unit/V1/ResourceNullTest.php
 			# We are providing an invalid parameter to test the deprecation message
+
+		-
+			message: "#^Parameter \\#1 \\$key of method Art4\\\\JsonApiClient\\\\Tests\\\\Fixtures\\\\AccessableTraitMock\\:\\:get\\(\\) expects Art4\\\\JsonApiClient\\\\Helper\\\\AccessKey\\|int\\|string, mixed given\\.$#"
+			count: 1
+			path: tests/Unit/Helper/AccessableTraitTest.php
+			# We are providing an invalid parameter to test the deprecation message
+
+		-
+			message: "#^Parameter \\#1 \\$key of method Art4\\\\JsonApiClient\\\\Tests\\\\Fixtures\\\\AccessableTraitMock\\:\\:has\\(\\) expects Art4\\\\JsonApiClient\\\\Helper\\\\AccessKey\\|int\\|string, mixed given\\.$#"
+			count: 1
+			path: tests/Unit/Helper/AccessableTraitTest.php
+			# We are providing an invalid parameter to test the deprecation message

CHANGELOG.md

@@ -11,6 +11,11 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 - Add support for PHP 8.2
 
+### Deprecated
+
+- Providing Argument #1 ($key) in `\Art4\JsonApiClient\Accessable::has()` not as `int|string` is deprecated and will throw an Exception in 2.0.0.
+- Providing Argument #1 ($key) in `\Art4\JsonApiClient\Accessable::get()` not as `int|string` is deprecated and will throw an Exception in 2.0.0.
+
 ## [1.1.0 - 2021-10-05](https://github.com/Art4/json-api-client/compare/1.0.0...1.1.0)
 
 ### Added
@@ -25,16 +30,16 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ### Deprecated
 
-- `\Art4\JsonApiClient\Accessable::has()` will add `bool` as a native return type declaration in v2.0, do the same in your implementation now to avoid errors.
-- `\Art4\JsonApiClient\Accessable::getKeys()` will add `array` as a native return type declaration in v2.0, do the same in your implementation now to avoid errors.
-- `\Art4\JsonApiClient\Exception\Exception` will extend `\Throwable` in v2.0, do the same in your implementation now to avoid errors.
-- `\Art4\JsonApiClient\Factory::make()` methods first parameter signature will be `string` in v2.0.
-- `\Art4\JsonApiClient\Factory::make()` will add `\Art4\JsonApiClient\Accessable` as a native return type declaration in v2.0, do the same in your implementation now to avoid errors.
-- `\Art4\JsonApiClient\Input\Input::getAsObject()` will add `\stdClass` as a native return type declaration in v2.0, do the same in your implementation now to avoid errors.
-- `\Art4\JsonApiClient\Manager::parse()` will add `\Art4\JsonApiClient\Accessable` as a native return type declaration in v2.0, do the same in your implementation now to avoid errors.
-- `\Art4\JsonApiClient\Manager::getFactory()` will add `\Art4\JsonApiClient\Factory` as a native return type declaration in v2.0, do the same in your implementation now to avoid errors.
-- `\Art4\JsonApiClient\Manager::getParam()` methods first parameter signature will be `string` in v2.0.
-- `\Art4\JsonApiClient\Serializer\Serializer::serialize()` will add `?array` as a native return type declaration in v2.0, do the same in your implementation now to avoid errors.
+- `\Art4\JsonApiClient\Accessable::has()` will add `bool` as a native return type declaration in 2.0.0, do the same in your implementation now to avoid errors.
+- `\Art4\JsonApiClient\Accessable::getKeys()` will add `array` as a native return type declaration in 2.0.0, do the same in your implementation now to avoid errors.
+- `\Art4\JsonApiClient\Exception\Exception` will extend `\Throwable` in 2.0.0, do the same in your implementation now to avoid errors.
+- `\Art4\JsonApiClient\Factory::make()` methods first parameter signature will be `string` in 2.0.0.
+- `\Art4\JsonApiClient\Factory::make()` will add `\Art4\JsonApiClient\Accessable` as a native return type declaration in 2.0.0, do the same in your implementation now to avoid errors.
+- `\Art4\JsonApiClient\Input\Input::getAsObject()` will add `\stdClass` as a native return type declaration in 2.0.0, do the same in your implementation now to avoid errors.
+- `\Art4\JsonApiClient\Manager::parse()` will add `\Art4\JsonApiClient\Accessable` as a native return type declaration in 2.0.0, do the same in your implementation now to avoid errors.
+- `\Art4\JsonApiClient\Manager::getFactory()` will add `\Art4\JsonApiClient\Factory` as a native return type declaration in 2.0.0, do the same in your implementation now to avoid errors.
+- `\Art4\JsonApiClient\Manager::getParam()` methods first parameter signature will be `string` in 2.0.0.
+- `\Art4\JsonApiClient\Serializer\Serializer::serialize()` will add `?array` as a native return type declaration in 2.0.0, do the same in your implementation now to avoid errors.
 
 ## [1.0.0 - 2021-03-05](https://github.com/Art4/json-api-client/compare/0.10.2...1.0.0)
 

src/Accessable.php

@@ -27,22 +27,20 @@ public function get($key);
     /**
      * Check if a value exists
      *
-     * @deprecated `\Art4\JsonApiClient\Accessable::has()` will add `bool` as a native return type declaration in v2.0. Do the same in your implementation now to avoid errors.
+     * @return-type-will-change bool `\Art4\JsonApiClient\Accessable::has()` will add `bool` as a native return type declaration in 2.0.0, do the same in your implementation now to avoid errors.
      *
      * @param mixed $key The key
      *
      * @return bool
      */
-    public function has($key);
-    // public function has($key): bool;
+    public function has($key)/*: bool */;
 
     /**
      * Returns the keys of all setted values
      *
-     * @deprecated `\Art4\JsonApiClient\Accessable::getKeys()` will add `array` as a native return type declaration in v2.0. Do the same in your implementation now to avoid errors.
+     * @return-type-will-change array `\Art4\JsonApiClient\Accessable::getKeys()` will add `array` as a native return type declaration in 2.0.0, do the same in your implementation now to avoid errors.
      *
      * @return array<string|int> Keys of all setted values
      */
-    public function getKeys();
-    // public function getKeys(): array;
+    public function getKeys()/*: array */;
 }

src/Exception/AccessException.php

@@ -8,4 +8,4 @@
 
 namespace Art4\JsonApiClient\Exception;
 
-class AccessException extends \RuntimeException implements Exception, \Throwable {}
+class AccessException extends \RuntimeException implements Exception {}

src/Exception/Exception.php

@@ -9,7 +9,7 @@
 namespace Art4\JsonApiClient\Exception;
 
 /**
- * @deprecated `\Art4\JsonApiClient\Exception\Exception` will extend `\Throwable` in v2.0. Do the same in your implementation now to avoid errors.
+ * Please note: `\Art4\JsonApiClient\Exception\Exception` will extend `\Throwable` in 2.0.0, do the same in your implementation now to avoid errors.
  */
-// interface Exception extends \Throwable
-interface Exception {}
+interface Exception /*extends \Throwable */
+{}

src/Exception/FactoryException.php

@@ -8,4 +8,4 @@
 
 namespace Art4\JsonApiClient\Exception;
 
-class FactoryException extends \Exception implements Exception, \Throwable {}
+class FactoryException extends \Exception implements Exception {}

src/Exception/InputException.php

@@ -8,4 +8,4 @@
 
 namespace Art4\JsonApiClient\Exception;
 
-class InputException extends \Exception implements Exception, \Throwable {}
+class InputException extends \Exception implements Exception {}

src/Exception/ValidationException.php

@@ -8,4 +8,4 @@
 
 namespace Art4\JsonApiClient\Exception;
 
-class ValidationException extends \InvalidArgumentException implements Exception, \Throwable {}
+class ValidationException extends \InvalidArgumentException implements Exception {}

src/Factory.php

@@ -16,14 +16,11 @@ interface Factory
     /**
      * Create a new instance of a class
      *
-     * @deprecated The `\Art4\JsonApiClient\Factory::make()` methods first parameter signature will be `string` in v2.0.
-     * @deprecated `\Art4\JsonApiClient\Factory::make()` will add `\Art4\JsonApiClient\Accessable` as a native return type declaration in v2.0. Do the same in your implementation now to avoid errors.
+     * @return-type-will-change Accessable `\Art4\JsonApiClient\Factory::make()` will add `\Art4\JsonApiClient\Accessable` as a native return type declaration in 2.0.0, do the same in your implementation now to avoid errors.
      *
-     * @param string $name
-     * @param array<mixed|Manager|Accessable>  $args
+     * @param array<mixed|Manager|Accessable> $args
      *
      * @return \Art4\JsonApiClient\Accessable
      */
-    public function make($name, array $args = []);
-    // public function make(string $name, array $args = []): Accessable;
+    public function make(string $name, array $args = [])/*: Accessable */;
 }

src/Helper/AccessKey.php

@@ -22,31 +22,20 @@ final class AccessKey extends SplStack
     /**
      * Transforms the Key to a string
      *
-     * @param int|string $key
-     *
      * @return AccessKey<string>
      */
-    public static function create($key): AccessKey
+    public static function create(string $key): AccessKey
     {
-        // Ignore arrays and objects
-        if (is_object($key) or is_array($key)) {
-            $key = '';
-        }
-
-        $key_string = strval($key);
-
-        $key = new self();
-        $key->raw = $key_string;
-
-        $keys = explode('.', $key_string);
+        $accessKey = new self();
+        $accessKey->raw = $key;
 
-        foreach ($keys as $value) {
-            $key->push($value);
+        foreach (explode('.', $key) as $value) {
+            $accessKey->push($value);
         }
 
-        $key->rewind();
+        $accessKey->rewind();
 
-        return $key;
+        return $accessKey;
     }
 
     /**

src/Helper/AccessableTrait.php

@@ -57,11 +57,12 @@ final public function has($key): bool
     {
         if (! is_int($key) && ! is_string($key) && (! is_object($key) || ! $key instanceof AccessKey)) {
             trigger_error(sprintf(
-                '%s::has(): Providing Argument #1 ($key) as %s is deprecated since 1.2.0, please provide as int|string|%s instead.',
+                '%s::has(): Providing Argument #1 ($key) as `%s` is deprecated since 1.2.0, please provide as `int|string` instead.',
                 get_class($this),
-                gettype($key),
-                AccessKey::class
+                gettype($key)
             ), \E_USER_DEPRECATED);
+
+            $key = '';
         }
 
         $key = $this->parseKey($key);
@@ -97,6 +98,16 @@ final public function has($key): bool
      */
     public function get($key)
     {
+        if (! is_int($key) && ! is_string($key) && (! is_object($key) || ! $key instanceof AccessKey)) {
+            trigger_error(sprintf(
+                '%s::get(): Providing Argument #1 ($key) as `%s` is deprecated since 1.2.0, please provide as `int|string` instead.',
+                get_class($this),
+                gettype($key)
+            ), \E_USER_DEPRECATED);
+
+            $key = '';
+        }
+
         $key = $this->parseKey($key);
 
         $string = $key->shift();
@@ -136,17 +147,13 @@ private function getValue(string $key)
      * Parse a dot.notated.key to an object
      *
      * @param int|string|AccessKey<string> $key The key
-     *
-     * @return AccessKey<string> The parsed key
      */
     private function parseKey($key): AccessKey
     {
         if (is_object($key) and $key instanceof AccessKey) {
             return $key;
         }
 
-        $key = AccessKey::create($key);
-
-        return $key;
+        return AccessKey::create(strval($key));
     }
 }

src/Helper/RootAccessable.php

@@ -9,8 +9,6 @@
 namespace Art4\JsonApiClient\Helper;
 
 use Art4\JsonApiClient\Accessable;
-use Art4\JsonApiClient\Element;
-use Art4\JsonApiClient\Manager;
 
 /**
  * RootAccessable

src/Input/Input.php

@@ -16,7 +16,7 @@ interface Input
     /**
      * Get the input as simple object
      *
-     * @deprecated `\Art4\JsonApiClient\Input\Input::getAsObject()` will add `\stdClass` as a native return type declaration in v2.0. Do the same in your implementation now to avoid errors.
+     * @return-type-will-change \stdClass `\Art4\JsonApiClient\Input\Input::getAsObject()` will add `\stdClass` as a native return type declaration in 2.0.0, do the same in your implementation now to avoid errors.
      *
      * This should be a native PHP stdClass object, so Manager could
      * iterate over all public attributes
@@ -25,6 +25,5 @@ interface Input
      *
      * @return \stdClass
      */
-    public function getAsObject();
-    // public function getAsObject(): \stdClass;
+    public function getAsObject()/*: \stdClass */;
 }

src/Manager.php

@@ -18,36 +18,30 @@ interface Manager
     /**
      * Parse the input
      *
-     * @deprecated `\Art4\JsonApiClient\Manager::parse()` will add `\Art4\JsonApiClient\Accessable` as a native return type declaration in v2.0. Do the same in your implementation now to avoid errors.
+     * @return-type-will-change Accessable `\Art4\JsonApiClient\Manager::parse()` will add `\Art4\JsonApiClient\Accessable` as a native return type declaration in 2.0.0, do the same in your implementation now to avoid errors.
      *
      * @throws \Art4\JsonApiClient\Exception\InputException If $input contains invalid JSON API
      * @throws \Art4\JsonApiClient\Exception\ValidationException If $input contains invalid JSON API
      *
      * @return \Art4\JsonApiClient\Accessable
      */
-    public function parse(Input $input);
-    // public function parse(Input $input): Accessable;
+    public function parse(Input $input)/*: Accessable */;
 
     /**
      * Get a factory from the manager
      *
-     * @deprecated `\Art4\JsonApiClient\Manager::getFactory()` will add `\Art4\JsonApiClient\Factory` as a native return type declaration in v2.0. Do the same in your implementation now to avoid errors.
+     * @return-type-will-change Factory `\Art4\JsonApiClient\Manager::getFactory()` will add `\Art4\JsonApiClient\Factory` as a native return type declaration in 2.0.0, do the same in your implementation now to avoid errors.
      *
      * @return \Art4\JsonApiClient\Factory
      */
-    public function getFactory();
-    // public function getFactory(): Factory;
+    public function getFactory()/*: Factory */;
 
     /**
      * Get a param by key
      *
-     * @deprecated The `\Art4\JsonApiClient\Manager::getParam()` methods first parameter signature will be `string` in v2.0.
-     *
-     * @param string $key
-     * @param mixed  $default
+     * @param mixed $default
      *
      * @return mixed
      */
-    public function getParam($key, $default);
-    // public function getParam(string $key, $default);
+    public function getParam(string $key, $default);
 }

src/Manager/ErrorAbortManager.php

@@ -79,12 +79,11 @@ public function getFactory(): Factory
     /**
      * Get a param by key
      *
-     * @param string $key
-     * @param mixed  $default
+     * @param mixed $default
      *
      * @return mixed
      */
-    public function getParam($key, $default)
+    public function getParam(string $key, $default)
     {
         if (array_key_exists($key, $this->config)) {
             return $this->config[$key];

src/Serializer/Serializer.php

@@ -15,9 +15,9 @@ interface Serializer
     /**
      * Serialize data
      *
-     * @deprecated `\Art4\JsonApiClient\Serializer\Serializer::serialize()` will add `?array` as a native return type declaration in v2.0. Do the same in your implementation now to avoid errors.
+     * @return-type-will-change ?array `\Art4\JsonApiClient\Serializer\Serializer::serialize()` will add `?array` as a native return type declaration in 2.0.0, do the same in your implementation now to avoid errors.
      *
      * @return array<string, mixed>|null
      */
-    public function serialize(Accessable $data);
+    public function serialize(Accessable $data)/*: ?array */;
 }

src/V1/Factory.php

@@ -55,10 +55,9 @@ public function __construct(array $overload = [])
     /**
      * Create a new instance of a class
      *
-     * @param string        $name
-     * @param array<mixed>  $args
+     * @param array<mixed> $args
      */
-    public function make($name, array $args = []): Accessable
+    public function make(string $name, array $args = []): Accessable
     {
         if (! isset($this->classes[$name])) {
             throw new FactoryException('"' . $name . '" is not a registered class');

src/V1/ResourceItemLink.php

@@ -57,7 +57,6 @@ public function get($key)
     /**
      * Set a link
      *
-     * @param string              $name The Name
      * @param string|object|mixed $link The Link
      */
     private function setLink(string $name, $link): void

src/V1/ResourceNull.php

@@ -35,14 +35,13 @@ public function __construct($data, Manager $manager, Accessable $parent) {}
      *
      * @return bool false
      */
-    public function has($key)
+    public function has($key): bool
     {
         if (! is_int($key) && ! is_string($key) && (! is_object($key) || ! $key instanceof AccessKey)) {
             trigger_error(sprintf(
-                '%s::has(): Providing Argument #1 ($key) as %s is deprecated since 1.2.0, please provide as int|string|%s instead.',
+                '%s::has(): Providing Argument #1 ($key) as `%s` is deprecated since 1.2.0, please provide as `int|string` instead.',
                 get_class($this),
-                gettype($key),
-                AccessKey::class
+                gettype($key)
             ), \E_USER_DEPRECATED);
         }
 
@@ -54,7 +53,7 @@ public function has($key)
      *
      * @return array<string> Keys of all setted values
      */
-    public function getKeys()
+    public function getKeys(): array
     {
         return [];
     }

tests/BC/AccessableTest.php

@@ -15,11 +15,14 @@ class AccessableTest extends TestCase
 {
     /**
      * This test will test a custom implementation of the Accessable interface.
-     * DO NOT CHANGE THIS!
-     * Changes are only allowed by increasing the major version number.
      */
     public function testBcForAccessableInterface(): void
     {
+        /**
+         * DO NOT CHANGE THIS CLASS!
+         *
+         * This anonymous class represents an implementation in user code
+         */
         $class = new class () implements Accessable {
             /**
              * Get a value by a key