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

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

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)

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)

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 = [])
     {

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)

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 = [])
     {

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
      */

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
 {
 

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 '';
     }
 
     /**

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()
     {

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