Start fixing up ViewBuilder API. Also fixed a few wrong doc blocks.

src/View/ViewBuilder.php

@@ -114,208 +114,474 @@ class ViewBuilder implements JsonSerializable, Serializable
     protected $_helpers = [];
 
     /**
+     * Sets path for template files.
+     *
+     * @param string $path Path for view files.
+     * @return $this
+     */
+    public function setTemplatePath($path)
+    {
+        $this->_templatePath = $path;
+
+        return $this;
+    }
+
+    /**
+     * Gets path for template files.
+     *
+     * @return string
+     */
+    public function getTemplatePath()
+    {
+        return $this->_templatePath;
+    }
+
+    /**
      * Get/set path for template files.
      *
+     * @deprecated 3.4.0 Use setTemplatePath()/getTemplatePath() instead.
      * @param string|null $path Path for view files. If null returns current path.
      * @return string|self
      */
     public function templatePath($path = null)
     {
-        if ($path === null) {
-            return $this->_templatePath;
+        if ($path !== null) {
+            return $this->setTemplatePath($path);
         }
 
-        $this->_templatePath = $path;
+        return $this->getTemplatePath();
+    }
+
+    /**
+     * Sets path for layout files.
+     *
+     * @param string $path Path for layout files.
+     * @return $this
+     */
+    public function setLayoutPath($path)
+    {
+        $this->_layoutPath = $path;
 
         return $this;
     }
 
     /**
+     * Gets path for layout files.
+     *
+     * @return string
+     */
+    public function getLayoutPath()
+    {
+        return $this->_layoutPath;
+    }
+
+    /**
      * Get/set path for layout files.
      *
+     * @deprecated 3.4.0 Use setLayoutPath()/getLayoutPath() instead.
      * @param string|null $path Path for layout files. If null returns current path.
      * @return string|self
      */
     public function layoutPath($path = null)
     {
-        if ($path === null) {
-            return $this->_layoutPath;
+        if ($path !== null) {
+            return $this->setLayoutPath($path);
         }
 
-        $this->_layoutPath = $path;
+        return $this->getLayoutPath();
+    }
+
+    /**
+     * Turns on or off CakePHP's conventional mode of applying layout files.
+     * On by default. Setting to off means that layouts will not be
+     * automatically applied to rendered views.
+     *
+     * @param bool $enable Boolean to turn on/off.
+     * @return $this
+     */
+    public function enableAutoLayout($enable)
+    {
+        $this->_autoLayout = (bool)$enable;
 
         return $this;
     }
 
     /**
+     * Returns if CakePHP's conventional mode of applying layout files is enabled.
+     * Disabled means that layouts will not be automatically applied to rendered views.
+     *
+     * @return bool
+     */
+    public function isAutoLayoutEnabled()
+    {
+        return $this->_autoLayout;
+    }
+
+    /**
      * Turns on or off CakePHP's conventional mode of applying layout files.
      * On by default. Setting to off means that layouts will not be
      * automatically applied to rendered views.
      *
-     * @param bool|null $autoLayout Boolean to turn on/off. If null returns current value.
+     * @deprecated 3.4.0 Use enableAutoLayout()/isAutoLayoutEnabled() instead.
+     * @param bool|null $enable Boolean to turn on/off. If null returns current value.
      * @return bool|self
      */
-    public function autoLayout($autoLayout = null)
+    public function autoLayout($enable = null)
     {
-        if ($autoLayout === null) {
-            return $this->_autoLayout;
+        if ($enable !== null) {
+            return $this->enableAutoLayout($enable);
         }
 
-        $this->_autoLayout = (bool)$autoLayout;
+        return $this->isAutoLayoutEnabled();
+    }
+
+    /**
+     * Sets the plugin name to use.
+     *
+     * `False` to remove current plugin name is deprecated as of 3.4.0. Use directly `null` instead.
+     *
+     * @param string|null|false $name Plugin name.
+     *   Use null or false to remove the current plugin name.
+     * @return $this
+     */
+    public function setPlugin($name)
+    {
+        $this->_plugin = $name;
 
         return $this;
     }
 
     /**
+     * Gets the plugin name to use.
+     *
+     * @return string
+     */
+    public function getPlugin()
+    {
+        return $this->_plugin;
+    }
+
+    /**
      * The plugin name to use
      *
+     * @deprecated 3.4.0 Use setPlugin()/getPlugin() instead.
      * @param string|null|false $name Plugin name. If null returns current plugin.
      *   Use false to remove the current plugin name.
      * @return string|self
      */
     public function plugin($name = null)
     {
-        if ($name === null) {
-            return $this->_plugin;
+        if ($name !== null) {
+            return $this->setPlugin($name);
         }
 
-        $this->_plugin = $name;
+        return $this->getPlugin();
+    }
+
+    /**
+     * Sets the helpers to use.
+     *
+     * @param array $helpers Helpers to use.
+     * @param bool $merge Whether or not to merge existing data with the new data.
+     * @return $this
+     */
+    public function setHelpers(array $helpers, $merge = true)
+    {
+        if ($merge) {
+            $helpers = array_merge($this->_helpers, $helpers);
+        }
+        $this->_helpers = $helpers;
 
         return $this;
     }
 
     /**
+     * Gets the helpers to use.
+     *
+     * @return array
+     */
+    public function getHelpers()
+    {
+        return $this->_helpers;
+    }
+
+    /**
      * The helpers to use
      *
+     * @deprecated 3.4.0 Use setHelpers()/getHelpers() instead.
      * @param array|null $helpers Helpers to use.
      * @param bool $merge Whether or not to merge existing data with the new data.
      * @return array|self
      */
     public function helpers(array $helpers = null, $merge = true)
     {
-        if ($helpers === null) {
-            return $this->_helpers;
-        }
-        if ($merge) {
-            $helpers = array_merge($this->_helpers, $helpers);
+        if ($helpers !== null) {
+            return $this->setHelpers($helpers, $merge);
         }
-        $this->_helpers = $helpers;
+
+        return $this->getHelpers();
+    }
+
+    /**
+     * Sets the view theme to use.
+     *
+     * `False` to remove current theme is deprecated as of 3.4.0. Use directly `null` instead.
+     *
+     * @param string|null|false $theme Theme name.
+     *   Use null or false to remove the current theme.
+     * @return $this
+     */
+    public function setTheme($theme)
+    {
+        $this->_theme = $theme;
 
         return $this;
     }
 
     /**
+     * Gets the view theme to use.
+     *
+     * @return string
+     */
+    public function getTheme()
+    {
+        return $this->_theme;
+    }
+
+    /**
      * The view theme to use.
      *
+     * @deprecated 3.4.0 Use setTheme()/getTheme() instead.
      * @param string|null|false $theme Theme name. If null returns current theme.
      *   Use false to remove the current theme.
      * @return string|self
      */
     public function theme($theme = null)
     {
-        if ($theme === null) {
-            return $this->_theme;
+        if ($theme !== null) {
+            return $this->setTheme($theme);
         }
 
-        $this->_theme = $theme;
+        return $this->getTheme();
+    }
+
+    /**
+     * Sets the name of the view file to render. The name specified is the
+     * filename in /src/Template/<SubFolder> without the .ctp extension.
+     *
+     * @param string $name View file name to set.
+     * @return $this
+     */
+    public function setTemplate($name)
+    {
+        $this->_template = $name;
 
         return $this;
     }
 
     /**
+     * Gets the name of the view file to render. The name specified is the
+     * filename in /src/Template/<SubFolder> without the .ctp extension.
+     *
+     * @return string
+     */
+    public function getTemplate()
+    {
+        return $this->_template;
+    }
+
+    /**
      * Get/set the name of the view file to render. The name specified is the
      * filename in /src/Template/<SubFolder> without the .ctp extension.
      *
+     * @deprecated 3.4.0 Use setTemplate()/getTemplate()
      * @param string|null $name View file name to set. If null returns current name.
      * @return string|self
      */
     public function template($name = null)
     {
-        if ($name === null) {
-            return $this->_template;
+        if ($name !== null) {
+            return $this->setTemplate($name);
         }
 
-        $this->_template = $name;
+        return $this->getTemplate();
+    }
+
+    /**
+     * Sets the name of the layout file to render the view inside of.
+     * The name specified is the filename of the layout in /src/Template/Layout
+     * without the .ctp extension.
+     *
+     * @param string $name Layout file name to set.
+     * @return $this
+     */
+    public function setLayout($name)
+    {
+        $this->_layout = $name;
 
         return $this;
     }
 
     /**
+     * Gets the name of the layout file to render the view inside of.
+     *
+     * @return string
+     */
+    public function getLayout()
+    {
+        return $this->_layout;
+    }
+
+    /**
      * Get/set the name of the layout file to render the view inside of.
      * The name specified is the filename of the layout in /src/Template/Layout
      * without the .ctp extension.
      *
+     * @deprecated 3.4.0 Use setLayout()/getLayout() instead.
      * @param string|null $name Layout file name to set. If null returns current name.
      * @return string|self
      */
     public function layout($name = null)
     {
-        if ($name === null) {
-            return $this->_layout;
+        if ($name !== null) {
+            return $this->setLayout($name);
         }
 
-        $this->_layout = $name;
+        return $this->getLayout();
+    }
+
+    /**
+     * Sets additional options for the view.
+     *
+     * This lets you provide custom constructor arguments to application/plugin view classes.
+     *
+     * @param array $options An array of options.
+     * @param bool $merge Whether or not to merge existing data with the new data.
+     * @return $this
+     */
+    public function setOptions(array $options, $merge = true)
+    {
+        if ($merge) {
+            $options = array_merge($this->_options, $options);
+        }
+        $this->_options = $options;
 
         return $this;
     }
 
     /**
+     * Gets additional options for the view.
+     *
+     * @return array
+     */
+    public function getOptions()
+    {
+        return $this->_options;
+    }
+
+    /**
      * Set additional options for the view.
      *
      * This lets you provide custom constructor arguments to application/plugin view classes.
      *
+     * @deprecated 3.4.0 Use setOptions()/getOptions() instead.
      * @param array|null $options Either an array of options or null to get current options.
      * @param bool $merge Whether or not to merge existing data with the new data.
      * @return array|self
      */
     public function options(array $options = null, $merge = true)
     {
-        if ($options === null) {
-            return $this->_options;
+        if ($options !== null) {
+            return $this->setOptions($options, $merge);
         }
-        if ($merge) {
-            $options = array_merge($this->_options, $options);
-        }
-        $this->_options = $options;
+
+        return $this->getOptions();
+    }
+
+    /**
+     * Sets the view name.
+     *
+     * @param string $name The name of the view.
+     * @return $this
+     */
+    public function setName($name)
+    {
+        $this->_name = $name;
 
         return $this;
     }
 
     /**
+     * Gets the view name.
+     *
+     * @return string
+     */
+    public function getName()
+    {
+        return $this->_name;
+    }
+
+    /**
      * Get/set the view name
      *
+     * @deprecated 3.4.0 Use setName()/getName() instead.
      * @param string|null $name The name of the view
-     * @return array|self
+     * @return string|self
      */
     public function name($name = null)
     {
-        if ($name === null) {
-            return $this->_name;
+        if ($name !== null) {
+            return $this->setName($name);
         }
-        $this->_name = $name;
+
+        return $this->getName();
+    }
+
+    /**
+     * Sets the view classname.
+     *
+     * Accepts either a short name (Ajax) a plugin name (MyPlugin.Ajax)
+     * or a fully namespaced name (App\View\AppView).
+     *
+     * @param string $name The class name for the view.
+     * @return $this
+     */
+    public function setClassName($name)
+    {
+        $this->_className = $name;
 
         return $this;
     }
 
     /**
+     * Gets the view classname.
+     *
+     * @return string
+     */
+    public function getClassName()
+    {
+        return $this->_className;
+    }
+
+    /**
      * Get/set the view classname.
      *
      * Accepts either a short name (Ajax) a plugin name (MyPlugin.Ajax)
      * or a fully namespaced name (App\View\AppView).
      *
+     * @deprecated 3.4.0 Use setClassName()/getClassName() instead.
      * @param string|null $name The class name for the view. Can
      *   be a plugin.class name reference, a short alias, or a fully
      *   namespaced name.
-     * @return array|self
+     * @return string|self
      */
     public function className($name = null)
     {
-        if ($name === null) {
-            return $this->_className;
+        if ($name !== null) {
+            return $this->setClassName($name);
         }
-        $this->_className = $name;
 
-        return $this;
+        return $this->getClassName();
     }
 
     /**