Visual Console Refactor: improved the documentation and other minor changes

Former-commit-id: 0734d290caf2309905ce727d2f20ede7f89e8516

pandora_console/include/rest-api/models/Model.php

@@ -4,19 +4,56 @@ declare(strict_types=1);
 
 namespace Models;
 
+/**
+ * This class should be extended to add functionalities to
+ * fetch, validate, transform and represent data entities.
+ */
 abstract class Model
 {
 
+    /**
+     * Internal data of the model.
+     *
+     * @var array
+     */
     private $data;
 
 
+    /**
+     * Validate the received data structure to ensure if we can extract the
+     * values required to build the model.
+     *
+     * @param array $data Input data.
+     *
+     * @return void
+     *
+     * @throws \InvalidArgumentException If any input value is considered
+     * invalid.
+     *
+     * @abstract
+     */
     abstract protected function validateData(array $data): void;
 
 
+    /**
+     * Returns a valid representation of the model.
+     *
+     * @param array $data Input data.
+     *
+     * @return array Data structure representing the model.
+     *
+     * @abstract
+     */
     abstract protected function decode(array $data): array;
 
 
-    public function __construct(array $unknownData)
+    /**
+     * Constructor of the model. It won't be public. The instances
+     * will be created through factories which start with from*.
+     *
+     * @param array $unknownData Input data structure.
+     */
+    protected function __construct(array $unknownData)
     {
         $this->validateData($unknownData);
         $this->data = $this->decode($unknownData);
@@ -24,11 +61,11 @@ abstract class Model
 
 
     /**
-     * Instance the class with the input data.
+     * Instance the class with the unknown input data.
      *
      * @param array $data Unknown data structure.
      *
-     * @return self
+     * @return self Instance of the model.
      */
     public static function fromArray(array $data): self
     {
@@ -44,6 +81,8 @@ abstract class Model
      *
      * @return array The modeled element data structure stored into the DB.
      * @throws \Exception When the data cannot be retrieved from the DB.
+     *
+     * @abstract
      */
     abstract protected static function fetchDataFromDB(array $filter): array;
 
@@ -63,7 +102,7 @@ abstract class Model
 
 
     /**
-     * Returns the JSON representation of the given value.
+     * JSON representation of the model.
      *
      * @return string
      */
@@ -74,7 +113,7 @@ abstract class Model
 
 
     /**
-     * Returns the text representation of this class.
+     * Text representation of the model.
      *
      * @return string
      */
@@ -84,12 +123,19 @@ abstract class Model
     }
 
 
+    /*
+     * -------------
+     * - UTILITIES -
+     * -------------
+     */
+
+
     /**
-     * Returns a Boolean of a mixed value.
+     * From a unknown value, it will try to extract a valid boolean value.
      *
-     * @param mixed $value
+     * @param mixed $value Unknown input.
      *
-     * @return boolean
+     * @return boolean Valid boolean value.
      */
     protected static function parseBool($value): bool
     {
@@ -106,12 +152,13 @@ abstract class Model
 
 
     /**
-     * Return a not empty string or a default value from a mixed value.
+     * Return a not empty string or a default value from a unknown value.
      *
-     * @param mixed $val
+     * @param mixed $val Input value.
-     * @param mixed $def Default value to use if we cannot extract a non empty string.
+     * @param mixed $def Default value.
      *
-     * @return mixed
+     * @return mixed A valid string (not empty) extracted from the input
+     * or the default value.
      */
     protected static function notEmptyStringOr($val, $def)
     {
@@ -120,12 +167,12 @@ abstract class Model
 
 
     /**
-     * Return a integer or a default value from a mixed value.
+     * Return a valid integer or a default value from a unknown value.
      *
-     * @param mixed $val
+     * @param mixed $val Input value.
-     * @param mixed $def
+     * @param mixed $def Default value.
      *
-     * @return mixed
+     * @return mixed A valid int extracted from the input or the default value.
      */
     protected static function parseIntOr($val, $def)
     {
@@ -134,18 +181,18 @@ abstract class Model
 
 
     /**
-     * Returns the value if it exists in the array
+     * Get a value from a dictionary from a possible pool of keys.
      *
-     * @param array $val  input array
+     * @param array $dict Input array.
-     * @param array $keys array with the keys to search
+     * @param array $keys Possible keys.
      *
-     * @return mixed
+     * @return mixed The first value found with the pool of keys or null.
      */
-    protected static function issetInArray(array $val, array $keys)
+    protected static function issetInArray(array $dict, array $keys)
     {
         foreach ($keys as $key => $value) {
-            if (isset($val[$value]) === true) {
+            if (isset($dict[$value]) === true) {
-                return $val[$value];
+                return $dict[$value];
             }
         }
 

pandora_console/include/rest-api/models/VisualConsole/Container.php

@@ -5,29 +5,25 @@ declare(strict_types=1);
 namespace Models\VisualConsole;
 use Models\Model;
 
+/**
+ * Model of a Visual Console.
+ */
 final class Container extends Model
 {
 
 
     /**
-     * Instance the class with the input data.
+     * Validate the received data structure to ensure if we can extract the
+     * values required to build the model.
      *
-     * @param mixed $data
+     * @param array $data Input data.
-     *
-     * @return self
-     */
-    public static function fromArray(array $data): self
-    {
-        return new self($data);
-    }
-
-
-    /**
-     * Validate the input data
-     *
-     * @param mixed $data
      *
      * @return void
+     *
+     * @throws \InvalidArgumentException If any input value is considered
+     * invalid.
+     *
+     * @overrides Model::validateData.
      */
     protected function validateData(array $data): void
     {
@@ -71,11 +67,13 @@ final class Container extends Model
 
 
     /**
-     * Returns a valid data structure.
+     * Returns a valid representation of the model.
      *
-     * @param mixed $data
+     * @param array $data Input data.
      *
-     * @return array
+     * @return array Data structure representing the model.
+     *
+     * @overrides Model::decode.
      */
     protected function decode(array $data): array
     {
@@ -92,53 +90,77 @@ final class Container extends Model
     }
 
 
+    /**
+     * Extract a group Id value.
+     *
+     * @param array $data Unknown input data structure.
+     *
+     * @return integer Valid identifier of a group.
+     *
+     * @throws \InvalidArgumentException When a valid group Id can't be found.
+     */
     private function extractGroupId(array $data): int
     {
-        if (isset($data['id_group']) === true
+        $groupId = static::parseIntOr(
-            && \is_numeric($data['id_group']) === true
+            static::issetInArray($data, ['id_group', 'groupId']),
-            && $data['id_group'] >= 0
+            null
-        ) {
+        );
-            return $data['id_group'];
-        } else if (isset($data['groupId']) === true
-            && \is_numeric($data['groupId']) === true
-            && $data['groupId'] >= 0
-        ) {
-            return $data['groupId'];
-        }
 
+        if ($groupId === null || $groupId < 0) {
             throw new \InvalidArgumentException(
                 'the group Id property is required and should be integer'
             );
         }
 
+        return $groupId;
+    }
 
+
+    /**
+     * Extract a image url value.
+     *
+     * @param array $data Unknown input data structure.
+     *
+     * @return mixed String representing the image url (not empty) or null.
+     */
     private function extractBackgroundUrl(array $data)
     {
-        $background = Model::notEmptyStringOr(
+        return static::notEmptyStringOr(
-            Model::issetInArray($data, ['background', 'backgroundURL']),
+            static::issetInArray($data, ['background', 'backgroundURL']),
             null
         );
-        return $background;
     }
 
 
+    /**
+     * Extract a background color value.
+     *
+     * @param array $data Unknown input data structure.
+     *
+     * @return mixed String representing the color (not empty) or null.
+     */
     private function extractBackgroundColor(array $data)
     {
-        $backgroundColor = Model::notEmptyStringOr(
+        return static::notEmptyStringOr(
-            Model::issetInArray($data, ['backgroundColor', 'background_color']),
+            static::issetInArray($data, ['backgroundColor', 'background_color']),
             null
         );
-        return $backgroundColor;
     }
 
 
+    /**
+     * Extract the "is favorite" switch value.
+     *
+     * @param array $data Unknown input data structure.
+     *
+     * @return boolean If the item is favorite or not.
+     */
     private function extractFavorite(array $data): bool
     {
-        $favorite = Model::parseBool(
+        return static::parseBool(
-            Model::issetInArray($data, ['is_favourite', 'isFavorite']),
+            static::issetInArray($data, ['is_favourite', 'isFavorite']),
             null
         );
-        return $favorite;
     }
 
 
@@ -162,8 +184,8 @@ final class Container extends Model
             throw new \Exception('error fetching the data from the DB');
         }
 
-        // Return a new instance.
+        // New instance.
-        return new self($row);
+        return new static($row);
     }
 
 

pandora_console/include/rest-api/models/VisualConsole/items/Box.php

@@ -2,106 +2,83 @@
 
 declare(strict_types=1);
 
-namespace Models\VisualConsole\items;
+namespace Models\VisualConsole\Items;
 use Models\VisualConsole\Item;
-use Models\Model;
 
+/**
+ * Model of a Box item of the Visual Console.
+ */
 final class Box extends Item
 {
 
 
     /**
-     * Validate the input data.
+     * Returns a valid representation of the model.
      *
-     * @param mixed $data
+     * @param array $data Input data.
      *
-     * @return void
+     * @return array Data structure representing the model.
      *
-     * @override
+     * @overrides Item::decode.
-     */
-    protected function validateData(array $data): void
-    {
-        parent::validateData($data);
-    }
-
-
-    /**
-     * Returns a valid data structure.
-     *
-     * @param mixed $data
-     *
-     * @return array
-     *
-     * @override
      */
     protected function decode(array $data): array
     {
-        $return = parent::decode($data);
+        $boxData = parent::decode($data);
-        $return['type'] = BOX_ITEM;
+        $boxData['type'] = BOX_ITEM;
-        $return['parentId'] = null;
+        $boxData['parentId'] = null;
-        $return['aclGroupId'] = null;
+        $boxData['aclGroupId'] = null;
-        $return['borderWidth'] = $this->extractBorderWidth($data);
+        $boxData['borderWidth'] = $this->extractBorderWidth($data);
-        $return['borderColor'] = $this->extractBorderColor($data);
+        $boxData['borderColor'] = $this->extractBorderColor($data);
-        $return['fillColor'] = $this->extractFillColor($data);
+        $boxData['fillColor'] = $this->extractFillColor($data);
-        return $return;
+        return $boxData;
     }
 
 
     /**
-     * Extract the value of borderWidth and
+     * Extract a border width value.
-     * return a integer.
      *
-     * @param mixed $data
+     * @param array $data Unknown input data structure.
      *
-     * @return integer
+     * @return integer Valid border width. 0 by default.
      */
     private function extractBorderWidth(array $data): int
     {
-        $borderWidth = Model::parseIntOr(
+        return static::parseIntOr(
-            Model::issetInArray($data, ['borderWidth', 'border_width']),
+            static::issetInArray($data, ['borderWidth', 'border_width']),
             0
         );
-        if ($borderWidth >= 0) {
-            return $borderWidth;
-        } else {
-            return 0;
-        }
     }
 
 
     /**
-     * Extract the value of borderColor and
+     * Extract a border color value.
-     * return to not empty string or null.
      *
-     * @param mixed $data
+     * @param array $data Unknown input data structure.
      *
-     * @return void
+     * @return mixed String representing the border color (not empty) or null.
      */
     private function extractBorderColor(array $data)
     {
-        $borderColor = Model::notEmptyStringOr(
+        return static::notEmptyStringOr(
-            Model::issetInArray($data, ['borderColor', 'border_color']),
+            static::issetInArray($data, ['borderColor', 'border_color']),
             null
         );
-        return $borderColor;
     }
 
 
     /**
-     * Extract the value of fillColor and
+     * Extract a fill color value.
-     * return to not empty string or null.
      *
-     * @param mixed $data
+     * @param array $data Unknown input data structure.
      *
-     * @return void
+     * @return mixed String representing the fill color (not empty) or null.
      */
     private function extractFillColor(array $data)
     {
-        $borderColor = Model::notEmptyStringOr(
+        return static::notEmptyStringOr(
-            Model::issetInArray($data, ['fillColor', 'fill_color']),
+            static::issetInArray($data, ['fillColor', 'fill_color']),
             null
         );
-        return $borderColor;
     }