refactor API interfaces #10

Author: gregor-j

src/Api/IArray.php

@@ -10,13 +10,14 @@
 /**
  * Interface IArray
  *
- * API extend the logic of values to contain member elements.
+ * API arrays extend the logic of elements to contain member elements. They are
+ * the basis for structs and tables.
  *
  * @package phpsap\interfaces\Api
  * @author  Gregor J.
  * @license MIT
  */
-interface IArray extends IValue
+interface IArray extends IElement
 {
     /**
      * JSON configuration key for members array.
@@ -25,12 +26,12 @@ interface IArray extends IValue
 
     /**
      * Cast a given output value to the implemented value.
-     * @param array $value The output array to typecast.
-     * @return array
+     * @param array<int|string, mixed> $value The output array to typecast.
+     * @return array<int|string, mixed>
      * @throws IArrayElementMissingException
      * @throws IInvalidArgumentException
      */
-    public function cast($value): array;
+    public function cast(array $value): array;
 
     /**
      * Return an array of member elements.

src/Api/IElement.php

@@ -12,8 +12,9 @@
 /**
  * Interface IElement
  *
- * API elements are struct or table members and have no direction or optional flag
- * of their own.
+ * API elements build the basis for API values, structs and tables. They have a
+ * name, a type, a direction and an optional flag. However, they don't contain
+ * any values.
  *
  * @package phpsap\interfaces\Api
  * @author  Gregor J.
@@ -22,60 +23,34 @@
 interface IElement extends IJsonSerializable
 {
     /**
-     * API element that casts to PHP string.
-     */
-    public const TYPE_STRING = 'string';
-
-    /**
-     * API element that casts to PHP int.
-     */
-    public const TYPE_INTEGER = 'int';
-
-    /**
-     * API element that casts to PHP bool.
-     */
-    public const TYPE_BOOLEAN = 'bool';
-
-    /**
-     * API element that casts to PHP float.
-     */
-    public const TYPE_FLOAT = 'float';
-
-    /**
-     * API element that casts to a hexadecimal encoded binary to a binary.
-     * (direction: output)
-     */
-    public const TYPE_HEXBIN = 'hexbin';
-
-    /**
-     * API date element that casts to a DateTime object.
+     * JSON configuration key for type value.
      */
-    public const TYPE_DATE = 'date';
+    public const JSON_TYPE = 'type';
 
     /**
-     * API time element that casts to a DateTime object.
+     * JSON configuration key for name value.
      */
-    public const TYPE_TIME = 'time';
+    public const JSON_NAME = 'name';
 
     /**
-     * API virtual timestamp element (e.g. string) that casts to a DateTime object.
+     * API input element.
      */
-    public const TYPE_TIMESTAMP = 'timestamp';
+    public const DIRECTION_INPUT = 'input';
 
     /**
-     * API virtual calendar week element (e.g. string) that casts to a DateTime object.
+     * API output element.
      */
-    public const TYPE_WEEK = 'week';
+    public const DIRECTION_OUTPUT = 'output';
 
     /**
-     * JSON configuration key for type value.
+     * JSON configuration key for direction value.
      */
-    public const JSON_TYPE = 'type';
+    public const JSON_DIRECTION = 'direction';
 
     /**
-     * JSON configuration key for name value.
+     * JSON configuration key for is optional flag.
      */
-    public const JSON_NAME = 'name';
+    public const JSON_OPTIONAL = 'optional';
 
     /**
      * The PHP type of the element.
@@ -90,10 +65,15 @@ public function getType(): string;
     public function getName(): string;
 
     /**
-     * Cast a given output value to the implemented value.
-     * @param bool|int|float|string $value The output to typecast.
-     * @return bool|int|float|string|SapDateTime|SapDateInterval
-     * @throws IInvalidArgumentException
+     * Get the direction of the parameter.
+     * interface.
+     * @return string
+     */
+    public function getDirection(): string;
+
+    /**
+     * Is the element optional?
+     * @return bool
      */
-    public function cast($value);
+    public function isOptional(): bool;
 }

src/Api/IStruct.php

@@ -7,7 +7,7 @@
 /**
  * Interface IStruct
  *
- * API extend the logic of arrays to contain member elements.
+ * API structs extend the logic of arrays to contain an associative array.
  *
  * @package phpsap\interfaces\Api
  * @author  Gregor J.

src/Api/ITable.php

@@ -7,7 +7,8 @@
 /**
  * Interface ITable
  *
- * API extend the logic of arrays but contains rows of member elements.
+ * API tables extend the logic of arrays to contain an array of associative
+ * arrays.
  *
  * @package phpsap\interfaces\Api
  * @author  Gregor J.

src/Api/IValue.php

@@ -4,11 +4,16 @@
 
 namespace phpsap\interfaces\Api;
 
+use phpsap\DateTime\SapDateInterval;
+use phpsap\DateTime\SapDateTime;
+use phpsap\interfaces\exceptions\IInvalidArgumentException;
+
 /**
  * Interface IValue
  *
- * API values extend the logic of an element but have a direction (input or output)
- * and an optional flag, unlike elements.
+ * API values extend the logic of an element. They describe primitive values,
+ * like integers, booleans, strings, etc., but also more complex values, like
+ * date and time, or intervals.
  *
  * @package phpsap\interfaces\Api
  * @author  Gregor J.
@@ -17,35 +22,56 @@
 interface IValue extends IElement
 {
     /**
-     * API input element.
+     * API element that casts to PHP string.
+     */
+    public const TYPE_STRING = 'string';
+
+    /**
+     * API element that casts to PHP int.
+     */
+    public const TYPE_INTEGER = 'int';
+
+    /**
+     * API element that casts to PHP bool.
+     */
+    public const TYPE_BOOLEAN = 'bool';
+
+    /**
+     * API element that casts to PHP float.
+     */
+    public const TYPE_FLOAT = 'float';
+
+    /**
+     * API element that casts to a hexadecimal encoded binary to a binary.
+     * (direction: output)
      */
-    public const DIRECTION_INPUT = 'input';
+    public const TYPE_HEXBIN = 'hexbin';
 
     /**
-     * API output element.
+     * API date element that casts to a DateTime object.
      */
-    public const DIRECTION_OUTPUT = 'output';
+    public const TYPE_DATE = 'date';
 
     /**
-     * JSON configuration key for direction value.
+     * API time element that casts to a DateTime object.
      */
-    public const JSON_DIRECTION = 'direction';
+    public const TYPE_TIME = 'time';
 
     /**
-     * JSON configuration key for is optional flag.
+     * API virtual timestamp element (e.g. string) that casts to a DateTime object.
      */
-    public const JSON_OPTIONAL = 'optional';
+    public const TYPE_TIMESTAMP = 'timestamp';
 
     /**
-     * Get the direction of the parameter.
-     * interface.
-     * @return string
+     * API virtual calendar week element (e.g. string) that casts to a DateTime object.
      */
-    public function getDirection(): string;
+    public const TYPE_WEEK = 'week';
 
     /**
-     * Is the element optional?
-     * @return bool
+     * Cast a given output value to the implemented value.
+     * @param bool|int|float|string $value The output to typecast.
+     * @return bool|int|float|string|SapDateTime|SapDateInterval
+     * @throws IInvalidArgumentException
      */
-    public function isOptional(): bool;
+    public function cast(bool|int|float|string $value): bool|int|float|string|SapDateTime|SapDateInterval;
 }