Configuration Documentation

NULL

List of allowed class values in the class attribute. By default, this is null, which means all classes are allowed.

array()

Lookup table of all allowed link frame targets. Some commonly used link targets include _blank, _self, _parent and _top. Values should be lowercase, as validation will be done in a case-sensitive manner despite W3C's recommendation. XHTML 1.0 Strict does not permit the target attribute so this directive will have no effect in that doctype. XHTML 1.1 does not enable the Target module by default, you will have to manually enable it (see the module documentation for more details.)

array()

List of allowed forward document relationships in the rel attribute. Common values may be nofollow or print. By default, this is empty, meaning that no document relationships are allowed.

array()

List of allowed reverse document relationships in the rev attribute. This attribute is a bit of an edge-case; if you don't know what it is for, stay away.

NULL

If null, class will auto-detect the doctype and, if matching XHTML 1.1 or XHTML 2.0, will use the restrictive NMTOKENS specification of class. Otherwise, it will use a relaxed CDATA definition. If true, the relaxed CDATA definition is forced; if false, the NMTOKENS definition is forced. To get behavior of HTML Purifier prior to 4.0.0, set this directive to false. Some rational behind the auto-detection: in previous versions of HTML Purifier, it was assumed that the form of class was NMTOKENS, as specified by the XHTML Modularization (representing XHTML 1.1 and XHTML 2.0). The DTDs for HTML 4.01 and XHTML 1.0, however specify class as CDATA. HTML 5 effectively defines it as CDATA, but with the additional constraint that each name should be unique (this is not explicitly outlined in previous specifications).

NULL

This is the content of the alt tag of an image if the user had not previously specified an alt attribute. This applies to all images without a valid alt attribute, as opposed to %Attr.DefaultInvalidImageAlt, which only applies to invalid images, and overrides in the case of an invalid image. Default behavior with null is to use the basename of the src tag for the alt.

''

This is the default image an img tag will be pointed to if it does not have a valid src attribute. In future versions, we may allow the image tag to be removed completely, but due to design issues, this is not possible right now.

'Invalid image'

This is the content of the alt tag of an invalid image if the user had not previously specified an alt attribute. It has no effect when the image is valid but there was no alt attribute present.

'ltr'

Defines the default text direction (ltr or rtl) of the document being parsed. This generally is the same as the value of the dir attribute in HTML, or ltr if that is not specified.

false

Allows the ID attribute in HTML. This is disabled by default due to the fact that without proper configuration user input can easily break the validation of a webpage by specifying an ID that is already on the surrounding HTML. If you don't mind throwing caution to the wind, enable this directive, but I strongly recommend you also consider blacklisting IDs you use (%Attr.IDBlacklist) or prefixing all user supplied IDs (%Attr.IDPrefix). When set to true HTML Purifier reverts to the behavior of pre-1.2.0 versions.

array()

List of forbidden class values in the class attribute. By default, this is empty, which means that no classes are forbidden. See also %Attr.AllowedClasses.

NULL

In HTML5, restrictions on the format of the id attribute have been significantly relaxed, such that any string is valid so long as it contains no spaces and is at least one character. In lieu of a general HTML5 compatibility flag, set this configuration directive to true to use the relaxed rules.

array()

Array of IDs not allowed in the document.

NULL

PCRE regular expression to be matched against all IDs. If the expression is matches, the ID is rejected. Use this with care: may cause significant degradation. ID matching is done after all other validation.

''

String to prefix to IDs. If you have no idea what IDs your pages may use, you may opt to simply add a prefix to all user-submitted ID attributes so that they are still usable, but will not conflict with core page IDs. Example: setting the directive to 'user_' will result in a user submitted 'foo' to become 'user_foo' Be sure to set %HTML.EnableAttrID to true before using this.

''

Temporary prefix for IDs used in conjunction with %Attr.IDPrefix. If you need to allow multiple sets of user content on web page, you may need to have a seperate prefix that changes with each iteration. This way, seperately submitted user content displayed on the same page doesn't clobber each other. Ideal values are unique identifiers for the content it represents (i.e. the id of the row in the database). Be sure to add a seperator (like an underscore) at the end. Warning: this directive will not work unless %Attr.IDPrefix is set to a non-empty value!

