From 0a36d3144fdc52bbd762b2dfdaa0f2b29446cec3 Mon Sep 17 00:00:00 2001
From: Ulf Gebhardt <ulf.gebhardt@webcraft-media.de>
Date: Mon, 6 Jun 2016 12:14:45 +0200
Subject: [PATCH] #3 code documentation cache

---
 api/qq/SYS_API_TREE.php           |  2 +-
 cache/cache.php                   | 46 +++++++++++++++++++++++++++---
 cache/cache_css.php               | 45 +++++++++++++++++++++++++++++
 cache/cache_filemask.php          | 41 +++++++++++++++++++++++++--
 cache/cache_js.php                | 45 +++++++++++++++++++++++++++++
 cache/cache_scss.php              | 47 +++++++++++++++++++++++++++++--
 cache/qq/SYS_CACHE_CHECK.php      | 14 +++++++++
 cache/qq/SYS_CACHE_DELETE.php     | 14 +++++++++
 cache/qq/SYS_CACHE_DELETE_ALL.php | 14 +++++++++
 cache/qq/SYS_CACHE_PUT.php        | 14 +++++++++
 10 files changed, 273 insertions(+), 9 deletions(-)

diff --git a/api/qq/SYS_API_TREE.php b/api/qq/SYS_API_TREE.php
index 9e649be..64cce47 100644
--- a/api/qq/SYS_API_TREE.php
+++ b/api/qq/SYS_API_TREE.php
@@ -12,7 +12,7 @@
 namespace SYSTEM\SQL;
 
 /**
- * SQL to get System Api Tree by group
+ * QQ to get System Api Tree by group
  */
 class SYS_API_TREE extends \SYSTEM\DB\QP {
     public static function get_class(){return \get_class();}
diff --git a/cache/cache.php b/cache/cache.php
index eaab588..4eecbca 100644
--- a/cache/cache.php
+++ b/cache/cache.php
@@ -1,6 +1,28 @@
 <?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_cache
+ */
 namespace SYSTEM\CACHE;
-class cache {    
+
+/**
+ * Cache Class provided by System for caching in the Database.
+ */
+class cache {
+    /**
+     * Get Data from Cache
+     *
+     * @param int $cache Cache Group to query
+     * @param sha1 $ident String Identifier for the cached Content
+     * @param bool $header Send Header
+     * @return mixed Returns the requested Cache Content or NULL
+     */
     public static function get($cache, $ident,$header = false){
         $result = \SYSTEM\SQL\SYS_CACHE_CHECK::Q1(array($cache,$ident));
         if(!$result){
@@ -14,16 +36,32 @@ class cache {
         return $result['cache'] == \SYSTEM\CACHE\cache_filemask::CACHE_FILEMASK ? \file_get_contents($result['data']) : $result['data'];
     }
     
+    /**
+     * Put Data into the Cache
+     *
+     * @param int $cache Cache Group to put Data to
+     * @param sha1 $ident String Identifier for the Content
+     * @param string $type String representing the Header-Type which will be sent with the content eg. JS for javascript
+     * @param string $data Content to be cached
+     * @param bool $fail_on_exist Fail on existing record
+     * @return mixed Returns the cached Content or NULL
+     */
     public static function put($cache, $ident, $type, $data, $fail_on_exist = false){        
         if(($fail_on_exist && self::get($cache,$ident) != NULL)){
-            return false;}
+            return NULL;}
 
         $result = \SYSTEM\SQL\SYS_CACHE_PUT::Q1(array($cache,$ident, $type, $data));                
         return $result ? $data : NULL;
     }
     
+    /**
+     * Delete Data from Cache
+     *
+     * @param int $cache Cache Group to delete Data from
+     * @param sha1 $ident String Identifier for the Content
+     * @return bool Returns boolean if successful or not
+     */
     public static function del($cache, $ident){
         $result = \SYSTEM\SQL\SYS_CACHE_DELETE::Q1(array($cache,$ident));                
-        return $result ? true : false;                                                          
-    }
+        return $result ? true : false;}
 }
\ No newline at end of file
diff --git a/cache/cache_css.php b/cache/cache_css.php
index 724990b..1d98e4f 100644
--- a/cache/cache_css.php
+++ b/cache/cache_css.php
@@ -1,17 +1,62 @@
 <?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_cache
+ */
 namespace SYSTEM\CACHE;
+
+/**
+ * CSS Cache Class provided by System for caching CSS in the Database.
+ */
 class cache_css {
+    /** int Cache ID for CSS cache */
     const CACHE_CSS = 10;
+    
+    /**
+     * Put Data into the Cache
+     *
+     * @param sha1 $ident String Identifier for the cached Content
+     * @param int $data Data to cache
+     * @return mixed Returns the cached Cache Content or NULL
+     */
     public static function put($ident,$data){
         return \SYSTEM\CACHE\cache::put(self::CACHE_CSS, $ident, 'CSS', $data);}
+        
+    /**
+     * Get Data from Cache
+     *
+     * @param sha1 $ident String Identifier for the cached Content
+     * @param bool $header Send Header
+     * @return mixed Returns the requested Cache Content or NULL
+     */
     public static function get($ident,$header = false){
         return \SYSTEM\CACHE\cache::get(self::CACHE_CSS, $ident,$header);}
+    
+    /**
+     * Calculate Ident for a list of Files
+     *
+     * @param array $files List of Files to be cached into one Cacheentry
+     * @return sha1 Returns the requested Ident
+     */
     public static function ident($files){
         $ident = '';
         foreach($files as $f){
             $ident .= $f->SERVERPATH().';';}
         return sha1($ident);
     }
+        
+    /**
+     * Calculate URL for a list of Files
+     *
+     * @param array $files List of Files to be cached into one Cacheentry
+     * @return url Returns the requested Cache-URL
+     */
     public static function url($files){
         $ident = self::ident($files);
         if(!\SYSTEM\CACHE\cache_css::get($ident)){
diff --git a/cache/cache_filemask.php b/cache/cache_filemask.php
index e9c08c9..2b402e9 100644
--- a/cache/cache_filemask.php
+++ b/cache/cache_filemask.php
@@ -1,14 +1,51 @@
 <?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_cache
+ */
 namespace SYSTEM\CACHE;
+
+/**
+ * File Cache Class provided by System for hiding Filepaths on the Server.
+ */
 class cache_filemask {
+    /** int Cache ID for Filemask cache */
     const CACHE_FILEMASK = 12;
+    
+    /**
+     * Put Data into the Cache
+     * Remark: Saves only the path into the Cache, not the File itself
+     *
+     * @param sha1 $file String Filepath of Content
+     * @return mixed Returns the cached Cache Content or NULL
+     */
     public static function put($file){
         $ext = pathinfo($file);
         $ext = strtoupper(array_key_exists('extension', $ext) ? $ext['extension'] : '');
         return \SYSTEM\CACHE\cache::put(self::CACHE_FILEMASK, self::ident($file), $ext ,$file);}
+        
+    /**
+     * Get Data from Cache
+     *
+     * @param sha1 $ident String Identifier for the cached Content
+     * @param bool $header Send Header
+     * @return mixed Returns the requested Cache Content or NULL
+     */
     public static function get($ident,$header = false){
         return \SYSTEM\CACHE\cache::get(self::CACHE_FILEMASK, $ident,$header);}
+        
+    /**
+     * Calculate Ident for a File
+     *
+     * @param array $file Filepath to be cached
+     * @return sha1 Returns the requested Ident
+     */
     public static function ident($file){
-        return sha1($file);
-    }
+        return sha1($file);}
 }
\ No newline at end of file
diff --git a/cache/cache_js.php b/cache/cache_js.php
index a8fc211..d0405f2 100644
--- a/cache/cache_js.php
+++ b/cache/cache_js.php
@@ -1,17 +1,62 @@
 <?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_cache
+ */
 namespace SYSTEM\CACHE;
+
+/**
+ * JS Cache Class provided by System for caching JS in the Database.
+ */
 class cache_js {
+    /** int Cache ID for JS cache */
     const CACHE_JS = 11;
+    
+    /**
+     * Put Data into the Cache
+     *
+     * @param sha1 $ident String Identifier for the cached Content
+     * @param int $data Data to cache
+     * @return mixed Returns the cached Cache Content or NULL
+     */
     public static function put($ident,$data){
         return \SYSTEM\CACHE\cache::put(self::CACHE_JS, $ident, 'JS', $data);}
+        
+    /**
+     * Get Data from Cache
+     *
+     * @param sha1 $ident String Identifier for the cached Content
+     * @param bool $header Send Header
+     * @return mixed Returns the requested Cache Content or NULL
+     */
     public static function get($ident,$header = false){
         return \SYSTEM\CACHE\cache::get(self::CACHE_JS, $ident,$header);}
+        
+    /**
+     * Calculate Ident for a list of Files
+     *
+     * @param array $files List of Files to be cached into one Cacheentry
+     * @return sha1 Returns the requested Ident
+     */
     public static function ident($files){
         $ident = '';
         foreach($files as $f){
             $ident .= $f->SERVERPATH().';';}
         return sha1($ident);
     }
+    
+    /**
+     * Calculate URL for a list of Files
+     *
+     * @param array $files List of Files to be cached into one Cacheentry
+     * @return url Returns the requested Cache-URL
+     */
     public static function url($files){
         $ident = self::ident($files);
         if(!\SYSTEM\CACHE\cache_js::get($ident)){
diff --git a/cache/cache_scss.php b/cache/cache_scss.php
index d2bfd0b..e779ef2 100644
--- a/cache/cache_scss.php
+++ b/cache/cache_scss.php
@@ -1,14 +1,57 @@
 <?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_cache
+ */
 namespace SYSTEM\CACHE;
+
+/**
+ * SCSS Cache Class provided by System for compiling and caching SCSS in the Database.
+ */
 class cache_scss {
+    /** int Cache ID for SCSS cache */
     const CACHE_SCSS = 1;
+    
+    /**
+     * Put Data into the Cache
+     *
+     * @param sha1 $file Filepath of the Content
+     * @param int $data Data to cache
+     * @return mixed Returns the cached Cache Content or NULL
+     */
     public static function put($file,$data){
         return \SYSTEM\CACHE\cache::put(self::CACHE_SCSS, self::ident($file), 'CSS', $data);}
+        
+    /**
+     * Get Data from Cache
+     *
+     * @param sha1 $file Filepath for the cached Content
+     * @param bool $header Send Header
+     * @return mixed Returns the requested Cache Content or NULL
+     */
     public static function get($file,$header = false){
         return \SYSTEM\CACHE\cache::get(self::CACHE_SCSS,  self::ident($file),$header);}
+    /**
+     * Calculate Ident for a File
+     *
+     * @param string $file Filepath to be cached
+     * @return sha1 Returns the requested Ident
+     */
     public static function ident($file){
-        return sha1($file.';'.filemtime($file));
-    }
+        return sha1($file.';'.filemtime($file));}
+        
+    /**
+     * Calculate URL for a File
+     *
+     * @param array $file Filepath to be cached
+     * @return url Returns the requested Cache-URL
+     */
     public static function url($file){
         if(!\SYSTEM\CACHE\cache_scss::get($file->SERVERPATH())){
             \LIB\lib_scssphp::php();
diff --git a/cache/qq/SYS_CACHE_CHECK.php b/cache/qq/SYS_CACHE_CHECK.php
index c7d68c8..a0cd5ac 100644
--- a/cache/qq/SYS_CACHE_CHECK.php
+++ b/cache/qq/SYS_CACHE_CHECK.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 check if cache entry exists
+ */
 class SYS_CACHE_CHECK extends \SYSTEM\DB\QP {
     public static function get_class(){return \get_class();}
     public static function pgsql(){return          
diff --git a/cache/qq/SYS_CACHE_DELETE.php b/cache/qq/SYS_CACHE_DELETE.php
index e3eb320..a11c7e9 100644
--- a/cache/qq/SYS_CACHE_DELETE.php
+++ b/cache/qq/SYS_CACHE_DELETE.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 delete cache entry
+ */
 class SYS_CACHE_DELETE extends \SYSTEM\DB\QP {
     public static function get_class(){return \get_class();}
     public static function pgsql(){return           
diff --git a/cache/qq/SYS_CACHE_DELETE_ALL.php b/cache/qq/SYS_CACHE_DELETE_ALL.php
index 53c0dec..177625f 100644
--- a/cache/qq/SYS_CACHE_DELETE_ALL.php
+++ b/cache/qq/SYS_CACHE_DELETE_ALL.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 delete all cache entries
+ */
 class SYS_CACHE_DELETE_ALL extends \SYSTEM\DB\QQ {
     public static function get_class(){return \get_class();}
     public static function pgsql(){return
diff --git a/cache/qq/SYS_CACHE_PUT.php b/cache/qq/SYS_CACHE_PUT.php
index 5d7683c..d681e04 100644
--- a/cache/qq/SYS_CACHE_PUT.php
+++ b/cache/qq/SYS_CACHE_PUT.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 write data into the cache
+ */
 class SYS_CACHE_PUT extends \SYSTEM\DB\QP {
     public static function get_class(){return \get_class();}
     public static function pgsql(){return