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