DokuWiki

It's better when it's simple

User Tools

Site Tools


Sidebar

Translations of this page?:

Learn about DokuWiki

Advanced Use

Corporate Use

Our Community


Follow us on Facebook, Twitter and other social networks.

Our Privacy Policy

devel:releases:refactor2020

developer changelog

Refactoring 2020

For the release of 2020 big parts of DokuWiki are refactored.

Please share all remarks and possible improvements. See forum topic. Thank you very much! klap-in

How to find 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 (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:

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

Removed code

Pull request 3067:

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

Deprecated and changed code

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.

JSON class is deprecated

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);

Handlers callwriters, modes and lexer are renamed

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:

Old New
Doku_Handler_CallWriter_Interface Doku_Handler_CallWriter dokuwiki\Parsing\Handler\CallWriterInterface dokuwiki\Parsing\Handler\CallWriter
new
new
Doku_Handler_Block
Doku_Handler_List
Doku_Handler_Nest Doku_Handler_Preformatted Doku_Handler_Quote Doku_Handler_Table
dokuwiki\Parsing\Handler\ReWriterInterface dokuwiki\Parsing\Handler\AbstractRewriter dokuwiki\Parsing\Handler\Block dokuwiki\Parsing\Handler\Lists dokuwiki\Parsing\Handler\Nest dokuwiki\Parsing\Handler\Preformatted dokuwiki\Parsing\Handler\Quote dokuwiki\Parsing\Handler\Table
Doku_Parserdokuwiki\Parsing\Parser
Doku_Lexer
Doku_LexerParallelRegex Doku_LexerStateStack
dokuwiki\Parsing\Lexer\Lexer dokuwiki\Parsing\Lexer\ParallelRegex dokuwiki\Parsing\Lexer\StateStack
Doku_Parser_Mode_Interface Doku_Parser_Mode Doku_Parser_Mode_acronym Doku_Parser_Mode_base Doku_Parser_Mode_camelcaselink Doku_Parser_Mode_code Doku_Parser_Mode_emaillink Doku_Parser_Mode_entity Doku_Parser_Mode_eol Doku_Parser_Mode_externallink Doku_Parser_Mode_file Doku_Parser_Mode_filelink Doku_Parser_Mode_footnote Doku_Parser_Mode_formatting Doku_Parser_Mode_header Doku_Parser_Mode_hr Doku_Parser_Mode_html Doku_Parser_Mode_internallink Doku_Parser_Mode_linebreak Doku_Parser_Mode_listblock Doku_Parser_Mode_media Doku_Parser_Mode_multiplyentity Doku_Parser_Mode_nocache Doku_Parser_Mode_notoc Doku_Parser_Mode_php Doku_Parser_Mode_Plugin Doku_Parser_Mode_preformatted Doku_Parser_Mode_quote Doku_Parser_Mode_quotes Doku_Parser_Mode_rss Doku_Parser_Mode_smiley Doku_Parser_Mode_table Doku_Parser_Mode_unformatted Doku_Parser_Mode_windowssharelink Doku_Parser_Mode_wordblockdokuwiki\Parsing\ParserMode\ModeInterface dokuwiki\Parsing\ParserMode\AbstractMode dokuwiki\Parsing\ParserMode\Acronym dokuwiki\Parsing\ParserMode\Base dokuwiki\Parsing\ParserMode\Camelcaselink dokuwiki\Parsing\ParserMode\Code dokuwiki\Parsing\ParserMode\Emaillink dokuwiki\Parsing\ParserMode\Entity dokuwiki\Parsing\ParserMode\Eol dokuwiki\Parsing\ParserMode\Externallink dokuwiki\Parsing\ParserMode\File dokuwiki\Parsing\ParserMode\Filelink dokuwiki\Parsing\ParserMode\Footnote dokuwiki\Parsing\ParserMode\Formatting dokuwiki\Parsing\ParserMode\Header dokuwiki\Parsing\ParserMode\Hr dokuwiki\Parsing\ParserMode\Html dokuwiki\Parsing\ParserMode\Internallink dokuwiki\Parsing\ParserMode\Linebreak dokuwiki\Parsing\ParserMode\Listblock dokuwiki\Parsing\ParserMode\Media dokuwiki\Parsing\ParserMode\Multiplyentity dokuwiki\Parsing\ParserMode\Nocache dokuwiki\Parsing\ParserMode\Notoc dokuwiki\Parsing\ParserMode\Php dokuwiki\Parsing\ParserMode\Plugin dokuwiki\Parsing\ParserMode\Preformatted dokuwiki\Parsing\ParserMode\Quote dokuwiki\Parsing\ParserMode\Quotes dokuwiki\Parsing\ParserMode\Rss dokuwiki\Parsing\ParserMode\Smiley dokuwiki\Parsing\ParserMode\Table dokuwiki\Parsing\ParserMode\Unformatted dokuwiki\Parsing\ParserMode\Windowssharelink dokuwiki\Parsing\ParserMode\Wordblock

Changes of the internals of the handler

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.

Changes of the internals of the parser

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);

Changes of the internals of the Lexer

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().

