DokuWiki Plugin Configuration — Settings, Plugin Manager, and Upgrade Handling

In this tutorial, you'll learn how to configure DokuWiki plugins, including plugin settings, configuration file structure, managing multiple plugins, and handling plugin upgrades safely.

What You'll Learn

• Plugin configuration files (default.php, metadata.php)
• Configuration Manager interface
• Setting plugin options programmatically in local.php
• Managing plugins at scale
• Plugin upgrade procedures
• Handling breaking changes during upgrades
• Plugin dependency management

Why It Matters

Most plugins offer configuration options that control their behavior. Knowing where these settings live, how to change them, and how to preserve them during upgrades saves you from losing custom configurations. When you manage multiple DokuWiki instances, understanding plugin configuration helps you maintain consistency across environments.

Real-World Use

An organization runs 10 DokuWiki instances for different departments. Each instance needs the same set of plugins with the same configuration. The administrator configures plugins centrally by adding settings to each instance's conf/local.php. When a new plugin is installed, the configuration is added to a deployment script that pushes changes to all instances simultaneously.

Learning Path

flowchart LR
  A[Custom Plugins] --> B[Plugin Configuration]
  B --> C[Plugin Security]
  C --> D[Template Anatomy]
  D --> E[Template Variables]
  E --> F[Bootstrap Template]

Plugin Configuration Files

Plugins with configuration options store their settings in the plugin's conf/ directory.

default.php

Contains default values for all configuration options:

<?php
// lib/plugins/myplugin/conf/default.php

$conf['api_url'] = 'https://default-api.example.com';
$conf['cache_ttl'] = 3600;
$conf['debug_mode'] = 0;
$conf['max_results'] = 20;
$conf['enable_feature_x'] = 1;

metadata.php

Defines the type and validation for each configuration option:

<?php
// lib/plugins/myplugin/conf/metadata.php

$meta['api_url'] = array('string');
$meta['cache_ttl'] = array('numeric');
$meta['debug_mode'] = array('onoff');
$meta['max_results'] = array('numeric', '_min' => 1, '_max' => 100);
$meta['enable_feature_x'] = array('onoff');

Supported metadata types:

Multichoice Example

<?php
$meta['theme'] = array(
    'multichoice',
    '_choices' => array('light', 'dark', 'auto')
);

Configuration Manager Interface

Plugin settings appear in the Configuration Manager under their own section.

1. Admin > Configuration Manager
2. Scroll to the plugin section (plugins are listed alphabetically)
3. Adjust settings as needed
4. Click "Save"

Each plugin's configuration is stored in conf/plugin/pluginname.local.php:

<?php
// conf/plugin/myplugin.local.php
$conf['api_url'] = 'https://custom-api.example.com';
$conf['debug_mode'] = 0;

This file is created automatically when you save plugin settings from the Configuration Manager.

Programmatic Configuration in local.php

You can override plugin settings in conf/local.php:

<?php
// conf/local.php

$conf['plugin']['myplugin']['api_url'] = 'https://internal-api.example.com';
$conf['plugin']['myplugin']['cache_ttl'] = 7200;
$conf['plugin']['myplugin']['debug_mode'] = 0;

Settings in local.php take priority over the plugin's own configuration file. This is useful for:

• Environment-specific overrides (development vs production)
• Centralized configuration management
• Scripted deployments

Managing Multiple Plugins

Inventory

Keep a list of installed plugins and their versions:

plugins.txt
-----------
blog        v2024-01-01  Enabled
discussion  v2024-02-15  Enabled
gallery     v2024-03-01  Enabled
tag         v2024-01-15  Enabled
bureaucracy v2024-02-01  Disabled

Bulk Enable/Disable

There is no built-in bulk operation, but you can edit the plugin state directly:

Enabled plugins are listed in conf/plugin/local.php with no special flag. Disabled plugins have an entry in the state file.

Configuration Sync

For multiple instances, maintain a standard conf/local.php that includes plugin settings:

<?php
// Standard plugin configuration across all instances
$conf['plugin']['blog']['namespace'] = 'blog';
$conf['plugin']['discussion']['showbutton'] = 1;
$conf['plugin']['gallery']['thumbnail_width'] = 150;
$conf['plugin']['tag']['tools'] = 1;

Plugin Upgrade Handling

Safe Upgrade Process

