3 namespace Org\Mxchange\CoreFramework\Object;
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\Object\ObjectRegistry;
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;
25 use \BadMethodCallException;
26 use \InvalidArgumentException;
32 * The simulator system class is the super class of all other classes. This
33 * class handles saving of games etc.
35 * @author Roland Haeder <webmaster@shipsimu.org>
37 * @copyright Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2023 Core Developer Team
38 * @license GNU GPL 3.0 or any newer version
39 * @link http://www.shipsimu.org
41 * This program is free software: you can redistribute it and/or modify
42 * it under the terms of the GNU General Public License as published by
43 * the Free Software Foundation, either version 3 of the License, or
44 * (at your option) any later version.
46 * This program is distributed in the hope that it will be useful,
47 * but WITHOUT ANY WARRANTY; without even the implied warranty of
48 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
49 * GNU General Public License for more details.
51 * You should have received a copy of the GNU General Public License
52 * along with this program. If not, see <http://www.gnu.org/licenses/>.
54 abstract class BaseFrameworkSystem extends stdClass implements FrameworkInterface {
56 * Self-referencing instance
58 private static $selfInstance = NULL;
63 private static $debugInstance = NULL;
68 private static $stubMethods = [
69 'partialStub' => true,
71 '__callStatic' => true,
77 private $realClass = __CLASS__;
82 private $callbackInstance = NULL;
87 private $genericArray = [];
89 /***********************
90 * Exception codes.... *
91 ***********************/
93 // @todo Try to clean these constants up
94 const EXCEPTION_IS_NULL_POINTER = 0x001;
95 const EXCEPTION_IS_NO_OBJECT = 0x002;
96 const EXCEPTION_IS_NO_ARRAY = 0x003;
97 const EXCEPTION_MISSING_METHOD = 0x004;
98 const EXCEPTION_CLASSES_NOT_MATCHING = 0x005;
99 const EXCEPTION_INDEX_OUT_OF_BOUNDS = 0x006;
100 const EXCEPTION_DIMENSION_ARRAY_INVALID = 0x007;
101 const EXCEPTION_ITEM_NOT_TRADEABLE = 0x008;
102 const EXCEPTION_ITEM_NOT_IN_PRICE_LIST = 0x009;
103 const EXCEPTION_GENDER_IS_WRONG = 0x00a;
104 const EXCEPTION_BIRTH_DATE_IS_INVALID = 0x00b;
105 const EXCEPTION_EMPTY_STRUCTURES_ARRAY = 0x00c;
106 const EXCEPTION_HAS_ALREADY_PERSONELL_LIST = 0x00d;
107 const EXCEPTION_NOT_ENOUGTH_UNEMPLOYEES = 0x00e;
108 const EXCEPTION_TOTAL_PRICE_NOT_CALCULATED = 0x00f;
109 const EXCEPTION_HARBOR_HAS_NO_SHIPYARDS = 0x010;
110 const EXCEPTION_CONTRACT_PARTNER_INVALID = 0x011;
111 const EXCEPTION_CONTRACT_PARTNER_MISMATCH = 0x012;
112 const EXCEPTION_CONTRACT_ALREADY_SIGNED = 0x013;
113 const EXCEPTION_UNEXPECTED_EMPTY_STRING = 0x014;
114 const EXCEPTION_PATH_NOT_FOUND = 0x015;
115 const EXCEPTION_INVALID_PATH_NAME = 0x016;
116 const EXCEPTION_READ_PROTECED_PATH = 0x017;
117 const EXCEPTION_WRITE_PROTECED_PATH = 0x018;
118 const EXCEPTION_DIR_POINTER_INVALID = 0x019;
119 const EXCEPTION_FILE_POINTER_INVALID = 0x01a;
120 const EXCEPTION_INVALID_RESOURCE = 0x01b;
121 const EXCEPTION_LIMIT_ELEMENT_IS_UNSUPPORTED = 0x01d;
122 const EXCEPTION_GETTER_IS_MISSING = 0x01e;
123 const EXCEPTION_ARRAY_EXPECTED = 0x01f;
124 const EXCEPTION_ARRAY_HAS_INVALID_COUNT = 0x020;
125 const EXCEPTION_ID_IS_INVALID_FORMAT = 0x021;
126 const EXCEPTION_MD5_CHECKSUMS_MISMATCH = 0x022;
127 const EXCEPTION_UNEXPECTED_STRING_SIZE = 0x023;
128 const EXCEPTION_SIMULATOR_ID_INVALID = 0x024;
129 const EXCEPTION_MISMATCHING_COMPRESSORS = 0x025;
130 const EXCEPTION_CONTAINER_ITEM_IS_NULL = 0x026;
131 const EXCEPTION_ITEM_IS_NO_ARRAY = 0x027;
132 const EXCEPTION_CONTAINER_MAYBE_DAMAGED = 0x028;
133 const EXCEPTION_INVALID_STRING = 0x029;
134 const EXCEPTION_VARIABLE_NOT_SET = 0x02a;
135 const EXCEPTION_ATTRIBUTES_ARE_MISSING = 0x02b;
136 const EXCEPTION_ARRAY_ELEMENTS_MISSING = 0x02c;
137 const EXCEPTION_TEMPLATE_ENGINE_UNSUPPORTED = 0x02d;
138 const EXCEPTION_FACTORY_REQUIRE_PARAMETER = 0x02e;
139 const EXCEPTION_MISSING_ELEMENT = 0x02f;
140 const EXCEPTION_HEADERS_ALREADY_SENT = 0x030;
141 const EXCEPTION_DEFAULT_CONTROLLER_GONE = 0x031;
142 const EXCEPTION_REQUIRED_INTERFACE_MISSING = 0x033;
143 const EXCEPTION_FATAL_ERROR = 0x034;
144 const EXCEPTION_FILE_NOT_FOUND = 0x035;
145 const EXCEPTION_ASSERTION_FAILED = 0x036;
146 const EXCEPTION_FILE_NOT_REACHABLE = 0x037;
147 const EXCEPTION_FILE_CANNOT_BE_READ = 0x038;
148 const EXCEPTION_FILE_CANNOT_BE_WRITTEN = 0x039;
149 const EXCEPTION_PATH_CANNOT_BE_WRITTEN = 0x03a;
150 const EXCEPTION_DATABASE_UPDATED_NOT_ALLOWED = 0x03b;
151 const EXCEPTION_FILTER_CHAIN_INTERCEPTED = 0x03c;
152 const EXCEPTION_INVALID_SOCKET = 0x03d;
153 const EXCEPTION_SELF_INSTANCE = 0x03e;
156 * Startup time in miliseconds
158 private static $startupTime = 0;
161 * Protected super constructor
163 * @param $className Name of the class
166 protected function __construct (string $className) {
168 $this->setRealClass($className);
170 // Is the startup time set? (0 cannot be true anymore)
171 if (self::$startupTime == 0) {
173 self::$startupTime = microtime(true);
178 * Destructor for all classes. You should not call this method on your own.
182 public function __destruct () {
183 // Is this object already destroyed?
184 if ($this->__toString() != 'DestructedObject') {
185 // Destroy all informations about this class but keep some text about it alive
186 $this->setRealClass('DestructedObject');
187 } elseif ((defined('DEBUG_DESTRUCTOR')) && (is_object($this->getDebugInstance()))) {
188 // Already destructed object
189 self::createDebugInstance(__CLASS__, __LINE__)->warningMessage(sprintf('The object <span class="object_name">%s</span> is already destroyed.',
193 // Do not call this twice
194 trigger_error(__METHOD__ . ': Called twice.');
200 * The __call() method where all non-implemented methods end up
202 * @param $methodName Name of the missing method
203 * @args $args Arguments passed to the method
206 public final function __call (string $methodName, array $args = NULL) {
208 self::$selfInstance = $this;
210 // Call static method
211 self::__callStatic($methodName, $args);
213 // Clear self-instance
214 self::$selfInstance = NULL;
218 * The __callStatic() method where all non-implemented static methods end up
220 * @param $methodName Name of the missing method
221 * @param $args Arguments passed to the method
223 * @throws InvalidArgumentException If self::$selfInstance is not a framework's own object
225 public static final function __callStatic (string $methodName, array $args = NULL) {
226 // Init argument string and class name
227 //* PRINT-DEBUG: */ printf('[%s:%d]: methodName=%s,args[]=%s - CALLED!' . PHP_EOL, __METHOD__, __LINE__, $methodName, gettype($args));
229 $className = 'unknown';
231 // Is self-instance set?
232 if (self::$selfInstance instanceof FrameworkInterface) {
233 // Framework's own instance
234 $className = self::$selfInstance->__toString();
235 } elseif (!is_null(self::$selfInstance)) {
237 throw new InvalidArgumentException(sprintf('self::instance[%s] is not expected.', gettype(self::$selfInstance)), self::EXCEPTION_SELF_INSTANCE);
240 // Is it NULL, empty or an array?
241 if (is_null($args)) {
243 $argsString = 'NULL';
244 } elseif (is_array($args)) {
248 // Some arguments are there
249 foreach ($args as $arg) {
250 // Add data about the argument
251 $argsString .= gettype($arg) . ':';
254 // Found a NULL argument
255 $argsString .= 'NULL';
256 } elseif (is_string($arg)) {
257 // Add length for strings
258 $argsString .= strlen($arg);
259 } elseif ((is_int($arg)) || (is_float($arg))) {
262 } elseif (is_array($arg)) {
263 // .. or size if array
264 $argsString .= count($arg);
265 } elseif (is_object($arg)) {
267 $reflection = new ReflectionClass($arg);
269 // Is an other object, maybe no __toString() available
270 $argsString .= $reflection->getName();
271 } elseif ($arg === true) {
272 // ... is boolean 'true'
273 $argsString .= 'true';
274 } elseif ($arg === false) {
275 // ... is boolean 'false'
276 $argsString .= 'false';
279 // Comma for next one
284 if (substr($argsString, -2, 1) == ',') {
286 $argsString = substr($argsString, 0, -2);
293 // Output stub message
294 // @TODO __CLASS__ does always return BaseFrameworkSystem but not the extending (=child) class
295 self::createDebugInstance(__CLASS__, __LINE__)->warningMessage(sprintf('[%s::%s]: Stub! Args: %s',
306 * Getter for $realClass
308 * @return $realClass The name of the real class (not BaseFrameworkSystem)
310 public function __toString () {
311 return $this->realClass;
315 * Magic method to catch setting of missing but set class fields/attributes
317 * @param $name Name of the field/attribute
318 * @param $value Value to store
321 public final function __set (string $name, $value) {
322 $this->debugBackTrace(sprintf('Tried to set a missing field. name=%s, value[%s]=%s',
325 print_r($value, true)
330 * Magic method to catch getting of missing fields/attributes
332 * @param $name Name of the field/attribute
335 public final function __get (string $name) {
336 $this->debugBackTrace(sprintf('Tried to get a missing field. name=%s',
342 * Magic method to catch unsetting of missing fields/attributes
344 * @param $name Name of the field/attribute
347 public final function __unset (string $name) {
348 $this->debugBackTrace(sprintf('Tried to unset a missing field. name=%s',
354 * Magic method to catch object serialization
356 * @return $unsupported Unsupported method
357 * @throws UnsupportedOperationException Objects of this framework cannot be serialized
359 public final function __sleep () {
360 throw new UnsupportedOperationException([$this, __FUNCTION__], FrameworkInterface::EXCEPTION_UNSPPORTED_OPERATION);
364 * Magic method to catch object deserialization
366 * @return $unsupported Unsupported method
367 * @throws UnsupportedOperationException Objects of this framework cannot be serialized
369 public final function __wakeup () {
370 throw new UnsupportedOperationException([$this, __FUNCTION__], FrameworkInterface::EXCEPTION_UNSPPORTED_OPERATION);
374 * Magic method to catch calls when an object instance is called
376 * @return $unsupported Unsupported method
377 * @throws UnsupportedOperationException Objects of this framework cannot be serialized
379 public final function __invoke () {
380 throw new UnsupportedOperationException([$this, __FUNCTION__], FrameworkInterface::EXCEPTION_UNSPPORTED_OPERATION);
384 * Setter for the real class name
386 * @param $realClass Class name (string)
389 public final function setRealClass (string $realClass) {
391 $this->realClass = $realClass;
395 * Setter for debug instance
397 * @param $debugInstance The instance for debug output class
400 public final function setDebugInstance (DebugMiddleware $debugInstance) {
401 self::$debugInstance = $debugInstance;
405 * Getter for debug instance
407 * @return $debugInstance Instance to class DebugConsoleOutput or DebugWebOutput
409 public final function getDebugInstance () {
410 return self::$debugInstance;
414 * Setter for web output instance
416 * @param $webInstance The instance for web output class
419 public final function setWebOutputInstance (OutputStreamer $webInstance) {
420 ObjectRegistry::getRegistry('generic')->addInstance('web_output', $webInstance);
424 * Getter for web output instance
426 * @return $webOutputInstance - Instance to class WebOutput
428 public final function getWebOutputInstance () {
429 return ObjectRegistry::getRegistry('generic')->getInstance('web_output');
433 * Setter for call-back instance
435 * @param $callbackInstance An instance of a FrameworkInterface class
438 public final function setCallbackInstance (FrameworkInterface $callbackInstance) {
439 $this->callbackInstance = $callbackInstance;
443 * Getter for call-back instance
445 * @return $callbackInstance An instance of a FrameworkInterface class
447 protected final function getCallbackInstance () {
448 return $this->callbackInstance;
452 * Checks whether an object equals this object. You should overwrite this
453 * method to implement own equality checks
455 * @param $objectInstance An instance of a FrameworkInterface object
456 * @return $equals Whether both objects equals
458 public function equals (FrameworkInterface $objectInstance) {
461 $this->__toString() == $objectInstance->__toString()
463 $this->hashCode() == $objectInstance->hashCode()
471 * Generates a generic hash code of this class. You should really overwrite
472 * this method with your own hash code generator code. But keep KISS in mind.
474 * @return $hashCode A generic hash code respresenting this whole class
476 public function hashCode () {
478 return crc32($this->__toString());
482 * Appends a trailing slash to a string
484 * @param $str A string (maybe) without trailing slash
485 * @return $str A string with an auto-appended trailing slash
486 * @throws InvalidArgumentException If a paramter has an invalid value
488 public final function addMissingTrailingSlash (string $str) {
490 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-FRAMEWORK-SYSTEM: str=%s - CALLED!', $str));
493 throw new InvalidArgumentException('Parameter "str" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
496 // Is there a trailing slash?
497 if (substr($str, -1, 1) != '/') {
501 // Return string with trailing slash
502 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-FRAMEWORK-SYSTEM: str=%s - EXIT!', $str));
507 * Debugs this instance by putting out it's full content
509 * @param $message Optional message to show in debug output
511 * @throws InvalidArgumentException If a paramter has an invalid value
513 public final function debugInstance (string $message = '') {
515 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-FRAMEWORK-SYSTEM: message=%s - CALLED!', $message));
516 if (empty($message)) {
518 throw new InvalidArgumentException('Parameter "message" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
521 // Restore the error handler to avoid trouble with missing array elements or undeclared variables
522 restore_error_handler();
528 if (!empty($message)) {
530 $content = sprintf('<div class="debug_message">
532 </div>' . PHP_EOL, $message);
535 // Generate the output
536 $content .= sprintf('<pre>%s</pre>',
545 ApplicationEntryPoint::exitApplication(sprintf('<div class="debug_header">
548 <div class="debug_content">
552 <div class="debug_include_list">
557 ClassLoader::getSelfInstance()->getPrintableIncludeList()
562 * Outputs a debug backtrace and stops further script execution
564 * @param $message An optional message to output
565 * @param $doExit Whether exit the program (true is default)
567 * @throws InvalidArgumentException If a paramter has an invalid value
569 public function debugBackTrace (string $message = '', bool $doExit = true) {
571 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-FRAMEWORK-SYSTEM: message=%s,doExit=%d - CALLED!', $message, intval($doExit)));
572 if (empty($message)) {
574 throw new InvalidArgumentException('Parameter "message" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
577 // Sorry, there is no other way getting this nice backtrace
578 if (!empty($message)) {
580 printf('Message: %s<br />' . PHP_EOL, $message);
584 debug_print_backtrace();
588 if ($doExit === true) {
589 // Yes, with error code
595 * Creates an instance of a debugger instance
597 * @param $className Name of the class (currently unsupported)
598 * @param $lineNumber Line number where the call was made
599 * @return $debugInstance An instance of a debugger class
600 * @throws InvalidArgumentException If a parameter has an invalid value
601 * @deprecated Not fully, as the new Logger facilities are not finished yet.
603 public final static function createDebugInstance (string $className, int $lineNumber = NULL) {
604 // Validate parameter
605 //* NOISY-DEBUG: */ printf('[%s:%d]: className=%s,lineNumber[%s]=%d - CALLED!' . PHP_EOL, __METHOD__, __LINE__, $className, gettype($lineNumber), $lineNumber);
606 if (empty($className)) {
608 throw new InvalidArgumentException('Parameter "className" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
611 // Is the debug instance set?
612 //* NOISY-DEBUG: */ printf('[%s:%d]: self::debugInstance[]=%s' . PHP_EOL, __METHOD__, __LINE__, gettype(self::$debugInstance));
613 if (is_null(self::$debugInstance)) {
614 // Init debug instance
615 self::$debugInstance = NULL;
619 // Get a debugger instance
620 //* NOISY-DEBUG: */ printf('[%s:%d]: className=%s' . PHP_EOL, __METHOD__, __LINE__, $className);
621 self::$debugInstance = DebugMiddleware::createDebugMiddleware(FrameworkBootstrap::getConfigurationInstance()->getConfigEntry('debug_' . FrameworkBootstrap::getRequestTypeFromSystem() . '_class'), $className);
622 } catch (NullPointerException $e) {
623 // Didn't work, no instance there
624 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));
629 //* NOISY-DEBUG: */ printf('[%s:%d]: self::debugInstance=%s - EXIT!' . PHP_EOL, __METHOD__, __LINE__, self::$debugInstance->__toString());
630 return self::$debugInstance;
634 * Simple output of a message with line-break
636 * @param $message Message to output
638 * @throws InvalidArgumentException If a paramter has an invalid value
640 public function outputLine (string $message) {
642 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-FRAMEWORK-SYSTEM: message=%s - CALLED!', $message));
643 if (empty($message)) {
645 throw new InvalidArgumentException('Parameter "message" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
649 print($message . PHP_EOL);
653 * Marks up the code by adding e.g. line numbers
655 * @param $phpCode Unmarked PHP code
656 * @return $markedCode Marked PHP code
657 * @throws InvalidArgumentException If a paramter has an invalid value
659 public function markupCode (string $phpCode) {
661 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-FRAMEWORK-SYSTEM: phpCode=%s - CALLED!', $phpCode));
662 if (empty($phpCode)) {
664 throw new InvalidArgumentException('Parameter "phpCode" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
671 $errorArray = error_get_last();
673 // Init the code with error message
674 if (is_array($errorArray)) {
676 $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>',
677 basename($errorArray['file']),
679 $errorArray['message'],
684 // Add line number to the code
685 foreach (explode(chr(10), $phpCode) as $lineNo => $code) {
687 $markedCode .= sprintf('<span id="code_line">%s</span>: %s' . PHP_EOL,
689 htmlentities($code, ENT_QUOTES)
698 * "Getter" for databse entry
700 * @return $entry An array with database entries
701 * @throws NullPointerException If the database result is not found
702 * @throws InvalidDatabaseResultException If the database result is invalid
703 * @deprecated Monolithic method, should be moved to proper classes
705 protected final function getDatabaseEntry () {
706 // This method is deprecated
707 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-FRAMEWORK-SYSTEM: CALLED!');
708 $this->deprecationWarning('Monolithic method, should be moved to proper classes');
710 // Is there an instance?
711 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-FRAMEWORK-SYSTEM: this->resultInstance[]=%s', gettype($this->getResultInstance())));
712 if (!$this->getResultInstance() instanceof SearchableResult) {
713 // Throw an exception here
714 throw new NullPointerException($this, self::EXCEPTION_IS_NULL_POINTER);
718 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-FRAMEWORK-SYSTEM: Invoking this->resultInstance->rewind() ...');
719 $this->getResultInstance()->rewind();
721 // Do we have an entry?
722 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-FRAMEWORK-SYSTEM: this->resultInstance->isValid()=%d', intval($this->getResultInstance()->isValid())));
723 if ($this->getResultInstance()->valid() === false) {
724 // @TODO Move the constant to e.g. BaseDatabaseResult when there is a non-cached database result available
725 throw new InvalidDatabaseResultException(array($this, $this->getResultInstance()), CachedDatabaseResult::EXCEPTION_INVALID_DATABASE_RESULT);
729 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-FRAMEWORK-SYSTEM: Invoking this->resultInstance->next() ...');
730 $this->getResultInstance()->next();
733 $entry = $this->getResultInstance()->current();
736 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: entry[]=%s - EXIT!', gettype($entry)));
741 * Getter for field name
743 * @param $fieldName Field name which we shall get
744 * @return $fieldValue Field value from the user
745 * @throws NullPointerException If the result instance is null
746 * @throws InvalidArgumentException If a parameter is not valid
747 * @deprecated Monolithic method, should be moved to proper classes
749 public final function getField (string $fieldName) {
751 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: fieldName=%s - CALLED!', $fieldName));
752 if (empty($fieldName)) {
754 throw new InvalidArgumentException('Parameter "fieldName" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
757 // This method is deprecated
758 $this->deprecationWarning('Monolithic method, should be moved to proper classes');
760 // Default field value
763 // Get result instance
764 $resultInstance = $this->getResultInstance();
766 // Is this instance null?
767 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-FRAMEWORK-SYSTEM: resultInstance[]=%s', gettype($resultInstance)));
768 if (is_null($resultInstance)) {
769 // Then the user instance is no longer valid (expired cookies?)
770 throw new NullPointerException($this, self::EXCEPTION_IS_NULL_POINTER);
774 $fieldArray = $resultInstance->current();
776 // Convert dashes to underscore
777 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-FRAMEWORK-SYSTEM: fieldArray()=%d', count($fieldArray)));
778 $fieldName2 = StringUtils::convertDashesToUnderscores($fieldName);
780 // Does the field exist?
781 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-FRAMEWORK-SYSTEM: fieldName2=%s', $fieldName2));
782 if ($this->isFieldSet($fieldName)) {
784 $fieldValue = $fieldArray[$fieldName2];
785 } elseif (FrameworkBootstrap::getConfigurationInstance()->isEnabled('developer_mode')) {
786 // Missing field entry, may require debugging
787 self::createDebugInstance(__CLASS__, __LINE__)->warningMessage('BASE-FRAMEWORK-SYSTEM: fieldArray<pre>=' . print_r($fieldArray, true) . '</pre>,fieldName=' . $fieldName . ' not found!');
789 // Missing field entry, may require debugging
790 self::createDebugInstance(__CLASS__, __LINE__)->warningMessage('BASE-FRAMEWORK-SYSTEM: fieldName=' . $fieldName . ' not found!');
794 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: fieldValue[]=%s - EXIT!', gettype($fieldValue)));
799 * Checks if given field is set
801 * @param $fieldName Field name to check
802 * @return $isSet Whether the given field name is set
803 * @throws NullPointerException If the result instance is null
804 * @throws InvalidArgumentException If a parameter is not valid
806 public function isFieldSet (string $fieldName) {
808 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: fieldName=%s - CALLED!', $fieldName));
809 if (empty($fieldName)) {
811 throw new InvalidArgumentException('Parameter "fieldName" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
814 // Get result instance
815 $resultInstance = $this->getResultInstance();
817 // Is this instance null?
818 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-FRAMEWORK-SYSTEM: resultInstance[]=%s', gettype($resultInstance)));
819 if (is_null($resultInstance)) {
820 // Then the user instance is no longer valid (expired cookies?)
821 throw new NullPointerException($this, self::EXCEPTION_IS_NULL_POINTER);
825 $fieldArray = $resultInstance->current();
827 // Convert dashes to underscore
828 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-FRAMEWORK-SYSTEM: fieldArray()=%d,fieldName=%s - BEFORE!', count($fieldArray), $fieldName));
829 $fieldName = StringUtils::convertDashesToUnderscores($fieldName);
832 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-FRAMEWORK-SYSTEM: fieldName=%s - AFTER!', $fieldName));
833 $isset = isset($fieldArray[$fieldName]);
836 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: isset=%d - EXIT!', intval($isset)));
841 * Outputs a deprecation warning to the developer.
843 * @param $message The message we shall output to the developer
845 * @throws InvalidArgumentException If a paramter has an invalid value
846 * @todo Write a logging mechanism for productive mode
848 public function deprecationWarning (string $message) {
850 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: message=%s - CALLED!', $message));
851 if (empty($message)) {
853 throw new InvalidArgumentException('Parameter "message" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
856 // Is developer mode active?
857 if (FrameworkBootstrap::getConfigurationInstance()->isEnabled('developer_mode')) {
858 // Debug instance is there?
859 if (!is_null($this->getDebugInstance())) {
860 // Output stub message
861 self::createDebugInstance(__CLASS__, __LINE__)->warningMessage($message);
864 trigger_error($message . "<br />\n");
868 // @TODO Finish this part!
869 DebugMiddleware::getSelfInstance()->partialStub('Developer mode inactive. Message:' . $message);
873 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-FRAMEWORK-SYSTEM: EXIT!');
877 * Checks whether the given PHP extension is loaded
879 * @param $phpExtension The PHP extension we shall check
880 * @return $isLoaded Whether the PHP extension is loaded
881 * @throws InvalidArgumentException If a parameter is not valid
883 public final function isPhpExtensionLoaded (string $phpExtension) {
885 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: phpExtension=%s - CALLED!', $phpExtension));
886 if (empty($phpExtension)) {
888 throw new InvalidArgumentException('Parameter "phpExtension" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
892 $isLoaded = in_array($phpExtension, get_loaded_extensions());
895 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: isLoaded=%d - EXIT!', intval($isLoaded)));
900 * "Getter" as a time() replacement but with milliseconds. You should use this
901 * method instead of the encapsulated getimeofday() function.
903 * @return $milliTime Timestamp with milliseconds
905 public function getMilliTime () {
906 // Get the time of day as float
907 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-FRAMEWORK-SYSTEM: CALLED!');
908 $milliTime = gettimeofday(true);
911 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: milliTime=%s - EXIT!', $milliTime));
916 * Idles (sleeps) for given milliseconds
918 * @return $hasSlept Whether it goes fine
919 * @throws InvalidArgumentException If a parameter is not valid
921 public function idle (int $milliSeconds) {
923 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: milliSeconds=%s - CALLED!', $milliSeconds));
924 if ($milliSeconds < 1) {
926 throw new InvalidArgumentException(sprintf('milliSeconds=%d are not a reasonable value to idle', $milliSeconds));
929 // Sleep is fine by default
932 // Idle so long with found function
933 if (function_exists('time_sleep_until')) {
934 // Get current time and add idle time
935 $sleepUntil = $this->getMilliTime() + abs($milliSeconds) / 1000;
937 // New PHP 5.1.0 function found, ignore errors
938 $hasSlept = @time_sleep_until($sleepUntil);
941 * My Sun station doesn't have that function even with latest PHP
944 usleep($milliSeconds * 1000);
948 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: hasSlept=%d - EXIT!', intval($hasSlept)));
953 * Checks whether the given encoded data was encoded with Base64
955 * @param $encodedData Encoded data we shall check
956 * @return $isBase64 Whether the encoded data is Base64
957 * @throws InvalidArgumentException If a parameter is not valid
959 protected function isBase64Encoded (string $encodedData) {
961 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: encodedData=%s - CALLED!', $encodedData));
962 if (empty($encodedData)) {
964 throw new InvalidArgumentException('Parameter "encodedData" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
968 $isBase64 = (@base64_decode($encodedData, true) !== false);
971 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: isBase64=%d - EXIT!', intval($isBase64)));
976 * Getter for startup time in miliseconds
978 * @return $startupTime Startup time in miliseconds
980 protected function getStartupTime () {
981 return self::$startupTime;
985 * "Getter" for a printable currently execution time in nice braces
987 * @return $executionTime Current execution time in nice braces
989 protected function getPrintableExecutionTime () {
990 // Calculate execution time and pack it in nice braces
991 $executionTime = sprintf('[ %01.5f ] ', (microtime(true) - $this->getStartupTime()));
994 return $executionTime;
998 * Determines if an element is set in the generic array
1000 * @param $keyGroup Main group for the key
1001 * @param $subGroup Sub group for the key
1002 * @param $key Key to check
1003 * @param $element Element to check
1004 * @return $isset Whether the given key is set
1005 * @throws InvalidArgumentException If a parameter is not valid
1007 protected final function isGenericArrayElementSet (string $keyGroup, string $subGroup, string $key, string $element) {
1009 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: keyGroup=%s,subGroup=%s,key=%s,element=%s - CALLED!', $keyGroup, $subGroup, $key, $element));
1010 if (empty($keyGroup)) {
1012 throw new InvalidArgumentException('Parameter "keyGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1013 } elseif (empty($subGroup)) {
1015 throw new InvalidArgumentException('Parameter "subGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1016 } elseif (empty($key)) {
1018 throw new InvalidArgumentException('Parameter "key" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1019 } elseif ($element === '') {
1021 throw new InvalidArgumentException('Parameter "element" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1025 $isset = isset($this->genericArray[$keyGroup][$subGroup][$key][$element]);
1028 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: isset=%d - EXIT!', intval($isset)));
1032 * Determines if a key is set in the generic array
1034 * @param $keyGroup Main group for the key
1035 * @param $subGroup Sub group for the key
1036 * @param $key Key to check
1037 * @return $isset Whether the given key is set
1038 * @throws InvalidArgumentException If a parameter is not valid
1040 protected final function isGenericArrayKeySet (string $keyGroup, string $subGroup, string $key) {
1042 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: keyGroup=%s,subGroup=%s,key=%s - CALLED!', $keyGroup, $subGroup, $key));
1043 if (empty($keyGroup)) {
1045 throw new InvalidArgumentException('Parameter "keyGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1046 } elseif (empty($subGroup)) {
1048 throw new InvalidArgumentException('Parameter "subGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1049 } elseif (empty($key)) {
1051 throw new InvalidArgumentException('Parameter "key" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1055 $isset = isset($this->genericArray[$keyGroup][$subGroup][$key]);
1058 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: isset=%d - EXIT!', intval($isset)));
1063 * Determines if a group is set in the generic array
1065 * @param $keyGroup Main group
1066 * @param $subGroup Sub group
1067 * @return $isset Whether the given group is set
1068 * @throws InvalidArgumentException If a parameter is not valid
1070 protected final function isGenericArrayGroupSet (string $keyGroup, string $subGroup) {
1072 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: keyGroup=%s,subGroup=%s - CALLED!', $keyGroup, $subGroup));
1073 if (empty($keyGroup)) {
1075 throw new InvalidArgumentException('Parameter "keyGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1076 } elseif (empty($subGroup)) {
1078 throw new InvalidArgumentException('Parameter "subGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1082 $isset = isset($this->genericArray[$keyGroup][$subGroup]);
1085 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: isset=%d - EXIT!', intval($isset)));
1090 * Getter for sub key group
1092 * @param $keyGroup Main key group
1093 * @param $subGroup Sub key group
1094 * @return $array An array with all array elements
1095 * @throws InvalidArgumentException If a parameter is not valid
1096 * @throws BadMethodCallException If key/sub group isn't there but this method is invoked
1098 protected final function getGenericSubArray (string $keyGroup, string $subGroup) {
1100 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: keyGroup=%s,subGroup=%s - CALLED!', $keyGroup, $subGroup));
1101 if (empty($keyGroup)) {
1103 throw new InvalidArgumentException('Parameter "keyGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1104 } elseif (empty($subGroup)) {
1106 throw new InvalidArgumentException('Parameter "subGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1107 } elseif (!$this->isGenericArrayGroupSet($keyGroup, $subGroup)) {
1108 // No, then abort here
1109 throw new BadMethodCallException(sprintf('keyGroup=%s,subGroup=%s not found.', $keyGroup, $subGroup), FrameworkInterface::EXCEPTION_BAD_METHOD_CALL);
1113 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: this->genericArray[%s][%s][]=%s - EXIT!', $keyGroup, $subGroup, gettype($this->genericArray[$keyGroup][$subGroup])));
1114 return $this->genericArray[$keyGroup][$subGroup];
1118 * Unsets a given key in generic array
1120 * @param $keyGroup Main group for the key
1121 * @param $subGroup Sub group for the key
1122 * @param $key Key to unset
1124 * @throws InvalidArgumentException If a parameter is not valid
1126 protected final function unsetGenericArrayKey (string $keyGroup, string $subGroup, string $key) {
1128 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: keyGroup=%s,subGroup=%s,key=%s - CALLED!', $keyGroup, $subGroup, $key));
1129 if (empty($keyGroup)) {
1131 throw new InvalidArgumentException('Parameter "keyGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1132 } elseif (empty($subGroup)) {
1134 throw new InvalidArgumentException('Parameter "subGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1135 } elseif (empty($key)) {
1137 throw new InvalidArgumentException('Parameter "key" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1141 unset($this->genericArray[$keyGroup][$subGroup][$key]);
1144 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-FRAMEWORK-SYSTEM: EXIT!');
1148 * Unsets a given element in generic array
1150 * @param $keyGroup Main group for the key
1151 * @param $subGroup Sub group for the key
1152 * @param $key Key to unset
1153 * @param $element Element to unset
1155 * @throws InvalidArgumentException If a parameter is not valid
1157 protected final function unsetGenericArrayElement (string $keyGroup, string $subGroup, string $key, string $element) {
1159 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: keyGroup=%s,subGroup=%s,key=%s,element=%s - CALLED!', $keyGroup, $subGroup, $key, $element));
1160 if (empty($keyGroup)) {
1162 throw new InvalidArgumentException('Parameter "keyGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1163 } elseif (empty($subGroup)) {
1165 throw new InvalidArgumentException('Parameter "subGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1166 } elseif (empty($key)) {
1168 throw new InvalidArgumentException('Parameter "key" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1169 } elseif ($element === '') {
1171 throw new InvalidArgumentException('Parameter "element" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1175 unset($this->genericArray[$keyGroup][$subGroup][$key][$element]);
1178 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-FRAMEWORK-SYSTEM: EXIT!');
1182 * Append a string to a given generic array key
1184 * @param $keyGroup Main group for the key
1185 * @param $subGroup Sub group for the key
1186 * @param $key Key to unset
1187 * @param $value Value to add/append
1189 * @throws InvalidArgumentException If a parameter is not valid
1191 protected final function appendStringToGenericArrayKey (string $keyGroup, string $subGroup, string $key, string $value, string $appendGlue = '') {
1193 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: keyGroup=%s,subGroup=%s,key=%s,value=%s,appendGlue=%s - CALLED!', $keyGroup, $subGroup, $key, $value, $appendGlue));
1194 if (empty($keyGroup)) {
1196 throw new InvalidArgumentException('Parameter "keyGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1197 } elseif (empty($subGroup)) {
1199 throw new InvalidArgumentException('Parameter "subGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1200 } elseif (empty($key)) {
1202 throw new InvalidArgumentException('Parameter "key" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1205 // Is it already there?
1206 if ($this->isGenericArrayKeySet($keyGroup, $subGroup, $key)) {
1208 $this->genericArray[$keyGroup][$subGroup][$key] .= $appendGlue . $value;
1211 $this->genericArray[$keyGroup][$subGroup][$key] = $value;
1215 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-FRAMEWORK-SYSTEM: EXIT!');
1219 * Append a string to a given generic array element
1221 * @param $keyGroup Main group for the key
1222 * @param $subGroup Sub group for the key
1223 * @param $key Key to unset
1224 * @param $element Element to check
1225 * @param $value Value to add/append
1227 * @throws InvalidArgumentException If a parameter is not valid
1229 protected final function appendStringToGenericArrayElement (string $keyGroup, string $subGroup, string $key, string $element, string $value, string $appendGlue = '') {
1231 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: keyGroup=%s,subGroup=%s,key=%s,element=%s,value=%s,appendGlue=%s - CALLED!', $keyGroup, $subGroup, $key, $element, $value, $appendGlue));
1232 if (empty($keyGroup)) {
1234 throw new InvalidArgumentException('Parameter "keyGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1235 } elseif (empty($subGroup)) {
1237 throw new InvalidArgumentException('Parameter "subGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1238 } elseif (empty($key)) {
1240 throw new InvalidArgumentException('Parameter "key" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1241 } elseif ($element === '') {
1243 throw new InvalidArgumentException('Parameter "element" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1246 // Is it already there?
1247 if ($this->isGenericArrayElementSet($keyGroup, $subGroup, $key, $element)) {
1249 $this->genericArray[$keyGroup][$subGroup][$key][$element] .= $appendGlue . $value;
1252 $this->setGenericArrayElement($keyGroup, $subGroup, $key, $element, $value);
1256 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-FRAMEWORK-SYSTEM: EXIT!');
1260 * Initializes given generic array group
1262 * @param $keyGroup Main group for the key
1263 * @param $subGroup Sub group for the key
1264 * @param $key Key to use
1265 * @param $forceInit Optionally force initialization
1267 * @throws InvalidArgumentException If a parameter is not valid
1268 * @throws BadMethodCallException If key/sub group has already been initialized
1270 protected final function initGenericArrayGroup (string $keyGroup, string $subGroup, bool $forceInit = false) {
1272 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: keyGroup=%s,subGroup=%s,forceInit=%d - CALLED!', $keyGroup, $subGroup, intval($forceInit)));
1273 if (empty($keyGroup)) {
1275 throw new InvalidArgumentException('Parameter "keyGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1276 } elseif (empty($subGroup)) {
1278 throw new InvalidArgumentException('Parameter "subGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1279 } elseif (($forceInit === false) && ($this->isGenericArrayGroupSet($keyGroup, $subGroup))) {
1280 // Already initialized
1281 throw new BadMethodCallException(sprintf('keyGroup=%s,subGroup=%s already initialized.', $keyGroup, $subGroup), FrameworkInterface::EXCEPTION_BAD_METHOD_CALL);
1285 $this->genericArray[$keyGroup][$subGroup] = [];
1288 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-FRAMEWORK-SYSTEM: EXIT!');
1292 * Initializes given generic array key
1294 * @param $keyGroup Main group for the key
1295 * @param $subGroup Sub group for the key
1296 * @param $key Key to use
1297 * @param $forceInit Optionally force initialization
1299 * @throws InvalidArgumentException If a parameter is not valid
1300 * @throws BadMethodCallException If key/sub group has already been initialized
1302 protected final function initGenericArrayKey (string $keyGroup, string $subGroup, string $key, bool $forceInit = false) {
1304 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: keyGroup=%s,subGroup=%s,key=%s,forceInit=%d - CALLED!', $keyGroup, $subGroup, $key, intval($forceInit)));
1305 if (empty($keyGroup)) {
1307 throw new InvalidArgumentException('Parameter "keyGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1308 } elseif (empty($subGroup)) {
1310 throw new InvalidArgumentException('Parameter "subGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1311 } elseif (empty($key)) {
1313 throw new InvalidArgumentException('Parameter "key" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1314 } elseif (($forceInit === false) && ($this->isGenericArrayKeySet($keyGroup, $subGroup, $key))) {
1315 // Already initialized
1316 throw new BadMethodCallException(sprintf('keyGroup=%s,subGroup=%s,key[%s]=%s already initialized.', $keyGroup, $subGroup, gettype($key), $key), FrameworkInterface::EXCEPTION_BAD_METHOD_CALL);
1320 $this->genericArray[$keyGroup][$subGroup][$key] = [];
1323 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-FRAMEWORK-SYSTEM: EXIT!');
1327 * Initializes given generic array element
1329 * @param $keyGroup Main group for the key
1330 * @param $subGroup Sub group for the key
1331 * @param $key Key to use
1332 * @param $element Element to use
1333 * @param $forceInit Optionally force initialization
1335 * @throws InvalidArgumentException If a parameter is not valid
1336 * @throws BadMethodCallException If key/sub group isn't there but this method is invoked
1338 protected final function initGenericArrayElement (string $keyGroup, string $subGroup, string $key, string $element, bool $forceInit = false) {
1340 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: keyGroup=%s,subGroup=%s,key=%s,element=%s,forceInit=%d - CALLED!', $keyGroup, $subGroup, $key, $element, intval($forceInit)));
1341 if (empty($keyGroup)) {
1343 throw new InvalidArgumentException('Parameter "keyGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1344 } elseif (empty($subGroup)) {
1346 throw new InvalidArgumentException('Parameter "subGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1347 } elseif (empty($key)) {
1349 throw new InvalidArgumentException('Parameter "key" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1350 } elseif ($element === '') {
1352 throw new InvalidArgumentException('Parameter "element" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1353 } elseif (($forceInit === false) && ($this->isGenericArrayElementSet($keyGroup, $subGroup, $key, $element))) {
1354 // Already initialized
1355 throw new BadMethodCallException(sprintf('keyGroup=%s,subGroup=%s,key[%s]=%s,element[%s]=%s already initialized.', $keyGroup, $subGroup, gettype($key), $key, gettype($element), $element), FrameworkInterface::EXCEPTION_BAD_METHOD_CALL);
1359 $this->genericArray[$keyGroup][$subGroup][$key][$element] = [];
1362 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-FRAMEWORK-SYSTEM: EXIT!');
1366 * Pushes an element to a generic key. If the key isn't found, it will be initialized.
1368 * @param $keyGroup Main group for the key
1369 * @param $subGroup Sub group for the key
1370 * @param $key Key to use
1371 * @param $value Value to add/append
1372 * @return $count Number of array elements
1373 * @throws InvalidArgumentException If a parameter is not valid
1375 protected final function pushValueToGenericArrayKey (string $keyGroup, string $subGroup, string $key, $value) {
1377 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: keyGroup=%s,subGroup=%s,key=%s,value[]=%s - CALLED!', $keyGroup, $subGroup, $key, gettype($value)));
1378 if (empty($keyGroup)) {
1380 throw new InvalidArgumentException('Parameter "keyGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1381 } elseif (empty($subGroup)) {
1383 throw new InvalidArgumentException('Parameter "subGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1384 } elseif (empty($key)) {
1386 throw new InvalidArgumentException('Parameter "key" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1387 } elseif (!$this->isGenericArrayKeySet($keyGroup, $subGroup, $key)) {
1389 $this->initGenericArrayKey($keyGroup, $subGroup, $key);
1393 $count = array_push($this->genericArray[$keyGroup][$subGroup][$key], $value);
1396 //* DEBUG: */ print(__METHOD__ . ': genericArray=' . print_r($this->genericArray[$keyGroup][$subGroup][$key], true));
1397 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: count=%d - EXIT!', $count));
1402 * Pushes an element to a generic array element. If the key isn't found, it will be initialized.
1404 * @param $keyGroup Main group for the key
1405 * @param $subGroup Sub group for the key
1406 * @param $key Key to use
1407 * @param $element Element to check
1408 * @param $value Value to add/append
1409 * @return $count Number of array elements
1410 * @throws InvalidArgumentException If a parameter is not valid
1412 protected final function pushValueToGenericArrayElement (string $keyGroup, string $subGroup, string $key, string $element, $value) {
1414 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: keyGroup=%s,subGroup=%s,key=%s,element=%s,value[]=%s - CALLED!', $keyGroup, $subGroup, $key, $element, gettype($value)));
1415 if (empty($keyGroup)) {
1417 throw new InvalidArgumentException('Parameter "keyGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1418 } elseif (empty($subGroup)) {
1420 throw new InvalidArgumentException('Parameter "subGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1421 } elseif (empty($key)) {
1423 throw new InvalidArgumentException('Parameter "key" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1424 } elseif ($element === '') {
1426 throw new InvalidArgumentException('Parameter "element" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1427 } elseif (!$this->isGenericArrayElementSet($keyGroup, $subGroup, $key, $element)) {
1429 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: Invoking this->initGenericArrayElement(%s,%s,%s,%s) ...', $keyGroup, $subGroup, $key, $element));
1430 $this->initGenericArrayElement($keyGroup, $subGroup, $key, $element);
1434 $count = array_push($this->genericArray[$keyGroup][$subGroup][$key][$element], $value);
1437 //* DEBUG: */ print(__METHOD__ . ': genericArray=' . print_r($this->genericArray[$keyGroup][$subGroup][$key], true));
1438 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: count=%d - EXIT!', $count));
1443 * Pops an element from a generic group
1445 * @param $keyGroup Main group for the key
1446 * @param $subGroup Sub group for the key
1447 * @param $key Key to unset
1448 * @return $value Last "popped" value
1449 * @throws InvalidArgumentException If a parameter is not valid
1450 * @throws BadMethodCallException If key/sub group isn't there but this method is invoked
1452 protected final function popGenericArrayElement (string $keyGroup, string $subGroup, string $key) {
1454 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: keyGroup=%s,subGroup=%s,key=%s - CALLED!', $keyGroup, $subGroup, $key));
1455 if (empty($keyGroup)) {
1457 throw new InvalidArgumentException('Parameter "keyGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1458 } elseif (empty($subGroup)) {
1460 throw new InvalidArgumentException('Parameter "subGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1461 } elseif (empty($key)) {
1463 throw new InvalidArgumentException('Parameter "key" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1464 } elseif (!$this->isGenericArrayKeySet($keyGroup, $subGroup, $key)) {
1466 throw new BadMethodCallException(sprintf('keyGroup=%s,subGroup=%s,key[%s]=%s not found.', $keyGroup, $subGroup, gettype($key), $key), FrameworkInterface::EXCEPTION_BAD_METHOD_CALL);
1470 $value = array_pop($this->genericArray[$keyGroup][$subGroup][$key]);
1473 //* DEBUG: */ print(__METHOD__ . ': genericArray=' . print_r($this->genericArray[$keyGroup][$subGroup][$key], true));
1474 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: value[]=%s - EXIT!', gettype($value)));
1479 * Shifts an element from a generic group
1481 * @param $keyGroup Main group for the key
1482 * @param $subGroup Sub group for the key
1483 * @param $key Key to unset
1484 * @return $value Last "shifted" value
1485 * @throws InvalidArgumentException If a parameter is not valid
1486 * @throws BadMethodCallException If key/sub group isn't there but this method is invoked
1488 protected final function shiftGenericArrayElement (string $keyGroup, string $subGroup, string $key) {
1490 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: keyGroup=%s,subGroup=%s,key=%s - CALLED!', $keyGroup, $subGroup, $key));
1491 if (empty($keyGroup)) {
1493 throw new InvalidArgumentException('Parameter "keyGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1494 } elseif (empty($subGroup)) {
1496 throw new InvalidArgumentException('Parameter "subGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1497 } elseif (empty($key)) {
1499 throw new InvalidArgumentException('Parameter "key" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1500 } elseif (!$this->isGenericArrayKeySet($keyGroup, $subGroup, $key)) {
1502 throw new BadMethodCallException(sprintf('keyGroup=%s,subGroup=%s,key[%s]=%s not found.', $keyGroup, $subGroup, gettype($key), $key), FrameworkInterface::EXCEPTION_BAD_METHOD_CALL);
1506 $value = array_shift($this->genericArray[$keyGroup][$subGroup][$key]);
1509 //* DEBUG: */ print(__METHOD__ . ': genericArray=' . print_r($this->genericArray[$keyGroup][$subGroup][$key], true));
1510 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: value[]=%s - EXIT!', gettype($value)));
1515 * Count generic array group
1517 * @param $keyGroup Main group for the key
1518 * @return $count Count of given group
1519 * @throws InvalidArgumentException If a parameter is not valid
1520 * @throws BadMethodCallException If key group isn't there but this method is invoked
1522 protected final function countGenericArray (string $keyGroup) {
1524 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: keyGroup=%s - CALLED!', $keyGroup));
1525 if (empty($keyGroup)) {
1527 throw new InvalidArgumentException('Parameter "keyGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1528 } elseif (!isset($this->genericArray[$keyGroup])) {
1530 throw new BadMethodCallException(sprintf('keyGroup=%s not found.', $keyGroup), FrameworkInterface::EXCEPTION_BAD_METHOD_CALL);
1534 $count = count($this->genericArray[$keyGroup]);
1537 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: count=%d - EXIT!', $count));
1542 * Count generic array sub group
1544 * @param $keyGroup Main group for the key
1545 * @param $subGroup Sub group for the key
1546 * @return $count Count of given group
1547 * @throws InvalidArgumentException If a parameter is not valid
1548 * @throws BadMethodCallException If key/sub group isn't there but this method is invoked
1550 protected final function countGenericArrayGroup (string $keyGroup, string $subGroup) {
1552 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: keyGroup=%s,subGroup=%s - CALLED!', $keyGroup, $subGroup));
1553 if (empty($keyGroup)) {
1555 throw new InvalidArgumentException('Parameter "keyGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1556 } elseif (empty($subGroup)) {
1558 throw new InvalidArgumentException('Parameter "subGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1559 } elseif (!$this->isGenericArrayGroupSet($keyGroup, $subGroup)) {
1561 throw new BadMethodCallException(sprintf('keyGroup=%s,subGroup=%s not found.', $keyGroup, $subGroup), FrameworkInterface::EXCEPTION_BAD_METHOD_CALL);
1565 $count = count($this->genericArray[$keyGroup][$subGroup]);
1568 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: count=%d - EXIT!', $count));
1573 * Count generic array elements
1575 * @param $keyGroup Main group for the key
1576 * @param $subGroup Sub group for the key
1577 * @param $key Key to count
1578 * @return $count Count of given key
1579 * @throws InvalidArgumentException If a parameter is not valid
1580 * @throws BadMethodCallException If key/sub group isn't there but this method is invoked
1582 protected final function countGenericArrayElements (string $keyGroup, string $subGroup, string $key) {
1584 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: keyGroup=%s,subGroup=%s,key=%s - CALLED!', $keyGroup, $subGroup, $key));
1585 if (empty($keyGroup)) {
1587 throw new InvalidArgumentException('Parameter "keyGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1588 } elseif (empty($subGroup)) {
1590 throw new InvalidArgumentException('Parameter "subGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1591 } elseif (empty($key)) {
1593 throw new InvalidArgumentException('Parameter "key" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1594 } elseif (!$this->isGenericArrayKeySet($keyGroup, $subGroup, $key)) {
1596 throw new BadMethodCallException(sprintf('keyGroup=%s,subGroup=%s,key[%s]=%s not found.', $keyGroup, $subGroup, gettype($key), $key), FrameworkInterface::EXCEPTION_BAD_METHOD_CALL);
1597 } elseif (!$this->isValidGenericArrayGroup($keyGroup, $subGroup)) {
1599 throw new BadMethodCallException(sprintf('keyGroup=%s,subGroup=%s is not a valid key/sub group.', $keyGroup, $subGroup), FrameworkInterface::EXCEPTION_BAD_METHOD_CALL);
1603 $count = count($this->genericArray[$keyGroup][$subGroup][$key]);
1606 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: count=%d - EXIT!', $count));
1611 * Getter for whole generic group array
1613 * @param $keyGroup Key group to get
1614 * @return $array Whole generic array group
1615 * @throws InvalidArgumentException If a parameter is not valid
1616 * @throws BadMethodCallException If key/sub group isn't there but this method is invoked
1618 protected final function getGenericArray (string $keyGroup) {
1620 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: keyGroup=%s - CALLED!', $keyGroup));
1621 if (empty($keyGroup)) {
1623 throw new InvalidArgumentException('Parameter "keyGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1624 } elseif (!isset($this->genericArray[$keyGroup])) {
1626 throw new BadMethodCallException(sprintf('keyGroup=%s not found', $keyGroup), FrameworkInterface::EXCEPTION_BAD_METHOD_CALL);
1630 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: this->genericArray[%s][]=%s - EXIT!', $keyGroup, gettype($this->genericArray[$keyGroup])));
1631 return $this->genericArray[$keyGroup];
1635 * Setter for generic array key
1637 * @param $keyGroup Key group to get
1638 * @param $subGroup Sub group for the key
1639 * @param $key Key to unset
1640 * @param $value Mixed value from generic array element
1642 * @throws InvalidArgumentException If a parameter is not valid
1643 * @throws BadMethodCallException If key/sub group isn't there but this method is invoked
1645 protected final function setGenericArrayKey (string $keyGroup, string $subGroup, string $key, $value) {
1647 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: keyGroup=%s,subGroup=%s,key=%s,value[]=%s - CALLED!', $keyGroup, $subGroup, $key, gettype($value)));
1648 if (empty($keyGroup)) {
1650 throw new InvalidArgumentException('Parameter "keyGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1651 } elseif (empty($subGroup)) {
1653 throw new InvalidArgumentException('Parameter "subGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1654 } elseif (empty($key)) {
1656 throw new InvalidArgumentException('Parameter "key" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1657 } elseif (!$this->isValidGenericArrayGroup($keyGroup, $subGroup)) {
1659 throw new BadMethodCallException(sprintf('keyGroup=%s,subGroup=%s not found', $keyGroup), FrameworkInterface::EXCEPTION_BAD_METHOD_CALL);
1663 $this->genericArray[$keyGroup][$subGroup][$key] = $value;
1666 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-FRAMEWORK-SYSTEM: EXIT!');
1670 * Getter for generic array key
1672 * @param $keyGroup Key group to get
1673 * @param $subGroup Sub group for the key
1674 * @param $key Key to unset
1675 * @return $value Mixed value from generic array element
1676 * @throws InvalidArgumentException If a parameter is not valid
1677 * @throws BadMethodCallException If key/sub group isn't there but this method is invoked
1679 protected final function getGenericArrayKey (string $keyGroup, string $subGroup, string $key) {
1681 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: keyGroup=%s,subGroup=%s,key=%s - CALLED!', $keyGroup, $subGroup, $key));
1682 if (empty($keyGroup)) {
1684 throw new InvalidArgumentException('Parameter "keyGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1685 } elseif (empty($subGroup)) {
1687 throw new InvalidArgumentException('Parameter "subGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1688 } elseif (empty($key)) {
1690 throw new InvalidArgumentException('Parameter "key" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1691 } elseif (!$this->isGenericArrayKeySet($keyGroup, $subGroup, $key)) {
1693 throw new BadMethodCallException(sprintf('keyGroup=%s,subGroup=%s,key[%s]=%s not found.', $keyGroup, $subGroup, gettype($key), $key), FrameworkInterface::EXCEPTION_BAD_METHOD_CALL);
1697 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: this->genericArray[%s][%s][%s][]=%s - EXIT!', $keyGroup, $subGroup, $key, gettype($this->genericArray[$keyGroup][$subGroup][$key])));
1698 return $this->genericArray[$keyGroup][$subGroup][$key];
1702 * Sets a value in given generic array key/element
1704 * @param $keyGroup Main group for the key
1705 * @param $subGroup Sub group for the key
1706 * @param $key Key to set
1707 * @param $element Element to set
1708 * @param $value Value to set
1710 * @throws InvalidArgumentException If a parameter is not valid
1712 protected final function setGenericArrayElement (string $keyGroup, string $subGroup, string $key, string $element, $value) {
1714 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: keyGroup=%s,subGroup=%s,key=%s,element=%s,value[]=%s - CALLED!', $keyGroup, $subGroup, $key, $element, gettype($value)));
1715 if (empty($keyGroup)) {
1717 throw new InvalidArgumentException('Parameter "keyGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1718 } elseif (empty($subGroup)) {
1720 throw new InvalidArgumentException('Parameter "subGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1721 } elseif (empty($key)) {
1723 throw new InvalidArgumentException('Parameter "key" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1724 } elseif ($element === '') {
1726 throw new InvalidArgumentException('Parameter "element" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1727 } elseif (!$this->isGenericArrayElementSet($keyGroup, $subGroup, $key, $element)) {
1729 $this->initGenericArrayElement($keyGroup, $subGroup, $key, $element);
1733 $this->genericArray[$keyGroup][$subGroup][$key][$element] = $value;
1736 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-FRAMEWORK-SYSTEM: EXIT!');
1740 * Getter for generic array element
1742 * @param $keyGroup Key group to get
1743 * @param $subGroup Sub group for the key
1744 * @param $key Key to look for
1745 * @param $element Element to look for
1746 * @return $value Mixed value from generic array element
1747 * @throws InvalidArgumentException If a parameter is not valid
1748 * @throws BadMethodCallException If key/sub group isn't there but this method is invoked
1750 protected final function getGenericArrayElement (string $keyGroup, string $subGroup, string $key, string $element) {
1752 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: keyGroup=%s,subGroup=%s,key=%s,element=%s - CALLED!', $keyGroup, $subGroup, $key, $element));
1753 if (empty($keyGroup)) {
1755 throw new InvalidArgumentException('Parameter "keyGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1756 } elseif (empty($subGroup)) {
1758 throw new InvalidArgumentException('Parameter "subGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1759 } elseif (empty($key)) {
1761 throw new InvalidArgumentException('Parameter "key" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1762 } elseif ($element === '') {
1764 throw new InvalidArgumentException('Parameter "element" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1765 } elseif (!$this->isGenericArrayElementSet($keyGroup, $subGroup, $key, $element)) {
1767 throw new BadMethodCallException(sprintf('keyGroup=%s,subGroup=%s,key[%s]=%s,element[%s]=%s not found.', $keyGroup, $subGroup, gettype($key), $key, gettype($element), $element), FrameworkInterface::EXCEPTION_BAD_METHOD_CALL);
1771 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: this->genericArray[%s][%s][%s][%s][]=%s - EXIT!', $keyGroup, $subGroup, $key, gettype($this->genericArray[$keyGroup][$subGroup][$key][$element])));
1772 return $this->genericArray[$keyGroup][$subGroup][$key][$element];
1776 * Checks if a given sub group is valid (array)
1778 * @param $keyGroup Key group to get
1779 * @param $subGroup Sub group for the key
1780 * @return $isValid Whether given sub group is valid
1781 * @throws InvalidArgumentException If a parameter is not valid
1783 protected final function isValidGenericArrayGroup (string $keyGroup, string $subGroup) {
1785 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: keyGroup=%s,subGroup=%s - CALLED!', $keyGroup, $subGroup));
1786 if (empty($keyGroup)) {
1788 throw new InvalidArgumentException('Parameter "keyGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1789 } elseif (empty($subGroup)) {
1791 throw new InvalidArgumentException('Parameter "subGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1795 $isValid = (($this->isGenericArrayGroupSet($keyGroup, $subGroup)) && (is_array($this->getGenericSubArray($keyGroup, $subGroup))));
1798 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: isValid=%d - EXIT!', intval($isValid)));
1803 * Checks if a given key is valid (array)
1805 * @param $keyGroup Key group to get
1806 * @param $subGroup Sub group for the key
1807 * @param $key Key to check
1808 * @return $isValid Whether given sub group is valid
1810 protected final function isValidGenericArrayKey (string $keyGroup, string $subGroup, string $key) {
1812 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: keyGroup=%s,subGroup=%s,key=%s - CALLED!', $keyGroup, $subGroup, $key));
1813 if (empty($keyGroup)) {
1815 throw new InvalidArgumentException('Parameter "keyGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1816 } elseif (empty($subGroup)) {
1818 throw new InvalidArgumentException('Parameter "subGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1819 } elseif (empty($key)) {
1821 throw new InvalidArgumentException('Parameter "key" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1825 $isValid = (($this->isGenericArrayKeySet($keyGroup, $subGroup, $key)) && (is_array($this->getGenericArrayKey($keyGroup, $subGroup, $key))));
1828 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: isValid=%d - EXIT!', intval($isValid)));
1833 * Initializes the web output instance
1837 protected function initWebOutputInstance () {
1838 // Init web output instance
1839 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-FRAMEWORK-SYSTEM: CALLED!');
1840 $outputInstance = ObjectFactory::createObjectByConfiguredName('output_class');
1843 $this->setWebOutputInstance($outputInstance);
1846 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-FRAMEWORK-SYSTEM: EXIT!');
1850 * Translates boolean true to 'Y' and false to 'N'
1852 * @param $boolean Boolean value
1853 * @return $translated Translated boolean value
1855 public static final function translateBooleanToYesNo (bool $boolean) {
1857 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: boolean=%d - CALLED!', intval($boolean)));
1858 $translated = ($boolean === true) ? 'Y' : 'N';
1860 // ... and return it
1861 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: translated=%s - EXIT!', $translated));
1866 * Creates a full-qualified file name (FQFN) for given file name by adding
1867 * a configured temporary file path to it.
1869 * @param $infoInstance An instance of a SplFileInfo class
1870 * @return $fileInfoInstance An instance of a SplFileInfo class (temporary file)
1871 * @throw PathWriteProtectedException If the path in 'temp_file_path' is write-protected
1872 * @throws FileIoException If the file cannot be written
1874 protected static function createTempPathForFile (SplFileInfo $infoInstance) {
1876 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: infoInstance=%s - CALLED!', $infoInstance->__toString()));
1877 $basePath = FrameworkBootstrap::getConfigurationInstance()->getConfigEntry('temp_file_path');
1879 // Is the path writeable?
1880 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: basePath=%s', $basePath));
1881 if (!is_writable($basePath)) {
1882 // Path is write-protected
1883 throw new PathWriteProtectedException($infoInstance, self::EXCEPTION_PATH_CANNOT_BE_WRITTEN);
1887 $fileInfoInstance = new SplFileInfo($basePath . DIRECTORY_SEPARATOR . $infoInstance->getBasename());
1890 if (!FrameworkBootstrap::isReachableFilePath($fileInfoInstance)) {
1892 throw new FileIoException($fileInfoInstance, self::EXCEPTION_FILE_NOT_REACHABLE);
1896 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: fileInfoInstance=%s - EXIT!', $fileInfoInstance->__toString()));
1897 return $fileInfoInstance;
1901 * "Getter" for a printable state name
1903 * @return $stateName Name of the node's state in a printable format
1904 * @throws BadMethodCallException If this instance doesn't have a callable getter for stateInstance
1905 * @todo Move this class away from this monolithic place (not whole class is monolithic)
1907 public final function getPrintableState () {
1908 // Check if getter is there
1909 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-FRAMEWORK-SYSTEM: CALLED!');
1910 if (!is_callable($this, 'getStateInstance')) {
1912 throw new BadMethodCallException(sprintf('this=%s has no callable getter for stateInstance', $this->__toString()), FrameworkInterface::EXCEPTION_BAD_METHOD_CALL);
1915 // Default is 'null'
1916 $stateName = 'null';
1918 // Get the state instance
1919 $stateInstance = $this->getStateInstance();
1921 // Is it an instance of Stateable?
1922 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: stateInstance[]=%s', gettype($stateInstance)));
1923 if ($stateInstance instanceof Stateable) {
1924 // Then use that state name
1925 $stateName = $stateInstance->getStateName();
1929 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: stateName=%s - EXIT!', $stateName));