Page MenuHomePhabricator

Update individual hook manuals on MediaWiki
Open, Needs TriagePublic3 Estimated Story Points

Description

We will need to update documentation on MediaWiki for each Hook's individual manual page to show the non-legacy style of registration.
e.g. https://www.mediawiki.org/wiki/Manual:Hooks/LoadExtensionSchemaUpdates

To do

Event Timeline

Restricted Application added a subscriber: Aklapper. · View Herald TranscriptApr 20 2020, 9:38 PM
apaskulin updated the task description. (Show Details)May 6 2020, 6:29 PM
Restricted Application added a subscriber: Liuxinyu970226. · View Herald TranscriptMay 6 2020, 6:29 PM

@nnikkhoui How does this look for updating the template for individual hooks? This should be easy to do since it uses all the same data, we'll just need to add the new examples.

Current template content

(Source: https://www.mediawiki.org/wiki/Template:MediaWikiHook)

Define function:

public static function onMyHook( $x, $y ) { ... }

Attach hook: In extension.json:

{
	"Hooks": {
		"MyHook": "MyExtensionHooks::onMyHook"
	}
}

MediaWiki ≤1.25:

$wgHooks['MyHook'][] = 'MyExtensionHooks::onMyHook';
Proposed template content

Create handler:

namespace MediaWiki\Extension\MyExtension;

class HookHandler {
    public function onMyHook( $x, $y ) { ... }
}

Attach hook: In extension.json:

{
    "Hooks": {
        "MyHook": {
            "handler": "main"
        }
    },
    "HookHandlers": {
        "main": {
            "class": "MediaWiki\\Extension\\MyExtension\\HookHandler"
        }
    }
}

MediaWiki ≤1.34:
Define function:

public static function onMyHook( $x, $y ) { ... }

Attach hook: In extension.json:

{
	"Hooks": {
		"MyHook": "MyExtensionHooks::onMyHook"
	}
}

MediaWiki ≤1.25:

$wgHooks['MyHook'][] = 'MyExtensionHooks::onMyHook';

It looks really good to me!! Couple of ideas:

  1. We could add 'services' to the 'template parameters' section? services would be any MediaWiki services that are to be injected into the hook handler's constructor, and is another (optional) key in the handler definition object. May just help to remind developers that you can now inject services into the hook handler constructor!
  1. The "Finding a hook's version and Gerrit ID" section should be updated for hooks introduced after 1.35. Since we're no longer using hooks.txt (or at least not updating it anymore? (correct me if thats wrong @tstarling) ) then we could mention 'version' can be obtained from the @since tag in the hook handler interface but only if @since > 1.35 ( since all the migrated hook interfaces have been initialized with @since 1.35. For the gerrit change id, you would just need the change ID of when the interface was merged into master, so i think this could work:

git log --diff-filter=A -- ./includes/[PATH_TO_HOOK]

  1. Some of the hook names have been changed in their new interface. For example, any hook that previously had double colons in the name (e.g. https://www.mediawiki.org/wiki/Manual:Hooks/PageHistoryPager::doBatchLookups ) will now have underscores in place of the colons ( e.g. https://gerrit.wikimedia.org/r/c/mediawiki/core/+/574266/20/includes/actions/Hook/PageHistoryPager__doBatchLookupsHook.php).

I'm thinking these hooks might have to have some indicator that after 1.35 the name was changed, so that future extensions call them by their correct name (even though the colons do still work for backwards compatibility)!

Looking at my previous comment, instead of just services we instead would want to note that it is the ObjectFactory spec, not just services.

apaskulin updated the task description. (Show Details)May 28 2020, 9:15 PM
apaskulin set the point value for this task to 3.Jun 2 2020, 12:43 AM
apaskulin updated the task description. (Show Details)Jun 10 2020, 3:52 PM