Remember how I said we’re no longer doing Release Candidates? Well, as you may have noticed, we just did three Release Candidates within a short succession. And a look at the issue reports and forum posts shows how that was a good idea.

Despite me having no problems with the development version of DokuWiki for the last years, there were quite a few problems that only surfaced once we had a much broader install base. Nearly all issues arise from compatibility with plugins or templates.

Here are the main problems I have seen so far with the Release Candidates and what to do about them. This post is mainly aimed at plugin and template developers to give them an idea on how to fix any problem in their extensions.

End users should have a look at What to do when a plugin doesn't work on Hogfather.

Missing DOKU_LEXER constants

The big refactoring we did means a lot of code moved around. We now make heavy use of auto loading which means PHP will dynamically load the code it needs avoiding to load code not needed. This should enhance the performance and makes coding a little easier, too.

However a side effect was that certain constants were not always loaded, even though plugins relied on them being defined. The result were error messages or weird behavior in regards to cached page output with page content only sometimes being shown, just to vanish on the next page reload.

This was a clear bug in DokuWiki and has been fixed with RC3. A lot of previously broken plugins will now magically work again.

Bad Imports

Another problem I’ve seen with some plugins is that they import some of DokuWiki’s files and that those files no longer exist or have been moved elsewhere. A typical error message would be

PHP Fatal error:  require_once(): Failed opening required '/data/dokuwiki/inc/JSON.php'

The quick solution in most cases is to simply remove the call to require or include. DokuWiki’s autoloading will take care of loading the file when needed.

A note of warning about the above error though: the JSON class is deprecated and PHP’s builtin json_encode and json_decode functions should be used instead. (See further down for additional hints on deprecated code).

Deferred JavaScript

By default Hogfather loads all JavaScript with the defer attribute. This means, all JavaScript is loaded asynchronously and executed last. This increases the perceived loading speed for the end user, because the actual content is available much faster.

However plugin and template developers have to take care with their own JavaScript. If you encounter broken JavaScript (errors in the JavaScript console, missing functionality like the toolbar, etc.) you might be affected by the change of JavaScript loading.

If your plugin or template is affected, check the following advice:

• If possible, use script.js and DokuWiki’s include mechanisms to load additional script files - it will automatically be loaded with the defer attribute
• If you load additional scripts via the TPL_METAHEADER_OUTPUT event, be sure to add the defer attribute
• If you embed scripts directly in the output of your plugin, make sure that code has no dependencies on any of DokuWiki’s libraries (like jQuery) or ensure it is only executed later. Eg. embed some configuration only and trigger the actual script execution based on that config via script.js
• Never use document.write()! Instead use DOM manipulation methods

End users can disable the deferred loading by toggling the defer_js feature flag for now. However the behavior will become default in a future DokuWiki release and needs to be fixed properly.

Inaccessible DokuWiki Internals

We cleaned up a lot of our code and brought it to modern PHP standards. That also means we use proper access declaration and no longer use underscores to signal private properties or methods.

It might happen, that a plugin used some DokuWiki internal that now has been marked as private or protected and can no longer be accessed by plugins. In that case a bug report should be opened, describing the use case.

We may either find a better way to achieve the same goal or we may open up certain internals again.

Deprecated Code

A lot of code has been marked as deprecated. Which means it will be removed in future releases of DokuWiki. While this does not cause plugins to malfunction now, it may lead to nasty surprises after future updates.

Plugin authors can easily check if they use any deprecated functions, classes or methods:

• enable the allowdebug option
• use the plugin
• check data/cache/debug.log for any information about deprecated calls caused by the plugin

Signature Mismatches

This is an old problem with PHP 7+ compatibility. Please read my post Declaration should be compatible with... for more info.