[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  
   4  namespace dokuwiki\Debug;
   5  
   6  use Doku_Event;
   7  use dokuwiki\Extension\EventHandler;
   8  use dokuwiki\Logger;
   9  
  10  class DebugHelper
  11  {
  12      const INFO_DEPRECATION_LOG_EVENT = 'INFO_DEPRECATION_LOG';
  13  
  14      /**
  15       * Check if deprecation messages shall be handled
  16       *
  17       * This is either because its logging is not disabled or a deprecation handler was registered
  18       *
  19       * @return bool
  20       */
  21      public static function isEnabled()
  22      {
  23          /** @var EventHandler $EVENT_HANDLER */
  24          global $EVENT_HANDLER;
  25          if (
  26              !Logger::getInstance(Logger::LOG_DEPRECATED)->isLogging() &&
  27              ($EVENT_HANDLER === null || !$EVENT_HANDLER->hasHandlerForEvent('INFO_DEPRECATION_LOG'))
  28          ) {
  29              // avoid any work if no one cares
  30              return false;
  31          }
  32          return true;
  33      }
  34  
  35      /**
  36       * Log accesses to deprecated fucntions to the debug log
  37       *
  38       * @param string $alternative (optional) The function or method that should be used instead
  39       * @param int $callerOffset (optional) How far the deprecated method is removed from this one
  40       * @param string $thing (optional) The deprecated thing, defaults to the calling method
  41       * @triggers \dokuwiki\Debug::INFO_DEPRECATION_LOG_EVENT
  42       */
  43      public static function dbgDeprecatedFunction($alternative = '', $callerOffset = 1, $thing = '')
  44      {
  45          if (!self::isEnabled()) return;
  46  
  47          $backtrace = debug_backtrace();
  48          for ($i = 0; $i < $callerOffset; $i += 1) {
  49              if(count($backtrace) > 1) array_shift($backtrace);
  50          }
  51  
  52          list($self, $call) = $backtrace;
  53  
  54          if (!$thing) {
  55              $thing = trim(
  56                  (!empty($self['class']) ? ($self['class'] . '::') : '') .
  57                  $self['function'] . '()', ':');
  58          }
  59  
  60          self::triggerDeprecationEvent(
  61              $backtrace,
  62              $alternative,
  63              $thing,
  64              trim(
  65                  (!empty($call['class']) ? ($call['class'] . '::') : '') .
  66                  $call['function'] . '()', ':'),
  67              $self['file'] ?? $call['file'] ?? '',
  68              $self['line'] ?? $call['line'] ?? 0
  69          );
  70      }
  71  
  72      /**
  73       * This marks logs a deprecation warning for a property that should no longer be used
  74       *
  75       * This is usually called withing a magic getter or setter.
  76       * For logging deprecated functions or methods see dbgDeprecatedFunction()
  77       *
  78       * @param string $class The class with the deprecated property
  79       * @param string $propertyName The name of the deprecated property
  80       *
  81       * @triggers \dokuwiki\Debug::INFO_DEPRECATION_LOG_EVENT
  82       */
  83      public static function dbgDeprecatedProperty($class, $propertyName)
  84      {
  85          if (!self::isEnabled()) return;
  86  
  87          $backtrace = debug_backtrace();
  88          array_shift($backtrace);
  89          $call = $backtrace[1];
  90          $caller = trim($call['class'] . '::' . $call['function'] . '()', ':');
  91          $qualifiedName = $class . '::$' . $propertyName;
  92          self::triggerDeprecationEvent(
  93              $backtrace,
  94              '',
  95              $qualifiedName,
  96              $caller,
  97              $backtrace[0]['file'],
  98              $backtrace[0]['line']
  99          );
 100      }
 101  
 102      /**
 103       * Trigger a custom deprecation event
 104       *
 105       * Usually dbgDeprecatedFunction() or dbgDeprecatedProperty() should be used instead.
 106       * This method is intended only for those situation where they are not applicable.
 107       *
 108       * @param string $alternative
 109       * @param string $deprecatedThing
 110       * @param string $caller
 111       * @param string $file
 112       * @param int $line
 113       * @param int $callerOffset How many lines should be removed from the beginning of the backtrace
 114       */
 115      public static function dbgCustomDeprecationEvent(
 116          $alternative,
 117          $deprecatedThing,
 118          $caller,
 119          $file,
 120          $line,
 121          $callerOffset = 1
 122      )
 123      {
 124          if (!self::isEnabled()) return;
 125  
 126          $backtrace = array_slice(debug_backtrace(), $callerOffset);
 127  
 128          self::triggerDeprecationEvent(
 129              $backtrace,
 130              $alternative,
 131              $deprecatedThing,
 132              $caller,
 133              $file,
 134              $line
 135          );
 136  
 137      }
 138  
 139      /**
 140       * @param array $backtrace
 141       * @param string $alternative
 142       * @param string $deprecatedThing
 143       * @param string $caller
 144       * @param string $file
 145       * @param int $line
 146       */
 147      private static function triggerDeprecationEvent(
 148          array $backtrace,
 149          $alternative,
 150          $deprecatedThing,
 151          $caller,
 152          $file,
 153          $line
 154      )
 155      {
 156          $data = [
 157              'trace' => $backtrace,
 158              'alternative' => $alternative,
 159              'called' => $deprecatedThing,
 160              'caller' => $caller,
 161              'file' => $file,
 162              'line' => $line,
 163          ];
 164          $event = new Doku_Event(self::INFO_DEPRECATION_LOG_EVENT, $data);
 165          if ($event->advise_before()) {
 166              $msg = $event->data['called'] . ' is deprecated. It was called from ';
 167              $msg .= $event->data['caller'] . ' in ' . $event->data['file'] . ':' . $event->data['line'];
 168              if ($event->data['alternative']) {
 169                  $msg .= ' ' . $event->data['alternative'] . ' should be used instead!';
 170              }
 171              Logger::getInstance(Logger::LOG_DEPRECATED)->log($msg);
 172          }
 173          $event->advise_after();
 174      }
 175  }