From 4039b7682d75296e298bd3e484258c191d602236 Mon Sep 17 00:00:00 2001 From: Ad Schellevis Date: Sat, 3 Feb 2018 15:57:07 +0100 Subject: [PATCH] MVC, fix class documentation for https://github.com/opnsense/core/pull/2159 --- .../Base/ApiMutableModelControllerBase.php | 91 +++++++++++++++---- 1 file changed, 75 insertions(+), 16 deletions(-) diff --git a/src/opnsense/mvc/app/controllers/OPNsense/Base/ApiMutableModelControllerBase.php b/src/opnsense/mvc/app/controllers/OPNsense/Base/ApiMutableModelControllerBase.php index 8f29f5978..9453f566e 100644 --- a/src/opnsense/mvc/app/controllers/OPNsense/Base/ApiMutableModelControllerBase.php +++ b/src/opnsense/mvc/app/controllers/OPNsense/Base/ApiMutableModelControllerBase.php @@ -58,8 +58,8 @@ abstract class ApiMutableModelControllerBase extends ApiControllerBase private $modelHandle = null; /** - * validate on initialization - * @throws Exception + * Validate on initialization + * @throws \Exception when not bound to a model class or a set/get reference is missing */ public function initialize() { @@ -73,8 +73,9 @@ abstract class ApiMutableModelControllerBase extends ApiControllerBase } /** - * retrieve model settings + * Retrieve model settings * @return array settings + * @throws \ReflectionException when not bound to a valid model */ public function getAction() { @@ -87,8 +88,9 @@ abstract class ApiMutableModelControllerBase extends ApiControllerBase } /** - * override this to customize what part of the model gets exposed + * Override this to customize what part of the model gets exposed * @return array + * @throws \ReflectionException */ protected function getModelNodes() { @@ -96,7 +98,9 @@ abstract class ApiMutableModelControllerBase extends ApiControllerBase } /** + * Get (or create) model object * @return null|BaseModel + * @throws \ReflectionException */ protected function getModel() { @@ -108,12 +112,14 @@ abstract class ApiMutableModelControllerBase extends ApiControllerBase } /** - * validate and save model after update or insertion. + * Validate and save model after update or insertion. * Use the reference node and tag to rename validation output for a specific node to a new offset, which makes * it easier to reference specific uuids without having to use them in the frontend descriptions. - * @param $node reference node, to use as relative offset - * @param $prefix prefix to use when $node is provided (defaults to static::$internalModelName) + * @param string $node reference node, to use as relative offset + * @param string $prefix prefix to use when $node is provided (defaults to static::$internalModelName) * @return array result / validation output + * @throws \Phalcon\Validation\Exception on validation issues + * @throws \ReflectionException when binding to the model class fails */ protected function validateAndSave($node = null, $prefix = null) { @@ -125,10 +131,11 @@ abstract class ApiMutableModelControllerBase extends ApiControllerBase } /** - * validate this model + * Validate this model * @param $node reference node, to use as relative offset * @param $prefix prefix to use when $node is provided (defaults to static::$internalModelName) * @return array result / validation output + * @throws \ReflectionException when binding to the model class fails */ protected function validate($node = null, $prefix = null) { @@ -153,8 +160,10 @@ abstract class ApiMutableModelControllerBase extends ApiControllerBase } /** - * save model after update or insertion, validate() first to avoid raising exceptions + * Save model after update or insertion, validate() first to avoid raising exceptions * @return array result / validation output + * @throws \Phalcon\Validation\Exception on validation issues + * @throws \ReflectionException when binding to the model class fails */ protected function save() { @@ -164,19 +173,21 @@ abstract class ApiMutableModelControllerBase extends ApiControllerBase } /** - * hook to be overridden if the controller is to take an action when + * Hook to be overridden if the controller is to take an action when * setAction is called. This hook is called after a model has been * constructed and validated but before it serialized to the configuration * and written to disk - * @return Error message on error, or null/void on success + * @return string error message on error, or null/void on success */ protected function setActionHook() { } /** - * update model settings + * Update model settings * @return array status / validation errors + * @throws \Phalcon\Validation\Exception on validation issues + * @throws \ReflectionException when binding to the model class fails */ public function setAction() { @@ -198,6 +209,13 @@ abstract class ApiMutableModelControllerBase extends ApiControllerBase return $result; } + /** + * Model search wrapper + * @param string $path path to search, relative to this model + * @param array $fields fieldnames to fetch in result + * @return array + * @throws \ReflectionException when binding to the model class fails + */ public function searchBase($path, $fields) { $this->sessionClose(); @@ -212,6 +230,14 @@ abstract class ApiMutableModelControllerBase extends ApiControllerBase ); } + /** + * Model get wrapper, fetches an array item and returns it's contents + * @param string $key_name result root key + * @param string $path path to fetch, relative to our model + * @param null|string $uuid node key + * @return array + * @throws \ReflectionException when binding to the model class fails + */ public function getBase($key_name, $path, $uuid = null) { $mdl = $this->getModel(); @@ -231,6 +257,14 @@ abstract class ApiMutableModelControllerBase extends ApiControllerBase return array(); } + /** + * Model add wrapper, adds a new item to an array field using a specified post variable + * @param string $post_field root key to retrieve item content from + * @param string $path relative model path + * @return array + * @throws \Phalcon\Validation\Exception on validation issues + * @throws \ReflectionException when binding to the model class fails + */ public function addBase($post_field, $path) { $result = array("result" => "failed"); @@ -261,6 +295,14 @@ abstract class ApiMutableModelControllerBase extends ApiControllerBase return $result; } + /** + * Model delete wrapper, removes an item specified by path and uuid + * @param string $path relative model path + * @param null|string $uuid node key + * @return array + * @throws \Phalcon\Validation\Exception on validation issues + * @throws \ReflectionException when binding to the model class fails + */ public function delBase($path, $uuid) { @@ -285,19 +327,28 @@ abstract class ApiMutableModelControllerBase extends ApiControllerBase return $result; } - public function setBase($postval, $path, $uuid) + /** + * Model setter wrapper, sets the contents of an array item using this requests post variable and path settings + * @param string $post_field root key to retrieve item content from + * @param string $path relative model path + * @param $uuid node key + * @return array + * @throws \Phalcon\Validation\Exception on validation issues + * @throws \ReflectionException when binding to the model class fails + */ + public function setBase($post_field, $path, $uuid) { - if ($this->request->isPost() && $this->request->hasPost($postval)) { + if ($this->request->isPost() && $this->request->hasPost($post_field)) { $mdl = $this->getModel(); if ($uuid != null) { $node = $mdl->getNodeByReference($path . '.' . $uuid); if ($node != null) { $result = array("result" => "failed", "validations" => array()); - $node->setNodes($this->request->getPost($postval)); + $node->setNodes($this->request->getPost($post_field)); $valMsgs = $mdl->performValidation(); foreach ($valMsgs as $field => $msg) { - $fieldnm = str_replace($node->__reference, $postval, $msg->getField()); + $fieldnm = str_replace($node->__reference, $post_field, $msg->getField()); $result["validations"][$fieldnm] = $msg->getMessage(); } @@ -314,6 +365,14 @@ abstract class ApiMutableModelControllerBase extends ApiControllerBase return array("result" => "failed"); } + /** + * Generic toggle function, assumes our model item has an enabled boolean type field. + * @param string $path relative model path + * @param $uuid node key + * @return array + * @throws \Phalcon\Validation\Exception on validation issues + * @throws \ReflectionException when binding to the model class fails + */ public function toggleBase($path, $uuid) { $result = array("result" => "failed");