From 6f3d7a58f2d18e834a5d6cf51bc1702ac5bef117 Mon Sep 17 00:00:00 2001 From: Joshua Wilson Date: Sat, 23 Jan 2016 15:37:15 -0500 Subject: [PATCH] Phpdoc cleanup for System\Traits removed in WidgetMaker trait phpdoc cleanup of backend traits and classes Minor fix for cases when file is not found --- modules/backend/behaviors/FormController.php | 7 ++++- .../backend/classes/ControllerBehavior.php | 6 ++-- modules/backend/classes/FormWidgetBase.php | 2 +- modules/backend/classes/WidgetBase.php | 5 ++-- modules/backend/traits/FormModelSaver.php | 2 +- modules/backend/traits/WidgetMaker.php | 8 +++-- modules/backend/widgets/Form.php | 29 ++++++++++++------- modules/system/traits/AssetMaker.php | 3 -- modules/system/traits/ConfigMaker.php | 10 +++++-- modules/system/traits/PropertyContainer.php | 8 ++++- modules/system/traits/ViewMaker.php | 18 +++++++----- 11 files changed, 60 insertions(+), 38 deletions(-) diff --git a/modules/backend/behaviors/FormController.php b/modules/backend/behaviors/FormController.php index cbf79fa5a..9f40933eb 100644 --- a/modules/backend/behaviors/FormController.php +++ b/modules/backend/behaviors/FormController.php @@ -39,7 +39,12 @@ class FormController extends ControllerBehavior const CONTEXT_PREVIEW = 'preview'; /** - * @var Backend\Classes\WidgetBase Reference to the widget object. + * @var \Backend\Classes\Controller|FormController Reference to the back end controller. + */ + protected $controller; + + /** + * @var \Backend\Widgets\Form Reference to the widget object. */ protected $formWidget; diff --git a/modules/backend/classes/ControllerBehavior.php b/modules/backend/classes/ControllerBehavior.php index 4a63a8398..ba0d959f6 100644 --- a/modules/backend/classes/ControllerBehavior.php +++ b/modules/backend/classes/ControllerBehavior.php @@ -27,7 +27,7 @@ class ControllerBehavior extends ExtensionBase protected $config; /** - * @var Backend\Classes\Controller Reference to the back end controller. + * @var \Backend\Classes\Controller Reference to the back end controller. */ protected $controller; @@ -71,8 +71,8 @@ class ControllerBehavior extends ExtensionBase /** * Safe accessor for configuration values. - * @param $name Config name, supports array names like "field[key]" - * @param $default Default value if nothing is found + * @param string $name Config name, supports array names like "field[key]" + * @param mixed $default Default value if nothing is found * @return string */ public function getConfig($name = null, $default = null) diff --git a/modules/backend/classes/FormWidgetBase.php b/modules/backend/classes/FormWidgetBase.php index 168deedb8..3ab2c4499 100644 --- a/modules/backend/classes/FormWidgetBase.php +++ b/modules/backend/classes/FormWidgetBase.php @@ -99,7 +99,7 @@ abstract class FormWidgetBase extends WidgetBase /** * Process the postback value for this widget. If the value is omitted from * postback data, it will be NULL, otherwise it will be an empty string. - * @param $value The existing value for this widget. + * @param mixed $value The existing value for this widget. * @return string The new value for this widget. */ public function getSaveValue($value) diff --git a/modules/backend/classes/WidgetBase.php b/modules/backend/classes/WidgetBase.php index 0e98bfdf0..cf93e5256 100644 --- a/modules/backend/classes/WidgetBase.php +++ b/modules/backend/classes/WidgetBase.php @@ -26,7 +26,7 @@ abstract class WidgetBase public $config; /** - * @var Backend\Classes\Controller Backend controller object. + * @var \Backend\Classes\Controller Backend controller object. */ protected $controller; @@ -42,9 +42,8 @@ abstract class WidgetBase /** * Constructor - * @param Backend\Classes\Controller $controller + * @param \Backend\Classes\Controller $controller * @param array $configuration Proactive configuration definition. - * @return void */ public function __construct($controller, $configuration = []) { diff --git a/modules/backend/traits/FormModelSaver.php b/modules/backend/traits/FormModelSaver.php index 3348a00ac..22eaba562 100644 --- a/modules/backend/traits/FormModelSaver.php +++ b/modules/backend/traits/FormModelSaver.php @@ -39,7 +39,7 @@ trait FormModelSaver /** * Sets a data collection to a model attributes, relations will also be set. * @param array $saveData Data to save. - * @param Model $model Model to save to + * @param \October\Rain\Database\Model $model Model to save to * @return array The collection of models to save. */ protected function setModelAttributes($model, $saveData) diff --git a/modules/backend/traits/WidgetMaker.php b/modules/backend/traits/WidgetMaker.php index a069f09e6..63b3f6ff6 100644 --- a/modules/backend/traits/WidgetMaker.php +++ b/modules/backend/traits/WidgetMaker.php @@ -14,14 +14,15 @@ use SystemException; * @package october\backend * @author Alexey Bobkov, Samuel Georges */ - trait WidgetMaker { + /** * Makes a widget object with the supplied configuration file. * @param string $class Widget class name * @param array $widgetConfig An array of config. - * @return WidgetBase The widget object + * @return \Backend\Classes\WidgetBase The widget object + * @throws SystemException */ public function makeWidget($class, $widgetConfig = []) { @@ -43,7 +44,8 @@ trait WidgetMaker * @param string $class Widget class name * @param mixed $fieldConfig A field name, an array of config or a FormField object. * @param array $widgetConfig An array of config. - * @return FormWidgetBase The widget object + * @return \Backend\Classes\FormWidgetBase The widget object + * @throws SystemException */ public function makeFormWidget($class, $fieldConfig = [], $widgetConfig = []) { diff --git a/modules/backend/widgets/Form.php b/modules/backend/widgets/Form.php index d1622a398..c2134f153 100644 --- a/modules/backend/widgets/Form.php +++ b/modules/backend/widgets/Form.php @@ -93,7 +93,7 @@ class Form extends WidgetBase ]; /** - * @var array Collection of all form widgets used in this form. + * @var FormWidgetBase[] Collection of all form widgets used in this form. */ protected $formWidgets = []; @@ -108,7 +108,7 @@ class Form extends WidgetBase public $previewMode = false; /** - * @var Backend\Classes\WidgetManager + * @var \Backend\Classes\WidgetManager */ protected $widgetManager; @@ -166,7 +166,8 @@ class Form extends WidgetBase * - null: Renders all sections * * @param array $options - * @return mixed + * @return string|bool The rendered partial contents, or false if suppressing an exception + * @throws \SystemException */ public function render($options = []) { @@ -219,9 +220,14 @@ class Form extends WidgetBase /** * Renders a single form field * - * @param string $field + * Options: + * - useContainer: Wrap the result in a container, used by AJAX. Default: true + * + * @param string|array $field The field name or definition * @param array $options - * @return mixed + * @return string|bool The rendered partial contents, or false if suppressing an exception + * @throws ApplicationException + * @throws \SystemException */ public function renderField($field, $options = []) { @@ -247,9 +253,9 @@ class Form extends WidgetBase /** * Renders the HTML element for a field - * - * @param $field - * @return mixed + * @param FormWidgetBase $field + * @return string|bool The rendered partial contents, or false if suppressing an exception + * @throws \SystemException */ public function renderFieldElement($field) { @@ -358,7 +364,7 @@ class Form extends WidgetBase if (!isset($this->allFields[$field])) { continue; } - + /** @var FormWidgetBase $fieldObject */ $fieldObject = $this->allFields[$field]; $result['#' . $fieldObject->getId('group')] = $this->makePartial('field', ['field' => $fieldObject]); } @@ -826,6 +832,7 @@ class Form extends WidgetBase * Looks up the field value. * @param mixed $field * @return string + * @throws ApplicationException */ protected function getFieldValue($field) { @@ -856,7 +863,7 @@ class Form extends WidgetBase protected function getFieldDepends($field) { if (!$field->dependsOn) { - return; + return ''; } $dependsOn = is_array($field->dependsOn) ? $field->dependsOn : [$field->dependsOn]; @@ -885,7 +892,7 @@ class Form extends WidgetBase } /** - * Returns postback data from a submitted form. + * Returns post data from a submitted form. * * @return array */ diff --git a/modules/system/traits/AssetMaker.php b/modules/system/traits/AssetMaker.php index 317768876..4d3d0d6d6 100644 --- a/modules/system/traits/AssetMaker.php +++ b/modules/system/traits/AssetMaker.php @@ -2,10 +2,8 @@ use Url; use Html; -use File; use System\Models\Parameters; use System\Models\PluginVersion; -use SystemException; /** * Asset Maker Trait @@ -14,7 +12,6 @@ use SystemException; * @package october\system * @author Alexey Bobkov, Samuel Georges */ - trait AssetMaker { diff --git a/modules/system/traits/ConfigMaker.php b/modules/system/traits/ConfigMaker.php index 55d22f893..332020650 100644 --- a/modules/system/traits/ConfigMaker.php +++ b/modules/system/traits/ConfigMaker.php @@ -25,6 +25,10 @@ trait ConfigMaker /** * Reads the contents of the supplied file and applies it to this object. + * @param array $configFile + * @param array $requiredConfig + * @return array|stdClass + * @throws SystemException */ public function makeConfig($configFile = [], $requiredConfig = []) { @@ -100,7 +104,7 @@ trait ConfigMaker * Makes a config object from an array, making the first level keys properties a new object. * Property values are converted to camelCase and are not set if one already exists. * @param array $configArray Config array. - * @return stdObject The config object + * @return stdClass The config object */ public function makeConfigFromArray($configArray = []) { @@ -149,11 +153,11 @@ trait ConfigMaker foreach ($configPath as $path) { $_fileName = $path . '/' . $fileName; if (File::isFile($_fileName)) { - break; + return $_fileName; } } - return $_fileName; + return ''; } /** diff --git a/modules/system/traits/PropertyContainer.php b/modules/system/traits/PropertyContainer.php index 40528e7a4..f7d7a2d2d 100644 --- a/modules/system/traits/PropertyContainer.php +++ b/modules/system/traits/PropertyContainer.php @@ -52,6 +52,8 @@ trait PropertyContainer /** * Sets multiple properties. + * @param array $properties + * @return array */ public function setProperties($properties) { @@ -60,14 +62,18 @@ trait PropertyContainer /** * Sets a property value + * @param string $name + * @param mixed $value + * @return void */ public function setProperty($name, $value) { - return $this->properties[$name] = $value; + $this->properties[$name] = $value; } /** * Returns all properties. + * @return array */ public function getProperties() { diff --git a/modules/system/traits/ViewMaker.php b/modules/system/traits/ViewMaker.php index c53ba54f8..258752c9c 100644 --- a/modules/system/traits/ViewMaker.php +++ b/modules/system/traits/ViewMaker.php @@ -50,6 +50,7 @@ trait ViewMaker * @param array $params Parameter variables to pass to the view. * @param bool $throwException Throw an exception if the partial is not found. * @return mixed Partial contents or false if not throwing an exception. + * @throws SystemException */ public function makePartial($partial, $params = [], $throwException = true) { @@ -88,9 +89,8 @@ trait ViewMaker /** * Renders supplied contents inside a layout. * @param string $contents The inner contents as a string. - * @param string $name Specifies the layout name. - * If this parameter is omitted, the $layout property will be used. - * @return string The layout contents + * @param string $layout Specifies the layout name. + * @throws SystemException */ public function makeViewContent($contents, $layout = null) { @@ -101,7 +101,7 @@ trait ViewMaker // Append any undefined block content to the body block Block::set('undefinedBlock', $contents); Block::append('body', Block::get('undefinedBlock')); - return $this->makeLayout(); + return $this->makeLayout($layout); } /** @@ -111,12 +111,13 @@ trait ViewMaker * @param array $params Parameter variables to pass to the view. * @param bool $throwException Throw an exception if the layout is not found * @return string The layout contents + * @throws SystemException */ public function makeLayout($name = null, $params = [], $throwException = true) { $layout = ($name === null) ? $this->layout : $name; if ($layout == '') { - return; + return ''; } $layoutPath = $this->getViewPath($layout . '.htm', $this->layoutPath); @@ -180,11 +181,11 @@ trait ViewMaker foreach ($viewPath as $path) { $_fileName = File::symbolizePath($path) . '/' . $fileName; if (File::isFile($_fileName)) { - break; + return $_fileName; } } - return $_fileName; + return ''; } /** @@ -197,7 +198,7 @@ trait ViewMaker public function makeFileContents($filePath, $extraParams = []) { if (!strlen($filePath) || !File::isFile($filePath)) { - return; + return ''; } if (!is_array($extraParams)) { @@ -287,5 +288,6 @@ trait ViewMaker if ($result = Event::fire($event, $params)) { return implode(PHP_EOL.PHP_EOL, (array) $result); } + return ''; } }