Extension:HTMLPurifier
 Release status: stable |
|
|---|---|
| Implementation | Tag |
| Description | Allows users to input raw HTML by using HTML Purifier to sanitize it. |
| Author(s) | Sophivorustalk |
| Latest version | 4.1 |
| MediaWiki | >= 1.35.0 |
| Database changes | No |
| License | GNU General Public License 3.0 or later |
| Download | |
| Example | [1] |
| Quarterly downloads | 5 (Ranked 109th) |
| Translate the HTMLPurifier extension if it is available at translatewiki.net | |
The HTMLPurifier extension allows users to input raw HTML by using HTML Purifier to sanitize it.
Installation
edit- Download and move the extracted
HTMLPurifierfolder to yourextensions/directory.
Developers and code contributors should install the extension from Git instead, using:cd extensions/
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/HTMLPurifier - Only when installing from Git, run Composer to install PHP dependencies, by issuing
composer install --no-devin the extension directory. (See T173141 for potential complications.) - Add the following code at the bottom of your LocalSettings.php file:
wfLoadExtension( 'HTMLPurifier' );
Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.
Usage
editOnce installed, users will be able to use the <html> tag to input HTML in any page, like so:
<html>This <a href="https://example.com/">link</a> was done with HTML rather than wikitext!</html>
To avoid security risks, all HTML is passed through HTML Purifier, a mature and thoroughly audited PHP library that strips off all malicious and suspect code.
Note that the <html> tag introduced by this extension has nothing to do with the <html> tag introduced by $wgRawHtml. You should keep that setting to its default value of false.
Configuration
editThe only configuration option is an associative array that controls the configuration of HTML Purifier itself. For example:
$wgHTMLPurifierConfig = [
'Cache.SerializerPath' => $wgCacheDirectory, // Use the MediaWiki cache directory for HTML Purifier
'Attr.EnableID' => true, // Allow ID attributes
'CSS.Trusted' => true, // Allow inline styling
];
The extension has a HTMLPurifierBeforePurify hook to do more advanced configurations. For example, to allow <video> tags, add the following to your LocalSettings.php (see this documentation for more):
$wgHooks['HTMLPurifierBeforePurify'][] = function ( &$config ) {
$definition = $htmlPurifierConfig->getHTMLDefinition(true);
$definition->addElement( 'video',
'Block', // content set
'Flow', // allowed children
'Common', // attribute collection
[ // attributes
'src' => 'URI',
'width' => 'Length',
'height' => 'Length',
'controls' => 'Bool'
]
);
};
The extension also has a HTMLPurifierAfterPurify hook to further transform the purified HTML. For example, to reintroduce extracted <style> tags, add the following to your LocalSettings.php:
$wgHTMLPurifierConfig['Filter.ExtractStyleBlocks'] = true;
$wgHooks['HTMLPurifierAfterPurify'][] = function ( &$html, $purifier ) {
$styles = $purifier->context->get( 'StyleBlocks' );
foreach ( $styles as $style ) {
$html .= "<style>$style</style>";
}
};
See also
edit- HTML restriction - Other extensions that allow users to input raw HTML securely
- Manual:$wgRawHtml - Config option to allow raw HTML