From 1a4b09af1c02f72867b5ba9ba92629cd72f1b93a Mon Sep 17 00:00:00 2001 From: andig Date: Wed, 18 Jan 2017 18:44:29 +0100 Subject: [PATCH] Code cleanup (#556) --- lib/Controller/AggregatorController.php | 9 ++++- lib/Controller/CapabilitiesController.php | 14 ++++++-- lib/Controller/ChannelController.php | 5 +-- lib/Controller/Controller.php | 9 +++-- lib/Controller/DataController.php | 7 +++- lib/Controller/EntityController.php | 31 +++++++++++++++--- lib/Controller/IotController.php | 11 ++++++- lib/Interpreter/Interpreter.php | 22 ++++++++----- lib/Router.php | 40 ++++++++++++----------- 9 files changed, 105 insertions(+), 43 deletions(-) diff --git a/lib/Controller/AggregatorController.php b/lib/Controller/AggregatorController.php index 6637f3192..a5f045a0e 100644 --- a/lib/Controller/AggregatorController.php +++ b/lib/Controller/AggregatorController.php @@ -24,7 +24,6 @@ namespace Volkszaehler\Controller; use Volkszaehler\Model; -use Volkszaehler\Definition; /** * Aggregator controller @@ -35,6 +34,9 @@ class AggregatorController extends EntityController { /** * Get aggregator + * @param null $identifier + * @return array + * @throws \Exception */ public function get($identifier = NULL) { $aggregator = parent::get($identifier); @@ -54,6 +56,9 @@ public function get($identifier = NULL) { /** * Create new aggregator or add entity to aggregator + * @param null $identifier + * @return array|Model\Aggregator + * @throws \Exception */ public function add($identifier = NULL) { if (isset($identifier)) { // add entity to aggregator @@ -88,6 +93,8 @@ public function add($identifier = NULL) { /** * Delete Aggregator or remove entity from aggregator + * @param $identifier + * @return array|null */ public function delete($identifier) { if (!isset($identifier)) diff --git a/lib/Controller/CapabilitiesController.php b/lib/Controller/CapabilitiesController.php index 56d2682a1..0d918e5fb 100644 --- a/lib/Controller/CapabilitiesController.php +++ b/lib/Controller/CapabilitiesController.php @@ -23,8 +23,9 @@ namespace Volkszaehler\Controller; +use Doctrine\DBAL\Connection; + use Volkszaehler\Router; -use Volkszaehler\Model; use Volkszaehler\Util; use Volkszaehler\View; use Volkszaehler\Definition; @@ -40,8 +41,11 @@ class CapabilitiesController extends Controller { /** * Fast MyISAM/ InnoDB table count + * @param Connection $conn + * @param string $table + * @return int Number of database rows */ - private function sqlCount($conn, $table) { + private function sqlCount(Connection $conn, $table) { $explain = $conn->fetchAssoc('EXPLAIN SELECT COUNT(id) FROM ' . $table . ' USE INDEX (PRIMARY)'); if (isset($explain['rows'])) // estimated for InnoDB @@ -58,8 +62,11 @@ private function sqlCount($conn, $table) { /** * Estimated table disk space + * @param Connection $conn + * @param string $table + * @return mixed */ - private function dbSize($conn, $table = null) { + private function dbSize(Connection $conn, $table = null) { $sql = 'SELECT SUM(data_length + index_length) FROM information_schema.tables WHERE LOWER(table_schema) = LOWER(?)'; $params = array(Util\Configuration::read('db.dbname')); @@ -73,6 +80,7 @@ private function dbSize($conn, $table = null) { /** * @param string $section select specific sub section for output + * @return array */ public function get($section = NULL) { $capabilities = array(); diff --git a/lib/Controller/ChannelController.php b/lib/Controller/ChannelController.php index cc9c37967..77f377b56 100644 --- a/lib/Controller/ChannelController.php +++ b/lib/Controller/ChannelController.php @@ -24,8 +24,6 @@ namespace Volkszaehler\Controller; use Volkszaehler\Model; -use Volkszaehler\Util; -use Volkszaehler\Definition; /** * Channel controller @@ -37,6 +35,9 @@ class ChannelController extends EntityController { /** * Get channel + * @param null $identifier + * @return array + * @throws \Exception */ public function get($identifier = NULL) { $channel = parent::get($identifier); diff --git a/lib/Controller/Controller.php b/lib/Controller/Controller.php index 8fb60eb35..e2189f255 100644 --- a/lib/Controller/Controller.php +++ b/lib/Controller/Controller.php @@ -34,8 +34,6 @@ * @author Steffen Vogel * @author Andreas Goetz * @package default - * - * @todo Check how controllers can modify the response/headers */ abstract class Controller { @@ -89,7 +87,10 @@ public function getParameters() { /** * Run operation * - * @param string $operation runs the operation if class method is available + * @param $op Operation to run + * @param null $uuid Uuid to operate on + * @return operation result + * @throws \Exception */ public function run($op, $uuid = null) { if (!method_exists($this, $op)) { @@ -107,6 +108,8 @@ public function run($op, $uuid = null) { /** * Helper function to convert single/multiple parameters to array format + * @param $data + * @return array */ protected static function makeArray($data) { if (!is_array($data)) { diff --git a/lib/Controller/DataController.php b/lib/Controller/DataController.php index 9258574ae..896b9333c 100644 --- a/lib/Controller/DataController.php +++ b/lib/Controller/DataController.php @@ -53,6 +53,7 @@ public function __construct(Request $request, EntityManager $em, View $view) { * Query for data by given channel or group or multiple channels * * @param string|array uuid + * @return array */ public function get($uuid) { $from = $this->getParameters()->get('from'); @@ -78,6 +79,8 @@ public function get($uuid) { * * @todo deduplicate Model\Channel code * @param string|array uuid + * @return array + * @throws \Exception */ public function add($uuid) { $channel = EntityController::factory($this->em, $uuid, true); @@ -138,7 +141,9 @@ public function add($uuid) { * Delete tuples from single or multiple channels * * @todo deduplicate Model\Channel code - * @param string|array uuid + * @param string|array $uuids + * @return array + * @throws \Exception */ public function delete($uuids) { $from = null; diff --git a/lib/Controller/EntityController.php b/lib/Controller/EntityController.php index 6102cfdd6..3ee810c80 100644 --- a/lib/Controller/EntityController.php +++ b/lib/Controller/EntityController.php @@ -23,7 +23,6 @@ namespace Volkszaehler\Controller; -use Symfony\Component\HttpFoundation\Request; use Doctrine\ORM\EntityManager; use Volkszaehler\Model; @@ -47,7 +46,9 @@ class EntityController extends Controller { /** * Get entity * - * @param string $identifier + * @param $uuids + * @return array + * @throws \Exception */ public function get($uuids) { if (is_string($uuids)) { // single entity @@ -79,10 +80,25 @@ public function get($uuids) { } } + /** + * Return a single entity, potentially from cache + * @param $uuid + * @param bool $allowCache + * @return mixed + */ public function getSingleEntity($uuid, $allowCache = false) { return self::factory($this->em, $uuid, $allowCache); } + /** + * Static entity factory- usable for scripting + * + * @param EntityManager $em + * @param $uuid + * @param bool $allowCache + * @return mixed + * @throws \Exception + */ static function factory(EntityManager $em, $uuid, $allowCache = false) { if (!Util\UUID::validate($uuid)) { throw new \Exception('Invalid UUID: \'' . $uuid . '\''); @@ -120,6 +136,8 @@ static function factory(EntityManager $em, $uuid, $allowCache = false) { /** * Delete entity by uuid + * @param $identifier + * @throws \Exception */ public function delete($identifier) { if (!($entity = $this->get($identifier)) instanceof Model\Entity) { @@ -140,6 +158,9 @@ public function delete($identifier) { /** * Edit entity properties + * @param $identifier + * @return array + * @throws \Exception */ public function edit($identifier) { if (!($entity = $this->get($identifier)) instanceof Model\Entity) { @@ -161,6 +182,9 @@ public function edit($identifier) { /** * Update/set/delete properties of entities + * @param Model\Entity $entity + * @param $parameters + * @throws \Exception */ protected function setProperties(Model\Entity $entity, $parameters) { foreach ($parameters as $key => $value) { @@ -183,9 +207,8 @@ protected function setProperties(Model\Entity $entity, $parameters) { } /** - * Filter entites by properties + * Filter entities by properties * - * @todo improve performance * @param array of property => value filters * @return array of entities */ diff --git a/lib/Controller/IotController.php b/lib/Controller/IotController.php index 2a5247f1c..23834747f 100644 --- a/lib/Controller/IotController.php +++ b/lib/Controller/IotController.php @@ -40,6 +40,13 @@ class IotController extends Controller { */ protected $ec; + /** + * IotController constructor + * + * @param Request $request + * @param EntityManager $em + * @param View $view + */ public function __construct(Request $request, EntityManager $em, View $view) { parent::__construct($request, $em, $view); $this->ec = new EntityController($request, $em); @@ -48,7 +55,9 @@ public function __construct(Request $request, EntityManager $em, View $view) { /** * Run operation * - * @param string $operation runs the operation if class method is available + * @param null $uuid + * @return array + * @throws \Exception */ public function get($uuid = null) { if ($uuid === null || is_array($uuid) || strlen($uuid) < 32) { diff --git a/lib/Interpreter/Interpreter.php b/lib/Interpreter/Interpreter.php index 44b60fe8f..2c2c1151f 100644 --- a/lib/Interpreter/Interpreter.php +++ b/lib/Interpreter/Interpreter.php @@ -23,7 +23,6 @@ namespace Volkszaehler\Interpreter; -use Volkszaehler\Util; use Volkszaehler\Model; use Volkszaehler\Interpreter\SQL; use Doctrine\ORM; @@ -65,10 +64,14 @@ abstract class Interpreter implements \IteratorAggregate { /** * Constructor * - * @param Channel $channel - * @param EntityManager $em + * @param Model\Channel $channel + * @param ORM\EntityManager $em * @param integer $from timestamp in ms since 1970 * @param integer $to timestamp in ms since 1970 + * @param null $tupleCount + * @param null $groupBy + * @param array $options + * @throws \Exception */ public function __construct(Model\Channel $channel, ORM\EntityManager $em, $from, $to, $tupleCount = null, $groupBy = null, $options = array()) { $this->channel = $channel; @@ -132,7 +135,8 @@ abstract public function convertRawTuple($row); /** * Check if option is specified * - * @param string $str option name + * @param string $str option name + * @return bool */ protected function hasOption($str) { return in_array($str, $this->options); @@ -172,10 +176,10 @@ public function getMax() { } /** - * Get raw data + * Get raw data from database * - * @param string|integer $groupBy - * @return Volkszaehler\DataIterator + * @return DataIterator + * @throws \Exception */ protected function getData() { if (!$this->hasOption('exact')) { @@ -255,6 +259,7 @@ protected function getData() { * @author Andreas Götz * @param string $expression sql parameter * @return string grouped sql expression + * @throws \Exception */ public static function groupExprSQL($expression) { throw new \Exception('Derived classes must implement static function groupExprSQL.'); @@ -298,11 +303,10 @@ public static function buildDateTimeFilterSQL($from = NULL, $to = NULL, &$parame * Parses a timestamp * * @link http://de3.php.net/manual/en/datetime.formats.php - * @todo add millisecond resolution * * @param mixed $string int, float or string to parse - * @param float $now in ms since 1970 * @return float + * @throws \Exception */ public static function parseDateTimeString($string) { if (ctype_digit((string)$string)) { // handling as ms timestamp diff --git a/lib/Router.php b/lib/Router.php index b9caff8e8..4538d6f13 100644 --- a/lib/Router.php +++ b/lib/Router.php @@ -39,7 +39,7 @@ /** * Router * - * This class povides routing to incoming requests to controllers + * This class routes incoming requests to controllers * * @package default * @author Steffen Vogel @@ -109,12 +109,12 @@ public function __construct() { * Handle the request * Source: Symfony\Component\HttpKernel\HttpKernel * - * @param Request $request A Request instance - * @param int $type The type of the request (for Symfony compatibility, not implemented) - * @param bool $catch Whether to catch exceptions or not - * - * @return Response A Response instance - */ + * @param Request $request A Request instance + * @param int $type The type of the request (for Symfony compatibility, not implemented) + * @param bool $catch Whether to catch exceptions or not + * @return Response A Response instance + * @throws \Exception + */ public function handle(Request $request, $type = HttpKernelInterface::MASTER_REQUEST, $catch = true) { try { // initialize view to ensure StreamedResponse->streamed is false @@ -132,17 +132,17 @@ public function handle(Request $request, $type = HttpKernelInterface::MASTER_REQ throw $e; } - return $this->handleException($e, $request, $type); + return $this->handleException($e, $request); } } /** * Determine context, format and uuid of the raw request * - * @param Request $request A Request instance - * @param int $type The type of the request (for Symfony compatibility, not implemented) - * - * @return Response A Response instance + * @param Request $request A Request instance + * @param int $type The type of the request (for Symfony compatibility, not implemented) + * @return Response A Response instance + * @throws \Exception */ public function handleRaw(Request $request, $type = HttpKernelInterface::MASTER_REQUEST) { // workaround for https://github.com/symfony/symfony/issues/13617 @@ -191,6 +191,10 @@ public function handleRaw(Request $request, $type = HttpKernelInterface::MASTER_ * Processes the request * * Example: http://sub.domain.local/middleware.php/channel/550e8400-e29b-11d4-a716-446655440000/data.json?operation=edit&title=New Title + * @param Request $request + * @param $context + * @param $uuid + * @return Response */ function handler(Request $request, $context, $uuid) { // get controller operation @@ -211,13 +215,11 @@ function handler(Request $request, $context, $uuid) { * Handles an exception by trying to convert it to a Response * Source: Symfony\Component\HttpKernel\HttpKernel * - * @param \Exception $e An \Exception instance - * @param Request $request A Request instance - * @param int $type The type of the request (for Symfony compatibility, not implemented) - * + * @param \Exception $e An \Exception instance + * @param Request $request A Request instance * @return Response A Response instance */ - private function handleException(\Exception $e, $request, $type) { + private function handleException(\Exception $e, Request $request) { if (null === $this->view) { $this->view = new View\JSON($request); // fallback view instantiates error handler } @@ -228,8 +230,8 @@ private function handleException(\Exception $e, $request, $type) { /** * Factory method for Doctrine EntityManager * - * @todo add other caching drivers (memcache, xcache) - * @todo put into static class? singleton? function or state class? + * @param bool $admin + * @return ORM\EntityManager */ public static function createEntityManager($admin = FALSE) { $config = new ORM\Configuration;