Extension:Configure

From MediaWiki.org
Jump to: navigation, search
MediaWiki extensions manual - list
Crystal Clear action run.png
Configure

Release status: beta
SpecialConfigure.jpg
Implementation Special page, API
Description Allow authorised users to configure the wiki via a web-based interface
Author(s) IAlextalk
Last version 0.17.2 (22 January 2012)
MediaWiki 1.18alpha for current version
1.7.0 for old versions (see notes)
License GPLv2 or higher
Download
Download snapshot (Git master)
Git [?]:

README
CHANGELOG
Parameters
Added rights
  • configure
  • configure-all
  • configure-interwiki
  • extensions
  • extensions-all
  • extensions-interwiki
  • viewconfig
  • viewconfig-all
  • viewconfig-interwiki
Hooks used
UserGetAllRights
Check usage (experimental)


Bugs: list open list all report

The Configure extension allows bureaucrats (by default) to modify configuration settings of the wiki.

Contents

[edit] Installation

  • Download a snapshot and extract it to your extensions directory. See #Versions to select the good version.
  • Edit LocalSettings.php and add the following lines:

require_once( "$IP/extensions/Configure/Configure.php" );

efConfigureSetup();


Note Note: as mentioned, you have to call efConfigureSetup() function in LocalSettings.php because you may want to customize some settings of the extension and to prevent an attack, the settings have to be always defined (this is done by including the Configure.php file), even if they won't be changed because they can arbitrary be set if the register_globals feature of PHP is turned on.

By default, only some settings are editable, if you want to be able to edit all of them (like in version < 0.10.10), add the following line in LocalSettings.php:

$wgConfigureEditableSettings = array();

[edit] Optimisation

The definition file for Special:Extensions (i.e. configurable extensions) is in a plain text format and will need to be parsed when accessing e.g. Special:Extensions or Special:ViewConfig. To speed up this operation, a PHP extension is provided in the load_txt_def subdirectory. If you want to install it, please read load_txt_def/INSTALL for instructions. Once installed, Configure will automatically use it.

[edit] Versions

For MediaWiki 1.7 to 1.12, either:

For MediaWiki 1.13:

For MediaWiki 1.14 and 1.15:

For MediaWiki 1.16:

For MediaWiki 1.17:

For MediaWiki 1.18 and greater:

[edit] Configuration settings

This extension adds some configuration settings. They are not editable through Special:Configure or Special:Extensions. You need to change them in LocalSettings.php.

[edit] $wgConfigureHandler

Configuration handler, either "files" or "db". See #Handler comparison to choose your handler.

[edit] $wgConfigureFilesPath

The extension will require a directory to store the configuration and this directory has to be writable by the web server. The default path is the $IP/serialized directory. You can use this setting to change it. Don't forget to override this variable between the time you include the Configure.php file and the time you call efConfigureSetup(), otherwise your changes won't be used.

Warning Warning: serialized directory may be publicly viewable (if using MediaWiki < 1.13 or a web server other than Apache), and users will be able to see the whole configuration, so please make it unreadable by web interface or change it to a directory that isn't accessible via the web.

[edit] $wgConfigureDatabase

Database used to store the configuration, if $wgConfigureHandler is 'db'.

To use the local database's name and tables' prefix (or schema when using PostgreSQL) set it to

$wgConfigureDatabase = false;

[edit] $wgConfigureAllowDeferSetup

Whether to allow to defer a part of efConfigureSetup() until the cache objects are set by MediaWiki instead of doing it in efConfigureSetup(). It is only used if $wgConfigureHandler is 'db'.

Note Note: If you want to use $wgConfigureExtensionsVar (see below), you may need to set it to false, otherwise the variables won't be set in efConfigureSetup() but later.

[edit] $wgConfigureFileSystemCache

Path for file-system cache, only works when $wgConfigureHandler is 'db'.

[edit] $wgConfigureFileSystemCacheExpiry

Expiry for the file-system cache, note that it is not purged when saving a new version of the configuration, so set this to a low value.

[edit] $wgConfigureWikis

