Installation

To add this package as a local, per-project dependency to your project, simply add a dependency on mediawiki/parser-hooks to your project's composer.json file. Here is a minimal example of a composer.json file that just defines a dependency on ParserHooks 1.4:

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

Manual

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.

Usage

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

General concept

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

HookDefinition

An instance of the HookDefinition class represents the signature of a parser hook. It defines the name of the parser hook and the parameters (including their types, default values, etc) it accepts. It does not define any behaviour, and is thus purely declarative. Instances of this class 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 documentation based on them.

The parameter definitions are ParamProcessor objects. See the ParamProcessor documentation on how to specify these.

HookHandler

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, which is supposed to return a string.

Knitting it all together

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

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

Tests

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

The tests can be run for the tests/phpunit directory of your MediaWiki installation with this command: