1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
|
# ParserHooks
[](http://travis-ci.org/JeroenDeDauw/ParserHooks)
[](https://scrutinizer-ci.com/g/JeroenDeDauw/ParserHooks/?branch=master)
[](https://scrutinizer-ci.com/g/JeroenDeDauw/ParserHooks/)
On Packagist:
[](https://packagist.org/packages/mediawiki/parser-hooks)
[](https://packagist.org/packages/mediawiki/parser-hooks)
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.
## Platform compatibility and release status
The PHP and MediaWiki version ranges listed are those in which ParserHooks is known to work. It might also
work with more recent versions of PHP and MediaWiki, though this is not guaranteed. Increases of
minimum requirements are indicated in bold. For a detailed list of changes, see the [release notes](RELEASE-NOTES.md).
<table>
<tr>
<th>ParserHooks</th>
<th>PHP</th>
<th>MediaWiki</th>
<th>Release status</th>
</tr>
<tr>
<th>1.6.x</th>
<td><strong>7.2</strong> - 7.4</td>
<td><strong>1.31</strong> - 1.33</td>
<td><strong>Stable release</strong></td>
</tr>
<tr>
<th>1.5.x</th>
<td>5.3 - 7.1</td>
<td>1.16 - 1.27</td>
<td>Bugfixes only</td>
</tr>
<tr>
<th>1.0.x - 1.4.x</th>
<td>5.3 - 5.6</td>
<td>1.16 - 1.23</td>
<td>Obsolete release, no support</td>
</tr>
</table>
## Installation
You can use [Composer](http://getcomposer.org/) to download and install
this package as well as its dependencies. Alternatively you can simply clone
the git repository and take care of loading yourself.
### Composer
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.5:
{
"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\ParamDefinition objects. See the
[ParamProcessor](https://github.com/JeroenDeDauw/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\ProcessingResult,
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 MediaWiki Parser object.
```php
$awesomeHookDefinition = new HookDefinition( 'awesome', array( /* ... */ ) );
$anotherHookDefinition = new HookDefinition( 'another', array( /* ... */ ) );
$awesomeHookHandler = new AwesomeHookHandler( /* ... */ );
$anotherHookHandler = new AnotherHookHandler( /* ... */ );
$hookRegistrant = new HookRegistrant( $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 of
duplication by doing something as follows on top of the above code:
```php
$hookRegistrant->registerFunctionHandler( $extraAwesomeHookDefinition, $awesomeHookHandler );
```
Where $extraAwesomeHookDefinition is a variation of $awesomeHookDefinition.
### Parser functions and tag hooks
To register a parser function, use HookRegistrant::registerFunctionHandler.
```php
$hookRegistrant->registerFunctionHandler( $awesomeHookDefinition, $awesomeHookHandler );
```
To register a tag hook, use HookRegistrant::registerHookHandler.
```php
$hookRegistrant->registerHookHandler( $awesomeHookDefinition, $awesomeHookHandler );
```
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:
php phpunit.php --wiki wikiName -c ../../extensions/ParserHooks/
## Authors
ParserHooks has been written by [Jeroen De Dauw](https://www.mediawiki.org/wiki/User:Jeroen_De_Dauw)
as a hobby project to support the
[SubPageList MediaWiki extension](https://github.com/JeroenDeDauw/SubPageList/blob/master/README.md).
## Release notes
### 1.6 (2019-07-14)
* 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
### 1.5 (2016-03-05)
* 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
### 1.4 (2014-07-05)
* 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
### 1.3 (2014-06-25)
* Updated i18n message files
* Changed class loading to PSR-4
* Updated the used Validator version to 2.x >= 2.0.4
### 1.2.1 (2013-11-22)
* Updated the used Validator version from 1.0 alpha to 1.0.0.1 stable, or later
### 1.2 (2013-09-30)
* Fixed parameter handling bug in FunctionRunner
* Added system test for tag hook handling
### 1.1 (2013-09-25)
* Added HookRunner and HookRegistrant::registerHook
* Added HookRegistrant::registerFunctionHandler and HookRegistrant::registerHookHandler
* Fixed parameter handling bug in FunctionRunner
* Improved HookRegistrantTest
You can [read the release blog post](https://www.entropywins.wtf/blog/2013/09/25/parserhooks-1-1-released/)
### 1.0.1 (2013-09-22)
* 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)
### 1.0 (2013-07-14)
* Initial release ([blog post](https://www.entropywins.wtf/blog/2013/07/14/parserhooks-declarative-oop-api-for-mediawiki-released/))
## Links
* [ParserHooks on Packagist](https://packagist.org/packages/mediawiki/parser-hooks)
* [ParserHooks on Ohloh](https://www.ohloh.net/p/parserhooks)
* [ParserHooks on MediaWiki.org](https://www.mediawiki.org/wiki/Extension:ParserHooks)
* [ParserHooks on Scrutinizer CI](https://scrutinizer-ci.com/g/JeroenDeDauw/ParserHooks)
* [ParserHooks on coveralls.io](https://coveralls.io/r/wikimedia/mediawiki-extensions-ParserHooks)
* [TravisCI build status](https://travis-ci.org/JeroenDeDauw/ParserHooks)
|
