From 5770a31ef82cfff9e824870587717912d3da2ff4 Mon Sep 17 00:00:00 2001
From: Ulf Gebhardt <ulf.gebhardt@webcraft-media.de>
Date: Sat, 11 Jun 2016 00:22:02 +0200
Subject: [PATCH] #3 docu system

---
 ...ut.php => autoload_exception_shortcut.inc} |  0
 ...rtcut.php => autoload_result_shortcut.inc} |  0
 system/HEADER.php                             | 13 +++
 system/autoload.php                           | 61 +++++++-------
 system/locale.php                             | 44 ++++++++--
 system/qq/SYS_LOCALE_SET_LOCALE.php           | 14 ++++
 system/system.php                             | 82 +++++++++++++++----
 system/time.php                               | 37 ++++++++-
 8 files changed, 197 insertions(+), 54 deletions(-)
 rename log/{register_exception_shortcut.php => autoload_exception_shortcut.inc} (100%)
 rename log/{register_result_shortcut.php => autoload_result_shortcut.inc} (100%)

diff --git a/log/register_exception_shortcut.php b/log/autoload_exception_shortcut.inc
similarity index 100%
rename from log/register_exception_shortcut.php
rename to log/autoload_exception_shortcut.inc
diff --git a/log/register_result_shortcut.php b/log/autoload_result_shortcut.inc
similarity index 100%
rename from log/register_result_shortcut.php
rename to log/autoload_result_shortcut.inc
diff --git a/system/HEADER.php b/system/HEADER.php
index 77cd9cf..92ac5ff 100644
--- a/system/HEADER.php
+++ b/system/HEADER.php
@@ -1,6 +1,19 @@
 <?php
+/**
+ * System - PHP Framework
+ *
+ * PHP Version 5.6
+ *
+ * @copyright   2016 Ulf Gebhardt (http://www.webcraft-media.de)
+ * @license     http://www.opensource.org/licenses/mit-license.php MIT
+ * @link        https://github.com/webcraftmedia/system
+ * @package     SYSTEM
+ */
 namespace SYSTEM;
 
