Extension:HTMLPurifier

MediaWiki extensions manual
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 3.0
MediaWiki >= 1.31.0
Database changes No
License GNU General Public License 3.0 or later
Download
Example [1]
Quarterly downloads 9 (Ranked 125th)
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 your extensions/ 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

edit

Once 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

edit

The 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:

$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