tyler.durden/pandorafms
1
0
Fork 0
mirror of https://github.com/pandorafms/pandorafms.git synced 2025-07-28 16:24:54 +02:00
Code Issues Packages Projects Releases Wiki Activity

Visual Console Refactor: improved the documentation and other minor changes

Browse Source 
Former-commit-id: 0734d290caf2309905ce727d2f20ede7f89e8516
This commit is contained in:
Alejandro Gallardo Escobar 2019-03-25 15:19:13 +01:00
parent f6f868ddfe
commit 99463938d1
3 changed files with 165 additions and 119 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

93
pandora_console/include/rest-api/models/Model.php
View File

@ -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];
}
}

106
pandora_console/include/rest-api/models/VisualConsole/Container.php
View File

@ -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);
}

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

@ -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;
}