document view methods

src/View.php

@@ -33,33 +33,70 @@ class View
         $this->data = array_merge($engine->getSharedData(), $data);
     }
 
+    /**
+     * The string representation of a view is it's rendered content
+     *
+     * @return string
+     */
     public function __toString()
     {
         return $this->render();
     }
 
+    /**
+     * Calls to undefined methods are executed as helper
+     *
+     * @param $name
+     * @param $arguments
+     * @return mixed
+     */
     public function __call($name, $arguments)
     {
         return $this->engine->helper($this, $name, ...$arguments);
     }
 
+    /**
+     * Add $data for the view
+     *
+     * Later defined data overwrites current data.
+     *
+     * @param array $data
+     * @return View
+     */
     public function addData(array $data): self
     {
         $this->data = array_merge($this->data, $data);
         return $this;
     }
 
-    public function setSections(array $sections): self
+    /**
+     * Predefine section content
+     *
+     * @param string[] $sections
+     * @return View
+     */
+    public function setSections(string ...$sections): self
     {
         $this->sections = $sections;
         return $this;
     }
 
+    /**
+     * Get the current sections
+     *
+     * @return array
+     */
     public function getSections(): array
     {
         return $this->sections;
     }
 
+    /**
+     * Render the view
+     *
+     * @param array|null $data
+     * @return string
+     */
     public function render(array $data = null): string
     {
         if ($data) {
@@ -67,9 +104,9 @@ class View
         }
         unset($data);
 
-        $v = $this;
-        $e = [$this, 'escape'];
-        extract($this->data, EXTR_SKIP);
+        $v = $this;             // provide the view and it's method under $v
+        $e = [$this, 'escape']; // provide the escape method under $e
+        extract($this->data, EXTR_SKIP); // preserves $v, $e and $this
 
         $level = ob_get_level();
         try {
@@ -78,24 +115,41 @@ class View
             $content = trim(ob_get_clean());
 
             if ($this->parentTemplate) {
-                $this->parentTemplate->setSections(array_merge($this->sections, ['content' => $content]));
+                $this->parentTemplate->setSections(...array_merge($this->sections, ['content' => $content]));
                 $content = $this->parentTemplate->render();
             }
 
             return $content;
-        } catch (\Throwable $exception) {
+        } finally {
             while (ob_get_level() >  $level) {
                 ob_end_clean();
             }
-            throw $exception;
         }
     }
 
-    public function extend(string $path, array $data = null)
+    /**
+     * Extend the view $name with this view
+     *
+     * When no data is given all data in this view will be provided.
+     *
+     * @param string $name
+     * @param array $data
+     */
+    public function extend(string $name, array $data = null)
     {
-        $this->parentTemplate = $this->engine->view($path, $data ?? $this->data);
+        $this->parentTemplate = $this->engine->view($name, $data ?? $this->data);
     }
 
+    /**
+     * Start content for section $name
+     *
+     * If $append is true the content will be added to the section - otherwise existing content will be replaced.
+     *
+     * Every whitespace except spaces will be trimmed from the content.
+     *
+     * @param string $name
+     * @param bool $append
+     */
     public function start(string $name, bool $append = false)
     {
         if ($name === 'content') {
@@ -111,6 +165,9 @@ class View
         ob_start();
     }
 
+    /**
+     * End content of the current opened section
+     */
     public function end()
     {
         if (is_null($this->sectionName)) {
@@ -123,6 +180,17 @@ class View
         $this->appendSection = false;
     }
 
+    /**
+     * Provide $content as section $name
+     *
+     * If $append is true $content will be added to the section - otherwise existing content will be replaced.
+     *
+     * Every whitespace except spaces will be trimmed from $content.
+     *
+     * @param string $name
+     * @param string $content
+     * @param bool $append
+     */
     public function provide(string $name, string $content, bool $append = false)
     {
         $content = trim($content, "\t\n\r\0\x0b");
@@ -133,6 +201,13 @@ class View
         }
     }
 
+    /**
+     * Get the content of section $name or $default
+     *
+     * @param string $name
+     * @param string|null $default
+     * @return string
+     */
     public function section(string $name, string $default = null): string
     {
         if (!isset($this->sections[$name])) {
@@ -142,23 +217,26 @@ class View
         return $this->sections[$name];
     }
 
-    public function fetch($name, array $data = array())
+    /**
+     * Fetch template $name with $data
+     *
+     * @param $name
+     * @param array $data
+     * @return string
+     */
+    public function fetch(string $name, array $data = array())
     {
         return $this->engine->render($name, $data);
     }
 
-    public function insert($name, array $data = [])
-    {
-        echo $this->engine->render($name, $data);
-    }
-
     /**
-     * Apply multiple functions to variable.
+     * Apply multiple functions to variable
+     *
      * @param  mixed  $var
      * @param  string $functions
      * @return mixed
      */
-    public function batch($var, $functions)
+    public function batch($var, string $functions)
     {
         foreach (explode('|', $functions) as $function) {
             $var = $this->engine->helper($this, $function, $var);
@@ -168,17 +246,19 @@ class View
     }
 
     /**
-     * Escape string.
+     * Escape string
+     *
      * @param  string      $string
-     * @param  null|string $functions
+     * @param  string $functions
      * @return string
      */
-    public function escape($string, $functions = null)
+    public function escape(string $string, string $functions = null)
     {
         static $flags;
         if (!isset($flags)) {
             $flags = ENT_QUOTES | (defined('ENT_SUBSTITUTE') ? ENT_SUBSTITUTE : 0);
         }
+
         if ($functions) {
             $string = $this->batch($string, $functions);
         }