UTF-8 functions

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

Old New
inline code\dokuwiki\Utf8\Asian::isAsianWords()
\dokuwiki\Utf8\Asian::separateAsianWords()
\dokuwiki\Utf8\Asian::splitAsianWords()
IDX_ASIAN\dokuwiki\Utf8\Asian::REGEXP
utf8_isASCII
utf8_check
utf8_strip
utf8_stripspecials
utf8_bad_replace
utf8_deaccent
utf8_romanize
utf8_correctIdx
\dokuwiki\Utf8\Clean::isASCII()
\dokuwiki\Utf8\Clean::isUtf8()
\dokuwiki\Utf8\Clean::strip()
\dokuwiki\Utf8\Clean::stripspecials()
\dokuwiki\Utf8\Clean::replaceBadBytes()
\dokuwiki\Utf8\Clean::deaccent()
\dokuwiki\Utf8\Clean::romanize()
\dokuwiki\Utf8\Clean::correctIdx()
utf8_tohtml
utf8_unhtml
utf8_to_utf16be
utf16be_to_utf8
\dokuwiki\Utf8\Conversion::toHtml()
\dokuwiki\Utf8\Conversion::fromHtml()
\dokuwiki\Utf8\Conversion::toUtf16be()
\dokuwiki\Utf8\Conversion::fromUtf16be()
utf8_basename
utf8_strlen
utf8_substr
utf8_substr_replace
utf8_ltrim
utf8_rtrim
utf8_trim
utf8_strtolower
utf8_strtoupper
utf8_ucfirst
utf8_ucwords
utf8_strpos
\dokuwiki\Utf8\PhpString::basename()
\dokuwiki\Utf8\PhpString::strlen()
\dokuwiki\Utf8\PhpString::substr()
\dokuwiki\Utf8\PhpString::substr_replace()
\dokuwiki\Utf8\PhpString::ltrim()
\dokuwiki\Utf8\PhpString::rtrim()
\dokuwiki\Utf8\PhpString::trim()
\dokuwiki\Utf8\PhpString::strtolower()
\dokuwiki\Utf8\PhpString::strtoupper()
\dokuwiki\Utf8\PhpString::ucfirst()
\dokuwiki\Utf8\PhpString::ucwords()
\dokuwiki\Utf8\PhpString::strpos()
utf8_to_unicode
unicode_to_utf8
\dokuwiki\Utf8\Unicode::fromUtf8()
\dokuwiki\Utf8\Unicode::toUtf8()
globals
UTF8_UPPER_TO_LOWER
UTF8_LOWER_TO_UPPER
UTF8_LOWER_ACCENTS
UTF8_UPPER_ACCENTS
UTF8_ROMANIZATION
UTF8_SPECIAL_CHARS
UTF8_SPECIAL_CHARS2

\dokuwiki\Utf8\Table::upperCaseToLowerCase()
\dokuwiki\Utf8\Table::lowerCaseToUpperCase()
\dokuwiki\Utf8\Table::lowerAccents()
\dokuwiki\Utf8\Table::upperAccents()
\dokuwiki\Utf8\Table::romanization()
\dokuwiki\Utf8\Table::specialChars()
TO CHECK: combined? or deprecated/removed??

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

SafeFN::validate_printable_utf8
SafeFN::validate_safe
SafeFN::validatePrintableUtf8()
SafeFN::validateSafe()

Cache

cache
cache_parser
cache_renderer
cache_instructions
dokuwiki\Cache\Cache
dokuwiki\Cache\CacheParser
dokuwiki\Cache\CacheRenderer
dokuwiki\Cache\CacheInstructions

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

_event setEvent($event)
getEvent()
_timegetTime()
_nocacheisNoCache()

FIXME? 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()

Changelog

Renamed and moved classes:

Changelog
MediaChangelog
PageChangelog
dokuwiki\ChangeLog\Changelog
dokuwiki\ChangeLog\MediaChangeLog
dokuwiki\ChangeLog\PageChangeLog

Sitemap

Renamed and moved classes:

SitemapItem
Sitemapper
dokuwiki\Sitemap\Item
dokuwiki\Sitemap\Mapper

Extension and Event

Refactored mostly in 2757

Renamed and moved classes:

Old New
Doku_Plugin_Controller
DokuWiki_PluginInterface
DokuWiki_PluginTrait
Doku_Plugin
DokuWiki_Action_Plugin
DokuWiki_Admin_Plugin
DokuWiki_Auth_Plugin
DokuWiki_CLI_Plugin
DokuWiki_Remote_Plugin
DokuWiki_Syntax_Plugin
dokuwiki\Extension\PluginController
dokuwiki\Extension\PluginInterface
dokuwiki\Extension\PluginTrait
dokuwiki\Extension\Plugin
dokuwiki\Extension\ActionPlugin
dokuwiki\Extension\AdminPlugin
dokuwiki\Extension\AuthPlugin
dokuwiki\Extension\CLIPlugin
dokuwiki\Extension\RemotePlugin
dokuwiki\Extension\SyntaxPlugin
Doku_Event
Doku_Event_Handler
dokuwiki\Extension\Event
dokuwiki\Extension\EventHandler
DokuCLI \splitbrain\phpcli\CLI

