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                 // Is the output stream set
 126                 //* NOISY-DEBUG: */ printf('[%s:%d]: message=%s,stripTags=%d - CALLED!' . PHP_EOL, __METHOD__, __LINE__, $message, intval($stripTags));
 127                 if (empty($message)) {
 128                         // @TODO Initialization phase
 129                         //* NOISY-DEBUG: */ printf('[%s:%d]: message is empty - EXIT!' . PHP_EOL, __METHOD__, __LINE__);
 130                         return;
 131                 }
 132
 133                 // Get backtrace
 134                 $backtrace = debug_backtrace(!DEBUG_BACKTRACE_PROVIDE_OBJECT);
 135
 136                 // Is the deprecated debugOutput() or partialStub() invoked before?
 137                 if (isset($backtrace[4]) && $backtrace[3]['function'] == 'partialStub') {
 138                         // Prepend class::function:line from 2nd element
 139                         //* NOISY-DEBUG: */ printf('[%s:%d]: partialStub() was invoked ...' . PHP_EOL, __METHOD__, __LINE__);
 140                         $message = sprintf('[%s::%s:%d]: %s',
 141                                 $backtrace[4]['class'],
 142                                 $backtrace[4]['function'],
 143                                 (isset($backtrace[4]['line']) ? $backtrace[4]['line'] : '0'),
 144                                 $message
 145                         );
 146                 } elseif (isset($backtrace[3]) && $backtrace[2]['function'] == 'debugOutput') {
 147                         // Prepend class::function:line from 2nd element
 148                         //* NOISY-DEBUG: */ printf('[%s:%d]: debugOutput() was invoked ...' . PHP_EOL, __METHOD__, __LINE__);
 149                         $message = sprintf('[%s::%s:%d]: DEPRECATED: %s',
 150                                 $backtrace[3]['class'],
 151                                 $backtrace[3]['function'],
 152                                 (isset($backtrace[3]['line']) ? $backtrace[3]['line'] : '0'),
 153                                 $message
 154                         );
 155                 } else {
 156                         // Prepend class::function:line from 2nd element
 157                         //* NOISY-DEBUG: */ printf('[%s:%d]: Ordinary invocation ...' . PHP_EOL, __METHOD__, __LINE__);
 158                         $message = sprintf('[%s::%s:%d]: %s',
 159                                 $backtrace[2]['class'],
 160                                 $backtrace[2]['function'],
 161                                 (isset($backtrace[2]['line']) ? $backtrace[2]['line'] : '0'),
 162                                 $message
 163                         );
 164                 }
 165
 166                 // Use the output instance
 167                 $this->getOutputInstance()->outputStream($message, $stripTags);
 168
 169                 // Trace message
 170                 //* NOISY-DEBUG: */ printf('[%s:%d]: EXIT!' . PHP_EOL, __METHOD__, __LINE__);
 171         }
 172
 173         /**
 174          * Getter for an instance of this class
 175          *
 176          * @return      $selfInstance           An instance of this class
 177          */
 178         public static final function getSelfInstance() {
 179                 return self::$selfInstance;
 180         }
 181
 182         /**
 183          * Outputs a trace message whether to debug instance (should be set!) or
 184          * dies with or ptints the message. Do NEVER EVER rewrite the exit() call to
 185          * ApplicationEntryPoint::app_exit(), this would cause an endless loop.
 186          *
 187          * @param       $message        Message we shall send out...
 188          * @param       $doPrint        Whether print or die here (default: print)
 189          * @paran       $stripTags      Whether to strip tags (default: false)
 190          * @return      void
 191          * @throws      InvalidArgumentException        If a parameter has an invalid value
 192          * @throws      NullPointerException    If this->outputInstance is NULL
 193          * @todo        Remove $doPrint parameter
 194          */
 195         public function traceMessage (string $message, bool $doPrint = true, bool $stripTags = false) {
 196                 // Check parameter
 197                 //* NOISY-DEBUG: */ printf('[%s:%d]: message=%s,doPrint=%d,stripTags=%d - CALLED!' . PHP_EOL, __METHOD__, __LINE__, $message, intval($doPrint), intval($stripTags));
 198                 if (empty($message)) {
 199                         // Throw IAE
 200                         throw new InvalidArgumentException('Parameter "message" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
 201                 } elseif (is_null($this->getOutputInstance())) {
 202                         // Should not be NULL
 203                         throw new NullPointerException($this, self::EXCEPTION_IS_NULL_POINTER);
 204                 }
 205
 206                 // Use debug output handler
 207                 //* NOISY-DEBUG: */ printf('[%s:%d]: Invoking this->output(%s,%d) ...' . PHP_EOL, __METHOD__, __LINE__, $message, intval($stripTags));
 208                 $this->output($message, $stripTags);
 209
 210                 // Trace message
 211                 //* NOISY-DEBUG: */ printf('[%s:%d]: EXIT!' . PHP_EOL, __METHOD__, __LINE__);
 212         }
 213
 214         /**
 215          * Outputs a debug message whether to debug instance (should be set!) or
 216          * dies with or ptints the message. Do NEVER EVER rewrite the exit() call to
 217          * ApplicationEntryPoint::app_exit(), this would cause an endless loop.
 218          *
 219          * @param       $message        Message we shall send out...
 220          * @param       $doPrint        Whether print or die here (default: print)
 221          * @paran       $stripTags      Whether to strip tags (default: false)
 222          * @return      void
 223          * @throws      InvalidArgumentException        If a parameter has an invalid value
 224          * @throws      NullPointerException    If this->outputInstance is NULL
 225          * @todo        Remove $doPrint parameter
 226          */
 227         public function debugMessage (string $message, bool $doPrint = true, bool $stripTags = false) {
 228                 // Check parameter
 229                 //* NOISY-DEBUG: */ printf('[%s:%d]: message=%s,doPrint=%d,stripTags=%d - CALLED!' . PHP_EOL, __METHOD__, __LINE__, $message, intval($doPrint), intval($stripTags));
 230                 if (empty($message)) {
 231                         // Throw IAE
 232                         throw new InvalidArgumentException('Parameter "message" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
 233                 } elseif (is_null($this->getOutputInstance())) {
 234                         // Should not be NULL
 235                         throw new NullPointerException($this, self::EXCEPTION_IS_NULL_POINTER);
 236                 }
 237
 238                 // Use debug output handler
 239                 //* NOISY-DEBUG: */ printf('[%s:%d]: Invoking this->output(%s,%d) ...' . PHP_EOL, __METHOD__, __LINE__, $message, intval($stripTags));
 240                 $this->output($message, $stripTags);
 241
 242                 // Trace message
 243                 //* NOISY-DEBUG: */ printf('[%s:%d]: EXIT!' . PHP_EOL, __METHOD__, __LINE__);
 244         }
 245
 246         /**
 247          * Outputs a warning message whether to debug instance (should be set!) or
 248          * dies with or ptints the message. Do NEVER EVER rewrite the exit() call to
 249          * ApplicationEntryPoint::app_exit(), this would cause an endless loop.
 250          *
 251          * @param       $message        Message we shall send out...
 252          * @param       $doPrint        Whether print or die here (default: print)
 253          * @paran       $stripTags      Whether to strip tags (default: false)
 254          * @return      void
 255          * @throws      InvalidArgumentException        If a parameter has an invalid value
 256          * @throws      NullPointerException    If this->outputInstance is NULL
 257          * @todo        Remove $doPrint parameter
 258          */
 259         public function warningMessage (string $message, bool $doPrint = true, bool $stripTags = false) {
 260                 // Check parameter
 261                 //* NOISY-DEBUG: */ printf('[%s:%d]: message=%s,doPrint=%d,stripTags=%d - CALLED!' . PHP_EOL, __METHOD__, __LINE__, $message, intval($doPrint), intval($stripTags));
 262                 if (empty($message)) {
 263                         // Throw IAE
 264                         throw new InvalidArgumentException('Parameter "message" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
 265                 } elseif (is_null($this->getOutputInstance())) {
 266                         // Should not be NULL
 267                         throw new NullPointerException($this, self::EXCEPTION_IS_NULL_POINTER);
 268                 }
 269
 270                 // Use debug output handler
 271                 //* NOISY-DEBUG: */ printf('[%s:%d]: Invoking this->output(%s,%d) ...' . PHP_EOL, __METHOD__, __LINE__, $message, intval($stripTags));
 272                 $this->output($message, $stripTags);
 273
 274                 // Trace message
 275                 //* NOISY-DEBUG: */ printf('[%s:%d]: EXIT!' . PHP_EOL, __METHOD__, __LINE__);
 276         }
 277
 278         /**
 279          * Outputs a debug message whether to debug instance (should be set!) or
 280          * dies with or ptints the message. Do NEVER EVER rewrite the exit() call to
 281          * ApplicationEntryPoint::app_exit(), this would cause an endless loop.
 282          *
 283          * @param       $message        Message we shall send out...
 284          * @param       $doPrint        Whether print or die here (default: print)
 285          * @paran       $stripTags      Whether to strip tags (default: false)
 286          * @return      void
 287          * @throws      InvalidArgumentException        If a parameter has an invalid value
 288          * @throws      NullPointerException    If this->outputInstance is NULL
 289          * @todo        Remove $doPrint parameter
 290          * @deprecated  Rewrite to "new" methods above
 291          */
 292         public function debugOutput (string $message, bool $doPrint = true, bool $stripTags = false) {
 293                 // Check parameter
 294                 //* NOISY-DEBUG: */ printf('[%s:%d]: message=%s,doPrint=%d,stripTags=%d - CALLED!' . PHP_EOL, __METHOD__, __LINE__, $message, intval($doPrint), intval($stripTags));
 295                 if (empty($message)) {
 296                         // Throw IAE
 297                         throw new InvalidArgumentException('Parameter "message" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
 298                 } elseif (is_null($this->getOutputInstance())) {
 299                         // Should not be NULL
 300                         throw new NullPointerException($this, self::EXCEPTION_IS_NULL_POINTER);
 301                 }
 302
 303                 // Invoke new version
 304                 $this->debugMessage($message, $doPrint, $stripTags);
 305
 306                 // Trace message
 307                 //* NOISY-DEBUG: */ printf('[%s:%d]: EXIT!' . PHP_EOL, __METHOD__, __LINE__);
 308         }
 309
 310 }