[ Index ] |
PHP Cross Reference of DokuWiki |
[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 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body