Restore some backwards compatibility for injected handlers

Some plugins, for example the move plugin, use their own handler class.
We need to give these plugins time to adjust their code.

This should restore the functionality of the move plugin. We still need
to extract the handler class itself.

It also adds another debug method for triggering the deprecation event,
since none of the two existing methods are suitable here. This
dbgCustomDeprecationEvent method should be used sparingly and only where
the other two don't work.

Co-authored-by: Phy <git@phy25.com>

inc/Debug/DebugHelper.php

@@ -83,6 +83,48 @@ class DebugHelper
         );
     }
 
+    /**
+     * Trigger a custom deprecation event
+     *
+     * Usually dbgDeprecatedFunction() or dbgDeprecatedProperty() should be used instead.
+     * This method is intended only for those situation where they are not applicable.
+     *
+     * @param string $alternative
+     * @param string $deprecatedThing
+     * @param string $caller
+     * @param string $file
+     * @param int    $line
+     * @param int    $callerOffset How many lines should be removed from the beginning of the backtrace
+     */
+    public static function dbgCustomDeprecationEvent(
+        $alternative,
+        $deprecatedThing,
+        $caller,
+        $file,
+        $line,
+        $callerOffset = 1
+    ) {
+        global $conf;
+        /** @var EventHandler $EVENT_HANDLER */
+        global $EVENT_HANDLER;
+        if (!$conf['allowdebug'] && !$EVENT_HANDLER->hasHandlerForEvent(self::INFO_DEPRECATION_LOG_EVENT)) {
+            // avoid any work if no one cares
+            return;
+        }
+
+        $backtrace = array_slice(debug_backtrace(), $callerOffset);
+
+        self::triggerDeprecationEvent(
+            $backtrace,
+            $alternative,
+            $deprecatedThing,
+            $caller,
+            $file,
+            $line
+        );
+
+    }
+
     /**
      * @param array  $backtrace
      * @param string $alternative

inc/Parsing/Parser.php

@@ -107,7 +107,21 @@ class Parser {
         // Normalize CRs and pad doc
         $doc = "\n" . str_replace("\r\n", "\n", $doc) . "\n";
         $this->lexer->parse($doc);
-        $this->handler->finalize();
+
+        if (!method_exists($this->handler, 'finalize')) {
+            /** @deprecated 2019-10 we have a legacy handler from a plugin, assume legacy _finalize exists */
+
+            \dokuwiki\Debug\DebugHelper::dbgCustomDeprecationEvent(
+                'finalize()',
+                get_class($this->handler) . '::_finalize()',
+                __METHOD__,
+                __FILE__,
+                __LINE__
+            );
+            $this->handler->_finalize();
+        } else {
+            $this->handler->finalize();
+        }
         return $this->handler->calls;
     }