Allows foreign wiki configuration. Can be either:

  • true: allow any wiki
  • false: don't allow any wiki (default)
  • an array: array of allowed wikis (e.g. $wgConfigureWikis = $wgLocalDatabases)

Users will need *-interwiki right to edit foreign wiki configuration (configure-interwiki, extensions-interwiki, viewconfig-interwiki)

[edit] $wgConfigureExtDir

Base directory for extensions files, only change it if you need to.

[edit] $wgConfigureAdditionalExtensions

Array of custom extensions (keys have no importance, it has the same format as $extensions in Configure.settings-ext.php)

Each value of this array should be an array with the following keys:

  • name: name of the extension (required)
  • dir: dir name of the extension, if different than extension's name
  • file: main file name, if different that name.php
  • settings-file: file containing settings definitions, if different than the main file
  • settings: array of settings mapping setting's name to its type (see #Settings types for the list of allowed types)
  • array: array types for settings defined as array above
  • view-restricted: list of settings that can only be viewed by users with extensions-all right
  • edit-restricted: list of settings that can only be modified by users with extensions-all right
  • schema: set it to true if the extension requires a database schema change
  • url: url to the documentation page

Example:

$wgConfigureAdditionalExtensions[] = array(
    'name' => 'Custom',
    'settings' => array(
        'wgCustomSettingBool' => 'bool',
        'wgCustomSettingText' => 'text',
        'wgCustomSettingArray' => 'array',
    ),
    'array' => array(
        'wgCustomSettingArray' => 'assoc',
    ),
    'schema' => true,
    'url' => 'http://www.mediawiki.org/wiki/Extension:MyCustomExtension',
);

Note Note: In this case, the file to include is $IP/extensions/Custom/Custom.php

[edit] $wgConfigureDisabledExtensions

This contains a list of disabled extensions (this can also disable extensions $wgConfigureAdditionalExtensions).

[edit] $wgConfigureExtensionsVar

Allows to enable an extension by setting a variable instead of directly include the file.

You'll need to handle the variable and include yourself the extension's file. Format is

$wgConfigureExtensionsVar['ExtensionName'] = 'VarName';

Warning Warning: If you use database handler, you may need to set $wgConfigureAllowDeferSetup = false; to use it correctly.

[edit] $wgConfigureOnlyUseVarForExt

If this true, extensions will be considered as installed only if they are defined in $wgConfigureExtensionsVar, Configure won't check anymore for extensions in the file system.

[edit] $wgConfigureViewRestrictions

Array of supplementary view restrictions. Format is

$wgConfigureViewRestrictions['wgSetting'] = array( 'right1', 'right2' );

if multiple rights are given, the user must have all of them to see the setting.

[edit] $wgConfigureEditRestrictions

Array of supplementary edit restrictions. Format is

$wgConfigureEditRestrictions['wgSetting'] = array( 'right1', 'right2' );

if multiple rights are given, the user must have all of them to edit the setting.

[edit] $wgConfigureNotEditableSettings

Array of not editable settings, by anyone. They won't be saved in files or database.

[edit] $wgConfigureEditableSettings

Array of editable settings. If this is a non-empty array only the settings in this array will be allowed to be modified.

[edit] $wgConfigureAPI

Whether to use the API module.

[edit] $wgConfigureUpdateCacheEpoch

Whether to update $wgCacheEpoch when saving changes in Special:Configure.

[edit] $wgConfigureStyleVersion

Like $wgStyleVersion but for Configure itself. You shouldn't change it.

[edit] Special pages

This extension adds three special pages:

[edit] Special:Configure

Main view of Special:Configure
Right needed to access this page: configure (given by default to bureaucrats)

It allows one to configure settings of MediaWiki itself. This page shows all settings available for MediaWiki, grouped by function (e.g. Manual:Configuration settings). Each setting has a link to its description page on this wiki. The list of old versions is displayed at the top of the page, by clicking on a version, it will show the configuration as it was at that time, so that the configuration can be reverted to any version.

Some settings are restricted and can only be changed by users with configure-all right. This include the following settings:

  • paths/files (because they require also "external" changes, i.e. server rewrite rules, squid configuration, ...)
  • database
  • settings containing password such as $wgSMTP
  • groups (to not allow users with only configure right to grant themself configure-all right)
  • $wgSecretKey and $wgProxyKey (they contain sensitive data)

