framework/config/class_FrameworkConfiguration.php

   1 <?php
   2
   3 // Own namespace
   4 namespace Org\Mxchange\CoreFramework\Configuration;
   5
   6 // Import framework stuff
   7 use Org\Mxchange\CoreFramework\Configuration\NoConfigEntryException;
   8 use Org\Mxchange\CoreFramework\Generic\FrameworkInterface;
   9 use Org\Mxchange\CoreFramework\Generic\UnsupportedOperationException;
  10 use Org\Mxchange\CoreFramework\Object\BaseFrameworkSystem;
  11 use Org\Mxchange\CoreFramework\Registry\Registerable;
  12 use Org\Mxchange\CoreFramework\Utils\Strings\StringUtils;
  13
  14 // Import SPL stuff
  15 use \InvalidArgumentException;
  16 use \UnexpectedValueException;
  17
  18 /**
  19  * A class for the configuration stuff implemented in a singleton design pattern
  20  *
  21  * NOTE: We cannot put this in framework/main/ because it would be loaded (again) in
  22  * class loader. See framework/loader/class_ClassLoader.php for instance
  23  *
  24  * @see                 ClassLoader
  25  * @author              Roland Haeder <webmaster@shipsimu.org>
  26  * @version             1.0.1
  27  * @copyright   Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2022 Core Developer Team
  28  * @license             GNU GPL 3.0 or any newer version
  29  * @link                http://www.shipsimu.org
  30  *
  31  * This program is free software: you can redistribute it and/or modify
  32  * it under the terms of the GNU General Public License as published by
  33  * the Free Software Foundation, either version 3 of the License, or
  34  * (at your option) any later version.
  35  *
  36  * This program is distributed in the hope that it will be useful,
  37  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  38  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  39  * GNU General Public License for more details.
  40  *
  41  * You should have received a copy of the GNU General Public License
  42  * along with this program. If not, see <http://www.gnu.org/licenses/>.
  43  */
  44 class FrameworkConfiguration implements Registerable {
  45         // Some constants for the configuration system
  46         const EXCEPTION_CONFIG_KEY_IS_EMPTY = 0x130;
  47         const EXCEPTION_CONFIG_KEY_WAS_NOT_FOUND = 0x131;
  48         const EXCEPTION_CONFIG_VALUE_TYPE_UNSUPPORTED = 0x132;
  49
  50         /**
  51          * The framework's main configuration array which will be initialized with
  52          * hard-coded configuration data and might be overwritten/extended by
  53          * config data from the database.
  54          */
  55         private static $configData = [];
  56
  57         /**
  58          * Call-back instance (unused)
  59          */
  60         private $callbackInstance = NULL;
  61
  62         /**
  63          * Default constructor, the configuration entries are static, not the
  64          * whole instance.
  65          *
  66          * @return      void
  67          */
  68         public function __construct () {
  69                 // Empty for now
  70         }
  71
  72         /**
  73          * Compatiblity method to return this class' name
  74          *
  75          * @return      __CLASS__       This class' name
  76          */
  77         public function __toString () {
  78                 return get_class($this);
  79         }
  80
  81         /**
  82          * Checks whether the given configuration key is set
  83          *
  84          * @param       $configKey      The configuration key we shall check
  85          * @return      $isset  Whether the given configuration key is set
  86          * @throws      InvalidArgumentException        If $configKey is empty
  87          */
  88         public function isConfigurationEntrySet (string $configKey) {
  89                 // Is it null?
  90                 //* NOISY-DEBUG: */ printf('[%s:%d]: configKey=%s - CALLED!' . PHP_EOL, __METHOD__, __LINE__, $configKey);
  91                 if (empty($configKey)) {
  92                         // Entry is empty
  93                         throw new InvalidArgumentException('Parameter "configKey" is empty', self::EXCEPTION_CONFIG_KEY_IS_EMPTY);
  94                 }
  95
  96                 // Is it set?
  97                 $isset = ((isset(self::$configData[$configKey])) || (array_key_exists($configKey, self::$configData)));
  98
  99                 // Return the result
 100                 //* NOISY-DEBUG: */ printf('[%s:%d]: isset=%s - EXIT!' . PHP_EOL, __METHOD__, __LINE__, intval($isset));
 101                 return $isset;
 102         }
 103
 104         /**
 105          * Read a configuration element.
 106          *
 107          * @param       $configKey              The configuration element
 108          * @return      $configValue    The fetched configuration value
 109          * @throws      InvalidArgumentException        If $configKey is empty
 110          * @throws      NoConfigEntryException          If a configuration element was not found
 111          */
 112         public function getConfigEntry (string $configKey) {
 113                 // Is it null?
 114                 //* NOISY-DEBUG: */ printf('[%s:%d]: configKey=%s - CALLED!' . PHP_EOL, __METHOD__, __LINE__, $configKey);
 115                 if (empty($configKey)) {
 116                         // Entry is empty
 117                         throw new InvalidArgumentException('Parameter "configKey" is empty', self::EXCEPTION_CONFIG_KEY_IS_EMPTY);
 118                 }
 119
 120                 // Convert dashes to underscore
 121                 $configKey = StringUtils::convertDashesToUnderscores($configKey);
 122
 123                 // Is a valid configuration key provided?
 124                 //* NOISY-DEBUG: */ printf('[%s:%d]: configKey=%s - AFTER!' . PHP_EOL, __METHOD__, __LINE__, $configKey);
 125                 if (!$this->isConfigurationEntrySet($configKey)) {
 126                         // Entry was not found!
 127                         throw new NoConfigEntryException(array(__CLASS__, $configKey), self::EXCEPTION_CONFIG_KEY_WAS_NOT_FOUND);
 128                 }
 129
 130                 // Return the requested value
 131                 //* NOISY-DEBUG: */ printf('[%s:%d]: Returning configData[%s]=[%s]:%s - EXIT!' . PHP_EOL, __METHOD__, __LINE__, $configKey, gettype(self::$configData[$configKey]), self::$configData[$configKey]);
 132                 return self::$configData[$configKey];
 133         }
 134
 135         /**
 136          * Set a configuration key
 137          *
 138          * @param       $configKey      The configuration key we want to add/change
 139          * @param       $configValue    The configuration value we want to set
 140          * @return      void
 141          * @throws      InvalidArgumentException        If $configKey is empty
 142          * @throws      InvalidArgumentException        If $configValue has an unsupported variable type
 143          */
 144         public final function setConfigEntry (string $configKey, $configValue) {
 145                 // Is a valid configuration key key provided?
 146                 //* NOISY-DEBUG: */ printf('[%s:%d]: configKey=%s,configValue[]=%s - CALLED!' . PHP_EOL, __METHOD__, __LINE__, $configKey, gettype($configValue));
 147                 if (empty($configKey)) {
 148                         // Entry is empty
 149                         throw new InvalidArgumentException('Parameter "configKey" is empty', self::EXCEPTION_CONFIG_KEY_IS_EMPTY);
 150                 } elseif ((is_array($configValue)) || (is_object($configValue)) || (is_resource($configValue))) {
 151                         // These cannot be set as this is not intended for configuration values, please use FrameworkArrayObject instead.
 152                         throw new InvalidArgumentException(sprintf('configValue[]=%s for configKey=%s is not supported.', gettype($configValue), $configKey), self::EXCEPTION_CONFIG_VALUE_TYPE_UNSUPPORTED);
 153                 }
 154
 155                 // Cast to string
 156                 $configKey = StringUtils::convertDashesToUnderscores($configKey);
 157
 158                 // Set the configuration value
 159                 //* NOISY-DEBUG: */ printf('[%s:%d]: Setting configKey=%s,configValue[%s]=%s - EXIT!' . PHP_EOL, __METHOD__, __LINE__, $configKey, gettype($configValue), $configValue);
 160                 self::$configData[$configKey] = $configValue;
 161         }
 162
 163         /**
 164          * Getter for whole configuration array
 165          *
 166          * @return      $config         Configuration array
 167          */
 168         public final function getConfigurationArray () {
 169                 // Return it
 170                 //* NOISY-DEBUG: */ printf('[%s:%d]: self::configData()=%d - EXIT!' . PHP_EOL, __METHOD__, __LINE__, count(self::$configData));
 171                 return self::$configData;
 172         }
 173
 174         /**
 175          * Sorts the configuration array, saves A LOT calls if done after all configuration files have been loaded. You should NOT
 176          * set any configuration entries by your own, means outside any configuration file. If you still do so, you HAVE to call
 177          * this method afterwards
 178          *
 179          * @return      void
 180          */
 181         public final function sortConfigurationArray () {
 182                 // Resort the array
 183                 //* NOISY-DEBUG: */ printf('[%s:%d]: Sorting %d records - CALLED!' . PHP_EOL, __METHOD__, __LINE__, count(self::$configData));
 184                 ksort(self::$configData);
 185
 186                 // Debug message
 187                 //* NOISY-DEBUG: */ printf('[%s:%d]: EXIT!' . PHP_EOL, __METHOD__, __LINE__);
 188         }
 189
 190         /**
 191          * Unset a configuration key, the entry must be there or else an
 192          * exception is thrown.
 193          *
 194          * @param       $configKey      Configuration key to unset
 195          * @return      void
 196          * @throws      InvalidArgumentException        If $configKey is empty
 197          * @throws      NoConfigEntryException  If a configuration element was not found
 198          */
 199         public final function unsetConfigEntry (string $configKey) {
 200                 // Validate parameters
 201                 //* NOISY-DEBUG: */ printf('[%s:%d]: configKey=%s - CALLED!' . PHP_EOL, __METHOD__, __LINE__, $configKey);
 202                 if (empty($configKey)) {
 203                         // Entry is empty
 204                         throw new InvalidArgumentException('Parameter "configKey" is empty', self::EXCEPTION_CONFIG_KEY_IS_EMPTY);
 205                 }
 206
 207                 // Convert dashes to underscore
 208                 $configKey = StringUtils::convertDashesToUnderscores($configKey);
 209
 210                 // Is the configuration key there?
 211                 //* NOISY-DEBUG: */ printf('[%s:%d]: configKey=%s - AFTER!' . PHP_EOL, __METHOD__, __LINE__, $configKey);
 212                 if (!$this->isConfigurationEntrySet($configKey)) {
 213                         // Entry was not found!
 214                         throw new NoConfigEntryException(array(__CLASS__, $configKey), self::EXCEPTION_CONFIG_KEY_WAS_NOT_FOUND);
 215                 }
 216
 217                 // Unset it
 218                 //* NOISY-DEBUG: */ printf('[%s:%d]: Unsetting configKey=%s ...' . PHP_EOL, __METHOD__, __LINE__, $configKey);
 219                 unset(self::$configData[$configKey]);
 220
 221                 // Debug message
 222                 //* NOISY-DEBUG: */ printf('[%s:%d]: EXIT!' . PHP_EOL, __METHOD__, __LINE__);
 223         }
 224
 225         /**
 226          * Checks if a configuration entry is_*_enabled set to 'Y'
 227          *
 228          * @param       $keyPart        Configuration to expand with is_$keyPart_enabled
 229          * @return      $enabled        Whether it has been set to Y or N
 230          * @throws      InvalidArgumentException        If a parameter is invalid
 231          * @throws      UnexpectedValueException        If a returned value is of an unexpected type or value
 232          */
 233         public function isEnabled (string $keyPart) {
 234                 // Validate parameters
 235                 //* NOISY-DEBUG: */ printf('[%s:%d]: keyPart=%s - CALLED!' . PHP_EOL, __METHOD__, __LINE__, $keyPart);
 236                 if (empty($keyPart)) {
 237                         // Entry is empty
 238                         throw new InvalidArgumentException('Parameter "keyPart" is empty', self::EXCEPTION_CONFIG_KEY_IS_EMPTY);
 239                 }
 240
 241                 // Construct final config key
 242                 $configKey = sprintf('is_%s_enabled', $keyPart);
 243
 244                 // Get value from it
 245                 //* NOISY-DEBUG: */ printf('[%s:%d]: configKey=%s' . PHP_EOL, __METHOD__, __LINE__, $configKey);
 246                 $isEnabled = $this->getConfigEntry($configKey);
 247
 248                 // Is it Y/N?
 249                 //* NOISY-DEBUG: */ printf('[%s:%d]: isEnabled[]=%s' . PHP_EOL, __METHOD__, __LINE__, gettype($isEnabled));
 250                 if (!is_bool($isEnabled)) {
 251                         // Throw exception
 252                         throw new UnexpectedValueException(sprintf('isEnabled[]=%s is unexpected', gettype($isEnabled)));
 253                 }
 254
 255                 // Return it
 256                 //* NOISY-DEBUG: */ printf('[%s:%d]: isEnabled=%d - EXIT!' . PHP_EOL, __METHOD__, __LINE__, intval($isEnabled));
 257                 return $isEnabled;
 258         }
 259
 260         /**
 261          * Generates a code for hashes from this class
 262          *
 263          * @return      $hashCode       The hash code respresenting this class
 264          */
 265         public function hashCode () {
 266                 return crc32($this->__toString());
 267         }
 268
 269         /**
 270          * Checks whether an object equals this object. You should overwrite this
 271          * method to implement own equality checks
 272          *
 273          * @param       $objectInstance         An instance of a FrameworkInterface object
 274          * @return      $equals                         Whether both objects equals
 275          */
 276         public function equals (FrameworkInterface $objectInstance) {
 277                 // Now test it
 278                 $equals = ((
 279                                 $this->__toString() === $objectInstance->__toString()
 280                                 ) && (
 281                                 $this->hashCode() === $objectInstance->hashCode()
 282                                 ));
 283
 284                 // Return the result
 285                 return $equals;
 286         }
 287
 288         /**
 289          * Setter for call-back instance
 290          *
 291          * @param       $callbackInstance       An instance of a FrameworkInterface class
 292          * @return      void
 293          */
 294         public function setCallbackInstance (FrameworkInterface $callbackInstance) {
 295                 $this->callbackInstance = $callbackInstance;
 296         }
 297
 298         /**
 299          * Getter for field name
 300          *
 301          * @param       $fieldName              Field name which we shall get
 302          * @return      $fieldValue             Field value from the user
 303          * @throws      NullPointerException    If the result instance is null
 304          */
 305         public final function getField (string $fieldName) {
 306                 // The super interface "FrameworkInterface" requires this
 307                 throw new UnsupportedOperationException([$this, __FUNCTION__], BaseFrameworkSystem::EXCEPTION_UNSPPORTED_OPERATION);
 308         }
 309
 310         /**
 311          * Checks if given field is set
 312          *
 313          * @param       $fieldName      Field name to check
 314          * @return      $isSet          Whether the given field name is set
 315          * @throws      NullPointerException    If the result instance is null
 316          */
 317         public function isFieldSet (string $fieldName) {
 318                 // The super interface "FrameworkInterface" requires this
 319                 throw new UnsupportedOperationException([$this, __FUNCTION__], BaseFrameworkSystem::EXCEPTION_UNSPPORTED_OPERATION);
 320         }
 321
 322 }