For the “Hogfather” release of 2020 big parts of DokuWiki are refactored. This page lists changes upto August 2020. For more recent changes see refactor2021.

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

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

Since the Igor 2022 release:

• logging of deprecated messages is controlled by the dontlog configuration setting; it is enabled by default, if not uncheck deprecated.
• use the plugin
• check LogViewer (or data/log/deprecated/<date>.log).

Up to the Hogfather 2020 release:

• enable the allowdebug setting in the Configuration Manager
• use the plugin
• Check logs for any information about deprecated calls caused by the plugin in data/cache/debug.log .

Pull request 3067:

mail_send() and mail_encode_address() are removed. Functions were replaced by the Mailer class some years ago.

Example

  $text = rawLocale('password');
- $text = str_replace('@DOKUWIKIURL@',DOKU_URL,$text);
- $text = str_replace('@FULLNAME@',$userinfo['name'],$text);
- $text = str_replace('@LOGIN@',$user,$text);
- $text = str_replace('@PASSWORD@',$password,$text);
- $text = str_replace('@TITLE@',$conf['title'],$text);
- 
- return mail_send($userinfo['name'].' <'.$userinfo['mail'].'>',
-         $lang['regpwmail'],
-         $text,
-         $conf['mailfrom']);
+ $trep = array(
+             'FULLNAME' => $userinfo['name'],
+             'LOGIN'    => $user,
+             'PASSWORD' => $password
+         );
+ 
+ $mail = new Mailer();
+ $mail->to($userinfo['name'].' <'.$userinfo['mail'].'>');
+ $mail->subject($lang['regpwmail']);
+ $mail->setBody($text,$trep);
+ return $mail->send();

Below, you find lists with renamed, changed and moved parts of DokuWiki. Some examples are provided for easier update of plugins and templates. References to codesearch.dokuwiki.org can help locate its usage.

Most of the changes documented here are merged with pull request 2358. Sometimes some smaller pull requests are referred as well.

Code changes: d443762baf and 2686

Search usage: "inc\/JSON.php", "json->encode" and "json->decode"

// Remove always the require, since years already autoloaded 
// and file is now removed as well
- require_once DOKU_INC . 'inc/JSON.php';
 
- $json = new JSON;
- $str = $json->encode($data);
- $data = $json->decode($str);
+ $str = json_encode($data);
+ $data = json_decode($str);
 
 
- $json = new JSON(JSON_LOOSE_TYPE);
- $str = $json->encode($data);
- $data = $json->decode($str);
+ $str = json_encode($data, true);
+ $data = json_decode($str, true);

e.g. Doku_Handler_List is replaced by dokuwiki\Parsing\Handler\Lists. Needed code update:

//import at begin of the file:
+ use dokuwiki\Parsing\Handler\Lists;
 
