Extension:Configure

From MediaWiki.org
(Redirected from Extension:Configuration)
Jump to: navigation, search
MediaWiki extensions manual
Crystal Clear action run.png
Configure

Release status: beta

SpecialConfigure.jpg
Implementation Special pageAPI
Description Allow authorized users to configure the wiki via a web-based interface
Author(s) IAlextalk
Latest version 0.17.3 (2012-07-27)
MediaWiki 1.18alpha-1.19 for current version
1.7.0 for old versions (see notes)
License GNU General Public License 2.0 or later
Download
README
CHANGELOG
Parameters
Added rights
  • configure
  • configure-all
  • configure-interwiki
  • extensions
  • extensions-all
  • extensions-interwiki
  • viewconfig
  • viewconfig-all
  • viewconfig-interwiki
Hooks used
UserGetAllRights

Translate the Configure extension if it is available at translatewiki.net

Check usage and version matrix; code metrics
Bugs: list open list all report

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

Installation[edit | edit source]

  • Download a snapshot and extract it to your extensions directory.
  • Edit LocalSettings.php and add the following lines:
require_once "$IP/extensions/Configure/Configure.php";
efConfigureSetup();
Note Note: The call to the efConfigureSetup() function in LocalSettings.php is necessary 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 (as was possible in versions < 0.10.10), add the following line to LocalSettings.php:

$wgConfigureEditableSettings = array();

Configuration settings for this extension[edit | edit source]

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

$wgConfigureHandler[edit | edit source]

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

$wgConfigureFilesPath[edit | edit source]

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.

$wgConfigureDatabase[edit | edit source]

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;

$wgConfigureAllowDeferSetup[edit | edit source]

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.

$wgConfigureFileSystemCache[edit | edit source]

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

$wgConfigureFileSystemCacheExpiry[edit | edit source]

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.

$wgConfigureWikis[edit | edit source]

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)

$wgConfigureExtDir[edit | edit source]

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

$wgConfigureAdditionalExtensions[edit | edit source]

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

$wgConfigureDisabledExtensions[edit | edit source]

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

$wgConfigureExtensionsVar[edit | edit source]

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.

$wgConfigureOnlyUseVarForExt[edit | edit source]

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.

$wgConfigureViewRestrictions[edit | edit source]

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.

$wgConfigureEditRestrictions[edit | edit source]

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.

$wgConfigureNotEditableSettings[edit | edit source]

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

$wgConfigureEditableSettings[edit | edit source]

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

$wgConfigureAPI[edit | edit source]

Whether to use the API module.

$wgConfigureUpdateCacheEpoch[edit | edit source]

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

$wgConfigureStyleVersion[edit | edit source]

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

User rights for this extension[edit | edit source]

This extension adds a few user rights:

Rights for Special:Configure

  • configure (given to bureaucrats by default)
  • configure-all (given to bureaucrats by default)
  • configure-interwiki

Rights for Special:ViewConfig

  • viewconfig (given to admins by default)
  • viewconfig-all
  • viewconfig-interwiki

Rights for Special:Extensions

  • extensions (given to bureaucrats by default)
  • extensions-all
  • extensions-interwiki

To grant a permission to a user group, add, for example:

$wgGroupPermissions['sysop']['configure'] = true;

to LocalSettings.php

Special pages for this extension[edit | edit source]

This extension adds three special pages:

Special:Configure[edit | edit source]

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 themselves configure-all right)
  • $wgSecretKey and $wgProxyKey (they contain sensitive data)

Unsupported settings[edit | edit source]

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

Special:Extensions[edit | edit source]

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 require a schema change. This extension cannot apply these patches, you'll need to do it by yourself.

List of supported extensions[edit | edit source]

Special:ViewConfig[edit | edit source]

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.


Optimisation[edit | edit source]

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.

Maintenance scripts[edit | edit source]

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.

findSettings.php[edit | edit source]

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.

manage.php[edit | edit source]

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)

migrateFiles.php[edit | edit source]

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.

migrateToDB.php[edit | edit source]

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.

writePHP.php[edit | edit source]

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)

Handler comparison[edit | edit source]

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

files[edit | edit source]

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

database[edit | edit source]

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

CSS customization (Vector)[edit | edit source]

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

Troubleshooting[edit | edit source]

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.

Bugs[edit | edit source]

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

Advanced use[edit | edit source]

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.

Settings types[edit | edit source]

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)

Arrays[edit | edit source]

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