View source for ICT:Hooks – How Hooks Work in MediaWiki

= ICT:Hooks – How Hooks Work in MediaWiki =
This page explains how MediaWiki’s hook system works, where hook parameters such as <code>$skin</code>, <code>$bar</code>, and <code>$links</code> come from, and how administrators can look up the official documentation for each hook.

This page is intended for future stewards of the archive infrastructure.

----

== 1. What a Hook Is ==
A '''hook''' is a point inside MediaWiki’s execution flow where custom PHP code can run.

MediaWiki internally calls:

<syntaxhighlight lang="php">
Hooks::run( 'HookName', [ $param1, $param2, ... ] );
</syntaxhighlight>

Your code registers a function to be executed at that moment:

<syntaxhighlight lang="php">
$wgHooks['HookName'][] = function ( $param1, $param2 ) {
    # custom logic
    return true;
};
</syntaxhighlight>

Returning <code>true</code> tells MediaWiki to continue normal processing.  
Returning <code>false</code> stops further handlers.

----

== 2. Where Do Parameters Like <code>$skin</code>, <code>$bar</code>, <code>$links</code> Come From ==
Each hook defines:

* how many parameters it passes  
* what type each parameter is  
* whether parameters are passed by reference  
* what you are allowed to modify  

This information is published in the official MediaWiki hook documentation.

For example:

=== SkinBuildSidebar ===
* Documentation: https://www.mediawiki.org/wiki/Manual:Hooks/SkinBuildSidebar
* Parameters:
  * <code>$skin</code> — instance of <code>Skin</code> or a subclass (e.g., <code>SkinVector</code>)
  * <code>&$bar</code> — associative array representing the sidebar sections

=== SkinTemplateNavigation::Universal ===
* Documentation: https://www.mediawiki.org/wiki/Manual:Hooks/SkinTemplateNavigation::Universal
* Parameters:
  * <code>$skin</code> — instance of <code>SkinTemplate</code>
  * <code>&$links</code> — nested array containing the action tabs (views, actions, variants)

These pages define exactly what the objects contain and how they may be modified.

----

== 3. How to Read Hook Documentation ==
Every hook page on mediawiki.org includes:

* a description of when the hook fires  
* a list of parameters  
* the PHP types of each parameter  
* examples of usage  
* notes about return values  

Example from the documentation:

<syntaxhighlight lang="php">
/**
 * @param Skin $skin
 * @param array &$bar
 */
</syntaxhighlight>

This tells you:

* <code>$skin</code> is a <code>Skin</code> object  
* <code>$bar</code> is an array passed by reference  
* modifying <code>$bar</code> changes the sidebar  

----

== 4. Why Hooks Are Used in LocalSettings.php ==
Hooks allow you to:

* hide or modify UI elements  
* enforce role‑based behavior  
* override default navigation  
* add or remove actions  
* customize rendering without modifying core files  

They are the official, stable way to extend MediaWiki.

All hook code in <code>LocalSettings.php</code> is standard PHP.

----

== 5. Example: Understanding the Parameters ==
=== Example 1: SkinBuildSidebar ===
<syntaxhighlight lang="php">
function ( $skin, &$bar ) { ... }
</syntaxhighlight>

* <code>$skin</code> → gives access to:
  * <code>$skin->getUser()</code>
  * <code>$skin->getTitle()</code>
  * <code>$skin->getSkinName()</code>

* <code>$bar</code> → the sidebar structure:
<syntaxhighlight lang="php">
$bar = [
    'navigation' => [
        [ 'text' => 'Main Page', 'href' => '/wiki/Main_Page' ],
    ],
    'tools' => [ ... ],
];
</syntaxhighlight>

=== Example 2: SkinTemplateNavigation::Universal ===
<syntaxhighlight lang="php">
function ( $skin, &$links ) { ... }
</syntaxhighlight>

* <code>$links</code> contains the action tabs:
<syntaxhighlight lang="php">
$links = [
    'views' => [
        'edit' => [ 'text' => 'Edit', 'href' => ... ],
        'history' => [ ... ],
    ],
    'actions' => [
        'delete' => [ ... ],
        'move' => [ ... ],
    ],
];
</syntaxhighlight>

----

== 6. How to Find Any Hook ==
All hooks are listed here:

* https://www.mediawiki.org/wiki/Manual:Hooks

Each hook page includes:

* purpose  
* parameters  
* examples  
* version notes  

This is the authoritative reference for understanding hook parameters.

----

== 7. Why This Matters for Successors ==
Understanding hooks ensures that future stewards can:

* safely modify UI behavior  
* understand why certain elements are hidden  
* maintain or extend the decluttered interface  
* avoid modifying core files or skins  
* keep the system stable and upgrade‑friendly  

This page provides the conceptual foundation needed to understand the hook‑based customizations used in the archive infrastructure.

----

''This page is part of the ICT documentation set for the archive infrastructure.''