framework/main/middleware/debug/class_DebugMiddleware.php

   1 <?php
   2 // Own namespace
   3 namespace Org\Mxchange\CoreFramework\Middleware\Debug;
   4
   5 // Import framework stuff
   6 use Org\Mxchange\CoreFramework\Factory\Object\ObjectFactory;
   7 use Org\Mxchange\CoreFramework\Generic\FrameworkInterface;
   8 use Org\Mxchange\CoreFramework\Generic\NullPointerException;
   9 use Org\Mxchange\CoreFramework\Logging\Logger;
  10 use Org\Mxchange\CoreFramework\Middleware\BaseMiddleware;
  11 use Org\Mxchange\CoreFramework\Registry\Registerable;
  12 use Org\Mxchange\CoreFramework\Stream\Output\OutputStreamer;
  13
  14 // Import SPL stuff
  15 use \InvalidArgumentException;
  16
  17 /**
  18  * The middlware debug output system. A *real* or concrete output class shall
  19  * become registered with this middleware because the back-fall class will
  20  * become deprecated soon.
  21  *
  22  * @author              Roland Haeder <webmaster@shipsimu.org>
  23  * @version             0.0.0
  24  * @copyright   Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2023 Core Developer Team
  25  * @license             GNU GPL 3.0 or any newer version
  26  * @link                http://www.shipsimu.org
  27  * @deprecated  See LoggerFactory for a more flexible approach
  28  *
  29  * This program is free software: you can redistribute it and/or modify
  30  * it under the terms of the GNU General Public License as published by
  31  * the Free Software Foundation, either version 3 of the License, or
  32  * (at your option) any later version.
  33  *
  34  * This program is distributed in the hope that it will be useful,
  35  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  36  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  37  * GNU General Public License for more details.
  38  *
  39  * You should have received a copy of the GNU General Public License
  40  * along with this program. If not, see <http://www.gnu.org/licenses/>.
  41  */
  42 class DebugMiddleware extends BaseMiddleware implements Registerable, Logger {
  43         /**
  44          * An instance of this class
  45          */
  46         private static $selfInstance = NULL;
  47
  48         /**
  49          * Protected constructor
  50          *
  51          * @return      void
  52          */
  53         private function __construct () {
  54                 // Call parent constructor
  55                 //* NOISY-DEBUG: */ printf('[%s:%d]: CONSTRUCTED!' . PHP_EOL, __METHOD__, __LINE__);
  56                 parent::__construct(__CLASS__);
  57
  58                 // Trace message
  59                 //* NOISY-DEBUG: */ printf('[%s:%d]: EXIT!' . PHP_EOL, __METHOD__, __LINE__);
  60         }
  61
  62         /**
  63          * Create a new debug output system.
  64          * If no output is given this class is currently being used for back-fall.
  65          * This fall-back mechanism will become deprecated very soon.
  66          *
  67          * @param       $outputClass    The class name which we shall use for
  68          *                                                      registering the *real* debug output
  69          * @param       $className              Class where a output should be created and
  70          *                                                      configured for
  71          * @return      $debugInstance  An instance of this middleware class
  72          * @throws      InvalidArgumentException        If a parameter has an invalid value
  73          */
  74         public static final function createDebugMiddleware (string $outputClass, string $className) {
  75                 // Check parameter
  76                 //* NOISY-DEBUG: */ printf('[%s:%d]: outputClass=%s,className=%s - CALLED!' . PHP_EOL, __METHOD__, __LINE__, $outputClass, $className);
  77                 if (empty($outputClass)) {
  78                         // Throw IAE
  79                         throw new InvalidArgumentException('Parameter "outputClass" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
  80                 } elseif (empty($className)) {
  81                         // Throw IAE
  82                         throw new InvalidArgumentException('Parameter "className" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
  83                 }
  84
  85                 // Is a static instance there?
  86                 //* NOISY-DEBUG: */ printf('[%s:%d]: self::selfInstance[]=%s' . PHP_EOL, __METHOD__, __LINE__, gettype(self::$selfInstance));
  87                 if (is_null(self::$selfInstance)) {
  88                         // Create an instance if this middleware
  89                         self::$selfInstance = new DebugMiddleware();
  90                 }
  91
  92                 // Is there a valid output instance provided?
  93                 //* NOISY-DEBUG: */ printf('[%s:%d]: outputClass=%s' . PHP_EOL, __METHOD__, __LINE__, $outputClass);
  94                 if (class_exists($outputClass) && is_null(self::$selfInstance->getOutputInstance())) {
  95                         // A name for a debug output class has been provided so we try to get it
  96                         //* NOISY-DEBUG: */ printf('[%s:%d]: Initializing outputClass=%s ...' . PHP_EOL, __METHOD__, __LINE__, $outputClass);
  97                         $outputInstance = ObjectFactory::createObjectByName($outputClass);
  98
  99                         // Set this as output class
 100                         //* NOISY-DEBUG: */ printf('[%s:%d]: outputInstance=%s' . PHP_EOL, __METHOD__, __LINE__, $outputInstance->__toString());
 101                         self::$selfInstance->setOutputInstance($outputInstance);
 102                 }
 103
 104                 // Is the output class loadable and an output instance is set?
 105                 if (class_exists($outputClass) && !is_null(self::$selfInstance->getOutputInstance())) {
 106                         // Then set class name
 107                         //* NOISY-DEBUG: */ printf('[%s:%d]: Setting className=%s as logger class ...' . PHP_EOL, __METHOD__, __LINE__, $className);
 108                         self::$selfInstance->getOutputInstance()->setLoggerClassName($className);
 109                 }
 110
 111                 // Return instance
 112                 //* NOISY-DEBUG: */ printf('[%s:%d]: debugInstance=%s - EXIT!' . PHP_EOL, __METHOD__, __LINE__, self::$selfInstance->__toString());
 113                 return self::$selfInstance;
 114         }
 115
 116         /**
 117          * This method shall send debug output which can be HTML code for the
 118          * browser or debug lines for a log file, etc. to the registered debug
 119          * output instance.
 120          *
 121          * @param       $message        Data we shall 'stream' out to the world
 122          * @param       $stripTags      Whether HTML tags shall be stripped out
 123          * @return      void
 124          * @throws      NullPointerException    If this->outputInstance is NULL
 125          */
 126         private function outputMessage (string $logLevel, string $message, bool $stripTags = false) {
 127                 // Get backtrace
 128                 //* NOISY-DEBUG: */ printf('[%s:%d]: logLevel=%s,message=%s,stripTags=%d - CALLED!' . PHP_EOL, __METHOD__, __LINE__, $logLevel, $message, intval($stripTags));
 129                 $backtrace = debug_backtrace(!DEBUG_BACKTRACE_PROVIDE_OBJECT);
 130
 131                 // Is the deprecated debugOutput() or partialStub() invoked before?
 132                 if (isset($backtrace[4]) && $backtrace[3]['function'] == 'partialStub') {
 133                         // Prepend class::function:line from 2nd element
 134                         //* NOISY-DEBUG: */ printf('[%s:%d]: partialStub() was invoked ...' . PHP_EOL, __METHOD__, __LINE__);
 135                         $message = sprintf('[%s::%s:%d]: [%s] %s',
 136                                 $backtrace[4]['class'],
 137                                 $backtrace[4]['function'],
 138                                 (isset($backtrace[4]['line']) ? $backtrace[4]['line'] : '0'),
 139                                 $logLevel,
 140                                 $message
 141                         );
 142                 } elseif (isset($backtrace[3]) && $backtrace[2]['function'] == 'debugOutput') {
 143                         // Prepend class::function:line from 2nd element
 144                         //* NOISY-DEBUG: */ printf('[%s:%d]: debugOutput() was invoked ...' . PHP_EOL, __METHOD__, __LINE__);
 145                         $message = sprintf('[%s::%s:%d]: [%s] %s',
 146                                 $backtrace[3]['class'],
 147                                 $backtrace[3]['function'],
 148                                 (isset($backtrace[3]['line']) ? $backtrace[3]['line'] : '0'),
 149                                 $logLevel,
 150                                 $message
 151                         );
 152                 } else {
 153                         // Prepend class::function:line from 2nd element
 154                         //* NOISY-DEBUG: */ printf('[%s:%d]: Ordinary invocation ...' . PHP_EOL, __METHOD__, __LINE__);
 155                         $message = sprintf('[%s::%s:%d]: [%s] %s',
 156                                 $backtrace[2]['class'],
 157                                 $backtrace[2]['function'],
 158                                 (isset($backtrace[2]['line']) ? $backtrace[2]['line'] : '0'),
 159                                 $logLevel,
 160                                 $message
 161                         );
 162                 }
 163
 164                 // Use the output instance
 165                 $this->getOutputInstance()->outputStream($message, $stripTags);
 166
 167                 // Trace message
 168                 //* NOISY-DEBUG: */ printf('[%s:%d]: EXIT!' . PHP_EOL, __METHOD__, __LINE__);
 169         }
 170
 171         /**
 172          * Getter for an instance of this class
 173          *
 174          * @return      $selfInstance           An instance of this class
 175          */
 176         public static final function getSelfInstance() {
 177                 return self::$selfInstance;
 178         }
 179
 180         /**
 181          * Outputs a trace message whether to debug instance (should be set!) or
 182          * dies with or ptints the message. Do NEVER EVER rewrite the exit() call to
 183          * ApplicationEntryPoint::app_exit(), this would cause an endless loop.
 184          *
 185          * @param       $message        Message we shall send out...
 186          * @param       $doPrint        Whether print or die here (default: print)
 187          * @paran       $stripTags      Whether to strip tags (default: false)
 188          * @return      void
 189          * @throws      InvalidArgumentException        If a parameter has an invalid value
 190          * @throws      NullPointerException    If this->outputInstance is NULL
 191          * @todo        Remove $doPrint parameter
 192          */
 193         public function traceMessage (string $message, bool $doPrint = true, bool $stripTags = false) {
 194                 // Check parameter
 195                 //* NOISY-DEBUG: */ printf('[%s:%d]: message=%s,doPrint=%d,stripTags=%d - CALLED!' . PHP_EOL, __METHOD__, __LINE__, $message, intval($doPrint), intval($stripTags));
 196                 if (empty($message)) {
 197                         // Throw IAE
 198                         throw new InvalidArgumentException('Parameter "message" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
 199                 } elseif (is_null($this->getOutputInstance())) {
 200                         // Should not be NULL
 201                         throw new NullPointerException($this, self::EXCEPTION_IS_NULL_POINTER);
 202                 }
 203
 204                 // Use debug output handler
 205                 //* NOISY-DEBUG: */ printf('[%s:%d]: Invoking this->outputMessage(%s,%s,%d) ...' . PHP_EOL, __METHOD__, __LINE__, Logger::LOGGER_LEVEL_TRACE, $message, intval($stripTags));
 206                 $this->outputMessage(Logger::LOGGER_LEVEL_TRACE, $message, $stripTags);
 207
 208                 // Trace message
 209                 //* NOISY-DEBUG: */ printf('[%s:%d]: EXIT!' . PHP_EOL, __METHOD__, __LINE__);
 210         }
 211
 212         /**
 213          * Outputs a debug message whether to debug instance (should be set!) or
 214          * dies with or ptints the message. Do NEVER EVER rewrite the exit() call to
 215          * ApplicationEntryPoint::app_exit(), this would cause an endless loop.
 216          *
 217          * @param       $message        Message we shall send out...
 218          * @param       $doPrint        Whether print or die here (default: print)
 219          * @paran       $stripTags      Whether to strip tags (default: false)
 220          * @return      void
 221          * @throws      InvalidArgumentException        If a parameter has an invalid value
 222          * @throws      NullPointerException    If this->outputInstance is NULL
 223          * @todo        Remove $doPrint parameter
 224          */
 225         public function debugMessage (string $message, bool $doPrint = true, bool $stripTags = false) {
 226                 // Check parameter
 227                 //* NOISY-DEBUG: */ printf('[%s:%d]: message=%s,doPrint=%d,stripTags=%d - CALLED!' . PHP_EOL, __METHOD__, __LINE__, $message, intval($doPrint), intval($stripTags));
 228                 if (empty($message)) {
 229                         // Throw IAE
 230                         throw new InvalidArgumentException('Parameter "message" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
 231                 } elseif (is_null($this->getOutputInstance())) {
 232                         // Should not be NULL
 233                         throw new NullPointerException($this, self::EXCEPTION_IS_NULL_POINTER);
 234                 }
 235
 236                 // Use debug output handler
 237                 //* NOISY-DEBUG: */ printf('[%s:%d]: Invoking this->outputMessage(%s,%s,%d) ...' . PHP_EOL, __METHOD__, __LINE__, $message, intval($stripTags));
 238                 $this->outputMessage(Logger::LOGGER_LEVEL_DEBUG, $message, $stripTags);
 239
 240                 // Trace message
 241                 //* NOISY-DEBUG: */ printf('[%s:%d]: EXIT!' . PHP_EOL, __METHOD__, __LINE__);
 242         }
 243
 244         /**
 245          * Outputs an informational message whether to debug instance (should be set!) or
 246          * dies with or ptints the message. Do NEVER EVER rewrite the exit() call to
 247          * ApplicationEntryPoint::app_exit(), this would cause an endless loop.
 248          *
 249          * @param       $message        Message we shall send out...
 250          * @param       $doPrint        Whether print or die here (default: print)
 251          * @paran       $stripTags      Whether to strip tags (default: false)
 252          * @return      void
 253          * @throws      InvalidArgumentException        If a parameter has an invalid value
 254          * @throws      NullPointerException    If this->outputInstance is NULL
 255          * @todo        Remove $doPrint parameter
 256          */
 257         public function infoMessage (string $message, bool $doPrint = true, bool $stripTags = false) {
 258                 // Check parameter
 259                 //* NOISY-DEBUG: */ printf('[%s:%d]: message=%s,doPrint=%d,stripTags=%d - CALLED!' . PHP_EOL, __METHOD__, __LINE__, $message, intval($doPrint), intval($stripTags));
 260                 if (empty($message)) {
 261                         // Throw IAE
 262                         throw new InvalidArgumentException('Parameter "message" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
 263                 } elseif (is_null($this->getOutputInstance())) {
 264                         // Should not be NULL
 265                         throw new NullPointerException($this, self::EXCEPTION_IS_NULL_POINTER);
 266                 }
 267
 268                 // Use debug output handler
 269                 //* NOISY-DEBUG: */ printf('[%s:%d]: Invoking this->outputMessage(%s,%s,%d) ...' . PHP_EOL, __METHOD__, __LINE__, Logger::LOGGER_LEVEL_INFO, $message, intval($stripTags));
 270                 $this->outputMessage(Logger::LOGGER_LEVEL_INFO, $message, $stripTags);
 271
 272                 // Trace message
 273                 //* NOISY-DEBUG: */ printf('[%s:%d]: EXIT!' . PHP_EOL, __METHOD__, __LINE__);
 274         }
 275
 276         /**
 277          * Outputs a warning message whether to debug instance (should be set!) or
 278          * dies with or ptints the message. Do NEVER EVER rewrite the exit() call to
 279          * ApplicationEntryPoint::app_exit(), this would cause an endless loop.
 280          *
 281          * @param       $message        Message we shall send out...
 282          * @param       $doPrint        Whether print or die here (default: print)
 283          * @paran       $stripTags      Whether to strip tags (default: false)
 284          * @return      void
 285          * @throws      InvalidArgumentException        If a parameter has an invalid value
 286          * @throws      NullPointerException    If this->outputInstance is NULL
 287          * @todo        Remove $doPrint parameter
 288          */
 289         public function warningMessage (string $message, bool $doPrint = true, bool $stripTags = false) {
 290                 // Check parameter
 291                 //* NOISY-DEBUG: */ printf('[%s:%d]: message=%s,doPrint=%d,stripTags=%d - CALLED!' . PHP_EOL, __METHOD__, __LINE__, $message, intval($doPrint), intval($stripTags));
 292                 if (empty($message)) {
 293                         // Throw IAE
 294                         throw new InvalidArgumentException('Parameter "message" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
 295                 } elseif (is_null($this->getOutputInstance())) {
 296                         // Should not be NULL
 297                         throw new NullPointerException($this, self::EXCEPTION_IS_NULL_POINTER);
 298                 }
 299
 300                 // Use debug output handler
 301                 //* NOISY-DEBUG: */ printf('[%s:%d]: Invoking this->outputMessage(%s,%s,%d) ...' . PHP_EOL, __METHOD__, __LINE__, Logger::LOGGER_LEVEL_WARNING, $message, intval($stripTags));
 302                 $this->outputMessage(Logger::LOGGER_LEVEL_WARNING, $message, $stripTags);
 303
 304                 // Trace message
 305                 //* NOISY-DEBUG: */ printf('[%s:%d]: EXIT!' . PHP_EOL, __METHOD__, __LINE__);
 306         }
 307
 308         /**
 309          * Output a partial stub message for the caller method
 310          *
 311          * @param       $message        An optional message to display
 312          * @return      void
 313          */
 314         public function partialStub (string $message = '') {
 315                 // Init variable
 316                 //* NOISY-DEBUG: */ printf('[%s:%d]: message=%s - CALLED!' . PHP_EOL, __METHOD__, __LINE__, $message);
 317                 $stubMessage = 'Partial stub!';
 318
 319                 // Is an extra message given?
 320                 if (!empty($message)) {
 321                         // Then add it as well
 322                         $stubMessage .= ' Message: ' . $message;
 323                 }
 324
 325                 // Output stub message
 326                 //* NOISY-DEBUG: */ printf('[%s:%d]: Invoking this->outputMessage(%s,%s) ...' . PHP_EOL, __METHOD__, __LINE__, Logger::LOGGER_LEVEL_WARNING, $subMessage);
 327                 $this->outputMessage(Logger::LOGGER_LEVEL_WARNING, $stubMessage);
 328
 329                 // Trace message
 330                 //* NOISY-DEBUG: */ printf('[%s:%d]: EXIT!' . PHP_EOL, __METHOD__, __LINE__);
 331         }
 332
 333         /**
 334          * Outputs a deprecated message whether to debug instance (should be set!) or
 335          * dies with or ptints the message. Do NEVER EVER rewrite the exit() call to
 336          * ApplicationEntryPoint::app_exit(), this would cause an endless loop.
 337          *
 338          * @param       $message        Message we shall send out...
 339          * @param       $doPrint        Whether print or die here (default: print)
 340          * @paran       $stripTags      Whether to strip tags (default: false)
 341          * @return      void
 342          * @throws      InvalidArgumentException        If a parameter has an invalid value
 343          * @throws      NullPointerException    If this->outputInstance is NULL
 344          * @todo        Remove $doPrint parameter
 345          * @todo        When all old method invocations are fixed, renamed this do deprecatedMessage
 346          */
 347         public function debugOutput (string $message, bool $doPrint = true, bool $stripTags = false) {
 348                 // Check parameter
 349                 //* NOISY-DEBUG: */ printf('[%s:%d]: message=%s,doPrint=%d,stripTags=%d - CALLED!' . PHP_EOL, __METHOD__, __LINE__, $message, intval($doPrint), intval($stripTags));
 350                 if (empty($message)) {
 351                         // Throw IAE
 352                         throw new InvalidArgumentException('Parameter "message" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
 353                 } elseif (is_null($this->getOutputInstance())) {
 354                         // Should not be NULL
 355                         throw new NullPointerException($this, self::EXCEPTION_IS_NULL_POINTER);
 356                 }
 357
 358                 // Invoke Inner method
 359                 //* NOISY-DEBUG: */ printf('[%s:%d]: Invoking this->outputMessage(%s,%s) ...' . PHP_EOL, __METHOD__, __LINE__, Logger::LOGGER_LEVEL_DEPRECATED, $subMessage);
 360                 $this->outputMessage(Logger::LOGGER_LEVEL_DEPRECATED, $message, $doPrint, $stripTags);
 361
 362                 // Trace message
 363                 //* NOISY-DEBUG: */ printf('[%s:%d]: EXIT!' . PHP_EOL, __METHOD__, __LINE__);
 364         }
 365
 366 }