Consistent behavior of `run()` method in widgets

All widgets return the result now for better extensibility

close #10771

framework/CHANGELOG.md

@@ -5,6 +5,7 @@ Yii Framework 2 Change Log
 -----------------------
 
 - Removed methods marked as deprected in 2.0.x (samdark)
+- Chg #10771: Consistent behavior of `run()` method in all framework widgets. All return the result now for better extensibility (pkirill99, cebe)
 - Chg #11397: Minimum required version of PHP is 5.5.0 now (samdark)
 - Chg: Removed `yii\base\Object::className()` in favor of native PHP syntax `::class`, which does not trigger autoloading (cebe)
 

framework/widgets/ActiveForm.php

@@ -185,6 +185,7 @@ class ActiveForm extends Widget
     /**
      * Runs the widget.
      * This registers the necessary javascript code and renders the form close tag.
+     * @return string the result of widget execution to be outputted.
      * @throws InvalidCallException if `beginField()` and `endField()` calls are not matching
      */
     public function run()
@@ -194,8 +195,8 @@ class ActiveForm extends Widget
         }
 
         $content = ob_get_clean();
-        echo Html::beginForm($this->action, $this->method, $this->options);
-        echo $content;
+        $html = Html::beginForm($this->action, $this->method, $this->options);
+        $html .= $content;
 
         if ($this->enableClientScript) {
             $id = $this->options['id'];
@@ -206,7 +207,9 @@ class ActiveForm extends Widget
             $view->registerJs("jQuery('#$id').yiiActiveForm($attributes, $options);");
         }
 
-        echo Html::endForm();
+        $html .= Html::endForm();
+
+        return $html;
     }
 
     /**

framework/widgets/Block.php

@@ -57,13 +57,15 @@ class Block extends Widget
     /**
      * Ends recording a block.
      * This method stops output buffering and saves the rendering result as a named block in the view.
+     * @return string the result of widget execution to be outputted.
      */
     public function run()
     {
         $block = ob_get_clean();
         if ($this->renderInPlace) {
-            echo $block;
+            return $block;
         }
         $this->view->blocks[$this->getId()] = $block;
+        return '';
     }
 }

framework/widgets/Breadcrumbs.php

@@ -127,11 +127,12 @@ class Breadcrumbs extends Widget
 
     /**
      * Renders the widget.
+     * @return string the result of widget execution to be outputted.
      */
     public function run()
     {
         if (empty($this->links)) {
-            return;
+            return '';
         }
         $links = [];
         if ($this->homeLink === null) {
@@ -148,7 +149,7 @@ class Breadcrumbs extends Widget
             }
             $links[] = $this->renderItem($link, isset($link['url']) ? $this->itemTemplate : $this->activeItemTemplate);
         }
-        echo Html::tag($this->tag, implode('', $links), $this->options);
+        return Html::tag($this->tag, implode('', $links), $this->options);
     }
 
     /**

framework/widgets/ContentDecorator.php

@@ -68,12 +68,13 @@ class ContentDecorator extends Widget
     /**
      * Ends recording a clip.
      * This method stops output buffering and saves the rendering result as a named clip in the controller.
+     * @return string the result of widget execution to be outputted.
      */
     public function run()
     {
         $params = $this->params;
         $params['content'] = ob_get_clean();
         // render under the existing context
-        echo $this->view->renderFile($this->viewFile, $params);
+        return $this->view->renderFile($this->viewFile, $params);
     }
 }

framework/widgets/DetailView.php

