Extension:HTMLPurifier
HTMLPurifier Release status: beta |
|
---|---|
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 126th) |
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
HTMLPurifier
folder 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-dev
in the extension directory. (See task 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.
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 $i => $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