ICT:LocalSettings organisation

LocalSettings.php Architecture and Maintenance Guide

Purpose

This document explains the structure, order and design decisions of LocalSettings.php for the Costa Sano MediaWiki installation.

The goal is:

• predictable behaviour
• easy maintenance
• safe upgrades
• easy handover to future ICT volunteers

This file is intentionally organised in logical blocks. Do not mix sections. Order matters.

---

Guiding Principles

1. Readability over cleverness

Future maintainers must understand the file quickly.

2. One responsibility per block

Each section handles only one topic:

• site
• namespaces
• security
• extensions
• extension configuration

3. Correct load order

Some settings MUST be defined before extensions are loaded.

Wrong order causes:

• Cargo tables not recognised
• namespaces ignored
• Lockdown not working
• PageForms parsing issues

---

Required Section Order

The file MUST follow this order.

1. Core site configuration

General wiki behaviour.

Examples:

$wgSitename
$wgServer
$wgScriptPath
$wgLanguageCode
$wgLocaltimezone
Database settings
SMTP / mail
Uploads

Reason: These are global and independent of extensions.

---

2. Namespace definitions (VERY IMPORTANT)

ALL custom namespaces must be defined here, BEFORE extensions.

define("NS_RESEARCH", 3000);
define("NS_CHAPTER", 3004);
define("NS_PLACE", 3006);
...
$wgExtraNamespaces[...]
$wgNamespaceAliases[...]

Reason: Extensions (Cargo, PageForms, Lockdown, VisualEditor) read namespaces during startup.

If namespaces are declared later:

• forms break
• Cargo queries fail
• permissions ignored

This was the cause of several earlier problems.

Rule: Namespaces first. Always.

---

3. Groups and permissions

User groups and rights only.

$wgGroupPermissions['club']['read'] = true;
$wgGroupPermissions['club']['edit'] = true;

No extensions here.

---

4. Lockdown security

wfLoadExtension( 'Lockdown' );
$wgNamespacePermissionLockdown[...]

Reason: Lockdown depends on:

• namespaces
• groups

Therefore it must come AFTER both.

---

5. Extensions (all together)

Load ALL extensions in one clean block.

Example:

wfLoadExtension('Cargo');
wfLoadExtension('PageForms');
wfLoadExtension('ParserFunctions');
wfLoadExtension('InputBox');
wfLoadExtension('Scribunto');
wfLoadExtension('VisualEditor');
wfLoadExtension('PdfHandler');
wfLoadExtension('PageImages');

Rules:

• no logic between loads
• keep together
• easy to see what is installed

---

6. Extension configuration

Settings that belong to extensions only.

Examples:

$wgCargoDBtype
$wgPageFormsUploadableFiles
$wgVisualEditorAvailableNamespaces
$wgScribuntoEngineConf

Reason: Cleaner separation between loading and configuring.

---

7. Site CSS/JS

$wgUseSiteCss = true;
$wgUseSiteJs  = true;

---

8. Debugging (last only)

$wgDebugLogFile
$wgShowExceptionDetails

Never place debugging options inside functional sections.

---

Namespace Design

Namespaces are used for both organisation and security.

UI pages

Research:

Dashboards and user entry points.

Data entities

Chapter:
Place:
Organisation:
Asset:
Heritage:

Pages created by forms only.

Users never manually create pages here.

Documentation

ICT:

Technical documentation for maintainers.

This separation keeps:

• data clean
• UI simple
• permissions easy

---

Cargo + PageForms Workflow

Each entity follows this pattern:

1. Template with #cargo_declare
2. Form using PageForms
3. Dashboard page using #cargo_query
4. Edit links using #formlink
5. After schema change → Special:CargoTables → Recreate data

Never manually delete Cargo tables.

---

Common Maintenance Tasks

After changing template schema

1. Save Template
2. Go to Special:CargoTables
3. Click "Recreate data"

After CSS or layout change

Use: ?action=purge

After LocalSettings change

Restart Apache:

sudo systemctl restart httpd

---

Rules for Future Maintainers

Do:

• keep section order
• document every new block
• add comments
• test after each change

Do NOT:

• mix extension loads with config
• move namespaces lower in file
• manually edit Cargo database tables
• duplicate dashboard pages in multiple namespaces

---

History

Version 4.1 Reorganised after implementation of:

• Cargo
• PageForms
• Namespaces with Lockdown
• Dashboard-based UI

This structure proved stable and should be preserved.