Renamed and moved functions:

+ 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

global $plugin_typesPluginController::PLUGIN_TYPES

Subscription

Renamed and refactored in separated classes:

Old New
Subscription with functions:
- isenabled()
- add()
- remove()
- subcribers()
- user_subscription()
- notifyaddresses()



- send_bulk()

- send_media_diff()

- send_diff()

- send_register()
dokuwiki\Subscriptions\SubscriberManager
- isenabled()
- add()
- remove()
- subscribers()
- userSubscription()
- notifyAddresses()

dokuwiki\Subscriptions\SubscriptionSender
dokuwiki\Subscriptions\BulkSubscriptionSender
- sendBulk()
dokuwiki\Subscriptions\MediaSubscriptionSender
- sendMediaDiff()
dokuwiki\Subscriptions\PageSubscriptionSender
- sendPageDiff()
dokuwiki\Subscriptions\RegistrationSubscriptionSender
- sendRegister()

dokuwiki\Subscriptions\SubscriberRegexBuilder
- buildRegex()

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);

Remote API and Server

Renamed and moved classes:

Old New
RemoteAPI
RemoteAPICore
RemoteAccessDeniedException
dokuwiki\Remote\Api
dokuwiki\Remote\ApiCore
dokuwiki\Remote\AccessDeniedException
variable:
DOKU_API_VERSION

ApiCore::API_VERSION
dokuwiki_xmlrpc_server
RemoteException
dokuwiki\Remote\XmlRpcServer
dokuwiki\Remote\RemoteException

HTTP Client

HTTPClient
DokuHTTPClient
HTTPClientException
dokuwiki\HTTP\HTTPClient
dokuwiki\HTTP\DokuHTTPClient
dokuwiki\HTTP\HTTPClientException

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.

Input

Renamed and moved classes:

Old New
Input
GetInput
PostInput
ServerInput
dokuwiki\Input\Input
dokuwiki\Input\Get
dokuwiki\Input\Post
dokuwiki\Input\Server

Settings

Refactored mostly in 2382

Renamed and moved classes:

Old New
configuration dokuwiki\plugin\config\core\Configuration dokuwiki\plugin\config\core\ConfigParser dokuwiki\plugin\config\core\Loader
dokuwiki\plugin\config\core\Writer
CM_KEYMARKER DOKU_PLUGIN_IMAGES PLUGIN_METADATA Configuration::KEYMARKER
admin_plugin_config::IMGDIR
admin_plugin_config::METADATA
setting
setting_array setting_authtype setting_compression setting_dirchoice setting_disableactions setting_email setting_fieldset setting_hidden setting_im_convert setting_license setting_multicheckbox setting_multichoice setting_no_class setting_no_default

setting_numeric setting_numericopt setting_onoff setting_password setting_regex setting_renderer setting_savedir setting_sepchar setting_string setting_undefined
dokuwiki\plugin\config\core\Setting\Setting dokuwiki\plugin\config\core\Setting\SettingArray dokuwiki\plugin\config\core\Setting\SettingAuthtype dokuwiki\plugin\config\core\Setting\SettingCompression dokuwiki\plugin\config\core\Setting\SettingDirchoice dokuwiki\plugin\config\core\Setting\SettingDisableactions dokuwiki\plugin\config\core\Setting\SettingEmail dokuwiki\plugin\config\core\Setting\SettingFieldset dokuwiki\plugin\config\core\Setting\SettingHidden dokuwiki\plugin\config\core\Setting\SettingImConvert dokuwiki\plugin\config\core\Setting\SettingLicense dokuwiki\plugin\config\core\Setting\SettingMulticheckbox dokuwiki\plugin\config\core\Setting\SettingMultichoice dokuwiki\plugin\config\core\Setting\SettingNoClass dokuwiki\plugin\config\core\Setting\SettingNoDefault dokuwiki\plugin\config\core\Setting\SettingNoKnownClass dokuwiki\plugin\config\core\Setting\SettingNumeric dokuwiki\plugin\config\core\Setting\SettingNumericopt dokuwiki\plugin\config\core\Setting\SettingOnoff dokuwiki\plugin\config\core\Setting\SettingPassword dokuwiki\plugin\config\core\Setting\SettingRegex dokuwiki\plugin\config\core\Setting\SettingRenderer dokuwiki\plugin\config\core\Setting\SettingSavedir dokuwiki\plugin\config\core\Setting\SettingSepchar dokuwiki\plugin\config\core\Setting\SettingString dokuwiki\plugin\config\core\Setting\SettingUndefined

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

Other

Renamed and moved classes:

FeedParser_File dokuwiki\FeedParserFile
PassHash dokuwiki\Passhash

Deprecated 2016

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) {

General cleanup suggestions

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';

Code improvements

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

Example for the renderer:

- $renderer->info['cache'] = false;
+ $renderer->nocache();
devel/releases/refactor2020.txt · Last modified: 2020-09-22 23:05 by Klap-in