From 0c302ab8a01e32c9ff9000817ba74d40a4a7c203 Mon Sep 17 00:00:00 2001
From: Ulf Gebhardt <ulf.gebhardt@webcraft-media.de>
Date: Wed, 8 Jun 2016 19:50:52 +0200
Subject: [PATCH] #3 docu token

---
 token/qq/SYS_SECURITY_CHANGE_EMAIL.php   | 17 +++++++-
 token/qq/SYS_SECURITY_CONFIRM_EMAIL.php  | 17 +++++++-
 token/qq/SYS_SECURITY_RESET_PASSWORD.php | 17 +++++++-
 token/qq/SYS_TOKEN_CONFIRM.php           | 14 +++++++
 token/qq/SYS_TOKEN_GET.php               | 14 +++++++
 token/qq/SYS_TOKEN_INSERT.php            | 14 +++++++
 token/token.php                          | 50 +++++++++++++++++++++++-
 token/token_change_email.php             | 35 ++++++++++++++++-
 token/token_confirm_email.php            | 35 ++++++++++++++++-
 token/token_handler.php                  | 31 +++++++++++++++
 token/token_reset_password.php           | 35 ++++++++++++++++-
 11 files changed, 268 insertions(+), 11 deletions(-)

diff --git a/token/qq/SYS_SECURITY_CHANGE_EMAIL.php b/token/qq/SYS_SECURITY_CHANGE_EMAIL.php
index 8532fa2..fcd7a52 100644
--- a/token/qq/SYS_SECURITY_CHANGE_EMAIL.php
+++ b/token/qq/SYS_SECURITY_CHANGE_EMAIL.php
@@ -1,9 +1,22 @@
 <?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 get change Email of an account
+ */
 class SYS_SECURITY_CHANGE_EMAIL extends \SYSTEM\DB\QP {
     public static function get_class(){return \get_class();}
     public static function mysql(){return 
 'UPDATE system_user SET email = ?, email_confirmed = NULL WHERE id = ?;';
     }
-}
-
+}
\ No newline at end of file
diff --git a/token/qq/SYS_SECURITY_CONFIRM_EMAIL.php b/token/qq/SYS_SECURITY_CONFIRM_EMAIL.php
index 7cee986..1aebf77 100644
--- a/token/qq/SYS_SECURITY_CONFIRM_EMAIL.php
+++ b/token/qq/SYS_SECURITY_CONFIRM_EMAIL.php
@@ -1,9 +1,22 @@
 <?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 get confirm Email of an account
+ */
 class SYS_SECURITY_CONFIRM_EMAIL extends \SYSTEM\DB\QP {
     public static function get_class(){return \get_class();}
     public static function mysql(){return 
 'UPDATE system_user SET email_confirmed = 1 WHERE id = ?;';
     }
-}
-
+}
\ No newline at end of file
diff --git a/token/qq/SYS_SECURITY_RESET_PASSWORD.php b/token/qq/SYS_SECURITY_RESET_PASSWORD.php
index f1803d1..4e44a25 100644
--- a/token/qq/SYS_SECURITY_RESET_PASSWORD.php
+++ b/token/qq/SYS_SECURITY_RESET_PASSWORD.php
@@ -1,9 +1,22 @@
 <?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 reset Password of an account
