diff --git a/pandora_console/include/rest-api/models/Model.php b/pandora_console/include/rest-api/models/Model.php index c7d8a4eff7..f28369e7f9 100644 --- a/pandora_console/include/rest-api/models/Model.php +++ b/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 $def Default value to use if we cannot extract a non empty string. + * @param mixed $val Input value. + * @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 $def + * @param mixed $val Input value. + * @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 $keys array with the keys to search + * @param array $dict Input array. + * @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) { - return $val[$value]; + if (isset($dict[$value]) === true) { + return $dict[$value]; } } diff --git a/pandora_console/include/rest-api/models/VisualConsole/Container.php b/pandora_console/include/rest-api/models/VisualConsole/Container.php index 56e807883a..7afc3ec5ba 100644 --- a/pandora_console/include/rest-api/models/VisualConsole/Container.php +++ b/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 - * - * @return self - */ - public static function fromArray(array $data): self - { - return new self($data); - } - - - /** - * Validate the input data - * - * @param mixed $data + * @param array $data Input 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 - && \is_numeric($data['id_group']) === true - && $data['id_group'] >= 0 - ) { - return $data['id_group']; - } else if (isset($data['groupId']) === true - && \is_numeric($data['groupId']) === true - && $data['groupId'] >= 0 - ) { - return $data['groupId']; + $groupId = static::parseIntOr( + static::issetInArray($data, ['id_group', 'groupId']), + null + ); + + if ($groupId === null || $groupId < 0) { + throw new \InvalidArgumentException( + 'the group Id property is required and should be integer' + ); } - 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( - Model::issetInArray($data, ['background', 'backgroundURL']), + return static::notEmptyStringOr( + 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( - Model::issetInArray($data, ['backgroundColor', 'background_color']), + return static::notEmptyStringOr( + 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( - Model::issetInArray($data, ['is_favourite', 'isFavorite']), + return static::parseBool( + 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. - return new self($row); + // New instance. + return new static($row); } diff --git a/pandora_console/include/rest-api/models/VisualConsole/items/Box.php b/pandora_console/include/rest-api/models/VisualConsole/items/Box.php index 48660d5ab4..144518ebb1 100644 --- a/pandora_console/include/rest-api/models/VisualConsole/items/Box.php +++ b/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 - */ - protected function validateData(array $data): void - { - parent::validateData($data); - } - - - /** - * Returns a valid data structure. - * - * @param mixed $data - * - * @return array - * - * @override + * @overrides Item::decode. */ protected function decode(array $data): array { - $return = parent::decode($data); - $return['type'] = BOX_ITEM; - $return['parentId'] = null; - $return['aclGroupId'] = null; - $return['borderWidth'] = $this->extractBorderWidth($data); - $return['borderColor'] = $this->extractBorderColor($data); - $return['fillColor'] = $this->extractFillColor($data); - return $return; + $boxData = parent::decode($data); + $boxData['type'] = BOX_ITEM; + $boxData['parentId'] = null; + $boxData['aclGroupId'] = null; + $boxData['borderWidth'] = $this->extractBorderWidth($data); + $boxData['borderColor'] = $this->extractBorderColor($data); + $boxData['fillColor'] = $this->extractFillColor($data); + return $boxData; } /** - * Extract the value of borderWidth and - * return a integer. + * Extract a border width value. * - * @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( - Model::issetInArray($data, ['borderWidth', 'border_width']), + return static::parseIntOr( + static::issetInArray($data, ['borderWidth', 'border_width']), 0 ); - if ($borderWidth >= 0) { - return $borderWidth; - } else { - return 0; - } } /** - * Extract the value of borderColor and - * return to not empty string or null. + * Extract a border color value. * - * @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( - Model::issetInArray($data, ['borderColor', 'border_color']), + return static::notEmptyStringOr( + static::issetInArray($data, ['borderColor', 'border_color']), null ); - return $borderColor; } /** - * Extract the value of fillColor and - * return to not empty string or null. + * Extract a fill color value. * - * @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( - Model::issetInArray($data, ['fillColor', 'fill_color']), + return static::notEmptyStringOr( + static::issetInArray($data, ['fillColor', 'fill_color']), null ); - return $borderColor; }