Requests for comment/PlatformSettings.php
| PlatformSettings.php | |
|---|---|
| Component | General |
| Creation date | |
| Author(s) | Legoktm |
| Document status | implemented See Phabricator. |
Introduce PlatformSettings.php as a standardized and recommended way for re-distributors and packagers of MediaWiki to be able to tune DefaultSettings.php as appropriate.
Background[edit]
Packagers of MediaWiki often have some customizations to DefaultSettings.php that they want to do. For example, the Debian package currently adds the following:
# Debian specific generated settings
# Use system mimetypes
$wgMimeTypeFile = '/etc/mime.types';
# Load legacy extensions
if ( is_file( "/etc/mediawiki-extensions/extensions.php" ) ) {
include "/etc/mediawiki-extensions/extensions.php";
}
# Add a "powered by Debian" footer icon
$wgFooterIcons['poweredby']['debian'] = [
"src" => "/wiki/resources/assets/debian/poweredby_debian_1x.png",
"url" => "https://www.debian.org/",
"alt" => "Powered by Debian",
"srcset" =>
"/wiki/resources/assets/debian/poweredby_debian_1_5x.png 1.5x, " .
"/wiki/resources/assets/debian/poweredby_debian_2x.png 2x",
];
# End Debian specific generated settings
This is currently done by having the installer use a custom DebianLocalSettingsGenerator, so when the installer is run, that snippet is added to the generated LocalSettings.php.
Problem[edit]
Because these settings are written into LocalSettings.php, existing installations won't see any changes to these defaults unless they regenerate their LocalSettings.php (rare). For example, I'd like to add some security hardening by setting $wgShellRestrictionMethod = 'firejail'; since I know that the package will make sure firejail is available. But unless everyone regenerates their LocalSettings.php, it won't take effect.
I specifically want to avoid hacking and patching MediaWiki to set better defaults, I believe the solution I've proposed is as minimal as possible, but still functional.
Proposal[edit]
Idea 1[edit]
Introduce the concept of distribution provided platform settings. The distributor/packager will create a PHP file located in $IP/includes/PlatformSettings.php. MediaWiki will check if that file exists, and if so load it, right after DefaultSettings.php, for example:
$ git diff includes/Setup.php
diff --git a/includes/Setup.php b/includes/Setup.php
index d6f4b2fe4c..9b4c42137a 100644
--- a/includes/Setup.php
+++ b/includes/Setup.php
@@ -52,6 +52,11 @@ require_once "$IP/includes/Defines.php";
// Load default settings
require_once "$IP/includes/DefaultSettings.php";
+// Load platform settings if they exist
+if ( file_exists( "$IP/includes/PlatformSettings.php" ) ) {
+ require_once "$IP/includes/PlatformSettings.php";
+}
+
// Load global functions
require_once "$IP/includes/GlobalFunctions.php";
The upside to this is mostly on the packaging end - instead of needing to patch DefaultSettings.php and constantly rebase the patch, this new file can just be dropped in. Since this runs before LocalSettings.php, users can still override these settings if they want to do so.
Idea 2[edit]
This was originally suggested by Krinkle. Have the packager override the LocalSettingsGenerator, and at the top of the generated LocalSettings.php add (for example) require '/usr/share/mediawiki/includes/PlatformSettings.php';.
This has the benefit of not requiring any changes to MediaWiki core since it can be implemented with the existing installer overrides system. The only downside is that once this is implemented, people with existing MediaWiki installs need to add that line to their LocalSettings.php, but that's a one time cost, and is acceptable.