false

This directive turns on auto-paragraphing, where double newlines are converted in to paragraphs whenever possible. Auto-paragraphing:

• Always applies to inline elements or text in the root node,
• Applies to inline elements or text with double newlines in nodes that allow paragraph tags,
• Applies to double newlines in paragraph tags

p tags must be allowed for this directive to take effect. We do not use br tags for paragraphing, as that is semantically incorrect.

To prevent auto-paragraphing as a content-producer, refrain from using double-newlines except to specify a new paragraph or in contexts where it has special meaning (whitespace usually has no meaning except in tags like pre, so this should not be difficult.) To prevent the paragraphing of inline text adjacent to block elements, wrap them in div tags (the behavior is slightly different outside of the root node.)

array()

This directive can be used to add custom auto-format injectors. Specify an array of injector names (class name minus the prefix) or concrete implementations. Injector class must exist.

false

This directive turns on the in-text display of URIs in <a> tags, and disables those links. For example, example becomes example (http://example.com).

false

This directive turns on linkification, auto-linking http, ftp and https URLs. a tags with the href attribute must be allowed.

'#%s'

Location of configuration documentation to link to, let %s substitute into the configuration's namespace and directive names sans the percent sign.

false

Internal auto-formatter that converts configuration directives in syntax %Namespace.Directive to links. a tags with the href attribute must be allowed.

array (
  'colgroup' => 
  array (
  ),
  'th' => 
  array (
  ),
  'td' => 
  array (
  ),
  'iframe' => 
  array (
    0 => 'src',
  ),
)

Given that an element has no contents, it will be removed by default, unless this predicate dictates otherwise. The predicate can either be an associative map from tag name to list of attributes that must be present for the element to be considered preserved: thus, the default always preserves colgroup, th and td, and also iframe if it has a src.

array (
  'td' => true,
  'th' => true,
)

When %AutoFormat.RemoveEmpty and %AutoFormat.RemoveEmpty.RemoveNbsp are enabled, this directive defines what HTML elements should not be removede if they have only a non-breaking space in them.

false

When enabled, HTML Purifier will treat any elements that contain only non-breaking spaces as well as regular whitespace as empty, and remove them when %AutoFormat.RemoveEmpty is enabled.

See %AutoFormat.RemoveEmpty.RemoveNbsp.Exceptions for a list of elements that don't have this behavior applied to them.

false

When enabled, HTML Purifier will attempt to remove empty elements that contribute no semantic information to the document. The following types of nodes will be removed:

• Tags with no attributes and no content, and that are not empty elements (remove <a></a> but not <br />), and
• Tags with no content, except for:
  • The colgroup element, or
  • Elements with the id or name attribute, when those attributes are permitted on those elements.

Please be very careful when using this functionality; while it may not seem that empty elements contain useful information, they can alter the layout of a document given appropriate styling. This directive is most useful when you are processing machine-generated HTML, please avoid using it on regular user HTML.

Elements that contain only whitespace will be treated as empty. Non-breaking spaces, however, do not count as whitespace. See %AutoFormat.RemoveEmpty.RemoveNbsp for alternate behavior.

This algorithm is not perfect; you may still notice some empty tags, particularly if a node had elements, but those elements were later removed because they were not permitted in that context, or tags that, after being auto-closed by another tag, where empty. This is for safety reasons to prevent clever code from breaking validation. The general rule of thumb: if a tag looked empty on the way in, it will get removed; if HTML Purifier made it empty, it will stay.

false

This directive causes span tags without any attributes to be removed. It will also remove spans that had all attributes removed during processing.

false

By default, HTML Purifier removes duplicate CSS properties, like color:red; color:blue. If this is set to true, duplicate properties are allowed.

false

This parameter determines whether or not !important cascade modifiers should be allowed in user CSS. If false, !important will stripped.

false

This parameter determines whether or not to allow "tricky" CSS properties and values. Tricky CSS properties/values can drastically modify page layout or be used for deceptive practices but do not directly constitute a security risk. For example, display:none; is considered a tricky property that will only be allowed if this directive is set to true.

NULL

Allows you to manually specify a set of allowed fonts. If NULL, all fonts are allowed. This directive affects generic names (serif, sans-serif, monospace, cursive, fantasy) as well as specific font families.

NULL

If HTML Purifier's style attributes set is unsatisfactory for your needs, you can overload it with your own list of tags to allow. Note that this method is subtractive: it does its job by taking away from HTML Purifier usual feature set, so you cannot add an attribute that HTML Purifier never supported in the first place.

Warning: If another directive conflicts with the elements here, that directive will win and override.

1

Revision identifier for your custom definition. See %HTML.DefinitionRev for details.

array()

This is the logical inverse of %CSS.AllowedProperties, and it will override that directive or any other directive. If possible, %CSS.AllowedProperties is recommended over this directive, because it can sometimes be difficult to tell whether or not you've forbidden all of the CSS properties you truly would like to disallow.

'1200px'

This parameter sets the maximum allowed length on img tags, effectively the width and height properties. Only absolute units of measurement (in, pt, pc, mm, cm) and pixels (px) are allowed. This is in place to prevent imagecrash attacks, disable with null at your own risk. This directive is similar to %HTML.MaxImgLength, and both should be concurrently edited, although there are subtle differences in the input format (the CSS max is a number with a unit).

false

Whether or not to allow safe, proprietary CSS values.

false

Indicates whether or not the user's CSS input is trusted or not. If the input is trusted, a more expansive set of allowed properties. See also %HTML.Trusted.

'Serializer'

This directive defines which method to use when caching definitions, the complex data-type that makes HTML Purifier tick. Set to null to disable caching (not recommended, as you will see a definite performance degradation).

NULL

Absolute path with no trailing slash to store serialized definitions in. Default is within the HTML Purifier library inside DefinitionCache/Serializer. This path must be writable by the webserver.

493

Directory permissions of the files and directories created inside the DefinitionCache/Serializer or other custom serializer path.

In HTML Purifier 4.8.0, this also supports NULL, which means that no chmod'ing or directory creation shall occur.

true

This directive enables aggressive pre-filter fixes HTML Purifier can perform in order to ensure that open angled-brackets do not get killed during parsing stage. Enabling this will result in two preg_replace_callback calls and at least two preg_replace calls for every HTML document parsed; if your users make very well-formed HTML, you can set this directive false. This has no effect when DirectLex is used.

Notice: This directive's default turned from false to true in HTML Purifier 3.2.0.

true

This directive enables aggressive pre-filter removal of script tags. This is not necessary for security, but it can help work around a bug in libxml where embedded HTML elements inside script sections cause the parser to choke. To revert to pre-4.9.0 behavior, set this to false. This directive has no effect if %Core.Trusted is true, %Core.RemoveScriptContents is false, or %Core.HiddenElements does not contain script.

false

By RFC 1123, underscores are not permitted in host names. (This is in contrast to the specification for DNS, RFC 2181, which allows underscores.) However, most browsers do the right thing when faced with an underscore in the host name, and so some poorly written websites are written with the expectation this should work. Setting this parameter to true relaxes our allowed character check so that underscores are permitted.

false

This directive allows parsing of many nested tags. If you set true, relaxes any hardcoded limit from the parser. However, in that case it may cause a Dos attack. Be careful when enabling it.

false

Whether or not to collect errors found while filtering the document. This is a useful way to give feedback to your users. Warning: Currently this feature is very patchy and experimental, with lots of possible error messages not yet implemented. It will not cause any problems, but it may not help your users either.

array (
  'aliceblue' => '#F0F8FF',
  'antiquewhite' => '#FAEBD7',
  'aqua' => '#00FFFF',
  'aquamarine' => '#7FFFD4',
  'azure' => '#F0FFFF',
  'beige' => '#F5F5DC',
  'bisque' => '#FFE4C4',
  'black' => '#000000',
  'blanchedalmond' => '#FFEBCD',
  'blue' => '#0000FF',
  'blueviolet' => '#8A2BE2',
  'brown' => '#A52A2A',
  'burlywood' => '#DEB887',
  'cadetblue' => '#5F9EA0',
  'chartreuse' => '#7FFF00',
  'chocolate' => '#D2691E',
  'coral' => '#FF7F50',
  'cornflowerblue' => '#6495ED',
  'cornsilk' => '#FFF8DC',
  'crimson' => '#DC143C',
  'cyan' => '#00FFFF',
  'darkblue' => '#00008B',
  'darkcyan' => '#008B8B',
  'darkgoldenrod' => '#B8860B',
  'darkgray' => '#A9A9A9',
  'darkgrey' => '#A9A9A9',
  'darkgreen' => '#006400',
  'darkkhaki' => '#BDB76B',
  'darkmagenta' => '#8B008B',
  'darkolivegreen' => '#556B2F',
  'darkorange' => '#FF8C00',
  'darkorchid' => '#9932CC',
  'darkred' => '#8B0000',
  'darksalmon' => '#E9967A',
  'darkseagreen' => '#8FBC8F',
  'darkslateblue' => '#483D8B',
  'darkslategray' => '#2F4F4F',
  'darkslategrey' => '#2F4F4F',
  'darkturquoise' => '#00CED1',
  'darkviolet' => '#9400D3',
  'deeppink' => '#FF1493',
  'deepskyblue' => '#00BFFF',
  'dimgray' => '#696969',
  'dimgrey' => '#696969',
  'dodgerblue' => '#1E90FF',
  'firebrick' => '#B22222',
  'floralwhite' => '#FFFAF0',
  'forestgreen' => '#228B22',
  'fuchsia' => '#FF00FF',
  'gainsboro' => '#DCDCDC',
  'ghostwhite' => '#F8F8FF',
  'gold' => '#FFD700',
  'goldenrod' => '#DAA520',
  'gray' => '#808080',
  'grey' => '#808080',
  'green' => '#008000',
  'greenyellow' => '#ADFF2F',
  'honeydew' => '#F0FFF0',
  'hotpink' => '#FF69B4',
  'indianred' => '#CD5C5C',
  'indigo' => '#4B0082',
  'ivory' => '#FFFFF0',
  'khaki' => '#F0E68C',
  'lavender' => '#E6E6FA',
  'lavenderblush' => '#FFF0F5',
  'lawngreen' => '#7CFC00',
  'lemonchiffon' => '#FFFACD',
  'lightblue' => '#ADD8E6',
  'lightcoral' => '#F08080',
  'lightcyan' => '#E0FFFF',
  'lightgoldenrodyellow' => '#FAFAD2',
  'lightgray' => '#D3D3D3',
  'lightgrey' => '#D3D3D3',
  'lightgreen' => '#90EE90',
  'lightpink' => '#FFB6C1',
  'lightsalmon' => '#FFA07A',
  'lightseagreen' => '#20B2AA',
  'lightskyblue' => '#87CEFA',
  'lightslategray' => '#778899',
  'lightslategrey' => '#778899',
  'lightsteelblue' => '#B0C4DE',
  'lightyellow' => '#FFFFE0',
  'lime' => '#00FF00',
  'limegreen' => '#32CD32',
  'linen' => '#FAF0E6',
  'magenta' => '#FF00FF',
  'maroon' => '#800000',
  'mediumaquamarine' => '#66CDAA',
  'mediumblue' => '#0000CD',
  'mediumorchid' => '#BA55D3',
  'mediumpurple' => '#9370DB',
  'mediumseagreen' => '#3CB371',
  'mediumslateblue' => '#7B68EE',
  'mediumspringgreen' => '#00FA9A',
  'mediumturquoise' => '#48D1CC',
  'mediumvioletred' => '#C71585',
  'midnightblue' => '#191970',
  'mintcream' => '#F5FFFA',
  'mistyrose' => '#FFE4E1',
  'moccasin' => '#FFE4B5',
  'navajowhite' => '#FFDEAD',
  'navy' => '#000080',
  'oldlace' => '#FDF5E6',
  'olive' => '#808000',
  'olivedrab' => '#6B8E23',
  'orange' => '#FFA500',
  'orangered' => '#FF4500',
  'orchid' => '#DA70D6',
  'palegoldenrod' => '#EEE8AA',
  'palegreen' => '#98FB98',
  'paleturquoise' => '#AFEEEE',
  'palevioletred' => '#DB7093',
  'papayawhip' => '#FFEFD5',
  'peachpuff' => '#FFDAB9',
  'peru' => '#CD853F',
  'pink' => '#FFC0CB',
  'plum' => '#DDA0DD',
  'powderblue' => '#B0E0E6',
  'purple' => '#800080',
  'rebeccapurple' => '#663399',
  'red' => '#FF0000',
  'rosybrown' => '#BC8F8F',
  'royalblue' => '#4169E1',
  'saddlebrown' => '#8B4513',
  'salmon' => '#FA8072',
  'sandybrown' => '#F4A460',
  'seagreen' => '#2E8B57',
  'seashell' => '#FFF5EE',
  'sienna' => '#A0522D',
  'silver' => '#C0C0C0',
  'skyblue' => '#87CEEB',
  'slateblue' => '#6A5ACD',
  'slategray' => '#708090',
  'slategrey' => '#708090',
  'snow' => '#FFFAFA',
  'springgreen' => '#00FF7F',
  'steelblue' => '#4682B4',
  'tan' => '#D2B48C',
  'teal' => '#008080',
  'thistle' => '#D8BFD8',
  'tomato' => '#FF6347',
  'turquoise' => '#40E0D0',
  'violet' => '#EE82EE',
  'wheat' => '#F5DEB3',
  'white' => '#FFFFFF',
  'whitesmoke' => '#F5F5F5',
  'yellow' => '#FFFF00',
  'yellowgreen' => '#9ACD32',
)

Lookup array of color names to six digit hexadecimal number corresponding to color, with preceding hash mark. Used when parsing colors. The lookup is done in a case-insensitive manner.

true

This parameter determines whether or not the filter should convert input that is a full document with html and body tags to a fragment of just the contents of a body tag. This parameter is simply something HTML Purifier can do during an edge-case: for most inputs, this processing is not necessary.

0

Specifies the number of tokens the DirectLex line number tracking implementations should process before attempting to resyncronize the current line count by manually counting all previous new-lines. When at 0, this functionality is disabled. Lower values will decrease performance, and this is only strictly necessary if the counting algorithm is buggy (in which case you should report it as a bug). This has no effect when %Core.MaintainLineNumbers is disabled or DirectLex is not being used.

false

This directive disables SGML-style exclusions, e.g. the exclusion of <object> in any descendant of a <pre> tag. Disabling excludes will allow some invalid documents to pass through HTML Purifier, but HTML Purifier will also be less likely to accidentally remove large documents during processing.

false

Allows international domain names in URLs. This configuration option requires the PEAR Net_IDNA2 module to be installed. It operates by punycoding any internationalized host names for maximum portability.

'utf-8'

If for some reason you are unable to convert all webpages to UTF-8, you can use this directive as a stop-gap compatibility change to let HTML Purifier deal with non UTF-8 input. This technique has notable deficiencies: absolutely no characters outside of the selected character encoding will be preserved, not even the ones that have been ampersand escaped (this is due to a UTF-8 specific feature that automatically resolves all entities), making it pretty useless for anything except the most I18N-blind applications, although %Core.EscapeNonASCIICharacters offers fixes this trouble with another tradeoff. This directive only accepts ISO-8859-1 if iconv is not enabled.

false

Warning: this configuration option is no longer does anything as of 4.6.0.

When true, a child is found that is not allowed in the context of the parent element will be transformed into text as if it were ASCII. When false, that element and all internal tags will be dropped, though text will be preserved. There is no option for dropping the element but preserving child nodes.

false

When true, invalid tags will be written back to the document as plain text. Otherwise, they are silently dropped.

false

This directive overcomes a deficiency in %Core.Encoding by blindly converting all non-ASCII characters into decimal numeric entities before converting it to its native encoding. This means that even characters that can be expressed in the non-UTF-8 encoding will be entity-ized, which can be a real downer for encodings like Big5. It also assumes that the ASCII repetoire is available, although this is the case for almost all encodings. Anyway, use UTF-8!

array (
  'script' => true,
  'style' => true,
)

This directive is a lookup array of elements which should have their contents removed when they are not allowed by the HTML definition. For example, the contents of a script tag are not normally shown in a document, so if script tags are to be removed, their contents should be removed to. This is opposed to a b tag, which defines some presentational changes but does not hide its contents.

'en'

ISO 639 language code for localizable things in HTML Purifier to use, which is mainly error reporting. There is currently only an English (en) translation, so this directive is currently useless.

false

Prior to HTML Purifier 4.9.0, entities were decoded by performing a global search replace for all entities whose decoded versions did not have special meanings under HTML, and replaced them with their decoded versions. We would match all entities, even if they did not have a trailing semicolon, but only if there weren't any trailing alphanumeric characters.

Original	Text	Attribute
¥	¥	¥
&yen	¥	¥
&yena	&yena	&yena
&yen=	¥=	¥=

In HTML Purifier 4.9.0, we changed the behavior of entity parsing to match entities that had missing trailing semicolons in less cases, to more closely match HTML5 parsing behavior:

Original	Text	Attribute
¥	¥	¥
&yen	¥	¥
&yena	¥a	&yena
&yen=	¥=	&yen=

This flag reverts back to pre-HTML Purifier 4.9.0 behavior.

NULL

This parameter determines what lexer implementation can be used. The valid values are:

null

Recommended, the lexer implementation will be auto-detected based on your PHP-version and configuration.

string lexer identifier

This is a slim way of manually overridding the implementation. Currently recognized values are: DOMLex (the default PHP5 implementation) and DirectLex (the default PHP4 implementation). Only use this if you know what you are doing: usually, the auto-detection will manage things for cases you aren't even aware of.

object lexer instance

Super-advanced: you can specify your own, custom, implementation that implements the interface defined by HTMLPurifier_Lexer. I may remove this option simply because I don't expect anyone to use it.

NULL

If true, HTML Purifier will add line number information to all tokens. This is useful when error reporting is turned on, but can result in significant performance degradation and should not be used when unnecessary. This directive must be used with the DirectLex lexer, as the DOMLex lexer does not (yet) support this functionality. If the value is null, an appropriate value will be selected based on other configuration.

true

Whether or not to normalize newlines to the operating system default. When false, HTML Purifier will attempt to preserve mixed newline files.

false

If set to true, blank nodes will be removed. This can be useful for maintaining backwards compatibility when upgrading from previous versions of PHP.

true

This directive enables pre-emptive URI checking in img tags, as the attribute validation strategy is not authorized to remove elements from the document. Revert to pre-1.3.0 behavior by setting to false.

false

Instead of escaping processing instructions in the form <? ... ?>, remove it out-right. This may be useful if the HTML you are validating contains XML processing instruction gunk, however, it can also be user-unfriendly for people attempting to post PHP snippets.

array()

This directive can be used to add custom filters; it is nearly the equivalent of the now deprecated HTMLPurifier->addFilter() method. Specify an array of concrete implementations.

true

Whether or not to escape the dangerous characters <, > and & as \3C, \3E and \26, respectively. This is can be safely set to false if the contents of StyleBlocks will be placed in an external stylesheet, where there is no risk of it being interpreted as HTML.

NULL

If you would like users to be able to define external stylesheets, but only allow them to specify CSS declarations for a specific node and prevent them from fiddling with other elements, use this directive. It accepts any valid CSS selector, and will prepend this to any CSS declaration extracted from the document. For example, if this directive is set to #user-content and a user uses the selector a:hover, the final selector will be #user-content a:hover.

The comma shorthand may be used; consider the above example, with #user-content, #user-content2, the final selector will be #user-content a:hover, #user-content2 a:hover.

Warning: It is possible for users to bypass this measure using a naughty + selector. This is a bug in CSS Tidy 1.3, not HTML Purifier, and I am working to get it fixed. Until then