Jingga/phpOMS
1
0
Fork 0
mirror of https://github.com/Karaka-Management/phpOMS.git synced 2026-01-13 18:48:40 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Add docblocks, better typehints and exceptions

Browse Source
This commit is contained in:
Dennis Eichhorn 2017-07-25 17:32:49 +02:00
parent e505f5612e
commit 2940e22c97
19 changed files with 354 additions and 84 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
Account/Account.php
View File

@ -19,7 +19,7 @@ namespace phpOMS\Account;
use phpOMS\Contract\ArrayableInterface;
use phpOMS\Localization\Localization;
use phpOMS\Localization\NullLocalization;
use phpOMS\Validation\Base\Email;
use phpOMS\Validation\Network\Email;
/**
* Account manager class.
@ -452,7 +452,7 @@ class Account implements ArrayableInterface, \JsonSerializable
*
* @since 1.0.0
*/
public function updateLastActive()
public function updateLastActive() /* : void */
{
$this->lastActive = new \DateTime('NOW');
}

27
Business/Marketing/NetPromoterScore.php
View File

@ -86,6 +86,15 @@ class NetPromoterScore {
return $total === 0 ? 0 : ((int) ($promoters * 100 / $total)) - ((int) ($detractors * 100 / $total));
}
/**
* Count detractors
*
* Detractors are all ratings below 7.
*
* @return int
*
* @since 1.0.0
*/
public function countDetractors() : int
{
$count = 0;
@ -98,6 +107,15 @@ class NetPromoterScore {
return $count;
}
/**
* Count passives
*
* Passives are all ratings between 7 and 8 (inclusive)
*
* @return int
*
* @since 1.0.0
*/
public function countPassives() : int
{
$count = 0;
@ -110,6 +128,15 @@ class NetPromoterScore {
return $count;
}
/**
* Count promoters
*
* Promotoers are all ratings larger 8
*
* @return int
*
* @since 1.0.0
*/
public function countPromoters() : int
{
$count = 0;

18
Dispatcher/Dispatcher.php
View File

@ -155,7 +155,7 @@ class Dispatcher
*
* @since 1.0.0
*/
private function dispatchClosure(\Closure $controller, array $data = null)
private function dispatchClosure(\Closure $controller, array $data = null) /* : void */
{
return $controller($this->app, ...$data);
}
@ -167,9 +167,11 @@ class Dispatcher
*
* @return mixed
*
* @throws PathException This exception is thrown in case the controller couldn't be found.
*
* @since 1.0.0
*/
private function getController(string $controller)
private function getController(string $controller) /* : object */
{
if (!isset($this->controllers[$controller])) {
if (!file_exists($path = __DIR__ . '/../../' . str_replace('\\', '/', $controller) . '.php')) {
@ -193,18 +195,12 @@ class Dispatcher
* @param ModuleAbstract $controller Controller
* @param string $name Controller string
*
* @return bool
* @return void
*
* @since 1.0.0
*/
public function set(ModuleAbstract $controller, string $name) : bool
public function set(ModuleAbstract $controller, string $name) /* : void */
{
if (!isset($this->controllers[$name])) {
$this->controllers[$name] = $controller;
return true;
}
return false;
$this->controllers[$name] = $controller;
}
}

67
Event/EventManager.php
View File

@ -56,7 +56,16 @@ class EventManager
}
/**
* {@inheritdoc}
* Attach new event
*
* @param string $group Name of the event (unique)
* @param \Closure $callback Callback for the event
* @param bool $remove Remove event after triggering it?
* @param bool $reset Reset event after triggering it? Remove must be false!
*
* @return bool
*
* @since 1.0.0
*/
public function attach(string $group, \Closure $callback, bool $remove = false, bool $reset = false) : bool
{
@ -70,12 +79,20 @@ class EventManager
}
/**
* {@inheritdoc}
* Trigger event
*
* @param string $group Name of the event
* @param string $id Sub-requirement for event
* @param mixed $data Data to pass to the callback
*
* @return bool Returns true on sucessfully triggering the event, false if the event couldn't be triggered which also includes sub-requirements missing.
*
* @since 1.0.0
*/
public function trigger(string $group, string $id = '', $data = null) /* : void */
public function trigger(string $group, string $id = '', $data = null) : bool
{
if(!isset($this->callbacks[$group])) {
return;
return false;
}
if (isset($this->groups[$group])) {
@ -90,9 +107,22 @@ class EventManager
} elseif($this->callbacks[$group]['reset']) {
$this->reset($group);
}
return true;
}
return false;
}
/**
* Reset group
*
* @param string $group Name of the event
*
* @return void
*
* @since 1.0.0
*/
private function reset(string $group) /* : void */
{
foreach($this->groups[$group] as $id => $ok) {
@ -101,7 +131,13 @@ class EventManager
}
/**
* {@inheritdoc}
* Check if a group has missing sub-requirements
*
* @param string $group Name of the event
*
* @return bool
*
* @since 1.0.0
*/
private function hasOutstanding(string $group) : bool
{
@ -119,9 +155,15 @@ class EventManager
}
/**
* {@inheritdoc}
* Detach an event
*
* @param string $group Name of the event
*
* @return void
*
* @since 1.0.0
*/
public function detach(string $group) : bool
public function detach(string $group) /* : bool */
{
if (isset($this->callbacks[$group])) {
unset($this->callbacks[$group]);
@ -130,12 +172,17 @@ class EventManager
if (isset($this->groups[$group])) {
unset($this->groups[$group]);
}
return true;
}
/**
* {@inheritdoc}
* Add sub-requirement for event
*
* @param string $group Name of the event
* @param string $id ID of the sub-requirement
*
* @return void
*
* @since 1.0.0
*/
public function addGroup(string $group, string $id) /* : void */
{

34
Localization/L11nManager.php
View File

@ -87,14 +87,14 @@ class L11nManager
*
* @return void
*
* @throws \Exception
* @throws \UnexpectedValueException This exception is thrown when no language definitions for the defined source `$from` exist.
*
* @since 1.0.0
*/
public function loadLanguage(string $language, string $from, array $translation) /* : void */
{
if (!isset($translation[$from])) {
throw new \Exception('Unexpected language key: ' . $from);
throw new \UnexpectedValueException($from);
}
if (!isset($this->language[$language][$from])) {
@ -146,9 +146,9 @@ class L11nManager
return $this->language[$language];
} elseif (isset($this->language[$language], $this->language[$language][$module])) {
return $this->language[$language][$module];
} else {
return [];
}
return [];
}
/**
@ -159,23 +159,31 @@ class L11nManager
* @param string $theme Theme
* @param string $translation Text
*
* @return string
* @return string In case the language element couldn't be found 'ERROR' will be returned
*
* @since 1.0.0
*/
public function getText(string $code, string $module, string $theme, string $translation) : string
{
if (!isset($this->language[$code][$module][$translation])) {
/** @var ModuleAbstract $class */
$class = '\Modules\\' . $module . '\\Controller';
$this->loadLanguage($code, $module, $class::getLocalization($code, $theme));
try {
/** @var ModuleAbstract $class */
$class = '\Modules\\' . $module . '\\Controller';
$this->loadLanguage($code, $module, $class::getLocalization($code, $theme));
if (!isset($this->language[$code][$module][$translation])) {
if(isset($this->logger)) {
$this->logger->warning(FileLogger::MSG_FULL, [
'message' => 'Undefined translation for \'' . $code . '/' . $module . '/' . $translation . '\'.',
]);
if (!isset($this->language[$code][$module][$translation])) {
if(isset($this->logger)) {
$this->logger->warning(FileLogger::MSG_FULL, [
'message' => 'Undefined translation for \'' . $code . '/' . $module . '/' . $translation . '\'.',
]);
}
return 'ERROR';
}
} catch(\Excpetion $e) {
$this->logger->warning(FileLogger::MSG_FULL, [
'message' => 'Undefined translation for \'' . $code . '/' . $module . '/' . $translation . '\'.',
]);
return 'ERROR';
}

13
Log/FileLogger.php
View File

@ -180,7 +180,7 @@ class FileLogger implements LoggerInterface
*
* @since 1.0.0
*/
public function startTimeLog($id = '')
public function startTimeLog($id = '') /* : void */
{
$mtime = explode(' ', microtime());
$mtime = $mtime[1] + $mtime[0];
@ -193,11 +193,11 @@ class FileLogger implements LoggerInterface
*
* @param string $id the ID by which this time measurement gets identified
*
* @return int the time measurement
* @return int The time measurement in ms
*
* @since 1.0.0
*/
public function endTimeLog($id = '')
public function endTimeLog($id = '') : int
{
$mtime = explode(' ', microtime());
$mtime = $mtime[1] + $mtime[0];
@ -217,7 +217,7 @@ class FileLogger implements LoggerInterface
*
* @since 1.0.0
*/
public function timingSort(&$timings)
public function timingSort(&$timings) /* : void */
{
uasort($timings, [$this, 'orderSort']);
}
@ -233,7 +233,7 @@ class FileLogger implements LoggerInterface
*
* @since 1.0.0
*/
private function interpolate(string $message, array $context = [], string $level = LogLevel::DEBUG)
private function interpolate(string $message, array $context = [], string $level = LogLevel::DEBUG) : string
{
$replace = [];
foreach ($context as $key => $val) {
@ -634,9 +634,8 @@ class FileLogger implements LoggerInterface
* @param bool $verbose Is verbose
* @param array $context Context
*
* @return array
*/
public function console(string $message, bool $verbose = true, array $context = [])
public function console(string $message, bool $verbose = true, array $context = []) /* : void */
{
$message = date('[Y-m-d H:i:s] ') . $message . "\r\n";

50
Message/Http/Header.php
View File

@ -17,6 +17,7 @@ declare(strict_types=1);
namespace phpOMS\Message\Http;
use phpOMS\Message\HeaderAbstract;
use phpOMS\DataStorage\LockExcpetion;
/**
* Response class.
@ -50,12 +51,25 @@ class Header extends HeaderAbstract
}
/**
* {@inheritdoc}
* Set header.
*
* @param string $key Header key (case insensitive)
* @param string $header Header value
* @param bool $overwrite Overwrite if already existing
*
* @return bool
*
* @throws LockException The http header needs to be defined at the beginning. If it is already pushed further interactions are impossible and locked.
* @throws \Exception If the header already exists and cannot be overwritten this exception will be thrown.
*
* @todo Allow to extend header key with additional values.
*
* @since 1.0.0
*/
public function set(string $key, string $header, bool $overwrite = false) : bool
{
if (self::$isLocked) {
throw new \Exception('Already locked');
throw new LockExcpetion('HTTP header');
}
$key = strtolower($key);
@ -86,8 +100,6 @@ class Header extends HeaderAbstract
*
* @return bool
*
* @throws \Exception
*
* @since 1.0.0
*/
private function isSecurityHeader(string $key) : bool
@ -111,7 +123,7 @@ class Header extends HeaderAbstract
}
/**
* Returns all headers.
* Returns all pushed headers.
*
* @return array
*
@ -123,7 +135,11 @@ class Header extends HeaderAbstract
}
/**
* {@inheritdoc}
* Get pushed header by name.
*
* @return string
*
* @since 1.0.0
*/
public function getHeader(string $name) : string
{
@ -137,14 +153,14 @@ class Header extends HeaderAbstract
*
* @return bool
*
* @throws \Exception
* @throws LockException The http header needs to be defined at the beginning. If it is already pushed further interactions are impossible and locked.
*
* @since 1.0.0
*/
public function remove(int $key) : bool
{
if (self::$isLocked) {
throw new \Exception('Already locked');
throw new \LockException('HTTP header');
}
if (isset($this->header[$key])) {
@ -157,7 +173,13 @@ class Header extends HeaderAbstract
}
/**
* {@inheritdoc}
* Get header by name.
*
* @param int $key Header key
*
* @return array
*
* @since 1.0.0
*/
public function get(string $key) : array
{
@ -165,11 +187,17 @@ class Header extends HeaderAbstract
}
/**
* {@inheritdoc}
* Check if header is defined.
*
* @param int $key Header key
*
* @return bool
*
* @since 1.0.0
*/
public function has(string $key) : bool
{
return array_key_exists($key, $this->header);
return isset($this->header[$key]);
}
/**

2
Message/Http/Response.php
View File

@ -104,8 +104,6 @@ class Response extends ResponseAbstract implements RenderableInterface
*
* @return string
*
* @throws \Exception
*
* @since 1.0.0
*/
public function render() : string

18
Message/RequestAbstract.php
View File

@ -193,17 +193,27 @@ abstract class RequestAbstract implements MessageInterface
}
/**
* {@inheritdoc}
* Get request source.
*
* @return int
*
* @since 1.0.0
*/
public function getRequestSource()
public function getRequestSource() : int
{
return $this->source;
}
/**
* {@inheritdoc}
* Set request source.
*
* @param int $source Request source
*
* @return void
*
* @since 1.0.0
*/
public function setRequestSource($source) /* : void */
public function setRequestSource(int $source) /* : void */
{
if (!RequestSource::isValidValue($source)) {
throw new InvalidEnumValue($source);

2
Model/Html/Meta.php
View File

@ -80,7 +80,7 @@ class Meta implements RenderableInterface
*
* @since 1.0.0
*/
public function addKeyword(string $keyword)
public function addKeyword(string $keyword) /* : void */
{
if (!in_array($keyword, $this->keywords)) {
$this->keywords[] = $keyword;

44
Module/Exception/InvalidModuleException.php Normal file
View File

@ -0,0 +1,44 @@
<?php
/**
* Orange Management
*
* PHP Version 7.1
*
* @category TBD
* @package TBD
* @author OMS Development Team <dev@oms.com>
* @copyright Dennis Eichhorn
* @license OMS License 1.0
* @version 1.0.0
* @link http://orange-management.com
*/
declare(strict_types=1);
namespace phpOMS\Module\Exception;
/**
* Zero devision exception.
*
* @category Framework
* @package phpOMS/Uri
* @author OMS Development Team <dev@oms.com>
* @license OMS License 1.0
* @link http://orange-management.com
* @since 1.0.0
*/
class InvalidModuleException extends \UnexpectedValueException
{
/**
* Constructor.
*
* @param string $message Exception message
* @param int $code Exception code
* @param \Exception Previous exception
*
* @since 1.0.0
*/
public function __construct(string $message, int $code = 0, \Exception $previous = null)
{
parent::__construct('Data for module "' . $message . '" could be found.', $code, $previous);
}
}

44
Module/Exception/InvalidThemeException.php Normal file
View File

@ -0,0 +1,44 @@
<?php
/**
* Orange Management
*
* PHP Version 7.1
*
* @category TBD
* @package TBD
* @author OMS Development Team <dev@oms.com>
* @copyright Dennis Eichhorn
* @license OMS License 1.0
* @version 1.0.0
* @link http://orange-management.com
*/
declare(strict_types=1);
namespace phpOMS\Module\Exception;
/**
* Zero devision exception.
*
* @category Framework
* @package phpOMS/Uri
* @author OMS Development Team <dev@oms.com>
* @license OMS License 1.0
* @link http://orange-management.com
* @since 1.0.0
*/
class InvalidThemeException extends \UnexpectedValueException
{
/**
* Constructor.
*
* @param string $message Exception message
* @param int $code Exception code
* @param \Exception Previous exception
*
* @since 1.0.0
*/
public function __construct(string $message, int $code = 0, \Exception $previous = null)
{
parent::__construct('Data for theme "' . $message . '" could be found.', $code, $previous);
}
}

2
Module/InfoManager.php
View File

@ -79,6 +79,8 @@ class InfoManager
*
* @return void
*
* @throws PathException This exception is thrown in case the info file path doesn't exist.
*
* @since 1.0.0
*/
public function load() /* : void */

19
Module/ModuleManager.php
View File

@ -21,6 +21,7 @@ use phpOMS\Autoloader;
use phpOMS\DataStorage\Database\DatabaseType;
use phpOMS\Message\Http\Request;
use phpOMS\System\File\PathException;
use phpOMS\Module\Exception\InvalidModuleException;
/**
* Modules class.
@ -343,7 +344,7 @@ class ModuleManager
*
* @return bool
*
* @throws \Exception
* @throws InvalidModuleException Throws this exception in case the installer doesn't exist
*
* @since 1.0.0
*/
@ -354,7 +355,7 @@ class ModuleManager
$class = '\\Modules\\' . $info->getDirectory() . '\\Admin\\Installer';
if (!Autoloader::exists($class)) {
throw new \Exception('Module installer does not exist');
throw new InvalidModuleException($info->getDirectory());
}
$class::reInit($this->modulePath, $info);
@ -436,7 +437,7 @@ class ModuleManager
*
* @return void
*
* @throws \Exception
* @throws InvalidModuleException Throws this exception in case the installer doesn't exist
*
* @since 1.0.0
*/
@ -446,7 +447,7 @@ class ModuleManager
$class = '\\Modules\\' . $info->getDirectory() . '\\Admin\\Installer';
if (!Autoloader::exists($class)) {
throw new \Exception('Module installer does not exist');
throw new InvalidModuleException($info->getDirectory());
}
$class::install($this->modulePath, $this->app->dbPool, $info);
@ -459,7 +460,7 @@ class ModuleManager
*
* @return void
*
* @throws \Exception
* @throws InvalidModuleException Throws this exception in case the deactiviation doesn't exist
*
* @since 1.0.0
*/
@ -468,7 +469,7 @@ class ModuleManager
$class = '\\Modules\\' . $info->getDirectory() . '\\Admin\\Deactivate';
if (!Autoloader::exists($class)) {
throw new \Exception('Module deactivation does not exist');
throw new InvalidModuleException($info->getDirectory());
}
/** @var $class DeactivateAbstract */
@ -482,16 +483,16 @@ class ModuleManager
*
* @return void
*
* @throws \Exception
* @throws InvalidModuleException Throws this exception in case the activation doesn't exist
*
* @since 1.0.0
*/
private function activateModule(InfoManager $info) /* : void */
{
$class = '\\Modules\\' . $info->getDirectory() . '\\Admin\\Deactivate';
$class = '\\Modules\\' . $info->getDirectory() . '\\Admin\\Activate';
if (!Autoloader::exists($class)) {
throw new \Exception('Module deactivation does not exist');
throw new InvalidModuleException($info->getDirectory());
}
/** @var $class ActivateAbstract */

35
Utils/ArrayUtils.php
View File

@ -49,7 +49,7 @@ class ArrayUtils
*
* @since 1.0.0
*/
public static function unsetArray(string $path, array $data, string $delim) : array
public static function unsetArray(string $path, array $data, string $delim = '/') : array
{
$nodes = explode($delim, trim($path, $delim));
$prevEl = null;
@ -87,7 +87,7 @@ class ArrayUtils
*
* @since 1.0.0
*/
public static function setArray(string $path, array $data, $value, string $delim, bool $overwrite = false) : array
public static function setArray(string $path, array $data, $value, string $delim = '/', bool $overwrite = false) : array
{
$pathParts = explode($delim, trim($path, $delim));
$current = &$data;
@ -142,6 +142,16 @@ class ArrayUtils
return $found;
}
/**
* Check if any of the needles are in the array
*
* @param mixed $needles Needles for search
* @param array $haystack Haystack for search
*
* @return bool
*
* @since 1.0.0
*/
public static function anyInArray(array $needles, array $haystack) : bool
{
foreach($needles as $needle) {
@ -153,6 +163,27 @@ class ArrayUtils
return false;
}
/**
* Check if all of the needles are in the array
*
* @param mixed $needles Needles for search
* @param array $haystack Haystack for search
*
* @return bool
*
* @since 1.0.0
*/
public static function allInArray(array $needles, array $haystack) : bool
{
foreach($needles as $needle) {
if(!in_array($needle, $haystack)) {
return false;
}
}
return true;
}
/**
* Stringify array.
*

2
Utils/ColorUtils.php
View File

@ -41,7 +41,7 @@ class ColorUtils
*
* @since 1.0.0
*/
public static function getRGBGradient(int $value, array $start, array $stop, array $end)
public static function getRGBGradient(int $value, array $start, array $stop, array $end) : array
{
$diff = [];
$gradient = [];

25
Utils/TestUtils.php
View File

@ -28,7 +28,18 @@ namespace phpOMS\Utils;
*/
class TestUtils
{
public static function setMember($obj, $name, $value) : bool
/**
* Set private object member
*
* @param object $object Object to modify
* @param string $name Member name to modify
* @param mixed $value Value to set
*
* @return bool The function returns true after setting the member
*
* @since 1.0.0
*/
public static function setMember(/* object */ $obj, string $name, $value) : bool
{
$reflectionClass = new \ReflectionClass(get_class($obj));
@ -51,7 +62,17 @@ class TestUtils
return true;
}
public static function getMember($obj, $name)
/**
* Get private object member
*
* @param object $object Object to read
* @param string $name Member name to read
*
* @return mixed Returns the member variable value
*
* @since 1.0.0
*/
public static function getMember(/* object */ $obj, string $name)
{
$reflectionClass = new \ReflectionClass(get_class($obj));

20
Views/View.php
View File

@ -20,6 +20,8 @@ use phpOMS\ApplicationAbstract;
use phpOMS\Localization\Localization;
use phpOMS\Message\RequestAbstract;
use phpOMS\Message\ResponseAbstract;
use phpOMS\Module\Exception\InvalidModuleException;
use phpOMS\Module\Exception\InvalidThemeException;
/**
* List view.
@ -163,7 +165,8 @@ class View extends ViewAbstract
*
* @return string
*
* @throws \Exception
* @throws InvalidModuleException Throws this exception if no data for the defined module could be found.
* @throws InvalidTemplateException Throws this exception if no data for the defined theme could be found.
*
* @since 1.0.0
*/
@ -173,7 +176,7 @@ class View extends ViewAbstract
$match = '/Modules/';
if (($start = strripos($this->template, $match)) === false) {
throw new \Exception('Unknown Module');
throw new InvalidModuleException($module);
}
$start = $start + strlen($match);
@ -185,7 +188,7 @@ class View extends ViewAbstract
$match = '/Theme/';
if (($start = strripos($this->template, $match)) === false) {
throw new \Exception('Unknown Theme');
throw new InvalidThemeException($theme);
}
$start = $start + strlen($match);
@ -196,6 +199,17 @@ class View extends ViewAbstract
return $this->app->l11nManager->getText($this->l11n->getLanguage(), $module, $theme, $translation);
}
/**
* Get translation.
*
* @param string $translation Text
* @param string $module Module name
* @param string $theme Theme name
*
* @return string
*
* @since 1.0.0
*/
protected function getHtml(string $translation, string $module = null, string $theme = null) : string
{
return htmlspecialchars($this->getText($translation, $module, $theme));

12
Views/ViewAbstract.php
View File

@ -177,7 +177,7 @@ abstract class ViewAbstract implements \Serializable
*
* @since 1.0.0 <d.eichhorn@oms.com>
*/
public function addView(string $id, View $view, int $order = 0, bool $overwrite = true) : bool
public function addView(string $id, View $view, int $order = 0, bool $overwrite = true) : bool
{
if ($overwrite || !isset($this->views[$id])) {
$this->views[$id] = $view;
@ -233,11 +233,11 @@ abstract class ViewAbstract implements \Serializable
/**
* Get view/template response.
*
* @return string
* @return string|array
*
* @since 1.0.0 <d.eichhorn@oms.com>
*/
public function render(...$data) : string
public function render(...$data)
{
$path = __DIR__ . '/../..' . $this->template . '.tpl.php';
@ -247,11 +247,11 @@ abstract class ViewAbstract implements \Serializable
ob_start();
/** @noinspection PhpIncludeInspection */
$data = include $path;
$tpl = include $path;
$ob = ob_get_clean();
if (is_array($data)) {
return $data;
if (is_array($tpl)) {
return $tpl;
}
return $ob;