+/**
+ * HEADER Class provided by System Send HTML Headers
+ */
 class HEADER {
     private static function checkHeader(){
         $file = null;
diff --git a/system/autoload.php b/system/autoload.php
index 41cdb1f..b1bb4a7 100644
--- a/system/autoload.php
+++ b/system/autoload.php
@@ -1,11 +1,26 @@
 <?php
+/**
+ * System - PHP Framework
+ *
+ * PHP Version 5.6
+ *
+ * @copyright   2016 Ulf Gebhardt (http://www.webcraft-media.de)
+ * @license     http://www.opensource.org/licenses/mit-license.php MIT
+ * @link        https://github.com/webcraftmedia/system
+ * @package     SYSTEM
+ */
 namespace SYSTEM;
 
+/**
+ * autoload Class provided by System to Autoload Classes
+ */
 class autoload {
-    
-    private static $files = array();       // array(class, namespace, file)
-    private static $folders = array();     // array(namespace, folder)   
-    private static $func = array();        // array(namespace, func)
+    /** array Registered Files Format array(class, namespace, file) */
+    private static $files = array();
+    /** array Registered Folders Format array(class, namespace, folder) */
+    private static $folders = array();   
+    /** string Registered Func Format array(namespace, func) */
+    private static $func = array();
 
     private static function getClassFromFile($file){
         $path_info = \pathinfo($file);
@@ -66,39 +81,25 @@ class autoload {
         self::$func[] = array($namespace, $func);
     }
     
+    /**
+     * Registers the Autoload Handler against the PHP Environment
+     *
+     * @return null Returns null
+     */
     public static function register_autoload(){
         spl_autoload_register('\SYSTEM\autoload::autoload');}
 
+    /**
+     * Autoloads a class. This function is registered against the PHP Environment.
+     * It is called from PHP if a new class is required.
+     *
+     * @param string $class Class to be autoloaded
+     * @return bool Returns true if successfull.
+     */
     public static function autoload($class){        
         $classns = self::getClassNamespaceFromClass($class);
-        
         if(!self::autoload_($classns[0],$classns[1]) || (!class_exists($class) && !interface_exists($class))){
             throw new \SYSTEM\LOG\ERROR("Class not found: ".$class);}
-        
         return true;
     }
-    
-    private static function file_extension($filename){
-        $path_info = pathinfo($filename);
-        return array_key_exists('extension', $path_info) ? strtolower($path_info['extension']) : NULL;
-    }
-    
-    //for docu we need all classes actually declared
-    public static function autoload_all(){
-        foreach(self::$files as $file){            
-            require_once $file[2];}        
-        
-        foreach(self::$folders as $folder){                
-            if ($handle = opendir($folder[1])) {
-                while (false !== ($file = readdir($handle))) {
-                    if (    $file != "." && $file != ".." && 
-                            self::file_extension($file) == 'php' &&
-                            !class_exists($folder[0].'\\'.substr($file,0,count($file)-5),false)) {                                                
-                        require_once $folder[1].'/'.$file;                        
-                    }
-                }
-            }
-            closedir($handle);
-        }                    
-    }
 }
\ No newline at end of file
diff --git a/system/locale.php b/system/locale.php
index 9044011..1aa4af2 100644
--- a/system/locale.php
+++ b/system/locale.php
@@ -1,9 +1,31 @@
 <?php
+/**
+ * System - PHP Framework
+ *
+ * PHP Version 5.6
+ *
+ * @copyright   2016 Ulf Gebhardt (http://www.webcraft-media.de)
+ * @license     http://www.opensource.org/licenses/mit-license.php MIT
+ * @link        https://github.com/webcraftmedia/system
+ * @package     SYSTEM
+ */
 namespace SYSTEM;
 
-class locale {    
+/**
+ * locale Class provided by System to start manage Session Language and check a
+ * language against the languages configured in the configuration
+ */
+class locale {
+    /** string Sessionkey for the language */
     const SESSION_KEY = 'locale';        
 
+    /**
+     * Set the Session language
+     * If the User is logged in it can trigger an Database update
+     *
+     * @param string $lang Language
+     * @return bool Returns true if successfull.
+     */
     public static function set($lang){
         if(!self::isLang($lang)){
             return false;}
@@ -11,21 +33,33 @@ class locale {
         \SYSTEM\SECURITY\security::save(self::SESSION_KEY, $lang);
         if(\SYSTEM\SECURITY\security::isLoggedIn()){
             $user = \SYSTEM\SECURITY\security::getUser();
-            $user->locale = $lang;
-            \SYSTEM\SQL\SYS_LOCALE_SET_LOCALE::Q1(array($lang, $user->id));            
+            if($user->locale != $lang){
+                $user->locale = $lang;
+                \SYSTEM\SQL\SYS_LOCALE_SET_LOCALE::Q1(array($lang, $user->id));}
         }
-            
         return true;
     }
 
+    /**
+     * Get the Session language
+     * If no language is saved in the Session it is set to the
+     * System-Default-Session defined in the config.
+     *
+     * @return string Returns Session Language
+     */
     public static function get(){
         $value = \SYSTEM\SECURITY\security::load(self::SESSION_KEY);
         if($value == NULL){
             return \SYSTEM\CONFIG\config::get(\SYSTEM\CONFIG\config_ids::SYS_CONFIG_DEFAULT_LANG);}
-
         return $value;
     }
 
+    /**
+     * Checks Language against languages defined in the config.
+     *
+     * @param string $lang Language to be checked
+     * @return bool Returns true if Language is within the configured Languages
+     */
     public static function isLang($lang){        
         if(!\in_array($lang, \SYSTEM\CONFIG\config::get(\SYSTEM\CONFIG\config_ids::SYS_CONFIG_LANGS))){
             return false;}
diff --git a/system/qq/SYS_LOCALE_SET_LOCALE.php b/system/qq/SYS_LOCALE_SET_LOCALE.php
index 3894a63..c349e8e 100644
--- a/system/qq/SYS_LOCALE_SET_LOCALE.php
+++ b/system/qq/SYS_LOCALE_SET_LOCALE.php
@@ -1,5 +1,19 @@
 <?php
+/**
+ * System - PHP Framework
+ *
+ * PHP Version 5.6
+ *
+ * @copyright   2016 Ulf Gebhardt (http://www.webcraft-media.de)
+ * @license     http://www.opensource.org/licenses/mit-license.php MIT
+ * @link        https://github.com/webcraftmedia/system
+ * @package     SYSTEM\SQL
+ */
 namespace SYSTEM\SQL;
+
+/**
+ * QQ to set a users language setting
+ */
 class SYS_LOCALE_SET_LOCALE extends \SYSTEM\DB\QP {
     public static function get_class(){return \get_class();}
     public static function pgsql(){return           
diff --git a/system/system.php b/system/system.php
index 27e9e0c..89a51fa 100644
--- a/system/system.php
+++ b/system/system.php
@@ -1,28 +1,65 @@
 <?php
-
+/**
+ * System - PHP Framework
+ *
+ * PHP Version 5.6
+ *
+ * @copyright   2016 Ulf Gebhardt (http://www.webcraft-media.de)
+ * @license     http://www.opensource.org/licenses/mit-license.php MIT
+ * @link        https://github.com/webcraftmedia/system
+ * @package     SYSTEM
+ */
 namespace SYSTEM;
 
+/**
+ * System Class provided by System to start the environment (system clock & config
+ * aswell as optional includes) and handles the Systemwide Database Credentials
+ */
 class system {
-    //array( array(ID, VALUE), array(ID, VALUE))
+    /**
+     * Start the System Environment. This Function sums up many things needed to
+     * be done after include of the autoload file.
+     * 
+     * Flushes given Config values
+     * Starts the internal clock.
+     * Sets Error-reporting level according to config
+     * (opt)Allows to turn off optional includes which pollute global Namespace.
+     * (opt)Register Error-Handler-DB-Writer to log System Events to the Database
+     * (opt)Register Error-Handler-JSON-Output to return Errors as JSON.
+     * 
+     * Config has following format
+     * array( array(ID, VALUE), array(ID, VALUE))
+     * For IDs @see \SYSTEM\CONFIG\config_ids
+     * Extend this class to define your own.
+     * 
+     * @param array $config Configuration Array passed upon Enviroment Start
+     * @param bool $short_exc Include Shortcut for System Log Classes in global Namespace
+     * @param bool $short_res Include Shortcut for System Result Classes in global Namespace
+     * @param bool $error_db Include Shortcut for System Log Classes in global Namespace
+     * @param bool $error_json Include Shortcut for System Log Classes in global Namespace
+     * @return null Returns null.
+     */
     public static function start($config,$short_exc=true,$short_res=true,$error_db=true,$error_json=true){
         \SYSTEM\CONFIG\config::setArray($config);
-        self::_start_time();        
-        self::_start_errorreporting();
+        \SYSTEM\time::start();        
+        \error_reporting(\SYSTEM\CONFIG\config::get(\SYSTEM\CONFIG\config_ids::SYS_CONFIG_ERRORREPORTING));
         
         if($short_exc){
-            \SYSTEM\system::include_ExceptionShortcut();} //allow ERROR() instead of \SYSTEM\LOG\ERROR()
+            require_once \SYSTEM\CONFIG\config::get(\SYSTEM\CONFIG\config_ids::SYS_CONFIG_PATH_SYSTEMPATHREL).'/log/autoload_exception_shortcut.inc';} //allow ERROR() instead of \SYSTEM\LOG\ERROR()
         if($short_res){
-            \SYSTEM\system::include_ResultShortcut();} //allow JsonResult() instead of \SYSTEM\LOG\JsonResult()
+            require_once \SYSTEM\CONFIG\config::get(\SYSTEM\CONFIG\config_ids::SYS_CONFIG_PATH_SYSTEMPATHREL).'/log/autoload_result_shortcut.inc';} //allow JsonResult() instead of \SYSTEM\LOG\JsonResult()
         if($error_db){
             \SYSTEM\system::register_errorhandler_dbwriter();} //write errors to database (must be first errorhandler to register)
         if($error_json){
             \SYSTEM\system::register_errorhandler_jsonoutput();} //print errors as json to caller (must be last errorhandler to register)
     }
-    public static function _start_time(){
-        \SYSTEM\time::start();}
-    public static function _start_errorreporting(){
-        \error_reporting(\SYSTEM\CONFIG\config::get(\SYSTEM\CONFIG\config_ids::SYS_CONFIG_ERRORREPORTING));}
-        
+    
+    /**
+     * Returns the Database Connection from System Config.
+     * Supports MYSQL and PostgreSQL
+     * 
+     * @return object Returns \SYSTEM\DB\DBInfoPG or \SYSTEM\DB\DBInfoMYS depending on configrated Database.
+     */
     public static function getSystemDBInfo(){
         if(\SYSTEM\CONFIG\config::get(\SYSTEM\CONFIG\config_ids::SYS_CONFIG_DB_TYPE) == \SYSTEM\CONFIG\config_ids::SYS_CONFIG_DB_TYPE_PG){
             return new \SYSTEM\DB\DBInfoPG( \SYSTEM\CONFIG\config::get(\SYSTEM\CONFIG\config_ids::SYS_CONFIG_DB_DBNAME),
@@ -39,18 +76,29 @@ class system {
         }
     }
     
+    /**
+     * Check if the System-Environment-Wide Database Connection is MYSQL or PostgreSQL
+     * 
+     * @return bool Returns true if Databaseconnection is PostgreSQL else false.
+     */
     public static function isSystemDbInfoPG(){
         return (\SYSTEM\CONFIG\config::get(\SYSTEM\CONFIG\config_ids::SYS_CONFIG_DB_TYPE) == \SYSTEM\CONFIG\config_ids::SYS_CONFIG_DB_TYPE_PG);}
-        
-    public static function include_ExceptionShortcut(){        
-        require_once \SYSTEM\CONFIG\config::get(\SYSTEM\CONFIG\config_ids::SYS_CONFIG_PATH_SYSTEMPATHREL).'/log/register_exception_shortcut.php';}
-    
-    public static function include_ResultShortcut(){
-        require_once \SYSTEM\CONFIG\config::get(\SYSTEM\CONFIG\config_ids::SYS_CONFIG_PATH_SYSTEMPATHREL).'/log/register_result_shortcut.php';}
     
+    /**
+     * Register the JSON Output Error Handle which will print all Errors as JSON
+     * to the caller
+     * 
+     * @return null Returns null
+     */
     public static function register_errorhandler_jsonoutput(){
         \SYSTEM\LOG\log::registerHandler('\SYSTEM\LOG\error_handler_jsonoutput');}
     
+    /**
+     * Register the Database Writer Error Handle which will write all Catched
+     * SystemExceptions to the Database
+     * 
+     * @return null Returns null
+     */
     public static function register_errorhandler_dbwriter(){        
         \SYSTEM\LOG\log::registerHandler('\SYSTEM\LOG\error_handler_dbwriter');}       
 }
\ No newline at end of file
diff --git a/system/time.php b/system/time.php
index b6002d4..6cb33f8 100644
--- a/system/time.php
+++ b/system/time.php
@@ -1,14 +1,47 @@
 <?php
+/**
+ * System - PHP Framework
+ *
+ * PHP Version 5.6
+ *
+ * @copyright   2016 Ulf Gebhardt (http://www.webcraft-media.de)
+ * @license     http://www.opensource.org/licenses/mit-license.php MIT
+ * @link        https://github.com/webcraftmedia/system
+ * @package     SYSTEM
+ */
 namespace SYSTEM;
-class time {    
+
+/**
+ * Time Class provided by System for Runtime Clock and time sting operations
+ */
+class time {
+    /** int System time - runtime clock*/
     private static $start_time;    
     
+    /**
+     * Start the Runtime Clock
+     *
+     * @return null Returns null.
+     */
     public static function start(){
         self::$start_time = microtime(true);}
-        
+    
+    /**
+     * Retrieve the Runtime Timestamp
+     *
+     * @return int Returns the Runtime Timestamp
+     */
     public static function getStartTime(){
         return self::$start_time;}
         
+    /**
+     * Calaculate the time which has passed for given timestamp.
+     * Scaling from seconds to years. Required strings from tag
+     * 'time' to be included.
+     *
+     * @param int $time Unixtimestamp to be converted
+     * @return string Returns scaled time string.
+     */
     public static function time_ago_string($time){
         $etime = time() - $time;
         if ($etime < 1){