@@ -131,6 +131,7 @@ class DetailView extends Widget
     /**
      * Renders the detail view.
      * This is the main entry of the whole detail view rendering.
+     * @return string the result of widget execution to be outputted.
      */
     public function run()
     {
@@ -142,7 +143,7 @@ class DetailView extends Widget
 
         $options = $this->options;
         $tag = ArrayHelper::remove($options, 'tag', 'table');
-        echo Html::tag($tag, implode("\n", $rows), $options);
+        return Html::tag($tag, implode("\n", $rows), $options);
     }
 
     /**

framework/widgets/FragmentCache.php

@@ -98,17 +98,18 @@ class FragmentCache extends Widget
      * Content displayed before this method call and after [[init()]]
      * will be captured and saved in cache.
      * This method does nothing if valid content is already found in cache.
+     * @return string the result of widget execution to be outputted.
      */
     public function run()
     {
         if (($content = $this->getCachedContent()) !== false) {
-            echo $content;
+            return $content;
         } elseif ($this->cache instanceof Cache) {
             array_pop($this->getView()->cacheStack);
             
             $content = ob_get_clean();
             if ($content === false || $content === '') {
-                return;
+                return '';
             }
             if (is_array($this->dependency)) {
                 $this->dependency = Yii::createObject($this->dependency);
@@ -119,8 +120,9 @@ class FragmentCache extends Widget
             if (empty($this->getView()->cacheStack) && !empty($this->dynamicPlaceholders)) {
                 $content = $this->updateDynamicContent($content, $this->dynamicPlaceholders);
             }
-            echo $content;
+            return $content;
         }
+        return '';
     }
 
     /**

framework/widgets/LinkPager.php

@@ -124,13 +124,14 @@ class LinkPager extends Widget
     /**
      * Executes the widget.
      * This overrides the parent implementation by displaying the generated page buttons.
+     * @return string the result of widget execution to be outputted.
      */
     public function run()
     {
         if ($this->registerLinkTags) {
             $this->registerLinkTags();
         }
-        echo $this->renderPageButtons();
+        return $this->renderPageButtons();
     }
 
     /**

framework/widgets/LinkSorter.php

@@ -59,10 +59,11 @@ class LinkSorter extends Widget
     /**
      * Executes the widget.
      * This method renders the sort links.
+     * @return string the result of widget execution to be outputted.
      */
     public function run()
     {
-        echo $this->renderSortLinks();
+        return $this->renderSortLinks();
     }
 
     /**

framework/widgets/MaskedInput.php

@@ -125,9 +125,9 @@ class MaskedInput extends InputWidget
     {
         $this->registerClientScript();
         if ($this->hasModel()) {
-            echo Html::activeInput($this->type, $this->model, $this->attribute, $this->options);
+            return Html::activeInput($this->type, $this->model, $this->attribute, $this->options);
         } else {
-            echo Html::input($this->type, $this->name, $this->value, $this->options);
+            return Html::input($this->type, $this->name, $this->value, $this->options);
         }
     }
 

framework/widgets/Menu.php

@@ -162,6 +162,7 @@ class Menu extends Widget
 
     /**
      * Renders the menu.
+     * @return string the result of widget execution to be outputted.
      */
     public function run()
     {
@@ -172,12 +173,14 @@ class Menu extends Widget
             $this->params = Yii::$app->request->getQueryParams();
         }
         $items = $this->normalizeItems($this->items, $hasActiveChild);
-        if (!empty($items)) {
+        if (empty($items)) {
+            return '';
+        }
+
         $options = $this->options;
         $tag = ArrayHelper::remove($options, 'tag', 'ul');
 
-            echo Html::tag($tag, $this->renderItems($items), $options);
-        }
+        return Html::tag($tag, $this->renderItems($items), $options);
     }
 
     /**

framework/widgets/Spaceless.php

@@ -60,10 +60,11 @@ class Spaceless extends Widget
 
     /**
      * Marks the end of content to be cleaned from whitespace characters between HTML tags.
-     * Stops capturing an output and echoes cleaned result.
+     * Stops capturing an output and returns cleaned result.
+     * @return string the result of widget execution to be outputted.
      */
     public function run()
     {
-        echo trim(preg_replace('/>\s+</', '><', ob_get_clean()));
+        return trim(preg_replace('/>\s+</', '><', ob_get_clean()));
     }
 }