localisation: Improve documentation around wgLocalisationCacheConf

Bug: T218207
Change-Id: I15a77d5df7b358b69cd9049036a69a28d31ebaae

diff --git a/includes/DefaultSettings.php b/includes/DefaultSettings.php
index 4ba1836..33230c8 100644 (file)
--- a/includes/DefaultSettings.php
+++ b/includes/DefaultSettings.php
@@ -2563,26 +2563,35 @@ $wgUseLocalMessageCache = false;
 $wgAdaptiveMessageCache = false;
 
 /**
- * Localisation cache configuration. Associative array with keys:
- * class:       The class to use. May be overridden by extensions.
- *
- * store:       The location to store cache data. May be 'files', 'array', 'db' or
- *              'detect'. If set to "files", data will be in CDB files. If set
- *              to "db", data will be stored to the database. If set to
- *              "detect", files will be used if $wgCacheDirectory is set,
- *              otherwise the database will be used.
- *              "array" is an experimental option that uses PHP files that
- *              store static arrays.
- *
- * storeClass:  The class name for the underlying storage. If set to a class
- *              name, it overrides the "store" setting.
- *
- * storeDirectory:  If the store class puts its data in files, this is the
- *                  directory it will use. If this is false, $wgCacheDirectory
- *                  will be used.
- *
- * manualRecache:   Set this to true to disable cache updates on web requests.
- *                  Use maintenance/rebuildLocalisationCache.php instead.
+ * Localisation cache configuration.
+ *
+ * Used by Language::getLocalisationCache() to decide how to construct the
+ * LocalisationCache instance. Associative array with keys:
+ *
+ * class:       The class to use for constructing the LocalisationCache object.
+ *              This may be overridden by extensions to a subclass of LocalisationCache.
+ *              Sub classes are expected to still honor the 'storeClass', 'storeDirectory'
+ *              and 'manualRecache' options where applicable.
+ *
+ * storeClass:  Which LCStore class implementation to use. This is optional.
+ *              The default LocalisationCache class offers the 'store' option
+ *              as abstraction for this.
+ *
+ * store:       How and where to store localisation cache data.
+ *              This option is ignored if 'storeClass' is explicitly set to a class name.
+ *              Must be one of:
+ *              - 'detect' (default): Automatically select 'files' if 'storeDirectory'
+ *                 or $wgCacheDirectory is set, and fall back to 'db' otherwise.
+ *              - 'files': Store in $wgCacheDirectory as CDB files.
+ *              - 'array': Store in $wgCacheDirectory as PHP static array files.
+ *              - 'db': Store in the l10n_cache database table.
+ *
+ * storeDirectory: If the selected LCStore class puts its data in files, then it
+ *                 will use this directory. If set to false (default), then
+ *                 $wgCacheDirectory is used instead.
+ *
+ * manualRecache: Set this to true to disable cache updates on web requests.
+ *                Use maintenance/rebuildLocalisationCache.php instead.
  */
 $wgLocalisationCacheConf = [
        'class' => LocalisationCache::class,

diff --git a/includes/cache/localisation/LCStoreCDB.php b/includes/cache/localisation/LCStoreCDB.php
index 8814cff..3455470 100644 (file)
--- a/includes/cache/localisation/LCStoreCDB.php
+++ b/includes/cache/localisation/LCStoreCDB.php
@@ -22,9 +22,7 @@ use Cdb\Reader;
 use Cdb\Writer;
 
 /**
- * LCStore implementation which stores data as a collection of CDB files in the
- * directory given by $wgCacheDirectory. If $wgCacheDirectory is not set, this
- * will throw an exception.
+ * LCStore implementation which stores data as a collection of CDB files.
  *
  * Profiling indicates that on Linux, this implementation outperforms MySQL if
  * the directory is on a local filesystem and there is ample kernel cache

diff --git a/includes/cache/localisation/LocalisationCache.php b/includes/cache/localisation/LocalisationCache.php
index db0f380..8a3a818 100644 (file)
--- a/includes/cache/localisation/LocalisationCache.php
+++ b/includes/cache/localisation/LocalisationCache.php
@@ -192,7 +192,7 @@ class LocalisationCache {
                global $wgCacheDirectory;
 
                $this->conf = $conf;
-               $storeConf = [];
+               $storeArg = [];
                if ( !empty( $conf['storeClass'] ) ) {
                        $storeClass = $conf['storeClass'];
                } else {
@@ -203,7 +203,7 @@ class LocalisationCache {
                                        break;
                                case 'db':
                                        $storeClass = LCStoreDB::class;
-                                       $storeConf['server'] = $conf['storeServer'] ?? [];
+                                       $storeArg['server'] = $conf['storeServer'] ?? [];
                                        break;
                                case 'array':
                                        $storeClass = LCStoreStaticArray::class;
@@ -212,11 +212,11 @@ class LocalisationCache {
                                        if ( !empty( $conf['storeDirectory'] ) ) {
                                                $storeClass = LCStoreCDB::class;
                                        } elseif ( $wgCacheDirectory ) {
-                                               $storeConf['directory'] = $wgCacheDirectory;
+                                               $storeArg['directory'] = $wgCacheDirectory;
                                                $storeClass = LCStoreCDB::class;
                                        } else {
                                                $storeClass = LCStoreDB::class;
-                                               $storeConf['server'] = $conf['storeServer'] ?? [];
+                                               $storeArg['server'] = $conf['storeServer'] ?? [];
                                        }
                                        break;
                                default:
@@ -228,10 +228,10 @@ class LocalisationCache {
 
                wfDebugLog( 'caches', static::class . ": using store $storeClass" );
                if ( !empty( $conf['storeDirectory'] ) ) {
-                       $storeConf['directory'] = $conf['storeDirectory'];
+                       $storeArg['directory'] = $conf['storeDirectory'];
                }
 
-               $this->store = new $storeClass( $storeConf );
+               $this->store = new $storeClass( $storeArg );
                foreach ( [ 'manualRecache', 'forceRecache' ] as $var ) {
                        if ( isset( $conf[$var] ) ) {
                                $this->$var = $conf[$var];