PHPDoc, a new test, and cryptographically save session handle maker

Methods that return Models from ActiveRecord and VersionedRecord will now return static[] and static which is more accurate PHPDoc notation.
Session method generateUniqueHandle is now cryptographically secure with 2^128 possible handles.
Added binary type support to SQL class.
Added a test for Session generateUniqueHandle

Author: hparadiz

src/IO/Database/SQL.php

@@ -197,6 +197,8 @@ public static function getSQLType($field)
                 return 'text';
             case 'blob':
                 return 'blob';
+            case 'binary':
+                return 'binary';
 
             case 'timestamp':
                 return 'timestamp';

src/Models/ActiveRecord.php

@@ -283,7 +283,7 @@ class ActiveRecord implements JsonSerializable
      *
      * @uses static::init
      *
-     * @return ActiveRecord Instance of the value of $this->Class
+     * @return static Instance of the value of $this->Class
      */
     public function __construct($record = [], $isDirty = false, $isPhantom = null)
     {
@@ -508,7 +508,7 @@ public static function isRelational()
      *
      * @param array $values Array of keys as fields and values.
      * @param boolean $save If the object should be immediately saved to database before being returned.
-     * @return ActiveRecord An object of this model.
+     * @return static An object of this model.
      */
     public static function create($values = [], $save = false)
     {
@@ -540,7 +540,7 @@ public function isA($class)
      *
      * @param string $className If you leave this blank the return will be $this
      * @param array $fieldValues Optional. Any field values you want to override.
-     * @return ActiveRecord A new model of a different class with this model's field's. Useful when you have similar classes or subclasses with the same parent.
+     * @return static A new model of a different class with this model's field's. Useful when you have similar classes or subclasses with the same parent.
      */
     public function changeClass($className = false, $fieldValues = false)
     {
@@ -842,7 +842,7 @@ public static function getByHandle($handle)
      * Get model object by primary key.
      *
      * @param int $id
-     * @return ActiveRecord|null
+     * @return static|null
      */
     public static function getByID($id)
     {
@@ -857,7 +857,7 @@ public static function getByID($id)
      * @param string $field Field name
      * @param string $value Field value
      * @param boolean $cacheIndex Optional. If we should cache the result or not. Default is false.
-     * @return ActiveRecord|null
+     * @return static|null
      */
     public static function getByField($field, $value, $cacheIndex = false)
     {
@@ -896,7 +896,7 @@ public static function getRecordByField($field, $value, $cacheIndex = false)
      *
      * @param array|string $conditions If passed as a string a database Where clause. If an array of field/value pairs will convert to a series of `field`='value' conditions joined with an AND operator.
      * @param array|string $options Only takes 'order' option. A raw database string that will be inserted into the OR clause of the query or an array of field/direction pairs.
-     * @return ActiveRecord|null Single model instantiated from the first database result
+     * @return static|null Single model instantiated from the first database result
      */
     public static function getByWhere($conditions, $options = [])
     {
@@ -944,7 +944,7 @@ public static function getRecordByWhere($conditions, $options = [])
      *
      * @param string $query Database query. The passed in string will be passed through vsprintf or sprintf with $params.
      * @param array|string $params If an array will be passed through vsprintf as the second parameter with the query as the first. If a string will be used with sprintf instead. If nothing provided you must provide your own query.
-     * @return ActiveRecord|null Single model instantiated from the first database result
+     * @return static|null Single model instantiated from the first database result
      */
     public static function getByQuery($query, $params = [])
     {
@@ -956,7 +956,7 @@ public static function getByQuery($query, $params = [])
      *
      * @param boolean $className The full name of the class including namespace. Optional. Will use the name of the current class if none provided.
      * @param array $options
-     * @return ActiveRecord[]|null Array of instantiated ActiveRecord models returned from the database result.
+     * @return static[]|null Array of instantiated ActiveRecord models returned from the database result.
      */
     public static function getAllByClass($className = false, $options = [])
     {
@@ -968,7 +968,7 @@ public static function getAllByClass($className = false, $options = [])
      *
      * @param ActiveRecord $Record
      * @param array $options
-     * @return ActiveRecord[]|null Array of instantiated ActiveRecord models returned from the database result.
+     * @return static[]|null Array of instantiated ActiveRecord models returned from the database result.
      */
     public static function getAllByContextObject(ActiveRecord $Record, $options = [])
     {
@@ -998,7 +998,7 @@ public static function getAllByContext($contextClass, $contextID, $options = [])
      * @param string $field Field name
      * @param string $value Field value
      * @param array $options
-     * @return ActiveRecord[]|null Array of models instantiated from the database result.
+     * @return static[]|null Array of models instantiated from the database result.
      */
     public static function getAllByField($field, $value, $options = [])
     {
@@ -1010,7 +1010,7 @@ public static function getAllByField($field, $value, $options = [])
      *
      * @param array|string $conditions If passed as a string a database Where clause. If an array of field/value pairs will convert to a series of `field`='value' conditions joined with an AND operator.
      * @param array|string $options
-     * @return ActiveRecord[]|null Array of models instantiated from the database result.
+     * @return static[]|null Array of models instantiated from the database result.
      */
     public static function getAllByWhere($conditions = [], $options = [])
     {
@@ -1113,7 +1113,7 @@ public static function getAllRecordsByWhere($conditions = [], $options = [])
      * Attempts to get all database records for this class and return them as an array of instantiated models.
      *
      * @param array $options
-     * @return ActiveRecord[]|null
+     * @return static[]|null
      */
     public static function getAll($options = [])
     {
@@ -1161,7 +1161,7 @@ public static function getAllRecords($options = [])
      *
      * @param string $query Database query. The passed in string will be passed through vsprintf or sprintf with $params.
      * @param array|string $params If an array will be passed through vsprintf as the second parameter with the query as the first. If a string will be used with sprintf instead. If nothing provided you must provide your own query.
-     * @return ActiveRecord[]|null Array of models instantiated from the first database result
+     * @return static[]|null Array of models instantiated from the first database result
      */
     public static function getAllByQuery($query, $params = [])
     {
@@ -1178,7 +1178,7 @@ public static function getTableByQuery($keyField, $query, $params = [])
      * Converts database record array to a model. Will attempt to use the record's Class field value to as the class to instantiate as or the name of this class if none is provided.
      *
      * @param array $record Database row as an array.
-     * @return ActiveRecord|null An instantiated ActiveRecord model from the provided data.
+     * @return static|null An instantiated ActiveRecord model from the provided data.
      */
     public static function instantiateRecord($record)
     {
@@ -1190,7 +1190,7 @@ public static function instantiateRecord($record)
      * Converts an array of database records to a model corresponding to each record. Will attempt to use the record's Class field value to as the class to instantiate as or the name of this class if none is provided.
      *
      * @param array $record An array of database rows.
-     * @return ActiveRecord|null An array of instantiated ActiveRecord models from the provided data.
+     * @return static|null An array of instantiated ActiveRecord models from the provided data.
      */
     public static function instantiateRecords($records)
     {

src/Models/Auth/Session.php

@@ -17,9 +17,11 @@
  * Session object
  *
  * @author Henry Paradiz <henry.paradiz@gmail.com>
- * @author  Chris Alfano <themightychris@gmail.com>
- *
- * {@inheritDoc}
+ * @author Chris Alfano <themightychris@gmail.com>
+ * @inheritDoc
+ * @property string $Handle Unique identifier for this session used by the cookie.
+ * @property string $LastRequest Timestamp of the last time this session was updated.
+ * @property string $Binary Actually raw binary in the string
  */
 class Session extends Model
 {
@@ -59,18 +61,13 @@ class Session extends Model
     ];
 
 
-    // Session
-    public static function __classLoaded()
-    {
-        parent::__classLoaded();
-
-        // auto-detect cookie domain
-        if (empty(static::$cookieDomain)) {
-            static::$cookieDomain = preg_replace('/^www\.([^.]+\.[^.]+)$/i', '$1', $_SERVER['HTTP_HOST']);
-        }
-    }
-
-
+    /**
+     * Gets or sets up a session based on current cookies.
+     * Will always update the current session's LastIP and LastRequest fields.
+     *
+     * @param boolean $create
+     * @return static|false
+     */
     public static function getFromRequest($create = true)
     {
         $sessionData = [
@@ -129,6 +126,12 @@ public static function updateSession(Session $Session, $sessionData)
         }
     }
 
+    /**
+     * Gets by handle.
+     *
+     * @param string $handle
+     * @return static
+     */
     public static function getByHandle($handle)
     {
         return static::getByField('Handle', $handle, true);
@@ -142,6 +145,15 @@ public function getData()
         ]);
     }
 
+    /**
+     * @inheritDoc
+     *
+     * Saves the session to the database and sets the session cookie.
+     * Will generate a unique handle for the session if none exists.
+     *
+     * @param boolean $deep
+     * @return void
+     */
     public function save($deep = true)
     {
         // set handle
@@ -163,6 +175,13 @@ public function save($deep = true)
         );
     }
 
+    /**
+     * Attempts to unset the cookie.
+     * Unsets the variable from the $_COOKIE global.
+     * Deletes session from database.
+     *
+     * @return void
+     */
     public function terminate()
     {
         setcookie(static::$cookieName, '', time() - 3600);
@@ -173,11 +192,20 @@ public function terminate()
 
 
 
+    /**
+     * Makes a random 32 digit string by generating 16 random bytes
+     * Is cryptographically secure.
+     * @see http://php.net/manual/en/function.random-bytes.php
+     *
+     * @return void
+     */
     public static function generateUniqueHandle()
     {
         do {
-            $handle = md5(mt_rand(0, mt_getrandmax()));
+            $handle = bin2hex(random_bytes(16));
         } while (static::getByHandle($handle));
+        // just in case checks if the handle exists in the database and if it does makes a new one.
+        // chance of happening is 1 in 2^128 though so might want to remove the database call
 
         return $handle;
     }

src/Models/Media/Media.php

@@ -34,11 +34,6 @@ class Media extends Model
     public static $subClasses = [__CLASS__, Image::class, PDF::class, Video::class, Audio::class];
     public static $collectionRoute = '/media';
 
-    // get rid of these??
-    public static $Namespaces = [];
-    public static $Types = [];
-
-
     public static $tableName = 'media';
 
     public static $fields = [

src/Models/Versioning.php

@@ -19,7 +19,9 @@
  *
  * @package Divergence
  * @author  Henry Paradiz <henry.paradiz@gmail.com>
- *
+ * @inheritDoc
+ * @property int $RevisionID ID of revision in the history table.
+ * @property static[] $History All revisions for this object. This is hooked in the Relations trait.
  */
 trait Versioning
 {
@@ -33,39 +35,62 @@ trait Versioning
             'notnull' => false,
         ],
     ];
-    
+
     public static $versioningRelationships = [
         'History' => [
             'type' => 'history',
             'order' => ['RevisionID' => 'DESC'],
         ],
     ];
-    
-    
+
+    /**
+     * Returns static::$historyTable
+     *
+     * @throws Exception If static::$historyTable is not set.
+     * @return string
+     */
     public static function getHistoryTable()
     {
         if (!static::$historyTable) {
             throw new Exception('Static variable $historyTable must be defined to use model versioning.');
         }
-        
+
         return static::$historyTable;
     }
-    
-    /*
-     * Implement specialized getters
+
+    /**
+     * The history table allows multiple records with the same ID.
+     * The primary key becomes RevisionID.
+     * This returns all the revisions by ID so you will get the history of that object.
+     *
+     * @return static[] Revisions by ID
      */
     public static function getRevisionsByID($ID, $options = [])
     {
         $options['conditions'][static::getPrimaryKey()] = $ID;
-        
+
         return static::getRevisions($options);
     }
 
+    /**
+     * Gets all versions of all objects for this object.
+     *
+     * Use getRevisionsByID instead.
+     *
+     * @param array $options Query options
+     * @return static[] Revisions
+     */
     public static function getRevisions($options = [])
     {
         return static::instantiateRecords(static::getRevisionRecords($options));
     }
-    
+
+    /**
+     * Gets raw revision data from the database and constructs a query
+     *
+     * @param array $options Query options
+     * @return array
+     */
     public static function getRevisionRecords($options = [])
     {
         $options = Util::prepareOptions($options, [
@@ -75,29 +100,34 @@ public static function getRevisionRecords($options = [])
             'limit' => false,
             'offset' => 0,
         ]);
-                
+
         $query = 'SELECT * FROM `%s` WHERE (%s)';
         $params = [
             static::getHistoryTable(),
             count($options['conditions']) ? join(') AND (', static::_mapConditions($options['conditions'])) : 1,
         ];
-        
+
         if ($options['order']) {
             $query .= ' ORDER BY ' . join(',', static::_mapFieldOrder($options['order']));
         }
-        
+
         if ($options['limit']) {
             $query .= sprintf(' LIMIT %u,%u', $options['offset'], $options['limit']);
         }
-        
-        
+
+
         if ($options['indexField']) {
             return DB::table(static::_cn($options['indexField']), $query, $params);
         } else {
             return DB::allRecords($query, $params);
         }
     }
 
+    /**
+     * Sets wasDirty, isDirty, Created for the object before save
+     *
+     * @return void
+     */
     public function beforeVersionedSave()
     {
         $this->wasDirty = false;
@@ -108,6 +138,11 @@ public function beforeVersionedSave()
         }
     }
 
+    /**
+     * After save to regular database this saves to the history table
+     *
+     * @return void
+     */
     public function afterVersionedSave()
     {
         if ($this->wasDirty && static::$createRevisionOnSave) {