framework/main/classes/database/class_BaseDatabaseWrapper.php

   1 <?php
   2 // Own namespace
   3 namespace CoreFramework\Database\Wrapper;
   4
   5 // Import framework stuff
   6 use CoreFramework\Criteria\Criteria;
   7 use CoreFramework\Criteria\Storing\StoreableCriteria;
   8 use CoreFramework\Database\Backend\BaseDatabaseBackend;
   9 use CoreFramework\Factory\ObjectFactory;
  10 use CoreFramework\Object\BaseFrameworkSystem;
  11
  12 /**
  13  * A generic database wrapper
  14  *
  15  * @author              Roland Haeder <webmaster@shipsimu.org>
  16  * @version             0.0.0
  17  * @copyright   Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2017 Core Developer Team
  18  * @license             GNU GPL 3.0 or any newer version
  19  * @link                http://www.shipsimu.org
  20  *
  21  * This program is free software: you can redistribute it and/or modify
  22  * it under the terms of the GNU General Public License as published by
  23  * the Free Software Foundation, either version 3 of the License, or
  24  * (at your option) any later version.
  25  *
  26  * This program is distributed in the hope that it will be useful,
  27  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  28  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  29  * GNU General Public License for more details.
  30  *
  31  * You should have received a copy of the GNU General Public License
  32  * along with this program. If not, see <http://www.gnu.org/licenses/>.
  33  */
  34 class BaseDatabaseWrapper extends BaseFrameworkSystem {
  35         /**
  36          * Cache instance
  37          */
  38         private $cacheInstance = NULL;
  39
  40         /**
  41          * Current table name to use
  42          */
  43         private $tableName = 'unknown';
  44
  45         /**
  46          * Protected constructor
  47          *
  48          * @return      void
  49          */
  50         protected function __construct ($class) {
  51                 // Call parent constructor
  52                 parent::__construct($class);
  53
  54                 // Initialize the cache instance
  55                 $this->initCacheInstance();
  56         }
  57
  58         /**
  59          * Initializes the cache instance with a new object
  60          *
  61          * @return      void
  62          */
  63         private final function initCacheInstance () {
  64                 // Is the cache enabled?
  65                 if ($this->getConfigInstance()->getConfigEntry('database_cache_enabled') === TRUE) {
  66                         // Set the new instance
  67                         $this->cacheInstance = CacheFactory::getFactory()->createConfiguredCache();
  68                 } // END - if
  69         }
  70
  71         /**
  72          * Setter for table name
  73          *
  74          * @param       $tableName      Name of table name to set
  75          * @return      void
  76          */
  77         protected final function setTableName ($tableName) {
  78                 $this->tableName = (string) $tableName;
  79         }
  80
  81         /**
  82          * Getter for table name
  83          *
  84          * @return      $tableName      Name of table name to set
  85          */
  86         protected final function getTableName () {
  87                 return $this->tableName;
  88         }
  89
  90         /**
  91          * 'Inserts' a data set instance into a local file database folder
  92          *
  93          * @param       $dataSetInstance        A storeable data set
  94          * @param       $onlyKeys                       Only use these keys for a cache key
  95          * @return      void
  96          */
  97         protected function queryInsertDataSet (StoreableCriteria $dataSetInstance, array $onlyKeys = array()) {
  98                 // Default cache key is NULL
  99                 $cacheKey = NULL;
 100
 101                 // Is cache enabled?
 102                 if ($this->getConfigInstance()->getConfigEntry('database_cache_enabled') === TRUE) {
 103                         // First get a key suitable for our cache and extend it with this class name
 104                         $cacheKey = $this->getCacheKeyByCriteria($dataSetInstance, $onlyKeys);
 105                         //* DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-WRAPPER: Using cache key ' . $cacheKey . ' for purging ...');
 106                 } // END - if
 107
 108                 // Does this key exists in cache?
 109                 if (($this->getConfigInstance()->getConfigEntry('database_cache_enabled') === TRUE) && ($this->cacheInstance->offsetExists($cacheKey))) {
 110                         // Purge the cache
 111                         $this->cacheInstance->purgeOffset($cacheKey);
 112                 } // END - if
 113
 114                 // Handle it over to the middleware
 115                 $this->getDatabaseInstance()->queryInsertDataSet($dataSetInstance);
 116         }
 117
 118         /**
 119          * 'Updates' a data set instance with a database layer
 120          *
 121          * @param       $dataSetInstance        A storeable data set
 122          * @param       $onlyKeys                       Only use these keys for a cache key
 123          * @return      void
 124          */
 125         protected function queryUpdateDataSet (StoreableCriteria $dataSetInstance, array $onlyKeys = array()) {
 126                 // Init cache key
 127                 $cacheKey = NULL;
 128
 129                 // Is cache enabled?
 130                 if ($this->getConfigInstance()->getConfigEntry('database_cache_enabled') === TRUE) {
 131                         // First get a key suitable for our cache and extend it with this class name
 132                         $cacheKey = $this->getCacheKeyByCriteria($dataSetInstance, $onlyKeys);
 133                         //* DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-WRAPPER: Using cache key ' . $cacheKey . ' for purging ...');
 134                 } // END - if
 135
 136                 // Does this key exists in cache?
 137                 if (($this->getConfigInstance()->getConfigEntry('database_cache_enabled') === TRUE) && ($this->cacheInstance->offsetExists($cacheKey))) {
 138                         // Purge the cache
 139                         $this->cacheInstance->purgeOffset($cacheKey);
 140                 } // END - if
 141
 142                 // Handle it over to the middleware
 143                 $this->getDatabaseInstance()->queryUpdateDataSet($dataSetInstance);
 144         }
 145
 146         /**
 147          * Getter for index key
 148          *
 149          * @return      $indexKey       Index key
 150          */
 151         public final function getIndexKey () {
 152                 return $this->getDatabaseInstance()->getIndexKey();
 153         }
 154
 155         /**
 156          * Getter for last exception
 157          *
 158          * @return      $lastException  Last exception or NULL if none occured
 159          */
 160         public final function getLastException () {
 161                 return $this->getDatabaseInstance()->getLastException();
 162         }
 163
 164         /**
 165          * Do a "select" query on the current table with the given search criteria and
 166          * store it in cache for later usage
 167          *
 168          * @param       $criteriaInstance       An instance of a Criteria class
 169          * @param       $onlyKeys                       Only use these keys for a cache key
 170          * @return      $resultInstance         An instance of a database result class
 171          */
 172         public function doSelectByCriteria (Criteria $criteriaInstance, array $onlyKeys = array()) {
 173                 // Default cache key if cache is not enabled
 174                 $cacheKey = NULL;
 175
 176                 // Is the cache enabled?
 177                 if ($this->getConfigInstance()->getConfigEntry('database_cache_enabled') === TRUE) {
 178                         // First get a key suitable for our cache and extend it with this class name
 179                         $cacheKey = $this->getCacheKeyByCriteria($criteriaInstance, $onlyKeys);
 180                 } // END - if
 181
 182                 // Does this key exists in cache?
 183                 if (($this->getConfigInstance()->getConfigEntry('database_cache_enabled') === TRUE) && ($this->cacheInstance->offsetExists($cacheKey, BaseDatabaseBackend::RESULT_INDEX_ROWS, 1))) {
 184                         // Debug message
 185                         //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-WRAPPER: Cache used for cacheKey=' . $cacheKey . ':' . print_r($this->cacheInstance->offsetGet($cacheKey), TRUE));
 186
 187                         // Then use this result
 188                         $result = $this->cacheInstance->offsetGet($cacheKey);
 189                 } else {
 190                         // Debug message
 191                         //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-WRAPPER: Quering database, cacheKey=' . $cacheKey);
 192
 193                         // Now it's time to ask the database layer for this select statement
 194                         $result = $this->getDatabaseInstance()->doSelectByTableCriteria($this->getTableName(), $criteriaInstance);
 195                         //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-WRAPPER: result[]=' . gettype($result));
 196
 197                         // Cache the result if not null
 198                         if (!is_null($result)) {
 199                                 // Is cache enabled?
 200                                 if ($this->getConfigInstance()->getConfigEntry('database_cache_enabled') === TRUE) {
 201                                         // A valid result has returned from the database layer
 202                                         $this->cacheInstance->offsetSet($cacheKey, $result);
 203                                 } // END - if
 204                         } else {
 205                                 // This invalid result must be wrapped
 206                                 $result = array(
 207                                         BaseDatabaseBackend::RESULT_INDEX_STATUS    => 'invalid',
 208                                         BaseDatabaseBackend::RESULT_INDEX_EXCEPTION => $this->getDatabaseInstance()->getLastException()
 209                                 );
 210                         }
 211                 }
 212
 213                 // Create an instance of a CachedDatabaseResult class with the given result
 214                 // @TODO Minor: Update above comment to e.g. BaseDatabaseResult
 215                 $resultInstance = ObjectFactory::createObjectByConfiguredName('database_result_class', array($result));
 216
 217                 // And return the instance
 218                 return $resultInstance;
 219         }
 220
 221         /**
 222          * Count the numbers of rows we shall receive
 223          *
 224          * @param       $criteriaInstance       An instance of a Criteria class
 225          * @param       $onlyKeys                       Only use these keys for a cache key
 226          * @return      $numRows                        Numbers of rows of database entries
 227          */
 228         public function doSelectCountByCriteria (Criteria $criteriaInstance, $onlyKeys = array()) {
 229                 // Total numbers is -1 so we can distinglish between failed and valid queries
 230                 $numRows = 0;
 231
 232                 // Get the result from above method
 233                 $resultInstance = $this->doSelectByCriteria($criteriaInstance, $onlyKeys);
 234
 235                 // Was that query fine?
 236                 if ($resultInstance->ifStatusIsOkay()) {
 237                         // Then get the number of rows
 238                         $numRows = $resultInstance->getAffectedRows();
 239
 240                         // Debug message
 241                         //* DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-WRAPPER: numRows=' . $numRows);
 242                 } // END - if
 243
 244                 // Return the result
 245                 return $numRows;
 246         }
 247
 248         /**
 249          * Getter for primary key used in wrapped table
 250          *
 251          * @return      $primaryKey             Primary key used in wrapped table
 252          */
 253         public final function getPrimaryKeyValue () {
 254                 // Get the table name and a database instance and ask for it
 255                 $primaryKey = $this->getDatabaseInstance()->getPrimaryKeyOfTable($this->getTableName());
 256
 257                 // Return value
 258                 return $primaryKey;
 259         }
 260
 261         /**
 262          * Count rows of this table
 263          *
 264          * @return      $count  Count of total rows in this table
 265          */
 266         public final function countTotalRows () {
 267                 // Get the table name and a database instance and ask for it
 268                 $count = $this->getDatabaseInstance()->countTotalRows($this->getTableName());
 269
 270                 // Return value
 271                 return $count;
 272         }
 273
 274         /**
 275          * Removes non-public data from given array.
 276          *
 277          * @param       $data   An array with possible non-public data that needs to be removed.
 278          * @return      $data   A cleaned up array with only public data.
 279          */
 280         public function removeNonPublicDataFromArray (array $data) {
 281                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('WRAPPER[' . $this->__toString() . ']: Calling this->getDatabaseInstance()->removeNonPublicDataFromArray(data) ...');
 282                 $data = $this->getDatabaseInstance()->removeNonPublicDataFromArray($data);
 283
 284                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('WRAPPER[' . $this->__toString() . ']: data[]=' . gettype($data));
 285                 return $data;
 286         }
 287
 288 }