Repository files navigation

On Packagist:

OOP interface for creating MediaWiki parser hooks in a declarative fashion.

This is a PHP library for MediaWiki extensions. It does not in itself add or enhance functionality of your wiki.

The PHP and MediaWiki version ranges listed are those in which ParserHooks is known to work. It might alsowork with more recent versions of PHP and MediaWiki, though this is not guaranteed. Increases ofminimum requirements are indicated in bold. For a detailed list of changes, see therelease notes.

You can useComposer to download and installthis package as well as its dependencies. Alternatively you can simply clonethe git repository and take care of loading yourself.

To add this package as a local, per-project dependency to your project, simply add adependency onmediawiki/parser-hooks to your project'scomposer.json file.Here is a minimal example of acomposer.json file that just defines a dependency onParserHooks 1.6:

{    "require": {        "mediawiki/parser-hooks": "~1.6"    }}

Get the ParserHooks code, either via git, or some other means. Also get all dependencies.You can find a list of the dependencies in the "require" section of the composer.json file.Load all dependencies and the load the ParserHooks library by including its entry point:ParserHooks.php.

All classes are located in the ParserHooks namespace, which is PSR-0 mapped onto the src/ directory.

The declarative OOP interface provided by this library allows you to define the signatures ofyour parser hooks and the handlers for them separately. The library makes use of the parametersspecified in this definition to do parameter processing via the ParamProcessor library. This meansthat the handler you write for your parser function will not need to care about what the name ofthe parser function is, or how the parameters for it should be processed. It has a "sizes" parameterthat takes an array of positive integers? Your handler will always get an actual PHP array of integerwithout needing to do any parsing, validation, defaulting, etc.

An instance of the HookDefinition class represents the signature of a parser hook. It definesthe name of the parser hook and the parameters (including their types, default values, etc) itaccepts. It does not define any behaviour, and is thus purely declarative. Instances of thisclass are used in handling of actual parser hooks, though can also be used in other contexts.For instance, you can feed these definitions to a tool that generates parser hook documentationbased on them.

The parameter definitions are ParamProcessor\ParamDefinition objects. See theParamProcessor documentation on how to specify these.

The actual behaviour for your parser hook is implemented in an implementation of HookHandler.These implementations have a handle method which gets a Parser and a ParamProcssor\ProcessingResult,which is supposed to return a string.

This library also provides two additional classes, FunctionRunner, and HookRegistrant. The formertakes care of invoking the ParamProcessor library based on a HookDefinition. The later takes careof registering the parser hooks defined by your HookDefinition objects to a MediaWiki Parser object.

$awesomeHookDefinition =newHookDefinition('awesome', [/* ... */ ] );$anotherHookDefinition =newHookDefinition('another', [/* ... */ ] );$awesomeHookHandler =newAwesomeHookHandler(/* ... */ );$anotherHookHandler =newAnotherHookHandler(/* ... */ );$hookRegistrant =newHookRegistrant($mediaWikiParser );$hookRegistrant->registerFunctionHandler($awesomeHookDefinition,$awesomeHookHandler );$hookRegistrant->registerFunctionHandler($anotherHookDefinition,$anotherHookHandler );

If you want to have the same hook, but with other default behaviour, you can avoid any kind ofduplication by doing something as follows on top of the above code:

$hookRegistrant->registerFunctionHandler($extraAwesomeHookDefinition,$awesomeHookHandler );

Where $extraAwesomeHookDefinition is a variation of $awesomeHookDefinition.

To register a parser function, use HookRegistrant::registerFunctionHandler.

$hookRegistrant->registerFunctionHandler($awesomeHookDefinition,$awesomeHookHandler );

To register a tag hook, use HookRegistrant::registerHookHandler.

$hookRegistrant->registerHookHandler($awesomeHookDefinition,$awesomeHookHandler );

Both functions take the exact same arguments, so once you created a HookDefinition anda HookHandler, you can have them registered as both parser function and tag hook withno extra work.

This library comes with a set up PHPUnit tests that cover all non-trivial code. You can run thesetests using the PHPUnit configuration file found in the root directory. The tests can also be runvia TravisCI, as a TravisCI configuration file is also provided in the root directory.

The tests can be run for thetests/phpunit directory of your MediaWiki installationwith this command:

php phpunit.php --wiki wikiName -c ../../extensions/ParserHooks/

ParserHooks has been written byJeroen De Dauwas a hobby project to support theSubPageList MediaWiki extension.

• Updated translations

• Added support for PHP 7.2, 7.3 and 7.4
• Added support for MediaWiki 1.31, 1.32 and 1.33
• Dropped support for PHP 7.1 and older
• Dropped support for MediaWiki 1.30 and older
• Updated translations

• Added license now shown on Special:Version
• Updated translations
• Made minor style improvements
• Ensured the extension works with PHP 7 and MediaWiki up to at least 1.27

• Changed the PHPUnit bootstrap so that the tests can be run via the MediaWiki test runner
• Updated the CI configuration to test the code against multiple MediaWiki versions
• Updated translations

• Updated translations
• Changed class loading to PSR-4
• Updated the used Validator version to 2.x >= 2.0.4

• Updated the used Validator version from 1.0 alpha to 1.0.0.1 stable, or later

• Fixed parameter handling bug in FunctionRunner
• Added system test for tag hook handling

• Added HookRunner and HookRegistrant::registerHook
• Added HookRegistrant::registerFunctionHandler and HookRegistrant::registerHookHandler
• Fixed parameter handling bug in FunctionRunner
• Improved HookRegistrantTest

You canread the release blog post

• Improved HookDefinition documentation
• Added extra type checking in HookDefinition
• Added extra tests for HookDefinition
• Added coveralls.io support
• Added PHPUnit file whitelisting (for more accurate and faster generated coverage reports)

• Initial release (blog post)

• ParserHooks on Packagist
• ParserHooks on Ohloh
• ParserHooks on MediaWiki.org
• ParserHooks on Scrutinizer CI
• ParserHooks on coveralls.io
• TravisCI build status