framework/main/classes/class_BaseFrameworkSystem.php

   1 <?php
   2 // Own namespace
   3 namespace Org\Mxchange\CoreFramework\Object;
   4
   5 // Import framework stuff
   6 use Org\Mxchange\CoreFramework\Bootstrap\FrameworkBootstrap;
   7 use Org\Mxchange\CoreFramework\EntryPoint\ApplicationEntryPoint;
   8 use Org\Mxchange\CoreFramework\Factory\Object\ObjectFactory;
   9 use Org\Mxchange\CoreFramework\Filesystem\FileIoException;
  10 use Org\Mxchange\CoreFramework\Filesystem\PathWriteProtectedException;
  11 use Org\Mxchange\CoreFramework\Generic\FrameworkInterface;
  12 use Org\Mxchange\CoreFramework\Generic\NullPointerException;
  13 use Org\Mxchange\CoreFramework\Generic\UnsupportedOperationException;
  14 use Org\Mxchange\CoreFramework\Helper\Application\ApplicationHelper;
  15 use Org\Mxchange\CoreFramework\Loader\ClassLoader;
  16 use Org\Mxchange\CoreFramework\Manager\ManageableApplication;
  17 use Org\Mxchange\CoreFramework\Middleware\Debug\DebugMiddleware;
  18 use Org\Mxchange\CoreFramework\Registry\GenericRegistry;
  19 use Org\Mxchange\CoreFramework\Result\Database\CachedDatabaseResult;
  20 use Org\Mxchange\CoreFramework\State\Stateable;
  21 use Org\Mxchange\CoreFramework\Stream\Output\OutputStreamer;
  22 use Org\Mxchange\CoreFramework\Utils\Strings\StringUtils;
  23
  24 // Import SPL stuff
  25 use \stdClass;
  26 use \InvalidArgumentException;
  27 use \ReflectionClass;
  28 use \SplFileInfo;
  29
  30 /**
  31  * The simulator system class is the super class of all other classes. This
  32  * class handles saving of games etc.
  33  *
  34  * @author              Roland Haeder <webmaster@shipsimu.org>
  35  * @version             0.0.0
  36  * @copyright   Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2021 Core Developer Team
  37  * @license             GNU GPL 3.0 or any newer version
  38  * @link                http://www.shipsimu.org
  39  *
  40  * This program is free software: you can redistribute it and/or modify
  41  * it under the terms of the GNU General Public License as published by
  42  * the Free Software Foundation, either version 3 of the License, or
  43  * (at your option) any later version.
  44  *
  45  * This program is distributed in the hope that it will be useful,
  46  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  47  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  48  * GNU General Public License for more details.
  49  *
  50  * You should have received a copy of the GNU General Public License
  51  * along with this program. If not, see <http://www.gnu.org/licenses/>.
  52  */
  53 abstract class BaseFrameworkSystem extends stdClass implements FrameworkInterface {
  54         /**
  55          * Self-referencing instance
  56          */
  57         private static $selfInstance = NULL;
  58
  59         /**
  60          * Stub methods
  61          */
  62         private static $stubMethods = [
  63                 'partialStub' => true,
  64                 '__call' => true,
  65                 '__callStatic' => true,
  66         ];
  67
  68         /**
  69          * The real class name
  70          */
  71         private $realClass = __CLASS__;
  72
  73         /**
  74          * Call-back instance
  75          */
  76         private $callbackInstance = NULL;
  77
  78         /**
  79          * Generic array
  80          */
  81         private $genericArray = [];
  82
  83         /***********************
  84          * Exception codes.... *
  85          ***********************/
  86
  87         // @todo Try to clean these constants up
  88         const EXCEPTION_IS_NULL_POINTER              = 0x001;
  89         const EXCEPTION_IS_NO_OBJECT                 = 0x002;
  90         const EXCEPTION_IS_NO_ARRAY                  = 0x003;
  91         const EXCEPTION_MISSING_METHOD               = 0x004;
  92         const EXCEPTION_CLASSES_NOT_MATCHING         = 0x005;
  93         const EXCEPTION_INDEX_OUT_OF_BOUNDS          = 0x006;
  94         const EXCEPTION_DIMENSION_ARRAY_INVALID      = 0x007;
  95         const EXCEPTION_ITEM_NOT_TRADEABLE           = 0x008;
  96         const EXCEPTION_ITEM_NOT_IN_PRICE_LIST       = 0x009;
  97         const EXCEPTION_GENDER_IS_WRONG              = 0x00a;
  98         const EXCEPTION_BIRTH_DATE_IS_INVALID        = 0x00b;
  99         const EXCEPTION_EMPTY_STRUCTURES_ARRAY       = 0x00c;
 100         const EXCEPTION_HAS_ALREADY_PERSONELL_LIST   = 0x00d;
 101         const EXCEPTION_NOT_ENOUGTH_UNEMPLOYEES      = 0x00e;
 102         const EXCEPTION_TOTAL_PRICE_NOT_CALCULATED   = 0x00f;
 103         const EXCEPTION_HARBOR_HAS_NO_SHIPYARDS      = 0x010;
 104         const EXCEPTION_CONTRACT_PARTNER_INVALID     = 0x011;
 105         const EXCEPTION_CONTRACT_PARTNER_MISMATCH    = 0x012;
 106         const EXCEPTION_CONTRACT_ALREADY_SIGNED      = 0x013;
 107         const EXCEPTION_UNEXPECTED_EMPTY_STRING      = 0x014;
 108         const EXCEPTION_PATH_NOT_FOUND               = 0x015;
 109         const EXCEPTION_INVALID_PATH_NAME            = 0x016;
 110         const EXCEPTION_READ_PROTECED_PATH           = 0x017;
 111         const EXCEPTION_WRITE_PROTECED_PATH          = 0x018;
 112         const EXCEPTION_DIR_POINTER_INVALID          = 0x019;
 113         const EXCEPTION_FILE_POINTER_INVALID         = 0x01a;
 114         const EXCEPTION_INVALID_RESOURCE             = 0x01b;
 115         const EXCEPTION_UNEXPECTED_OBJECT            = 0x01c;
 116         const EXCEPTION_LIMIT_ELEMENT_IS_UNSUPPORTED = 0x01d;
 117         const EXCEPTION_GETTER_IS_MISSING            = 0x01e;
 118         const EXCEPTION_ARRAY_EXPECTED               = 0x01f;
 119         const EXCEPTION_ARRAY_HAS_INVALID_COUNT      = 0x020;
 120         const EXCEPTION_ID_IS_INVALID_FORMAT         = 0x021;
 121         const EXCEPTION_MD5_CHECKSUMS_MISMATCH       = 0x022;
 122         const EXCEPTION_UNEXPECTED_STRING_SIZE       = 0x023;
 123         const EXCEPTION_SIMULATOR_ID_INVALID         = 0x024;
 124         const EXCEPTION_MISMATCHING_COMPRESSORS      = 0x025;
 125         const EXCEPTION_CONTAINER_ITEM_IS_NULL       = 0x026;
 126         const EXCEPTION_ITEM_IS_NO_ARRAY             = 0x027;
 127         const EXCEPTION_CONTAINER_MAYBE_DAMAGED      = 0x028;
 128         const EXCEPTION_INVALID_STRING               = 0x029;
 129         const EXCEPTION_VARIABLE_NOT_SET             = 0x02a;
 130         const EXCEPTION_ATTRIBUTES_ARE_MISSING       = 0x02b;
 131         const EXCEPTION_ARRAY_ELEMENTS_MISSING       = 0x02c;
 132         const EXCEPTION_TEMPLATE_ENGINE_UNSUPPORTED  = 0x02d;
 133         const EXCEPTION_UNSPPORTED_OPERATION         = 0x02e;
 134         const EXCEPTION_FACTORY_REQUIRE_PARAMETER    = 0x02f;
 135         const EXCEPTION_MISSING_ELEMENT              = 0x030;
 136         const EXCEPTION_HEADERS_ALREADY_SENT         = 0x031;
 137         const EXCEPTION_DEFAULT_CONTROLLER_GONE      = 0x032;
 138         const EXCEPTION_CLASS_NOT_FOUND              = 0x033;
 139         const EXCEPTION_REQUIRED_INTERFACE_MISSING   = 0x034;
 140         const EXCEPTION_FATAL_ERROR                  = 0x035;
 141         const EXCEPTION_FILE_NOT_FOUND               = 0x036;
 142         const EXCEPTION_ASSERTION_FAILED             = 0x037;
 143         const EXCEPTION_FILE_NOT_REACHABLE           = 0x038;
 144         const EXCEPTION_FILE_CANNOT_BE_READ          = 0x039;
 145         const EXCEPTION_FILE_CANNOT_BE_WRITTEN       = 0x03a;
 146         const EXCEPTION_PATH_CANNOT_BE_WRITTEN       = 0x03b;
 147         const EXCEPTION_DATABASE_UPDATED_NOT_ALLOWED = 0x03c;
 148         const EXCEPTION_FILTER_CHAIN_INTERCEPTED     = 0x03d;
 149         const EXCEPTION_INVALID_SOCKET               = 0x03e;
 150         const EXCEPTION_SELF_INSTANCE                = 0x03f;
 151
 152         /**
 153          * Startup time in miliseconds
 154          */
 155         private static $startupTime = 0;
 156
 157         /**
 158          * Protected super constructor
 159          *
 160          * @param       $className      Name of the class
 161          * @return      void
 162          */
 163         protected function __construct (string $className) {
 164                 // Set real class
 165                 $this->setRealClass($className);
 166
 167                 // Is the startup time set? (0 cannot be true anymore)
 168                 if (self::$startupTime == 0) {
 169                         // Then set it
 170                         self::$startupTime = microtime(true);
 171                 }
 172         }
 173
 174         /**
 175          * Destructor for all classes. You should not call this method on your own.
 176          *
 177          * @return      void
 178          */
 179         public function __destruct () {
 180                 // Is this object already destroyed?
 181                 if ($this->__toString() != 'DestructedObject') {
 182                         // Destroy all informations about this class but keep some text about it alive
 183                         $this->setRealClass('DestructedObject');
 184                 } elseif ((defined('DEBUG_DESTRUCTOR')) && (is_object($this->getDebugInstance()))) {
 185                         // Already destructed object
 186                         self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('The object <span class="object_name">%s</span> is already destroyed.',
 187                                 $this->__toString()
 188                         ));
 189                 } else {
 190                         // Do not call this twice
 191                         trigger_error(__METHOD__ . ': Called twice.');
 192                         exit;
 193                 }
 194         }
 195
 196         /**
 197          * The __call() method where all non-implemented methods end up
 198          *
 199          * @param       $methodName             Name of the missing method
 200          * @args        $args                   Arguments passed to the method
 201          * @return      void
 202          */
 203         public final function __call (string $methodName, array $args = NULL) {
 204                 // Set self-instance
 205                 self::$selfInstance = $this;
 206
 207                 // Call static method
 208                 self::__callStatic($methodName, $args);
 209
 210                 // Clear self-instance
 211                 self::$selfInstance = NULL;
 212         }
 213
 214         /**
 215          * The __callStatic() method where all non-implemented static methods end up
 216          *
 217          * @param       $methodName             Name of the missing method
 218          * @param       $args                   Arguments passed to the method
 219          * @return      void
 220          * @throws      InvalidArgumentException If self::$selfInstance is not a framework's own object
 221          */
 222         public static final function __callStatic (string $methodName, array $args = NULL) {
 223                 // Init argument string and class name
 224                 //* PRINT-DEBUG: */ printf('[%s:%d]: methodName=%s,args[]=%s - CALLED!' . PHP_EOL, __METHOD__, __LINE__, $methodName, gettype($args));
 225                 $argsString = '';
 226                 $className = 'unknown';
 227
 228                 // Is self-instance set?
 229                 if (self::$selfInstance instanceof FrameworkInterface) {
 230                         // Framework's own instance
 231                         $className = self::$selfInstance->__toString();
 232                 } elseif (!is_null(self::$selfInstance)) {
 233                         // Invalid argument!
 234                         throw new InvalidArgumentException(sprintf('self::instance[%s] is not expected.', gettype(self::$selfInstance)), self::EXCEPTION_SELF_INSTANCE);
 235                 }
 236
 237                 // Is it NULL, empty or an array?
 238                 if (is_null($args)) {
 239                         // No arguments
 240                         $argsString = 'NULL';
 241                 } elseif (is_array($args)) {
 242                         // Start braces
 243                         $argsString = '(';
 244
 245                         // Some arguments are there
 246                         foreach ($args as $arg) {
 247                                 // Add data about the argument
 248                                 $argsString .= gettype($arg) . ':';
 249
 250                                 if (is_null($arg)) {
 251                                         // Found a NULL argument
 252                                         $argsString .= 'NULL';
 253                                 } elseif (is_string($arg)) {
 254                                         // Add length for strings
 255                                         $argsString .= strlen($arg);
 256                                 } elseif ((is_int($arg)) || (is_float($arg))) {
 257                                         // ... integer/float
 258                                         $argsString .= $arg;
 259                                 } elseif (is_array($arg)) {
 260                                         // .. or size if array
 261                                         $argsString .= count($arg);
 262                                 } elseif (is_object($arg)) {
 263                                         // Get reflection
 264                                         $reflection = new ReflectionClass($arg);
 265
 266                                         // Is an other object, maybe no __toString() available
 267                                         $argsString .= $reflection->getName();
 268                                 } elseif ($arg === true) {
 269                                         // ... is boolean 'true'
 270                                         $argsString .= 'true';
 271                                 } elseif ($arg === false) {
 272                                         // ... is boolean 'false'
 273                                         $argsString .= 'false';
 274                                 }
 275
 276                                 // Comma for next one
 277                                 $argsString .= ', ';
 278                         }
 279
 280                         // Last comma found?
 281                         if (substr($argsString, -2, 1) == ',') {
 282                                 // Remove last comma
 283                                 $argsString = substr($argsString, 0, -2);
 284                         }
 285
 286                         // Close braces
 287                         $argsString .= ')';
 288                 }
 289
 290                 // Output stub message
 291                 // @TODO __CLASS__ does always return BaseFrameworkSystem but not the extending (=child) class
 292                 self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('[%s::%s]: Stub! Args: %s',
 293                         $className,
 294                         $methodName,
 295                         $argsString
 296                 ));
 297
 298                 // Return nothing
 299                 return NULL;
 300         }
 301
 302         /**
 303          * Getter for $realClass
 304          *
 305          * @return      $realClass The name of the real class (not BaseFrameworkSystem)
 306          */
 307         public function __toString () {
 308                 return $this->realClass;
 309         }
 310
 311         /**
 312          * Magic method to catch setting of missing but set class fields/attributes
 313          *
 314          * @param       $name   Name of the field/attribute
 315          * @param       $value  Value to store
 316          * @return      void
 317          */
 318         public final function __set (string $name, $value) {
 319                 $this->debugBackTrace(sprintf('Tried to set a missing field. name=%s, value[%s]=%s',
 320                         $name,
 321                         gettype($value),
 322                         print_r($value, true)
 323                 ));
 324         }
 325
 326         /**
 327          * Magic method to catch getting of missing fields/attributes
 328          *
 329          * @param       $name   Name of the field/attribute
 330          * @return      void
 331          */
 332         public final function __get (string $name) {
 333                 $this->debugBackTrace(sprintf('Tried to get a missing field. name=%s',
 334                         $name
 335                 ));
 336         }
 337
 338         /**
 339          * Magic method to catch unsetting of missing fields/attributes
 340          *
 341          * @param       $name   Name of the field/attribute
 342          * @return      void
 343          */
 344         public final function __unset (string $name) {
 345                 $this->debugBackTrace(sprintf('Tried to unset a missing field. name=%s',
 346                         $name
 347                 ));
 348         }
 349
 350         /**
 351          * Magic method to catch object serialization
 352          *
 353          * @return      $unsupported    Unsupported method
 354          * @throws      UnsupportedOperationException   Objects of this framework cannot be serialized
 355          */
 356         public final function __sleep () {
 357                 throw new UnsupportedOperationException(array($this, __FUNCTION__), self::EXCEPTION_UNSPPORTED_OPERATION);
 358         }
 359
 360         /**
 361          * Magic method to catch object deserialization
 362          *
 363          * @return      $unsupported    Unsupported method
 364          * @throws      UnsupportedOperationException   Objects of this framework cannot be serialized
 365          */
 366         public final function __wakeup () {
 367                 throw new UnsupportedOperationException(array($this, __FUNCTION__), self::EXCEPTION_UNSPPORTED_OPERATION);
 368         }
 369
 370         /**
 371          * Magic method to catch calls when an object instance is called
 372          *
 373          * @return      $unsupported    Unsupported method
 374          * @throws      UnsupportedOperationException   Objects of this framework cannot be serialized
 375          */
 376         public final function __invoke () {
 377                 throw new UnsupportedOperationException(array($this, __FUNCTION__), self::EXCEPTION_UNSPPORTED_OPERATION);
 378         }
 379
 380         /**
 381          * Setter for the real class name
 382          *
 383          * @param       $realClass      Class name (string)
 384          * @return      void
 385          */
 386         public final function setRealClass (string $realClass) {
 387                 // Set real class
 388                 $this->realClass = $realClass;
 389         }
 390
 391         /**
 392          * Setter for debug instance
 393          *
 394          * @param       $debugInstance  The instance for debug output class
 395          * @return      void
 396          */
 397         public final function setDebugInstance (DebugMiddleware $debugInstance) {
 398                 GenericRegistry::getRegistry()->addInstance('debug', $debugInstance);
 399         }
 400
 401         /**
 402          * Getter for debug instance
 403          *
 404          * @return      $debugInstance  Instance to class DebugConsoleOutput or DebugWebOutput
 405          */
 406         public final function getDebugInstance () {
 407                 // Get debug instance
 408                 $debugInstance = GenericRegistry::getRegistry()->getInstance('debug');
 409
 410                 // Return it
 411                 return $debugInstance;
 412         }
 413
 414         /**
 415          * Setter for web output instance
 416          *
 417          * @param       $webInstance    The instance for web output class
 418          * @return      void
 419          */
 420         public final function setWebOutputInstance (OutputStreamer $webInstance) {
 421                 GenericRegistry::getRegistry()->addInstance('web_output', $webInstance);
 422         }
 423
 424         /**
 425          * Getter for web output instance
 426          *
 427          * @return      $webOutputInstance - Instance to class WebOutput
 428          */
 429         public final function getWebOutputInstance () {
 430                 $webOutputInstance = GenericRegistry::getRegistry()->getInstance('web_output');
 431                 return $webOutputInstance;
 432         }
 433
 434         /**
 435          * Setter for call-back instance
 436          *
 437          * @param       $callbackInstance       An instance of a FrameworkInterface class
 438          * @return      void
 439          */
 440         public final function setCallbackInstance (FrameworkInterface $callbackInstance) {
 441                 $this->callbackInstance = $callbackInstance;
 442         }
 443
 444         /**
 445          * Getter for call-back instance
 446          *
 447          * @return      $callbackInstance       An instance of a FrameworkInterface class
 448          */
 449         protected final function getCallbackInstance () {
 450                 return $this->callbackInstance;
 451         }
 452
 453         /**
 454          * Checks whether an object equals this object. You should overwrite this
 455          * method to implement own equality checks
 456          *
 457          * @param       $objectInstance         An instance of a FrameworkInterface object
 458          * @return      $equals                         Whether both objects equals
 459          */
 460         public function equals (FrameworkInterface $objectInstance) {
 461                 // Now test it
 462                 $equals = ((
 463                         $this->__toString() == $objectInstance->__toString()
 464                 ) && (
 465                         $this->hashCode() == $objectInstance->hashCode()
 466                 ));
 467
 468                 // Return the result
 469                 return $equals;
 470         }
 471
 472         /**
 473          * Generates a generic hash code of this class. You should really overwrite
 474          * this method with your own hash code generator code. But keep KISS in mind.
 475          *
 476          * @return      $hashCode       A generic hash code respresenting this whole class
 477          */
 478         public function hashCode () {
 479                 // Simple hash code
 480                 return crc32($this->__toString());
 481         }
 482
 483         /**
 484          * Appends a trailing slash to a string
 485          *
 486          * @param       $str    A string (maybe) without trailing slash
 487          * @return      $str    A string with an auto-appended trailing slash
 488          */
 489         public final function addMissingTrailingSlash (string $str) {
 490                 // Is there a trailing slash?
 491                 if (substr($str, -1, 1) != '/') {
 492                         $str .= '/';
 493                 }
 494
 495                 // Return string with trailing slash
 496                 return $str;
 497         }
 498
 499         /**
 500          * Debugs this instance by putting out it's full content
 501          *
 502          * @param       $message        Optional message to show in debug output
 503          * @return      void
 504          */
 505         public final function debugInstance (string $message = '') {
 506                 // Restore the error handler to avoid trouble with missing array elements or undeclared variables
 507                 restore_error_handler();
 508
 509                 // Init content
 510                 $content = '';
 511
 512                 // Is a message set?
 513                 if (!empty($message)) {
 514                         // Construct message
 515                         $content = sprintf('<div class="debug_message">
 516         Message: %s
 517 </div>' . PHP_EOL, $message);
 518                 }
 519
 520                 // Generate the output
 521                 $content .= sprintf('<pre>%s</pre>',
 522                         trim(
 523                                 htmlentities(
 524                                         print_r($this, true)
 525                                 )
 526                         )
 527                 );
 528
 529                 // Output it
 530                 ApplicationEntryPoint::exitApplication(sprintf('<div class="debug_header">
 531         %s debug output:
 532 </div>
 533 <div class="debug_content">
 534         %s
 535 </div>
 536 Loaded includes:
 537 <div class="debug_include_list">
 538         %s
 539 </div>',
 540                         $this->__toString(),
 541                         $content,
 542                         ClassLoader::getSelfInstance()->getPrintableIncludeList()
 543                 ));
 544         }
 545
 546         /**
 547          * Replaces control characters with printable output
 548          *
 549          * @param       $str    String with control characters
 550          * @return      $str    Replaced string
 551          */
 552         protected function replaceControlCharacters (string $str) {
 553                 // Replace them
 554                 $str = str_replace(
 555                         chr(13), '[r]', str_replace(
 556                         chr(10), '[n]', str_replace(
 557                         chr(9) , '[t]',
 558                         $str
 559                 )));
 560
 561                 // Return it
 562                 return $str;
 563         }
 564
 565         /**
 566          * Output a partial stub message for the caller method
 567          *
 568          * @param       $message        An optional message to display
 569          * @return      void
 570          */
 571         protected function partialStub (string $message = '') {
 572                 // Init variable
 573                 $stubMessage = 'Partial stub!';
 574
 575                 // Is an extra message given?
 576                 if (!empty($message)) {
 577                         // Then add it as well
 578                         $stubMessage .= ' Message: ' . $message;
 579                 }
 580
 581                 // Debug instance is there?
 582                 if (!is_null($this->getDebugInstance())) {
 583                         // Output stub message
 584                         self::createDebugInstance(__CLASS__, __LINE__)->debugOutput($stubMessage);
 585                 } else {
 586                         // Trigger an error
 587                         trigger_error($stubMessage);
 588                         exit;
 589                 }
 590         }
 591
 592         /**
 593          * Outputs a debug backtrace and stops further script execution
 594          *
 595          * @param       $message        An optional message to output
 596          * @param       $doExit         Whether exit the program (true is default)
 597          * @return      void
 598          */
 599         public function debugBackTrace (string $message = '', bool $doExit = true) {
 600                 // Sorry, there is no other way getting this nice backtrace
 601                 if (!empty($message)) {
 602                         // Output message
 603                         printf('Message: %s<br />' . PHP_EOL, $message);
 604                 }
 605
 606                 print('<pre>');
 607                 debug_print_backtrace();
 608                 print('</pre>');
 609
 610                 // Exit program?
 611                 if ($doExit === true) {
 612                         exit();
 613                 }
 614         }
 615
 616         /**
 617          * Creates an instance of a debugger instance
 618          *
 619          * @param       $className              Name of the class (currently unsupported)
 620          * @param       $lineNumber             Line number where the call was made
 621          * @return      $debugInstance  An instance of a debugger class
 622          * @deprecated  Not fully, as the new Logger facilities are not finished yet.
 623          */
 624         public final static function createDebugInstance (string $className, int $lineNumber = NULL) {
 625                 // Validate parameter
 626                 if (empty($className)) {
 627                         // Throw IAE
 628                         throw new InvalidArgumentException('Parameter "className" is empty');
 629                 } elseif (!GenericRegistry::getRegistry()->instanceExists('debug')) {
 630                         // Init debug instance
 631                         $debugInstance = NULL;
 632
 633                         // Try it
 634                         try {
 635                                 // Get a debugger instance
 636                                 $debugInstance = DebugMiddleware::createDebugMiddleware(FrameworkBootstrap::getConfigurationInstance()->getConfigEntry('debug_' . FrameworkBootstrap::getRequestTypeFromSystem() . '_class'), $className);
 637                         } catch (NullPointerException $e) {
 638                                 // Didn't work, no instance there
 639                                 exit(sprintf('[%s:%d]: Cannot create debugInstance! Exception=%s,message=%s,className=%s,lineNumber=%d' . PHP_EOL, __METHOD__, __LINE__, $e->__toString(), $e->getMessage(), $className, $lineNumber));
 640                         }
 641
 642                         // Empty string should be ignored and used for testing the middleware
 643                         DebugMiddleware::getSelfInstance()->output('');
 644
 645                         // Set it in registry
 646                         GenericRegistry::getRegistry()->addInstance('debug', $debugInstance);
 647                 } else {
 648                         // Get instance from registry
 649                         $debugInstance = GenericRegistry::getRegistry()->getDebugInstance();
 650                 }
 651
 652                 // Return it
 653                 return $debugInstance;
 654         }
 655
 656         /**
 657          * Simple output of a message with line-break
 658          *
 659          * @param       $message        Message to output
 660          * @return      void
 661          */
 662         public function outputLine (string $message) {
 663                 // Simply output it
 664                 print($message . PHP_EOL);
 665         }
 666
 667         /**
 668          * Outputs a debug message whether to debug instance (should be set!) or
 669          * dies with or ptints the message. Do NEVER EVER rewrite the exit() call to
 670          * ApplicationEntryPoint::app_exit(), this would cause an endless loop.
 671          *
 672          * @param       $message        Message we shall send out...
 673          * @param       $doPrint        Whether print or die here (default: print)
 674          * @paran       $stripTags      Whether to strip tags (default: false)
 675          * @return      void
 676          */
 677         public function debugOutput (string $message, bool $doPrint = true, bool $stripTags = false) {
 678                 // Set debug instance to NULL
 679                 $debugInstance = NULL;
 680
 681                 // Get backtrace
 682                 $backtrace = debug_backtrace(!DEBUG_BACKTRACE_PROVIDE_OBJECT);
 683
 684                 // Is function partialStub/__callStatic ?
 685                 if (isset(self::$stubMethods[$backtrace[1]['function']])) {
 686                         // Prepend class::function:line from 3rd element
 687                         $message = sprintf('[%s::%s:%d]: %s',
 688                                 $backtrace[2]['class'],
 689                                 $backtrace[2]['function'],
 690                                 (isset($backtrace[2]['line']) ? $backtrace[2]['line'] : '0'),
 691                                 $message
 692                         );
 693                 } else {
 694                         // Prepend class::function:line from 2nd element
 695                         $message = sprintf('[%s::%s:%d]: %s',
 696                                 $backtrace[1]['class'],
 697                                 $backtrace[1]['function'],
 698                                 (isset($backtrace[1]['line']) ? $backtrace[1]['line'] : '0'),
 699                                 $message
 700                         );
 701                 }
 702
 703                 // Try it:
 704                 try {
 705                         // Get debug instance
 706                         $debugInstance = $this->getDebugInstance();
 707                 } catch (NullPointerException $e) {
 708                         // The debug instance is not set (yet)
 709                 }
 710
 711                 // Is the debug instance there?
 712                 if (is_object($debugInstance)) {
 713                         // Use debug output handler
 714                         $debugInstance->output($message, $stripTags);
 715
 716                         if ($doPrint === false) {
 717                                 // Die here if not printed
 718                                 exit();
 719                         }
 720                 } else {
 721                         // Are debug times enabled?
 722                         if (FrameworkBootstrap::getConfigurationInstance()->getConfigEntry('debug_' . FrameworkBootstrap::getRequestTypeFromSystem() . '_output_timings') == 'Y') {
 723                                 // Prepent it
 724                                 $message = $this->getPrintableExecutionTime() . $message;
 725                         }
 726
 727                         // Put directly out
 728                         if ($doPrint === true) {
 729                                 // Print message
 730                                 $this->outputLine($message);
 731                         } else {
 732                                 // Die here
 733                                 exit($message);
 734                         }
 735                 }
 736         }
 737
 738         /**
 739          * Marks up the code by adding e.g. line numbers
 740          *
 741          * @param       $phpCode                Unmarked PHP code
 742          * @return      $markedCode             Marked PHP code
 743          */
 744         public function markupCode (string $phpCode) {
 745                 // Init marked code
 746                 $markedCode = '';
 747
 748                 // Get last error
 749                 $errorArray = error_get_last();
 750
 751                 // Init the code with error message
 752                 if (is_array($errorArray)) {
 753                         // Get error infos
 754                         $markedCode = sprintf('<div id="error_header">File: <span id="error_data">%s</span>, Line: <span id="error_data">%s</span>, Message: <span id="error_data">%s</span>, Type: <span id="error_data">%s</span></div>',
 755                                 basename($errorArray['file']),
 756                                 $errorArray['line'],
 757                                 $errorArray['message'],
 758                                 $errorArray['type']
 759                         );
 760                 }
 761
 762                 // Add line number to the code
 763                 foreach (explode(chr(10), $phpCode) as $lineNo => $code) {
 764                         // Add line numbers
 765                         $markedCode .= sprintf('<span id="code_line">%s</span>: %s' . PHP_EOL,
 766                                 ($lineNo + 1),
 767                                 htmlentities($code, ENT_QUOTES)
 768                         );
 769                 }
 770
 771                 // Return the code
 772                 return $markedCode;
 773         }
 774
 775         /**
 776          * "Getter" for databse entry
 777          *
 778          * @return      $entry  An array with database entries
 779          * @throws      NullPointerException    If the database result is not found
 780          * @throws      InvalidDatabaseResultException  If the database result is invalid
 781          * @todo        Monolithic method, should be moved to proper classes
 782          */
 783         protected final function getDatabaseEntry () {
 784                 // Is there an instance?
 785                 if (!$this->getResultInstance() instanceof SearchableResult) {
 786                         // Throw an exception here
 787                         throw new NullPointerException($this, self::EXCEPTION_IS_NULL_POINTER);
 788                 }
 789
 790                 // Rewind it
 791                 $this->getResultInstance()->rewind();
 792
 793                 // Do we have an entry?
 794                 if ($this->getResultInstance()->valid() === false) {
 795                         // @TODO Move the constant to e.g. BaseDatabaseResult when there is a non-cached database result available
 796                         throw new InvalidDatabaseResultException(array($this, $this->getResultInstance()), CachedDatabaseResult::EXCEPTION_INVALID_DATABASE_RESULT);
 797                 }
 798
 799                 // Get next entry
 800                 $this->getResultInstance()->next();
 801
 802                 // Fetch it
 803                 $entry = $this->getResultInstance()->current();
 804
 805                 // And return it
 806                 return $entry;
 807         }
 808
 809         /**
 810          * Getter for field name
 811          *
 812          * @param       $fieldName              Field name which we shall get
 813          * @return      $fieldValue             Field value from the user
 814          * @throws      NullPointerException    If the result instance is null
 815          */
 816         public final function getField (string $fieldName) {
 817                 // Default field value
 818                 $fieldValue = NULL;
 819
 820                 // Get result instance
 821                 $resultInstance = $this->getResultInstance();
 822
 823                 // Is this instance null?
 824                 if (is_null($resultInstance)) {
 825                         // Then the user instance is no longer valid (expired cookies?)
 826                         throw new NullPointerException($this, self::EXCEPTION_IS_NULL_POINTER);
 827                 }
 828
 829                 // Get current array
 830                 $fieldArray = $resultInstance->current();
 831                 //* DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput($fieldName.':<pre>'.print_r($fieldArray, true).'</pre>');
 832
 833                 // Convert dashes to underscore
 834                 $fieldName2 = StringUtils::convertDashesToUnderscores($fieldName);
 835
 836                 // Does the field exist?
 837                 if ($this->isFieldSet($fieldName)) {
 838                         // Get it
 839                         $fieldValue = $fieldArray[$fieldName2];
 840                 } elseif (FrameworkBootstrap::getConfigurationInstance()->getConfigEntry('developer_mode_enabled')) {
 841                         // Missing field entry, may require debugging
 842                         self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-FRAMEWORK-SYSTEM: fieldArray<pre>=' . print_r($fieldArray, true) . '</pre>,fieldName=' . $fieldName . ' not found!');
 843                 } else {
 844                         // Missing field entry, may require debugging
 845                         self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-FRAMEWORK-SYSTEM: fieldName=' . $fieldName . ' not found!');
 846                 }
 847
 848                 // Return it
 849                 return $fieldValue;
 850         }
 851
 852         /**
 853          * Checks if given field is set
 854          *
 855          * @param       $fieldName      Field name to check
 856          * @return      $isSet          Whether the given field name is set
 857          * @throws      NullPointerException    If the result instance is null
 858          */
 859         public function isFieldSet (string $fieldName) {
 860                 // Get result instance
 861                 $resultInstance = $this->getResultInstance();
 862
 863                 // Is this instance null?
 864                 if (is_null($resultInstance)) {
 865                         // Then the user instance is no longer valid (expired cookies?)
 866                         throw new NullPointerException($this, self::EXCEPTION_IS_NULL_POINTER);
 867                 }
 868
 869                 // Get current array
 870                 $fieldArray = $resultInstance->current();
 871                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('[' . $this->__toString() . ':' . __LINE__ . '] fieldName=' . $fieldName . ',fieldArray=<pre>'.print_r($fieldArray, true).'</pre>');
 872
 873                 // Convert dashes to underscore
 874                 $fieldName = StringUtils::convertDashesToUnderscores($fieldName);
 875
 876                 // Determine it
 877                 $isSet = isset($fieldArray[$fieldName]);
 878
 879                 // Return result
 880                 return $isSet;
 881         }
 882
 883         /**
 884          * Outputs a deprecation warning to the developer.
 885          *
 886          * @param       $message        The message we shall output to the developer
 887          * @return      void
 888          * @todo        Write a logging mechanism for productive mode
 889          */
 890         public function deprecationWarning (string $message) {
 891                 // Is developer mode active?
 892                 if (FrameworkBootstrap::getConfigurationInstance()->getConfigEntry('developer_mode_enabled')) {
 893                         // Debug instance is there?
 894                         if (!is_null($this->getDebugInstance())) {
 895                                 // Output stub message
 896                                 self::createDebugInstance(__CLASS__, __LINE__)->debugOutput($message);
 897                         } else {
 898                                 // Trigger an error
 899                                 trigger_error($message . "<br />\n");
 900                                 exit;
 901                         }
 902                 } else {
 903                         // @TODO Finish this part!
 904                         $this->partialStub('Developer mode inactive. Message:' . $message);
 905                 }
 906         }
 907
 908         /**
 909          * Checks whether the given PHP extension is loaded
 910          *
 911          * @param       $phpExtension   The PHP extension we shall check
 912          * @return      $isLoaded       Whether the PHP extension is loaded
 913          */
 914         public final function isPhpExtensionLoaded (string $phpExtension) {
 915                 // Is it loaded?
 916                 $isLoaded = in_array($phpExtension, get_loaded_extensions());
 917
 918                 // Return result
 919                 return $isLoaded;
 920         }
 921
 922         /**
 923          * "Getter" as a time() replacement but with milliseconds. You should use this
 924          * method instead of the encapsulated getimeofday() function.
 925          *
 926          * @return      $milliTime      Timestamp with milliseconds
 927          */
 928         public function getMilliTime () {
 929                 // Get the time of day as float
 930                 $milliTime = gettimeofday(true);
 931
 932                 // Return it
 933                 return $milliTime;
 934         }
 935
 936         /**
 937          * Idles (sleeps) for given milliseconds
 938          *
 939          * @return      $hasSlept       Whether it goes fine
 940          */
 941         public function idle (int $milliSeconds) {
 942                 // Sleep is fine by default
 943                 $hasSlept = true;
 944
 945                 // Idle so long with found function
 946                 if (function_exists('time_sleep_until')) {
 947                         // Get current time and add idle time
 948                         $sleepUntil = $this->getMilliTime() + abs($milliSeconds) / 1000;
 949
 950                         // New PHP 5.1.0 function found, ignore errors
 951                         $hasSlept = @time_sleep_until($sleepUntil);
 952                 } else {
 953                         /*
 954                          * My Sun station doesn't have that function even with latest PHP
 955                          * package. :(
 956                          */
 957                         usleep($milliSeconds * 1000);
 958                 }
 959
 960                 // Return result
 961                 return $hasSlept;
 962         }
 963
 964         /**
 965          * Checks whether the given encoded data was encoded with Base64
 966          *
 967          * @param       $encodedData    Encoded data we shall check
 968          * @return      $isBase64               Whether the encoded data is Base64
 969          */
 970         protected function isBase64Encoded (string $encodedData) {
 971                 // Determine it
 972                 $isBase64 = (@base64_decode($encodedData, true) !== false);
 973
 974                 // Return it
 975                 return $isBase64;
 976         }
 977
 978         /**
 979          * Getter for startup time in miliseconds
 980          *
 981          * @return      $startupTime    Startup time in miliseconds
 982          */
 983         protected function getStartupTime () {
 984                 return self::$startupTime;
 985         }
 986
 987         /**
 988          * "Getter" for a printable currently execution time in nice braces
 989          *
 990          * @return      $executionTime  Current execution time in nice braces
 991          */
 992         protected function getPrintableExecutionTime () {
 993                 // Calculate execution time and pack it in nice braces
 994                 $executionTime = sprintf('[ %01.5f ] ', (microtime(true) - $this->getStartupTime()));
 995
 996                 // And return it
 997                 return $executionTime;
 998         }
 999
1000         /**
1001          * Determines if an element is set in the generic array
1002          *
1003          * @param       $keyGroup       Main group for the key
1004          * @param       $subGroup       Sub group for the key
1005          * @param       $key            Key to check
1006          * @param       $element        Element to check
1007          * @return      $isset          Whether the given key is set
1008          */
1009         protected final function isGenericArrayElementSet (string $keyGroup, string $subGroup, $key, $element) {
1010                 // Is it there?
1011                 //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key . ',element=' . $element);
1012                 $isset = isset($this->genericArray[$keyGroup][$subGroup][$key][$element]);
1013
1014                 // Return it
1015                 return $isset;
1016         }
1017         /**
1018          * Determines if a key is set in the generic array
1019          *
1020          * @param       $keyGroup       Main group for the key
1021          * @param       $subGroup       Sub group for the key
1022          * @param       $key            Key to check
1023          * @return      $isset          Whether the given key is set
1024          */
1025         protected final function isGenericArrayKeySet (string $keyGroup, string $subGroup, $key) {
1026                 // Is it there?
1027                 //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key);
1028                 $isset = isset($this->genericArray[$keyGroup][$subGroup][$key]);
1029
1030                 // Return it
1031                 return $isset;
1032         }
1033
1034
1035         /**
1036          * Determines if a group is set in the generic array
1037          *
1038          * @param       $keyGroup       Main group
1039          * @param       $subGroup       Sub group
1040          * @return      $isset          Whether the given group is set
1041          */
1042         protected final function isGenericArrayGroupSet (string $keyGroup, string $subGroup) {
1043                 // Is it there?
1044                 //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup);
1045                 $isset = isset($this->genericArray[$keyGroup][$subGroup]);
1046
1047                 // Return it
1048                 return $isset;
1049         }
1050
1051         /**
1052          * Getter for sub key group
1053          *
1054          * @param       $keyGroup       Main key group
1055          * @param       $subGroup       Sub key group
1056          * @return      $array          An array with all array elements
1057          */
1058         protected final function getGenericSubArray (string $keyGroup, string $subGroup) {
1059                 // Is it there?
1060                 if (!$this->isGenericArrayGroupSet($keyGroup, $subGroup)) {
1061                         // No, then abort here
1062                         trigger_error(__METHOD__ . ': keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ' not found.');
1063                         exit;
1064                 }
1065
1066                 // Return it
1067                 //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',value=' . print_r($this->genericArray[$keyGroup][$subGroup], true));
1068                 return $this->genericArray[$keyGroup][$subGroup];
1069         }
1070
1071         /**
1072          * Unsets a given key in generic array
1073          *
1074          * @param       $keyGroup       Main group for the key
1075          * @param       $subGroup       Sub group for the key
1076          * @param       $key            Key to unset
1077          * @return      void
1078          */
1079         protected final function unsetGenericArrayKey (string $keyGroup, string $subGroup, $key) {
1080                 // Remove it
1081                 //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key);
1082                 unset($this->genericArray[$keyGroup][$subGroup][$key]);
1083         }
1084
1085         /**
1086          * Unsets a given element in generic array
1087          *
1088          * @param       $keyGroup       Main group for the key
1089          * @param       $subGroup       Sub group for the key
1090          * @param       $key            Key to unset
1091          * @param       $element        Element to unset
1092          * @return      void
1093          */
1094         protected final function unsetGenericArrayElement (string $keyGroup, string $subGroup, $key, $element) {
1095                 // Debug message
1096                 //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key . ',element=' . $element);
1097
1098                 // Remove it
1099                 unset($this->genericArray[$keyGroup][$subGroup][$key][$element]);
1100         }
1101
1102         /**
1103          * Append a string to a given generic array key
1104          *
1105          * @param       $keyGroup       Main group for the key
1106          * @param       $subGroup       Sub group for the key
1107          * @param       $key            Key to unset
1108          * @param       $value          Value to add/append
1109          * @return      void
1110          */
1111         protected final function appendStringToGenericArrayKey (string $keyGroup, string $subGroup, $key, string $value, $appendGlue = '') {
1112                 // Debug message
1113                 //* NOISY-DEBUG: */ if (!is_object($value)) $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key . ',value[' . gettype($value) . ']=' . print_r($value, true) . ',appendGlue=' . $appendGlue);
1114
1115                 // Is it already there?
1116                 if ($this->isGenericArrayKeySet($keyGroup, $subGroup, $key)) {
1117                         // Append it
1118                         $this->genericArray[$keyGroup][$subGroup][$key] .= $appendGlue . (string) $value;
1119                 } else {
1120                         // Add it
1121                         $this->genericArray[$keyGroup][$subGroup][$key] = (string) $value;
1122                 }
1123         }
1124
1125         /**
1126          * Append a string to a given generic array element
1127          *
1128          * @param       $keyGroup       Main group for the key
1129          * @param       $subGroup       Sub group for the key
1130          * @param       $key            Key to unset
1131          * @param       $element        Element to check
1132          * @param       $value          Value to add/append
1133          * @return      void
1134          */
1135         protected final function appendStringToGenericArrayElement (string $keyGroup, string $subGroup, $key, $element, $value, $appendGlue = '') {
1136                 // Debug message
1137                 //* NOISY-DEBUG: */ if (!is_object($value)) $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key . ',element=' . $element . ',value[' . gettype($value) . ']=' . print_r($value, true) . ',appendGlue=' . $appendGlue);
1138
1139                 // Is it already there?
1140                 if ($this->isGenericArrayElementSet($keyGroup, $subGroup, $key, $element)) {
1141                         // Append it
1142                         $this->genericArray[$keyGroup][$subGroup][$key][$element] .= $appendGlue . (string) $value;
1143                 } else {
1144                         // Add it
1145                         $this->setStringGenericArrayElement($keyGroup, $subGroup, $key, $element, $value);
1146                 }
1147         }
1148
1149         /**
1150          * Sets a string in a given generic array element
1151          *
1152          * @param       $keyGroup       Main group for the key
1153          * @param       $subGroup       Sub group for the key
1154          * @param       $key            Key to unset
1155          * @param       $element        Element to check
1156          * @param       $value          Value to add/append
1157          * @return      void
1158          */
1159         protected final function setStringGenericArrayElement (string $keyGroup, string $subGroup, $key, $element, $value, $appendGlue = '') {
1160                 // Debug message
1161                 //* NOISY-DEBUG: */ if (!is_object($value)) $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key . ',element=' . $element . ',value[' . gettype($value) . ']=' . print_r($value, true) . ',appendGlue=' . $appendGlue);
1162
1163                 // Set it
1164                 $this->genericArray[$keyGroup][$subGroup][$key][$element] = (string) $value;
1165         }
1166
1167         /**
1168          * Initializes given generic array group
1169          *
1170          * @param       $keyGroup       Main group for the key
1171          * @param       $subGroup       Sub group for the key
1172          * @param       $key            Key to use
1173          * @param       $forceInit      Optionally force initialization
1174          * @return      void
1175          */
1176         protected final function initGenericArrayGroup (string $keyGroup, string $subGroup, bool $forceInit = false) {
1177                 // Debug message
1178                 //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',forceInit=' . intval($forceInit));
1179
1180                 // Is it already set?
1181                 if (($forceInit === false) && ($this->isGenericArrayGroupSet($keyGroup, $subGroup))) {
1182                         // Already initialized
1183                         trigger_error(__METHOD__ . ':keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ' already initialized.');
1184                         exit;
1185                 }
1186
1187                 // Initialize it
1188                 $this->genericArray[$keyGroup][$subGroup] = [];
1189         }
1190
1191         /**
1192          * Initializes given generic array key
1193          *
1194          * @param       $keyGroup       Main group for the key
1195          * @param       $subGroup       Sub group for the key
1196          * @param       $key            Key to use
1197          * @param       $forceInit      Optionally force initialization
1198          * @return      void
1199          */
1200         protected final function initGenericArrayKey (string $keyGroup, string $subGroup, $key, bool $forceInit = false) {
1201                 // Debug message
1202                 //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key . ',forceInit=' . intval($forceInit));
1203
1204                 // Is it already set?
1205                 if (($forceInit === false) && ($this->isGenericArrayKeySet($keyGroup, $subGroup, $key))) {
1206                         // Already initialized
1207                         trigger_error(__METHOD__ . ':keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key . ' already initialized.');
1208                         exit;
1209                 }
1210
1211                 // Initialize it
1212                 $this->genericArray[$keyGroup][$subGroup][$key] = [];
1213         }
1214
1215         /**
1216          * Initializes given generic array element
1217          *
1218          * @param       $keyGroup       Main group for the key
1219          * @param       $subGroup       Sub group for the key
1220          * @param       $key            Key to use
1221          * @param       $element        Element to use
1222          * @param       $forceInit      Optionally force initialization
1223          * @return      void
1224          */
1225         protected final function initGenericArrayElement (string $keyGroup, string $subGroup, $key, $element, bool $forceInit = false) {
1226                 // Debug message
1227                 //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key . ',element=' . $element . ',forceInit=' . intval($forceInit));
1228
1229                 // Is it already set?
1230                 if (($forceInit === false) && ($this->isGenericArrayElementSet($keyGroup, $subGroup, $key, $element))) {
1231                         // Already initialized
1232                         trigger_error(__METHOD__ . ':keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key . ',element=' . $element . ' already initialized.');
1233                         exit;
1234                 }
1235
1236                 // Initialize it
1237                 $this->genericArray[$keyGroup][$subGroup][$key][$element] = [];
1238         }
1239
1240         /**
1241          * Pushes an element to a generic key
1242          *
1243          * @param       $keyGroup       Main group for the key
1244          * @param       $subGroup       Sub group for the key
1245          * @param       $key            Key to use
1246          * @param       $value          Value to add/append
1247          * @return      $count          Number of array elements
1248          */
1249         protected final function pushValueToGenericArrayKey (string $keyGroup, string $subGroup, $key, $value) {
1250                 // Debug message
1251                 //* NOISY-DEBUG: */ if (!is_object($value)) $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key . ',value[' . gettype($value) . ']=' . print_r($value, true));
1252
1253                 // Is it set?
1254                 if (!$this->isGenericArrayKeySet($keyGroup, $subGroup, $key)) {
1255                         // Initialize array
1256                         $this->initGenericArrayKey($keyGroup, $subGroup, $key);
1257                 }
1258
1259                 // Then push it
1260                 $count = array_push($this->genericArray[$keyGroup][$subGroup][$key], $value);
1261
1262                 // Return count
1263                 //* DEBUG: */ print(__METHOD__ . ': genericArray=' . print_r($this->genericArray[$keyGroup][$subGroup][$key], true));
1264                 //* DEBUG: */ print(__METHOD__ . ': count=' . $count . PHP_EOL);
1265                 return $count;
1266         }
1267
1268         /**
1269          * Pushes an element to a generic array element
1270          *
1271          * @param       $keyGroup       Main group for the key
1272          * @param       $subGroup       Sub group for the key
1273          * @param       $key            Key to use
1274          * @param       $element        Element to check
1275          * @param       $value          Value to add/append
1276          * @return      $count          Number of array elements
1277          */
1278         protected final function pushValueToGenericArrayElement (string $keyGroup, string $subGroup, $key, $element, $value) {
1279                 // Debug message
1280                 //* NOISY-DEBUG: */ if (!is_object($value)) $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key . ',element=' . $element . ',value[' . gettype($value) . ']=' . print_r($value, true));
1281
1282                 // Is it set?
1283                 if (!$this->isGenericArrayElementSet($keyGroup, $subGroup, $key, $element)) {
1284                         // Initialize array
1285                         $this->initGenericArrayElement($keyGroup, $subGroup, $key, $element);
1286                 }
1287
1288                 // Then push it
1289                 $count = array_push($this->genericArray[$keyGroup][$subGroup][$key][$element], $value);
1290
1291                 // Return count
1292                 //* DEBUG: */ print(__METHOD__ . ': genericArray=' . print_r($this->genericArray[$keyGroup][$subGroup][$key], true));
1293                 //* DEBUG: */ print(__METHOD__ . ': count=' . $count . PHP_EOL);
1294                 return $count;
1295         }
1296
1297         /**
1298          * Pops an element from  a generic group
1299          *
1300          * @param       $keyGroup       Main group for the key
1301          * @param       $subGroup       Sub group for the key
1302          * @param       $key            Key to unset
1303          * @return      $value          Last "popped" value
1304          */
1305         protected final function popGenericArrayElement (string $keyGroup, string $subGroup, $key) {
1306                 // Debug message
1307                 //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key);
1308
1309                 // Is it set?
1310                 if (!$this->isGenericArrayKeySet($keyGroup, $subGroup, $key)) {
1311                         // Not found
1312                         trigger_error(__METHOD__ . ': keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key . ' not found.');
1313                         exit;
1314                 }
1315
1316                 // Then "pop" it
1317                 $value = array_pop($this->genericArray[$keyGroup][$subGroup][$key]);
1318
1319                 // Return value
1320                 //* DEBUG: */ print(__METHOD__ . ': genericArray=' . print_r($this->genericArray[$keyGroup][$subGroup][$key], true));
1321                 //* DEBUG: */ print(__METHOD__ . ': value[' . gettype($value) . ']=' . print_r($value, true) . PHP_EOL);
1322                 return $value;
1323         }
1324
1325         /**
1326          * Shifts an element from  a generic group
1327          *
1328          * @param       $keyGroup       Main group for the key
1329          * @param       $subGroup       Sub group for the key
1330          * @param       $key            Key to unset
1331          * @return      $value          Last "popped" value
1332          */
1333         protected final function shiftGenericArrayElement (string $keyGroup, string $subGroup, $key) {
1334                 // Debug message
1335                 //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key);
1336
1337                 // Is it set?
1338                 if (!$this->isGenericArrayKeySet($keyGroup, $subGroup, $key)) {
1339                         // Not found
1340                         trigger_error(__METHOD__ . ': keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key . ' not found.');
1341                         exit;
1342                 }
1343
1344                 // Then "shift" it
1345                 $value = array_shift($this->genericArray[$keyGroup][$subGroup][$key]);
1346
1347                 // Return value
1348                 //* DEBUG: */ print(__METHOD__ . ': genericArray=' . print_r($this->genericArray[$keyGroup][$subGroup][$key], true));
1349                 //* DEBUG: */ print(__METHOD__ . ': value[' . gettype($value) . ']=' . print_r($value, true) . PHP_EOL);
1350                 return $value;
1351         }
1352
1353         /**
1354          * Count generic array group
1355          *
1356          * @param       $keyGroup       Main group for the key
1357          * @return      $count          Count of given group
1358          */
1359         protected final function countGenericArray ($keyGroup) {
1360                 // Debug message
1361                 //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup);
1362
1363                 // Is it there?
1364                 if (!isset($this->genericArray[$keyGroup])) {
1365                         // Abort here
1366                         trigger_error(__METHOD__ . ': keyGroup=' . $keyGroup . ' not found.');
1367                         exit;
1368                 }
1369
1370                 // Then count it
1371                 $count = count($this->genericArray[$keyGroup]);
1372
1373                 // Debug message
1374                 //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',count=' . $count);
1375
1376                 // Return it
1377                 return $count;
1378         }
1379
1380         /**
1381          * Count generic array sub group
1382          *
1383          * @param       $keyGroup       Main group for the key
1384          * @param       $subGroup       Sub group for the key
1385          * @return      $count          Count of given group
1386          */
1387         protected final function countGenericArrayGroup (string $keyGroup, string $subGroup) {
1388                 // Debug message
1389                 //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup);
1390
1391                 // Is it there?
1392                 if (!$this->isGenericArrayGroupSet($keyGroup, $subGroup)) {
1393                         // Abort here
1394                         trigger_error(__METHOD__ . ': keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ' not found.');
1395                         exit;
1396                 }
1397
1398                 // Then count it
1399                 $count = count($this->genericArray[$keyGroup][$subGroup]);
1400
1401                 // Debug message
1402                 //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',count=' . $count);
1403
1404                 // Return it
1405                 return $count;
1406         }
1407
1408         /**
1409          * Count generic array elements
1410          *
1411          * @param       $keyGroup       Main group for the key
1412          * @param       $subGroup       Sub group for the key
1413          * @para        $key            Key to count
1414          * @return      $count          Count of given key
1415          */
1416         protected final function countGenericArrayElements (string $keyGroup, string $subGroup, $key) {
1417                 // Debug message
1418                 //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key);
1419
1420                 // Is it there?
1421                 if (!$this->isGenericArrayKeySet($keyGroup, $subGroup, $key)) {
1422                         // Abort here
1423                         trigger_error(__METHOD__ . ': keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ' not found.');
1424                         exit;
1425                 } elseif (!$this->isValidGenericArrayGroup($keyGroup, $subGroup)) {
1426                         // Not valid
1427                         trigger_error(__METHOD__ . ': keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ' is not an array.');
1428                         exit;
1429                 }
1430
1431                 // Then count it
1432                 $count = count($this->genericArray[$keyGroup][$subGroup][$key]);
1433
1434                 // Debug message
1435                 //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key . ',count=' . $count);
1436
1437                 // Return it
1438                 return $count;
1439         }
1440
1441         /**
1442          * Getter for whole generic group array
1443          *
1444          * @param       $keyGroup       Key group to get
1445          * @return      $array          Whole generic array group
1446          */
1447         protected final function getGenericArray ($keyGroup) {
1448                 // Debug message
1449                 //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup);
1450
1451                 // Is it there?
1452                 if (!isset($this->genericArray[$keyGroup])) {
1453                         // Then abort here
1454                         trigger_error(__METHOD__ . ': keyGroup=' . $keyGroup . ' does not exist.');
1455                         exit;
1456                 }
1457
1458                 // Return it
1459                 return $this->genericArray[$keyGroup];
1460         }
1461
1462         /**
1463          * Setter for generic array key
1464          *
1465          * @param       $keyGroup       Key group to get
1466          * @param       $subGroup       Sub group for the key
1467          * @param       $key            Key to unset
1468          * @param       $value          Mixed value from generic array element
1469          * @return      void
1470          */
1471         protected final function setGenericArrayKey (string $keyGroup, string $subGroup, $key, $value) {
1472                 // Debug message
1473                 //* NOISY-DEBUG: */ if (!is_object($value)) $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key . ',value[' . gettype($value) . ']=' . print_r($value, true));
1474
1475                 // Set value here
1476                 $this->genericArray[$keyGroup][$subGroup][$key] = $value;
1477         }
1478
1479         /**
1480          * Getter for generic array key
1481          *
1482          * @param       $keyGroup       Key group to get
1483          * @param       $subGroup       Sub group for the key
1484          * @param       $key            Key to unset
1485          * @return      $value          Mixed value from generic array element
1486          */
1487         protected final function getGenericArrayKey (string $keyGroup, string $subGroup, $key) {
1488                 // Debug message
1489                 //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key);
1490
1491                 // Is it there?
1492                 if (!$this->isGenericArrayKeySet($keyGroup, $subGroup, $key)) {
1493                         // Then abort here
1494                         trigger_error(__METHOD__ . ': keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key . ' does not exist.');
1495                         exit;
1496                 }
1497
1498                 // Return it
1499                 return $this->genericArray[$keyGroup][$subGroup][$key];
1500         }
1501
1502         /**
1503          * Sets a value in given generic array key/element
1504          *
1505          * @param       $keyGroup       Main group for the key
1506          * @param       $subGroup       Sub group for the key
1507          * @param       $key            Key to set
1508          * @param       $element        Element to set
1509          * @param       $value          Value to set
1510          * @return      void
1511          */
1512         protected final function setGenericArrayElement (string $keyGroup, string $subGroup, $key, $element, $value) {
1513                 // Debug message
1514                 //* NOISY-DEBUG: */ if (!is_object($value)) $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key . ',element=' . $element . ',value[' . gettype($value) . ']=' . print_r($value, true));
1515
1516                 // Then set it
1517                 $this->genericArray[$keyGroup][$subGroup][$key][$element] = $value;
1518         }
1519
1520         /**
1521          * Getter for generic array element
1522          *
1523          * @param       $keyGroup       Key group to get
1524          * @param       $subGroup       Sub group for the key
1525          * @param       $key            Key to look for
1526          * @param       $element        Element to look for
1527          * @return      $value          Mixed value from generic array element
1528          */
1529         protected final function getGenericArrayElement (string $keyGroup, string $subGroup, $key, $element) {
1530                 // Debug message
1531                 //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key . ',element=' . $element);
1532
1533                 // Is it there?
1534                 if (!$this->isGenericArrayElementSet($keyGroup, $subGroup, $key, $element)) {
1535                         // Then abort here
1536                         trigger_error(__METHOD__ . ': keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key . ',element=' . $element . ' does not exist.');
1537                         exit;
1538                 }
1539
1540                 // Return it
1541                 return $this->genericArray[$keyGroup][$subGroup][$key][$element];
1542         }
1543
1544         /**
1545          * Checks if a given sub group is valid (array)
1546          *
1547          * @param       $keyGroup       Key group to get
1548          * @param       $subGroup       Sub group for the key
1549          * @return      $isValid        Whether given sub group is valid
1550          */
1551         protected final function isValidGenericArrayGroup (string $keyGroup, string $subGroup) {
1552                 // Debug message
1553                 //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup);
1554
1555                 // Determine it
1556                 $isValid = (($this->isGenericArrayGroupSet($keyGroup, $subGroup)) && (is_array($this->getGenericSubArray($keyGroup, $subGroup))));
1557
1558                 // Return it
1559                 return $isValid;
1560         }
1561
1562         /**
1563          * Checks if a given key is valid (array)
1564          *
1565          * @param       $keyGroup       Key group to get
1566          * @param       $subGroup       Sub group for the key
1567          * @param       $key            Key to check
1568          * @return      $isValid        Whether given sub group is valid
1569          */
1570         protected final function isValidGenericArrayKey (string $keyGroup, string $subGroup, $key) {
1571                 // Debug message
1572                 //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key);
1573
1574                 // Determine it
1575                 $isValid = (($this->isGenericArrayKeySet($keyGroup, $subGroup, $key)) && (is_array($this->getGenericArrayKey($keyGroup, $subGroup, $key))));
1576
1577                 // Return it
1578                 return $isValid;
1579         }
1580
1581         /**
1582          * Initializes the web output instance
1583          *
1584          * @return      void
1585          */
1586         protected function initWebOutputInstance () {
1587                 // Init web output instance
1588                 $outputInstance = ObjectFactory::createObjectByConfiguredName('output_class');
1589
1590                 // Set it locally
1591                 $this->setWebOutputInstance($outputInstance);
1592         }
1593
1594         /**
1595          * Translates boolean true to 'Y' and false to 'N'
1596          *
1597          * @param       $boolean                Boolean value
1598          * @return      $translated             Translated boolean value
1599          */
1600         public static final function translateBooleanToYesNo (bool $boolean) {
1601                 // Make sure it is really boolean
1602                 assert(is_bool($boolean));
1603
1604                 // "Translate" it
1605                 $translated = ($boolean === true) ? 'Y' : 'N';
1606
1607                 // ... and return it
1608                 return $translated;
1609         }
1610
1611         /**
1612          * Creates a full-qualified file name (FQFN) for given file name by adding
1613          * a configured temporary file path to it.
1614          *
1615          * @param       $infoInstance   An instance of a SplFileInfo class
1616          * @return      $tempInstance   An instance of a SplFileInfo class (temporary file)
1617          * @throw       PathWriteProtectedException If the path in 'temp_file_path' is write-protected
1618          * @throws      FileIoException If the file cannot be written
1619          */
1620          protected static function createTempPathForFile (SplFileInfo $infoInstance) {
1621                 // Get config entry
1622                 $basePath = FrameworkBootstrap::getConfigurationInstance()->getConfigEntry('temp_file_path');
1623
1624                 // Is the path writeable?
1625                 if (!is_writable($basePath)) {
1626                         // Path is write-protected
1627                         throw new PathWriteProtectedException($infoInstance, self::EXCEPTION_PATH_CANNOT_BE_WRITTEN);
1628                 }
1629
1630                 // Add it
1631                 $tempInstance = new SplFileInfo($basePath . DIRECTORY_SEPARATOR . $infoInstance->getBasename());
1632
1633                 // Is it reachable?
1634                 if (!FrameworkBootstrap::isReachableFilePath($tempInstance)) {
1635                         // Not reachable
1636                         throw new FileIoException($tempInstance, self::EXCEPTION_FILE_NOT_REACHABLE);
1637                 }
1638
1639                 // Return it
1640                 return $tempInstance;
1641          }
1642
1643         /**
1644          * "Getter" for a printable state name
1645          *
1646          * @return      $stateName      Name of the node's state in a printable format
1647          * @todo        Move this class away from this monolithic place (not whole class is monolithic)
1648          */
1649         public final function getPrintableState () {
1650                 // Default is 'null'
1651                 $stateName = 'null';
1652
1653                 // Get the state instance
1654                 $stateInstance = $this->getStateInstance();
1655
1656                 // Is it an instance of Stateable?
1657                 if ($stateInstance instanceof Stateable) {
1658                         // Then use that state name
1659                         $stateName = $stateInstance->getStateName();
1660                 }
1661
1662                 // Return result
1663                 return $stateName;
1664         }
1665
1666 }