1. Back up configuration: Plugin settings are in conf/plugin/pluginname.local.php. Back up this file.
2. Read the changelog: Check for breaking changes, deprecated settings, or new requirements.
3. Replace plugin files: Download the new version and replace the plugin directory.
4. Run configuration updates: Some plugins include Migration scripts.
5. Test: Verify the plugin works with your existing configuration.

Handling Breaking Changes

If a plugin update changes configuration options:

1. Compare the old default.php with the new one
2. Update your local.php settings to match the new option names
3. Remove any deprecated settings
4. Add any new required settings

Plugin Update Script

#!/bin/bash
# update-plugin.sh - Safely update a DokuWiki plugin

PLUGIN_NAME="$1"
PLUGIN_DIR="/var/www/html/wiki/lib/plugins/$PLUGIN_NAME"
BACKUP_DIR="/var/www/html/wiki/data/backups/plugins"

# Backup current plugin configuration
cp -r "$PLUGIN_DIR/conf" "$BACKUP_DIR/$PLUGIN_NAME-conf-$(date +%Y%m%d)"

# Backup the current plugin
cp -r "$PLUGIN_DIR" "$BACKUP_DIR/$PLUGIN_NAME-$(date +%Y%m%d)"

# Download and extract new version
cd "$PLUGIN_DIR" || exit
wget "https://github.com/author/dokuwiki-plugin-$PLUGIN_NAME/archive/master.zip"
unzip -o master.zip
# Handle plugin upgrade instructions

Version Compatibility

Check DokuWiki version compatibility before upgrading plugins:

<?php
// Check DokuWiki version
echo DOKU_VERSION;

Plugins typically specify compatibility in their plugin.info.txt:

compatible  Bionic  Frusterick  Manners

The compatibility list shows which DokuWiki release codenames the plugin supports.

Plugin Manager (Extension Manager)

The Extension Manager provides:

• Plugin list: All installed plugins, their version, status (enabled/disabled), and available updates
• Search and install: Browse the DokuWiki plugin Repository
• Update checking: Compare installed versions with repository versions
• Uninstall: Remove plugins (with configuration cleanup)

Update Notifications

The Extension Manager displays a badge when updates are available. You can also configure email notifications for plugin updates.

Plugin Dependencies

DokuWiki does not have an automated dependency resolver. If a plugin depends on another plugin or a specific PHP extension, you must install it manually.

Check dependencies before installing:

• plugin.info.txt: Author may list dependencies in the description
• Installation instructions: README or plugin documentation
• PHP extensions: Some plugins require curl, json, mb_string, etc.

Common Mistakes

1. Editing plugin files directly: Changes are lost on update. Use the Configuration Manager or local.php for settings.
2. Ignoring configuration migration during upgrades: New plugin versions may change option names or remove old ones. Check the changelog.
3. Skipping testing after plugin updates: A plugin update that changes behavior can break pages that depend on it. Test on staging first.
4. Not backing up plugin configuration: If a plugin's conf/ directory is overwritten during update, your settings are lost. Back up first.
5. Overriding settings in multiple places: Settings can be in plugin's default.php, plugin's local.php, and main local.php. To avoid confusion, use only one override location.

Practice Questions

1. What is the difference between default.php and metadata.php in a plugin's configuration directory?
2. How do you override a plugin's configuration settings in conf/local.php?
3. What steps should you take to safely upgrade a plugin that has breaking configuration changes?
4. Challenge: Create a plugin configuration standards document for your organization. Include: standard configuration file locations, naming conventions for plugin-specific settings in local.php, a backup Strategy before plugin updates, a testing procedure after plugin updates, and a plugin inventory template. Implement this for at least 3 plugins on your wiki.

FAQ

Mini Project

Goal: Set up standardized plugin configuration management.

1. Install 3 plugins (Blog, Gallery, Discussion)
2. Configure each plugin through the Configuration Manager
3. Examine the generated conf/plugin/pluginname.local.php files
4. Copy these settings into conf/local.php with proper syntax
5. Delete the conf/plugin/pluginname.local.php files
6. Verify that settings from local.php still apply correctly
7. Document the configuration for each plugin, including the purpose of each setting
8. Create a backup of all plugin configurations

What's Next

Configuration makes plugins flexible. Learn about plugin security to write and maintain secure plugins.