From 727e7e696b400b669592602d994e06a6284a8e11 Mon Sep 17 00:00:00 2001
From: "Bruno O. Notario" <bruno@exacti.com.br>
Date: Mon, 9 Aug 2021 00:50:02 -0300
Subject: [PATCH] More phpdoc

A little bit of more documented classes
---
 system/engine/abstracthelper.php    |  4 +++
 system/engine/action.php            | 23 +++++++++------
 system/engine/classes.php           | 44 ++++++++++++++++++++++++++---
 system/engine/controller.php        | 26 ++++++++++++++---
 system/engine/interfaces/action.php | 36 ++++++++++++++++++-----
 system/engine/loader.php            |  4 ++-
 system/engine/model.php             |  5 ++++
 system/engine/registry.php          | 10 +++++--
 system/engine/response.php          | 39 ++++++++++++++++++++-----
 system/engine/traits/action.php     | 18 ++++++------
 system/system.php                   |  7 ++++-
 11 files changed, 174 insertions(+), 42 deletions(-)

diff --git a/system/engine/abstracthelper.php b/system/engine/abstracthelper.php
index a0d2938..8e9715f 100644
--- a/system/engine/abstracthelper.php
+++ b/system/engine/abstracthelper.php
@@ -24,6 +24,10 @@ abstract class AbstractHelper {
 	 */
 	public function __construct(Registry $registry = NULL) {
 		if(!$registry){
+			
+			/**
+			 * @global \Phacil\Framework\startEngineExacTI $engine
+			 */
 			global $engine;
 			$registry = $engine->registry;
 		}
diff --git a/system/engine/action.php b/system/engine/action.php
index 8006c92..1ba26ee 100644
--- a/system/engine/action.php
+++ b/system/engine/action.php
@@ -11,15 +11,19 @@ namespace Phacil\Framework;
 use \Phacil\Framework\Interfaces\Action as ActionInterface;
 use \Phacil\Framework\Traits\Action as ActionTrait;
 
-/** @package Phacil\Framework */
+/** 
+ * Action class to route all user controllers
+ * 
+ * @since 1.0.0
+ * 
+ * @package Phacil\Framework 
+ **/
 final class Action implements ActionInterface {
 
 	use ActionTrait;
 	
 	/**
-	 * @param string $route 
-	 * @param array $args 
-	 * @return void 
+	 * @inheritdoc
 	 */
 	public function __construct($route, $args = array()) {
 		$path = '';
@@ -123,15 +127,18 @@ final class Action implements ActionInterface {
 }
 
 
-/** @package Phacil\Framework */
+/** 
+ * Action class to route all framework system controllers
+ * 
+ * @since 1.0.1
+ * 
+ * @package Phacil\Framework */
 final class ActionSystem implements ActionInterface {
 	
 	use ActionTrait;
 
 	/**
-	 * @param string $route 
-	 * @param array $args 
-	 * @return void 
+	 * @inheritdoc
 	 */
 	public function __construct($route, $args = array()) {
 		$path = '';
diff --git a/system/engine/classes.php b/system/engine/classes.php
index cd27c10..c104ea6 100644
--- a/system/engine/classes.php
+++ b/system/engine/classes.php
@@ -8,11 +8,30 @@
 
 namespace Phacil\Framework;
 
-/** @package Phacil\Framework */
+/** 
+ * This class return the loaded classes and functions in HTML or array format.
+ * 
+ * @uses Classes()->classes() to view loaded classes
+ * @uses Classes()->functions() to view the funcions of loaded classes.
+ * 
+ * The method exists('class') check if a class exists and is most compatible instead PHP native function.
+ * 
+ * @uses Classes()->exists('class') to check if a class exists.
+ * 
+ * @package Phacil\Framework
+ * @since 1.5.0 */
 final class Classes {
 	
+	/**
+	 * 
+	 * @var string|null
+	 */
 	private $format;
 	
+	/**
+	 * @param string|null $format Define if the output is an array or HTML format
+	 * @return void 
+	 */
 	public function __construct($format = NULL) {
 		
 		$this->format = $format;
@@ -20,13 +39,16 @@ final class Classes {
 	}
 	
 	/**
+	 * Return the loaded classes 
 	 * @param string|null $origin 
-	 * @return string
+	 * @return string|array
 	 */
 	public function classes($origin = NULL){
 		$mClass = get_declared_classes();
 		
 		$pegaKey = 0;
+
+		$pegaClass = [];
 		
 		foreach($mClass as $key => $value){
 			if($value == 'startEngineExacTI'){
@@ -50,7 +72,10 @@ final class Classes {
 		return($pegaClass);
 	}
 	
-	/** @return array|string  */
+	/** 
+	 * Return the functions of loaded classes
+	 * 
+	 * @return array|string  */
 	public function functions(){
 		$classes = $this->classes('intern');
 		
@@ -74,6 +99,17 @@ final class Classes {
 		return $functions;
 		
 	}
+
+	/**
+	 * Check the class exists
+	 * 
+	 * @param string $class 
+	 * @return bool 
+	 */
+	public function exists($class)
+	{
+		return class_exists($class);
+	}
 	
 	
-}
\ No newline at end of file
+}
diff --git a/system/engine/controller.php b/system/engine/controller.php
index 92937e5..1c1778c 100644
--- a/system/engine/controller.php
+++ b/system/engine/controller.php
@@ -18,15 +18,26 @@ use Exception;
  * Extend this class to create interation with your module controller to Phacil engine controller.
  * 
  * Use as:
- * class YouClass extends \Phacil\Framework\Controller {}
+ * <code>
+ * <?php 
+ * namespace YourPrefix\Path\Controller;
+ * class YouClass extends \Phacil\Framework\Controller {
+ *  public function index() {
+ *      #Your code
+ *  }
+ * } 
+ * </code>
  * 
  * You can use the __construct function on call the \Phacil\Framework\Register object inside parent.
  * 
- *  Example: public funcion __construct(\Phacil\Framework\Registry $registry){ parent::__construct($registry); YOUR_CODE; }
+ * <code>
+ *  public funcion __construct(\Phacil\Framework\Registry $registry){ parent::__construct($registry); YOUR_CODE; }
+ * </code>
  * 
+ * @abstract
  * @package Phacil\Framework 
- * @since 1.0
- * */
+ * @since 0.1.0
+ */
 abstract class Controller {
     /**
      * 
@@ -106,6 +117,7 @@ abstract class Controller {
      * 
      * @param string $key 
      * @return Registry 
+     * @final
      */
     final public function __get($key) {
         return $this->registry->get($key);
@@ -116,6 +128,7 @@ abstract class Controller {
      * @param string $key 
      * @param object $value 
      * @return void 
+     * @final
      */
     final public function __set($key, $value) {
         $this->registry->set($key, $value);
@@ -125,6 +138,7 @@ abstract class Controller {
      * @param string $route 
      * @param array $args 
      * @return \Phacil\Framework\Interfaces\Action
+     * @final
      */
     final protected function forward($route, array $args = array()) {
         return new Action($route, $args);
@@ -134,6 +148,7 @@ abstract class Controller {
      * @param string $url 
      * @param int $status 
      * @return never 
+     * @final
      */
     final protected function redirect($url, $status = 302) {
         header('Status: ' . $status);
@@ -142,6 +157,7 @@ abstract class Controller {
     }
 
     /**
+     * @final
      * @param string $child 
      * @param array $args 
      * @return object 
@@ -187,6 +203,7 @@ abstract class Controller {
      * @throws RuntimeException 
      * @throws SmartyException 
      * @throws Exception 
+     * @final
      */
     final protected function render() {
 
@@ -409,6 +426,7 @@ abstract class Controller {
      * @param bool $commonChildren 
      * @return \Phacil\Framework\Response 
      * @throws Exception 
+     * @final
      */
     final protected function out ($commonChildren = true) {
         if($commonChildren === true){
diff --git a/system/engine/interfaces/action.php b/system/engine/interfaces/action.php
index b675fdd..10a13f6 100644
--- a/system/engine/interfaces/action.php
+++ b/system/engine/interfaces/action.php
@@ -11,31 +11,53 @@ namespace Phacil\Framework\Interfaces;
 interface Action {
 
 	/**
-	 * @param string $route 
-	 * @param array $args 
+	 * @param string $route HTTP route for the respective controller
+	 * @param array $args Args to be pass for the method controller
 	 * @return void 
 	 */
 	public function __construct($route, $args = array());
 
-	/** @return string  */
+	/** 
+	 * Return the controller file path
+	 * 
+	 * @return string  */
 	public function getFile();
 
-	/** @return string  */
+	/** 
+	 * Return the class of controller
+	 * 
+	 * @deprecated 2.0.0 This method return only legacy class. user getClassAlt instead.
+	 * @see \Phacil\Framework\Interfaces\Action::getClassAlt()
+	 * 
+	 * @return string  */
 	public function getClass();
 
 	/**
+	 * Set the class of controller to be loaded
 	 * 
 	 * @param string $class 
 	 * @return $this 
 	 */
 	public function setClass($class);
 
-	/** @return array  */
+	/** 
+	 * Get all classes for the new 2.0 framework version
+	 * 
+	 * @return array  
+	 */
 	public function getClassAlt();
 
-	/** @return string  */
+	/** 
+	 * Return the method to be loaded
+	 * 
+	 * @return string  
+	 */
 	public function getMethod();
 
-	/** @return array  */
+	/** 
+	 * Return the args
+	 * 
+	 * @return array  
+	 */
 	public function getArgs();
 }
\ No newline at end of file
diff --git a/system/engine/loader.php b/system/engine/loader.php
index 45f5f12..64b45d1 100644
--- a/system/engine/loader.php
+++ b/system/engine/loader.php
@@ -107,7 +107,9 @@ final class Loader implements \Phacil\Framework\Interfaces\Loader {
 
     /**
 	 * temp alias, consider change to loader controller function
-     * @param string $control 
+     * @param string $control Name of controller
+	 * @deprecated 2.0.0
+	 * @since 1.1.0
      * @return void 
      */
     public function control($control) { 
diff --git a/system/engine/model.php b/system/engine/model.php
index 00b780b..5f535ab 100644
--- a/system/engine/model.php
+++ b/system/engine/model.php
@@ -24,7 +24,12 @@ abstract class Model {
 	 */
 	public function __construct(Registry $registry = NULL) {
 		if(!$registry){
+			
+			/**
+			 * @global \Phacil\Framework\startEngineExacTI $engine
+			 */
 			global $engine;
+
 			$registry = $engine->registry;
 		}
 		$this->registry = $registry;
diff --git a/system/engine/registry.php b/system/engine/registry.php
index 1edd7b0..d2078a3 100644
--- a/system/engine/registry.php
+++ b/system/engine/registry.php
@@ -8,7 +8,13 @@
 
  namespace Phacil\Framework;
  
-/** @package Phacil\Framework */
+/** 
+ * The registration off all objects on this Framework.
+ * 
+ * @since 0.0.1
+ * 
+ * @package Phacil\Framework 
+ */
 final class Registry {
 	/**
 	 * data Objects
@@ -56,7 +62,7 @@ final class Registry {
 	 * @param string $key
 	 * @return void
 	 */
-	public function destroy(string $key) {
+	public function delete(string $key) {
 		if (isset($this->$key)) {
 			unset($this->$key);
 		}
diff --git a/system/engine/response.php b/system/engine/response.php
index 5a5e559..a8114f4 100644
--- a/system/engine/response.php
+++ b/system/engine/response.php
@@ -8,7 +8,12 @@
 
 namespace Phacil\Framework;
 
-/** @package Phacil\Framework */
+/** 
+ * HTTP response class.
+ * 
+ * @since 0.0.1
+ * 
+ * @package Phacil\Framework */
 final class Response {
 
 	/**
@@ -26,11 +31,19 @@ final class Response {
 	private $output;
 	
 	/**
-	 * @param string $header 
+	 * Add a HTTP header, it's must be a one string or two string args.
+	 * 
+	 * @param string $header The all entire header or just a key
+	 * @param string|null $content [optional] An content value header
 	 * @return void 
 	 */
-	public function addHeader($header) {
-		$this->headers[] = $header;
+	public function addHeader($header, $content = null) {
+		if($content){
+			$this->headers[$header] = $content;
+		} else {
+			$head = explode(':', $header, 2);
+			$this->headers[$head['0']] = isset($head[1]) ? $head[1]: false;
+		}
 	}
 
 	/**
@@ -113,9 +126,21 @@ final class Response {
 			}	
 				
 			if (!headers_sent()) {
-				foreach ($this->headers as $header) {
-					header($header, true);
+				foreach ($this->headers as $key => $header) {
+					try {
+						if(!$header)
+							header($key, true);
+						else 
+							header($key.": ".$header, true);
+
+					} catch (Exception $th) {
+						//throw $th;
+						throw new Exception("Error Processing Header ".$key, 1);
+					}
+					
 				}
+			} else {
+				throw new Exception("Error Processing Headers: Header or Content has been sent", 1);
 			}
 			
 			echo $ouput;
@@ -124,7 +149,7 @@ final class Response {
 
 	/** @return void  */
 	public function isJSON() {
-		$this->addHeader('Content-Type: application/json');
+		$this->addHeader('Content-Type', 'application/json');
 	}
 
 	/**
diff --git a/system/engine/traits/action.php b/system/engine/traits/action.php
index 71409b5..d7d1af7 100644
--- a/system/engine/traits/action.php
+++ b/system/engine/traits/action.php
@@ -12,6 +12,8 @@ namespace Phacil\Framework\Traits;
  * Trait for the Action class
  * 
  * Code reused in ActionSystem class
+ * 
+ * @see \Phacil\Framework\Interfaces\Action
  */
 trait Action {
 
@@ -45,12 +47,14 @@ trait Action {
 	 */
 	private $classAlt = [];
 
-	/** @return string  */
+	/** @inheritdoc */
 	public function getFile() {
 		return $this->file;
 	}
 	
-	/** @return string  */
+	/** 
+	 * @deprecated 2.0.0 This method return only legacy class. user getClassAlt instead.
+	 * @inheritdoc */
 	public function getClass() {
 		return $this->class;
 	}
@@ -60,26 +64,24 @@ trait Action {
 	}
 
 	/**
-	 * 
-	 * @param string $class 
-	 * @return $this 
+	 * @inheritdoc
 	 */
 	public function setClass($class) {
 		$this->class = $class;
 		return $this;
 	}
 
-	/** @return array  */
+	/** @inheritdoc  */
 	public function getClassAlt() {
 		return $this->classAlt;
 	}
 	
-	/** @return string  */
+	/** @inheritdoc  */
 	public function getMethod() {
 		return $this->method;
 	}
 	
-	/** @return array  */
+	/** @inheritdoc  */
 	public function getArgs() {
 		return $this->args;
 	}
diff --git a/system/system.php b/system/system.php
index fc92e1c..5c76bb2 100644
--- a/system/system.php
+++ b/system/system.php
@@ -252,9 +252,14 @@ final class startEngineExacTI {
 
 }
 
+/**
+ * @global startEngineExacTI $engine
+ */
 global $engine;
 
-/** @var \Phacil\Framework\startEngineExacTI $engine */
+/** 
+ * @global \Phacil\Framework\startEngineExacTI $engine 
+ * */
 $engine = new startEngineExacTI();
 
 // Registry