+ */
 class SYS_SECURITY_RESET_PASSWORD extends \SYSTEM\DB\QP {
     public static function get_class(){return \get_class();}
     public static function mysql(){return 
 'UPDATE system_user SET password_sha1 = ? WHERE id = ?;';
     }
-}
-
+}
\ No newline at end of file
diff --git a/token/qq/SYS_TOKEN_CONFIRM.php b/token/qq/SYS_TOKEN_CONFIRM.php
index 4cc7405..adc1295 100644
--- a/token/qq/SYS_TOKEN_CONFIRM.php
+++ b/token/qq/SYS_TOKEN_CONFIRM.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 confirm a token and make it invalid
+ */
 class SYS_TOKEN_CONFIRM extends \SYSTEM\DB\QP {
     public static function get_class(){return \get_class();}
     public static function mysql(){return
diff --git a/token/qq/SYS_TOKEN_GET.php b/token/qq/SYS_TOKEN_GET.php
index ce285f9..9c774ea 100644
--- a/token/qq/SYS_TOKEN_GET.php
+++ b/token/qq/SYS_TOKEN_GET.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 get a token
+ */
 class SYS_TOKEN_GET extends \SYSTEM\DB\QP {
     public static function get_class(){return \get_class();}
     public static function mysql(){return
diff --git a/token/qq/SYS_TOKEN_INSERT.php b/token/qq/SYS_TOKEN_INSERT.php
index 2e62512..9df4457 100644
--- a/token/qq/SYS_TOKEN_INSERT.php
+++ b/token/qq/SYS_TOKEN_INSERT.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 insert a token
+ */
 class SYS_TOKEN_INSERT extends \SYSTEM\DB\QP {
     public static function get_class(){return \get_class();}
     public static function mysql(){return
diff --git a/token/token.php b/token/token.php
index 8adb948..13eeba3 100644
--- a/token/token.php
+++ b/token/token.php
@@ -1,9 +1,29 @@
 <?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\TOKEN
+ */
 namespace SYSTEM\TOKEN;
 
+/**
+ * Token Class provided by System to provide unique security tokens.
+ */
 class token{
+    /** array Variable to store all registred token handlers*/
     private static $type_handlers = array(); 
 
+    /**
+     * Check if given class is a valid token handler
+     *
+     * @param string $handler Token_handler Class
+     * @return bool Returns true or false.
+     */
     private static function check_handler($handler){
         if( !\class_exists($handler) ||
             !\is_array($parents = \class_parents($handler)) ||
@@ -11,11 +31,24 @@ class token{
             return false;}
         return true;}   
 
+    /**
+     * Register given class as token_handler
+     *
+     * @param string $class Token_handler Class
+     * @return null Returns null.
+     */
     public static function register($class){
         if(!self::check_handler($class)){
             throw new \SYSTEM\LOG\ERROR('Problem with your Token class: '.$class.'; it might not be available or inherits from the wrong class!');}
         array_push(self::$type_handlers,$class);}
     
+    /**
+     * Request a token
+     *
+     * @param string $class Token_handler Class
+     * @param array $data Data sved to Database for the token_handler on confirm
+     * @return string Returns token string.
+     */
     public static function request($class,$data=array()){
         if(!\in_array($class, self::$type_handlers)){
             throw new \SYSTEM\LOG\ERROR("Token_handler class not known to Token class. Please register it first.");}
@@ -27,6 +60,13 @@ class token{
                                                         \SYSTEM\SECURITY\security::isLoggedIn() ? \SYSTEM\SECURITY\security::getUser()->id : null));
         return $token;
     }
+    
+    /**
+     * Confirm a token
+     *
+     * @param string $token Token string
+     * @return bool Returns true or false or throws an error depending on success.
+     */
     public static function confirm($token){
         $res = self::get($token);
         if(!$res){
@@ -37,9 +77,15 @@ class token{
             throw new \SYSTEM\LOG\ERROR('Token_handler class not known to Token class. Please register it first.');}
         if(!\call_user_func_array(array($res['class'], 'confirm'),array($res))){
             throw new \SYSTEM\LOG\ERROR('Token_handler rejected Token.');}
-        return \SYSTEM\SQL\SYS_TOKEN_CONFIRM::QI(array( \SYSTEM\SECURITY\security::isLoggedIn() ? \SYSTEM\SECURITY\security::getUser()->id : null,
-                                                        $token));
+        return \SYSTEM\SQL\SYS_TOKEN_CONFIRM::QI(array( \SYSTEM\SECURITY\security::isLoggedIn() ? \SYSTEM\SECURITY\security::getUser()->id : null, $token));
     }
+    
+    /**
+     * Get a existing token from db
+     *
+     * @param string $token Token string
+     * @return array Returns database entry for the given Token if it exists.
+     */
     public static function get($token){
         return \SYSTEM\SQL\SYS_TOKEN_GET::Q1(array($token));}
 }
\ No newline at end of file
diff --git a/token/token_change_email.php b/token/token_change_email.php
index b51d70b..0fab731 100644
--- a/token/token_change_email.php
+++ b/token/token_change_email.php
@@ -1,11 +1,44 @@
 <?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\TOKEN
+ */
 namespace SYSTEM\TOKEN;
+
+/**
+ * Email Change Token handler Class provided by System to provide a email-change mechanism.
+ */
 class token_change_email extends token_handler{
+    /**
+     * Generate the Token
+     *
+     * @return string Returns token string.
+     */
     public static function token(){
         return sha1(time().rand(0, 3000));}
+    
+    /**
+     * Expiredate when the Token expires (12h)
+     *
+     * @return int Returns unixtimestamp when the token expires.
+     */
     public static function expire(){
         return time() + (60 * 60 * 12);}
+        
+    /**
+     * Token confirm processing for the token_handler.
+     * Changes Email of an account if successful
+     *
+     * @param array Token data from db
+     * @return bool Returns true or false.
+     */
     public static function confirm($token_data){
         $data = \json_decode($token_data['data'],true);
         return \SYSTEM\SQL\SYS_SECURITY_CHANGE_EMAIL::QI(array($data['email'],$data['user'])) ? true : false;}
-}
+}
\ No newline at end of file
diff --git a/token/token_confirm_email.php b/token/token_confirm_email.php
index 9f7a49e..4dde5a9 100644
--- a/token/token_confirm_email.php
+++ b/token/token_confirm_email.php
@@ -1,11 +1,44 @@
 <?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\TOKEN
+ */
 namespace SYSTEM\TOKEN;
+
+/**
+ * Confirm Email Token handler Class provided by System to provide a email-confirmation mechanism.
+ */
 class token_confirm_email extends token_handler{
+    /**
+     * Generate the Token
+     *
+     * @return string Returns token string.
+     */
     public static function token(){
         return sha1(time().rand(0, 1000));}
+        
+    /**
+     * Expiredate when the Token expires (3d)
+     *
+     * @return int Returns unixtimestamp when the token expires.
+     */
     public static function expire(){
         return time() + (60 * 60 * 24 * 3);}
+        
+    /**
+     * Token confirm processing for the token_handler.
+     * Confirms Email of an account if successful
+     *
+     * @param array Token data from db
+     * @return bool Returns true or false.
+     */
     public static function confirm($token_data){
         $data = \json_decode($token_data['data'],true);
         return \SYSTEM\SQL\SYS_SECURITY_CONFIRM_EMAIL::QI(array($data['user'])) ? true : false;}
-}
+}
\ No newline at end of file
diff --git a/token/token_handler.php b/token/token_handler.php
index 1bdd1f2..205dc9b 100644
--- a/token/token_handler.php
+++ b/token/token_handler.php
@@ -1,8 +1,39 @@
 <?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\TOKEN
+ */
 namespace SYSTEM\TOKEN;
 
+/**
+ * Abstract token_handler Class provided by System to provide API for any token mechanism.
+ */
 abstract class token_handler {
+    /**
+     * Generate the Token
+     *
+     * @return string Returns token string.
+     */
     abstract public static function token();
+    
+    /**
+     * Expiredate when the Token expires
+     *
+     * @return int Returns unixtimestamp when the token expires.
+     */
     abstract public static function expire();
+    
+    /**
+     * Token confirm processing for the token_handler
+     *
+     * @param array Token data from db
+     * @return bool Returns true or false.
+     */
     abstract public static function confirm($token_data);
 }
\ No newline at end of file
diff --git a/token/token_reset_password.php b/token/token_reset_password.php
index f62183b..39da0e3 100644
--- a/token/token_reset_password.php
+++ b/token/token_reset_password.php
@@ -1,11 +1,44 @@
 <?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\TOKEN
+ */
 namespace SYSTEM\TOKEN;
+
+/**
+ * Reset Password Token handler Class provided by System to provide a reset-password mechanism.
+ */
 class token_reset_password extends token_handler{
+    /**
+     * Generate the Token
+     *
+     * @return string Returns token string.
+     */
     public static function token(){
         return sha1(time().rand(0, 2000));}
+        
+    /**
+     * Expiredate when the Token expires (1h)
+     *
+     * @return int Returns unixtimestamp when the token expires.
+     */
     public static function expire(){
         return time() + (60 * 60 * 1);}
+        
+    /**
+     * Token confirm processing for the token_handler.
+     * Changes the password of an account if successful
+     *
+     * @param array Token data from db
+     * @return bool Returns true or false.
+     */
     public static function confirm($token_data){
         $data = \json_decode($token_data['data'],true);
         return \SYSTEM\SQL\SYS_SECURITY_RESET_PASSWORD::QI(array($data['pw_sha1'],$data['user'])) ? true : false;}
-}
+}
\ No newline at end of file