[edit] Unsupported settings

Some settings are still uneditable because of their format. List of unsupported settings:

[edit] Special:Extensions

View of Special:Extensions for CheckUser.
Right needed to access this page: extensions (given by default to bureaucrats)

Same as Special:Configure, but for extensions. You need to put extensions in the extensions directory of your MediaWiki install or this extension won't detect them.

Warning Warning: Some extensions requires a schema change. This extension cannot apply these patches, you'll need to do it by yourself.

[edit] List of supported extensions

[edit] Special:ViewConfig

Main view of Special:ViewConfig for a user with all rights
Diff view
Right needed to access this page: viewconfig (given by default to sysops)

This special page allows sysop (by default) to see the current configuration of the wiki.

The main view lists all configurations by date.

  • Users with configure or extensions rights will have links to Special:Configure and/or Special:Extensions if they can access these pages.
  • Users with configure-interwiki, extensions-interwiki or viewconfig-interwiki rights will also have links to each wiki present in that version.

You can see or edit any version of the configuration by clinking on the links.

By selecting the versions with radio button and then selecting Compare selected versions, you'll see the diff between versions.


[edit] Maintenance scripts

This extension has some maintenance scripts in the scripts subdirectory. They assume that the extension is installed in the extensions directory of the MediaWiki software (i.e. files are in the extensions/Configure directory), if this is not the case, you can set the MW_INSTALL_PATH environment variable to the path of your MediaWiki installation and the scripts will use it.

[edit] findSettings.php

This script helps to develop the extension and maintain Manual:Configuration settings. If the --ext option is passed, then it searches for extensions settings instead of MediaWiki settings, otherwise it searches for settings in includes/DefaultSettings.php and compares them with the ones registred in the extension, Manual:Configuration settings (if the --from-doc option is passed to the script) or Manual:Configuration settings (alphabetical) (if the --from-doc --alpha options are passed to the script). May have some false positives if not using the latest development version.

[edit] manage.php

This script helps to manage configuration files. It should work even if the current version is broken. You can:

  • list all versions with the --list option
  • delete a specific version with the --delete version option (warning: you cannot undelete that version anymore).
  • revert to a specific version with the --revert version option (i.e. set that version as working version)

[edit] migrateFiles.php

This scripts reads all versions stored in serialized files and save them in plain PHP files, this is required for people updating from a version older that 0.10.11 and using files handler.

[edit] migrateToDB.php

This scripts reads all versions stored in files and save in the database.

Warning Warning: If you run this script twice, you'll have duplicate entries since this script doesn't detect that it has already been run.

[edit] writePHP.php

This script writes settings stored in serialized format in PHP script. Options:

  • --wgConf: write $wgConf->settings for all wikis, if not passed it will write variables as in the default LocalSettings.php
  • --wiki wiki: write settings of a specific wiki (not used if you pass --wgConf)
  • --version version: write settings taken from a specific version (default: current)
  • --file file: file used to store the output of the script (default: STDOUT)

[edit] Handler comparison

This extension can store the configuration in two ways: database or files. You can select it in $wgConfigureHandler.

[edit] files

This the default handler (for compatibiliy with pre-0.9.0 versions). It saves configuration in files (one by version). You can change the path in $wgConfigureFilesPath.

  • Symbol support vote.svg simple to use
  • Symbol support vote.svg able to modify all settings
  • Symbol oppose vote.svg can cause problem when using multiple servers
  • Symbol oppose vote.svg files can become very huge if configuring multiple wikis

[edit] database

This handler was introduced in version 0.9.0. The database's name can be configured in $wgConfigureDatabase. You'll need to apply the sql/configure.sql patch included with the extension in that database.

  • Symbol support vote.svg highly recommended for multiple wikis or multiple servers
  • Symbol oppose vote.svg might be difficult to configure properly for some users
  • Symbol oppose vote.svg cannot modify database and memcached settings

[edit] CSS customization (Vector)

