1<?php
2
3
4namespace dokuwiki\Debug;
5
6use Doku_Event;
7use dokuwiki\Extension\EventHandler;
8use dokuwiki\Logger;
9
10class 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}
176