//at place of usage:
- class Doku_Handler_Creole_List extends Doku_Handler_List {
+ class Doku_Handler_Creole_List extends Lists {

Tip: when using a IDE, like Intellij idea, it will suggest a lot of the imports if you use the class names.

The following classes are renamed:

Variables are not available anymore:

• $handler->status[]
• $handler->CallWriter

Functions renamed:

• $handler->_addCall()
• $handler->_finalize()

Search usage: status, CallWriter and _addCall, _finalize

Replacements:

- $status = $handler->status['section']
+ $status = $handler->getStatus('section')
 
- $handler->status['section'] = true
+ $handler->setStatus('section', true)

case DOKU_LEXER_ENTER:
-   $ReWriter = new Doku_Handler_Creole_List($handler->CallWriter);
-   $handler->CallWriter = & $ReWriter;
+   $ReWriter = new Doku_Handler_Creole_List($handler->getCallWriter());
+   $handler->setCallWriter($ReWriter);
 
case DOKU_LEXER_EXIT:
-   $handler->CallWriter->process();
-   $ReWriter = & $handler->CallWriter;
-   $handler->CallWriter = & $ReWriter->CallWriter;
+   $ReWriter = $handler->getCallWriter();
+   $handler->setCallWriter($ReWriter->process());

- $handler->_addCall('list_close', array(), $pos);
+ $handler->addCall('list_close', array(), $pos);

Note: some general addCall() can be replaced by the specific functions like header(), eof(), hr(), strong(), emphasis(), underline(), etc etc. Could be worth a check, however there should be typical a reason that these specific functions were not used.

Renamed variables: Handler and Lexer to handler and lexer. (maybe no difference in practice due to case-insensitivity)

Changed visibility, these variables are now protected: handler, lexer, modes, connected. The handler can be set via the constructor. There are no setters or getters for the others.

- $parser = new Doku_Parser();
- $parser->Handler = $handler;
+ $parser = new Parser($handler);

Variables and functions are not available anymore:

• $lexer->_mode
• function Doku_Lexer_Escape($str)

Search usage: _mode, Doku_Lexer_Escape and _dispatchTokens

- $lexer->_mode->getCurrent();
+ $lexer->getModeStack()->getCurrent();

- $str = Doku_Lexer_Escape($str);
+ $str = \dokuwiki\Parsing\Lexer\Lexer::escape($str);

Other renamed protected functions of Lexer: _dispatchTokens(), _isModeEnd(), _isSpecialMode(), _decodeSpecial(), _invokeParser() and _reduce().

Renamed protected functions of ParallelRegex: _getCompoundedRegex(), _getPerlMatchingFlags().

All UTF-8 functions are moved and renamed. Refactored mostly in 2780.

Class for handling UTF-8 in filenames. Renamed functions:

Changed visibility, these variables are now protected and have new setters/getters:

? CHECK: NO SETTER FOR nocache, while used in plugins

- $time = $cache->_time 
+ $time = $cache->getTime())
 
- $cache = new cache_renderer($ID, $file, 'xhtml');
- $useCache = $cache->_nocache
+ $cache = new CacheRenderer($ID, $file, 'xhtml');
+ $useCache = $cache->isNoCache()
 
- $cache->_event = $event
+ $cache->setEvent($event)
- $event = $cache->_event 
+ $event = $cache->getEvent()

Renamed and moved classes:

Renamed and moved classes:

Refactored mostly in 2757

Renamed and moved classes:

Renamed and moved functions:

• trigger_event() → Event::createAndTrigger()
• isdisabled() → !$plugin_controller->isEnabled()

+ use dokuwiki\Extension\Event;
 
- trigger_event('FEED_OPTS_POSTPROCESS', $eventData);
+ Event::createAndTrigger('FEED_OPTS_POSTPROCESS', $eventData);

  global $pluginController;
- $isDisabled = $pluginController->isdisabled($plugin);
+ $isDisabled = !$pluginController->isEnabled($plugin);

Variables

PR 2358 and 55cc5b9

Renamed public functions:

Renamed and changed to protected functions:

Renamed and refactored in separated classes:

Examples:

- $subscription = new Subscription();
- $success = $subscription->send_register($login, $fullname, $email);
+ $subscription = new RegistrationSubscriptionSender();
+ $success = $subscription->sendRegister($login, $fullname, $email);
 
- $sub = new Subscription();
- $info['subscribed'] = $sub->user_subscription();
+ $subManager = new SubscriberManager();
+ $info['subscribed'] = $subManager->userSubscription();
 
- $subscription = new Subscription();
- $success = $subscription->send_diff($to, $tpl, $id, $rev, $summary);
+ $subscription = new PageSubscriptionSender();
+ $success = $subscription->sendPageDiff($to, $tpl, $id, $rev, $summary);
 
 
- $subscription = new Subscription();
- $success = $subscription->send_media_diff($subscriber_mail, $template, $id, $rev);
+ $subscriptionSender = new MediaSubscriptionSender();
+ $success = $subscriptionSender->sendMediaDiff($subscriber_mail, $template, $id, $rev);
 
- $subscription = new Subscription();
- $success = $subscription->isenabled();
- $success = $subscription->subscribers($page, $user, $style, $data);
- $success = $subscription->add($id, $user, $style, $data)
- $success = $subscription->remove($id, $user, $style, $data)
- $success = $subscription->user_subscription($id, $user)
- $subscription->notifyaddresses($data)
+ $manager = new SubscriberManager();
+ $success = $manager->isenabled();
+ $success = $manager->subscribers($page, $user, $style, $data);
+ $success = $manager->add($id, $user, $style, $data);
+ $success = $manager->remove($id, $user, $style, $data);
+ $success = $manager->userSubscription($id, $user);
+ $manager->notifyAddresses($data);
 
- $subscription = new Subscription();
- $success = $subscription->send_bulk($page);
+ $subscriptionSender = new BulkSubscriptionSender();
+ $success = $subscriptionSender->sendBulk($page);

Renamed and moved classes:

Visibility changed to protected variables: connections, boundary

Visibility changed to protected and renamed functions: _ssltunnel, _sendData, _readData, _readLine, _debug _debug_html, _debug_text, _time, _parseHeaders, _buildHeaders, _getCookies, _postEncode, _postMultipartEncode, _uniqueConnectionId. All the underscored are removed from the function names, and two names changed more: debugHtml, debugText.

Renamed and moved classes:

Refactored mostly in 2382

Renamed and moved classes:

The Configuration class is significant refactored. So check yourself for functions moved to the new classes and renamed functions.

Renamed and moved classes:

There are some old signatures that need still some attention in some plugins.

In action.php:

- function alwaysHide(Doku_Event &$event, $params) {
+ function alwaysHide(Doku_Event $event, $params) {

and syntax.php:

- public function handle($match, $state, $pos, &$handler){
+ public function handle($match, $state, $pos, Doku_Handler $handler){
 
- public function render($mode, &$renderer, $data) {
+ public function render($mode, Doku_Renderer $renderer, $data) {

In 2012, c476695 replaced the path in constants by functions which are more dynamic.

- if (file_exists(DOKU_TPLINC . 'user/logo.png')){
-     //user defined PNG
-     echo '<img src="' . DOKU_TPL . 'user/logo.png" id="tmpl_header_logo_img" alt=""/>';
+ if (file_exists(tpl_incdir() . 'user/logo.png')) {
+     //user defined PNG
+     echo '<img src="' . tpl_basedir() . 'user/logo.png" id="tmpl_header_logo_img" alt=""/>';

The introduction of jQuery in 2011, replaced a set of helpful functions. See also jQuery FAQ.

$('…') as shortcut for document.getElementById('…') is replaced by jQuery('#…')

- var obj = $('some__id');
- // obj now is a DOM object
 
+ let $obj = jQuery('#some__id');
+ // $obj is a jQuery object - if you really need the DOM object use [0] e.g.:
+ let obj = $obj[0];

use jQuery's selectors instead

- var htmlelements = getElementsByClass( 'class', document, 'tag');
- // htmlelements now is an array of DOM elements
- for(var n in htmlelements ) {
-     dosomething( htmlelements[n] );
- }
 
  /* New code */
+ jQuery('tag.class').each(function(){
+     dosomething(this);
+ });
 
  /* Or, this new code */
+ let $jqueryelements = jQuery('tag.class');
+ // $jqueryelements is a jquery thing: an array plus some other stuff.
+ $jqueryelements.each(function(){
+     dosomething(this);
+ });
 
  /* or, if you prefer (it shows some part of the internals) */
+ for (let n = 0; n < $jqueryelements.length; ++n ) {
+     dosomething($jqueryelements[n]);
+ }

• It is common to start the variable which contain a jQuery object with a $-character, but it is not required.

registering callbacks to be run when the DOM is ready to be used - use jQuery's callback mechanism instead.

- addInitEvent(function(){
-     alert("DOM is ready");
- });
 
+ jQuery(function(){
+     alert("DOM is ready");
+ });

Registering event handlers - use jQuery's event methods instead.

  /* Old code */
- addEvent(obj, "click", function(){ 
-     alert("Click happened!")
- });
 
  /* Recenter old code */
- jQuery(obj).click(function(){ 
-     alert("Click happened!") 
- });
 
  /* New code */
+ jQuery(obj).on("click", function(){ 
+     alert("Click happened!") 
+ });

• replace “click” by the event you need e.g. “change”, “blur”, “focus” and the like (see jQuery link above)

executing AJAX requests - use jQuery's AJAX methods instead.

  /* Old code */
- sack = new sack(DOKU_BASE + 'lib/exe/ajax.php');                                                        
- sack.AjaxFailedAlert = '';                                                                              
- sack.encodeURIString = false;
- sack.runAJAX('call=linkwiz&q='+encodeURI(value));
 
  /* New code */
+ jQuery.post(
+     DOKU_BASE + 'lib/exe/ajax.php',
+     { call: 'linkwiz', q: value }
+ );

Lot of plugins uses the following older code. Today these are already included via the core or not needed anymore.

The following code is only needed if a file has main code that is executed. Otherwise it can be left out.

- if(!defined('DOKU_INC')) die('meh.');

Code beautification. The defines are already in core, so can be deleted. Further these code beautifications are not needed anymore with current debugging tools.

- // Some whitespace to help View > Source
- if(!defined('DOKU_LF')) define ('DOKU_LF', "\n");
 
- // Some whitespace to help View > Source
- if(!defined('DOKU_TAB')) define ('DOKU_TAB', "\t");
 
- if(!defined('NL')) define('NL',"\n");

This directory is set in the core, not needed per plugin.

- if(!defined('DOKU_PLUGIN')) {
-     define('DOKU_PLUGIN',DOKU_INC.'lib/plugins/');
- }

Scripts includes such as require and require_one are not needed for all the DokuWiki files or the typical plugin files. DokuWiki has an autoloader. More and more parts of the core use namespaces. Please use them, see autoloader how these are related to your files.

- require_once(DOKU_PLUGIN . 'syntax.php');
- require_once(DOKU_PLUGIN . 'action.php');
- require_once(DOKU_PLUGIN . 'admin.php');
etc
 
- require_once DOKU_INC . 'inc/parser/lexer.php';
- require_once DOKU_INC . 'inc/parser/handler.php';
etc

The historical getInfo() is superseeded by plugin.info.txt (more details). The old getInfo() can be removed in 99.9% of the cases.

- public function getInfo() {
- ...
- }

Do not use public properties, but setter/getter functions if available.

Example for the renderer:

- $renderer->info['cache'] = false;
+ $renderer->nocache();