Here are some CSS to improve page layout usability on huge list of item and such as $wgGroupPermissions :

/* Extensions:Configure */
#wgGroupPermissions tr:nth-child(even) { background-color: #eee; }
#wgGroupPermissions td.configure-grouparray-group {vertical-align: top} 
#wgGroupPermissions .configure-biglist > ul {
    height: 20em;
    overflow: auto;
}
 
#wgAddGroups .group-array-element ul,
#wgRemoveGroups .group-array-element ul,
#wgGroupsAddToSelf .group-array-element ul,
#wgGroupsRemoveFromSelf .group-array-element ul
{
    list-style-image: none;
    list-style-type: none;
}
#wgAddGroups tr:nth-child(2n),
#wgRemoveGroups tr:nth-child(2n),
#wgGroupsAddToSelf tr:nth-child(2n),
#wgGroupsRemoveFromSelf tr:nth-child(2n)
{
    background-color: #EEEEEE;
}
 
#wgAddGroups .group-array-element li,
#wgRemoveGroups .group-array-element li,
#wgGroupsAddToSelf .group-array-element li,
#wgGroupsRemoveFromSelf .group-array-element li
{
  margin-right: 1em;
  float: left;
}

[edit] Troubleshooting

If an admin changed the settings in a way that the wiki can't work anymore, you can do either:

  • use the manage.php command line script to revert the configuration to an older version. This script should work even if the configuration is broken.
  • directly update the configuration to fall back to the default configuration that is in LocalSettings.php:
    • if you have file-based storage: drop the conf-now.ser file you'll find in $wgConfigureFilesPath directory.
    • if you have database-based storage: set cv_is_latest field to 0 in the config_version table for the versions you don't want to be "active".
      Note Note: since data are cached, to might take a while before it produces any effect.

[edit] Bugs

  • Please report bugs on bugzilla, with Product=MediaWiki extensions and Component=Configure. Thank you.
  • Open issues

[edit] Advanced use

This extension uses an extended class of SiteConfiguration that replaces $wgConf. For "normal" installation, it isn't useful, but for some wiki farms, it will allow to configure multiple wikis with only one copy of the software. To change the configuration you want to load, pass an argument to efConfigureSetup(). A user with 'configure-interwiki' right will also be able to change any configuration.

By using this object to set your default values, settings which have the same value as the one set in $wgConf->settings will not be saved in the configuration or for array settings defined with "+" (see Manual:$wgConf#Settings merging, requires MediaWiki 1.14+) will only saves values that are differents instead of the whole settings.

[edit] Settings types

List of allowed values for settings types (e.g. settings key of $wgConfigureAdditionalExtensions):

  • bool: boolean
  • text: string
  • int: integer
  • lang: language code
  • An array: array of allowed values (will produce radio buttons). The format is array( 'value1' => 'desc1', 'value2' => 'desc2' /*, ... */ ) where value1 and value2 are the values to use if the radio is checked and desc1 and desc2 the description of the radion button, as displayed to th user.
  • array: arrays (see below)

[edit] Arrays

Arrays need more a more specific type too. This is not declared at the same place than the type (e.g. in array for $wgConfigureAdditionalExtensions)

  • simple: array of strings where keys have no importance
  • simple-dual: like simple, but values are array with 2 values (for $wgImageLimits).
  • assoc: associative arrays, values are strings
  • ns-bool: single dimension array with namespaces numbers in the key and a boolean value
  • ns-text: same as ns-bool but with a string in the value
  • ns-array: same as ns-text, but the value is an array of strings
  • ns-simple: like simple, but values are restricted to namespaces index
  • group-bool two dimensions array with group name in first key, right name in the second and boolean value (for $wgGroupPermissions)
  • group-array: two dimensions array with group name in first key and then a 'simple' array
  • rate-limits: specific for $wgRateLimits
  • promotion-conds: specific for $wgAutopromote
  • array: other types of arrays not currently supported
Retrieved from "http://www.mediawiki.org/w/index.php?title=Extension:Configure&oldid=530111"
Personal tools
Namespaces

Variants
Actions
Navigation
Support
Download
Development
Communication
Print/export
Toolbox