Mngr: Created page with "= LocalSettings.php Architecture and Maintenance Guide = TOC == 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. Read..."

2026-02-04T17:14:10Z

Created page with "= LocalSettings.php Architecture and Maintenance Guide = __TOC__ == 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. Read..."

New page

= LocalSettings.php Architecture and Maintenance Guide =
__TOC__

== 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:
<pre>
$wgSitename
$wgServer
$wgScriptPath
$wgLanguageCode
$wgLocaltimezone
Database settings
SMTP / mail
Uploads
</pre>

Reason:
These are global and independent of extensions.

----

=== 2. Namespace definitions (VERY IMPORTANT) ===

ALL custom namespaces must be defined here, BEFORE extensions.

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

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.

<pre>
$wgGroupPermissions['club']['read'] = true;
$wgGroupPermissions['club']['edit'] = true;
</pre>

No extensions here.

----

=== 4. Lockdown security ===

<pre>
wfLoadExtension( 'Lockdown' );
$wgNamespacePermissionLockdown[...]
</pre>

Reason:
Lockdown depends on:
* namespaces
* groups

Therefore it must come AFTER both.

----

=== 5. Extensions (all together) ===

Load ALL extensions in one clean block.

Example:
<pre>
wfLoadExtension('Cargo');
wfLoadExtension('PageForms');
wfLoadExtension('ParserFunctions');
wfLoadExtension('InputBox');
wfLoadExtension('Scribunto');
wfLoadExtension('VisualEditor');
wfLoadExtension('PdfHandler');
wfLoadExtension('PageImages');
</pre>

Rules:
* no logic between loads
* keep together
* easy to see what is installed

----

=== 6. Extension configuration ===

Settings that belong to extensions only.

Examples:
<pre>
$wgCargoDBtype
$wgPageFormsUploadableFiles
$wgVisualEditorAvailableNamespaces
$wgScribuntoEngineConf
</pre>

Reason:
Cleaner separation between loading and configuring.

----

=== 7. Site CSS/JS ===

<pre>
$wgUseSiteCss = true;
$wgUseSiteJs = true;
</pre>

----

=== 8. Debugging (last only) ===

<pre>
$wgDebugLogFile
$wgShowExceptionDetails
</pre>

Never place debugging options inside functional sections.

----

== Namespace Design ==

Namespaces are used for both organisation and security.

=== UI pages ===
<pre>
Research:
</pre>
Dashboards and user entry points.

=== Data entities ===
<pre>
Chapter:
Place:
Organisation:
Asset:
Heritage:
</pre>
Pages created by forms only.

Users never manually create pages here.

=== Documentation ===
<pre>
ICT:
</pre>
Technical documentation for maintainers.

This separation keeps:
* data clean
* UI simple
* permissions easy

----

== Cargo + PageForms Workflow ==

Each entity follows this pattern:

# Template with #cargo_declare
# Form using PageForms
# Dashboard page using #cargo_query
# Edit links using #formlink
# After schema change → Special:CargoTables → Recreate data

Never manually delete Cargo tables.

----

== Common Maintenance Tasks ==

=== After changing template schema ===
# Save Template
# Go to Special:CargoTables
# Click "Recreate data"

=== After CSS or layout change ===
Use:
?action=purge

=== After LocalSettings change ===
Restart Apache:
<pre>
sudo systemctl restart httpd
</pre>

----

== 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.

ICT:LocalSettings organisation - Revision history