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