Sanitizer Class Reference
[Parser]

XHTML sanitizer for MediaWiki. More...

List of all members.

Static Public Member Functions

static removeHTMLtags ($text, $processCallback=null, $args=array(), $extratags=array(), $removetags=array())
 Cleans up HTML, removes dangerous tags and attributes, and removes HTML comments.
static removeHTMLcomments ($text)
 Remove '', and everything between.
static validateTagAttributes ($attribs, $element)
 Take an array of attribute names and values and normalize or discard illegal values for the given element type.
static validateAttributes ($attribs, $whitelist)
 Take an array of attribute names and values and normalize or discard illegal values for the given whitelist.
static mergeAttributes ($a, $b)
 Merge two sets of HTML attributes.
static checkCss ($value)
 Pick apart some CSS and check it for forbidden or unsafe structures.
static cssDecodeCallback ($matches)
static fixTagAttributes ($text, $element)
 Take a tag soup fragment listing an HTML element's attributes and normalize it to well-formed XML, discarding unwanted attributes.
static encodeAttribute ($text)
 Encode an attribute value for HTML output.
static safeEncodeAttribute ($text)
 Encode an attribute value for HTML tags, with extra armoring against further wiki processing.
static escapeId ($id, $options=array())
 Given a value, escape it so that it can be used in an id attribute and return it.
static escapeClass ($class)
 Given a value, escape it so that it can be used as a CSS class and return it.
static escapeHtmlAllowEntities ($html)
 Given HTML input, escape with htmlspecialchars but un-escape entites.
static decodeTagAttributes ($text)
 Return an associative array of attribute names and values from a partial tag string.
static normalizeCharReferences ($text)
 Ensure that any entities and character references are legal for XML and XHTML specifically.
static normalizeCharReferencesCallback ($matches)
static normalizeEntity ($name)
 If the named entity is defined in the HTML 4.0/XHTML 1.0 DTD, return the named entity reference as is.
static decCharReference ($codepoint)
static hexCharReference ($codepoint)
static decodeCharReferences ($text)
 Decode any character references, numeric or named entities, in the text and return a UTF-8 string.
static decodeCharReferencesCallback ($matches)
static decodeChar ($codepoint)
 Return UTF-8 string for a codepoint if that is a valid character reference, otherwise U+FFFD REPLACEMENT CHARACTER.
static decodeEntity ($name)
 If the named entity is defined in the HTML 4.0/XHTML 1.0 DTD, return the UTF-8 encoding of that character.
static attributeWhitelist ($element)
 Fetch the whitelist of acceptable attributes for a given element name.
static setupAttributeWhitelist ()
 Foreach array key (an allowed HTML element), return an array of allowed attributes.
static stripAllTags ($text)
 Take a fragment of (potentially invalid) HTML and return a version with any tags removed, encoded as plain text.
static hackDocType ()
 Hack up a private DOCTYPE with HTML's standard entity declarations.
static cleanUrl ($url)

Static Private Member Functions

static armorLinksCallback ($matches)
 Regex replace callback for armoring links against further processing.
static getTagAttributeCallback ($set)
 Pick the appropriate attribute value from a match set from the MW_ATTRIBS_REGEX matches.
static normalizeAttributeValue ($text)
 Normalize whitespace and character references in an XML source- encoded text for an attribute value.
static normalizeWhitespace ($text)
static validateCodepoint ($codepoint)
 Returns true if a given Unicode codepoint is a valid character in XML.


Detailed Description

XHTML sanitizer for MediaWiki.

Definition at line 341 of file Sanitizer.php.


Member Function Documentation

static Sanitizer::armorLinksCallback ( matches  )  [static, private]

Regex replace callback for armoring links against further processing.

Parameters:
$matches Array
Returns:
string

Definition at line 1008 of file Sanitizer.php.

static Sanitizer::attributeWhitelist ( element  )  [static]

Fetch the whitelist of acceptable attributes for a given element name.

Parameters:
$element String
Returns:
Array

Definition at line 1269 of file Sanitizer.php.

static Sanitizer::checkCss ( value  )  [static]

Pick apart some CSS and check it for forbidden or unsafe structures.

Returns a sanitized string. This sanitized string will have character references and escape sequences decoded, and comments stripped. If the input is just too evil, only a comment complaining about evilness will be returned.

Currently URL references, 'expression', 'tps' are forbidden.

NOTE: Despite the fact that character references are decoded, the returned string may contain character references given certain clever input strings. These character references must be escaped before the return value is embedded in HTML.

Parameters:
$value String
Returns:
String

Definition at line 742 of file Sanitizer.php.

static Sanitizer::cleanUrl ( url  )  [static]

Definition at line 1490 of file Sanitizer.php.

Referenced by Parser::makeFreeExternalLink(), and Parser::replaceExternalLinks().

static Sanitizer::cssDecodeCallback ( matches  )  [static]

Definition at line 795 of file Sanitizer.php.

static Sanitizer::decCharReference ( codepoint  )  [static]

Definition at line 1164 of file Sanitizer.php.

static Sanitizer::decodeChar ( codepoint  )  [static]

Return UTF-8 string for a codepoint if that is a valid character reference, otherwise U+FFFD REPLACEMENT CHARACTER.

Parameters:
$codepoint Integer
Returns:
String
Access:
private

Definition at line 1235 of file Sanitizer.php.

static Sanitizer::decodeCharReferences ( text  )  [static]

static Sanitizer::decodeCharReferencesCallback ( matches  )  [static]

Parameters:
$matches String
Returns:
String

Definition at line 1214 of file Sanitizer.php.

static Sanitizer::decodeEntity ( name  )  [static]

If the named entity is defined in the HTML 4.0/XHTML 1.0 DTD, return the UTF-8 encoding of that character.

Otherwise, returns pseudo-entity source (eg )

Parameters:
$name Strings
Returns:
String

Definition at line 1251 of file Sanitizer.php.

static Sanitizer::decodeTagAttributes ( text  )  [static]

Return an associative array of attribute names and values from a partial tag string.

Attribute names are forces to lowercase, character references are decoded to UTF-8 text.

Parameters:
$text String
Returns:
Array

Definition at line 1020 of file Sanitizer.php.

Referenced by Parser::extensionSubstitution(), and Linker::makeKnownLinkObj().

static Sanitizer::encodeAttribute ( text  )  [static]

Encode an attribute value for HTML output.

Parameters:
$text String
Returns:
HTML-encoded text fragment

Definition at line 858 of file Sanitizer.php.

Referenced by Xml::expandAttributes(), and ApiFormatXml::recXmlPrint().

static Sanitizer::escapeClass ( class  )  [static]

Given a value, escape it so that it can be used as a CSS class and return it.

Todo:
For extra validity, input should be validated UTF-8.
See also:
http://www.w3.org/TR/CSS21/syndata.html Valid characters/format
Parameters:
$class String
Returns:
String

Definition at line 979 of file Sanitizer.php.

Referenced by ChangeTags::formatSummaryRow(), SpecialStatistics::getGroupStats(), getPageClasses(), OutputPage::headElement(), SkinTemplate::outputPage(), and OldChangesList::recentChangesLine().

static Sanitizer::escapeHtmlAllowEntities ( html  )  [static]

Given HTML input, escape with htmlspecialchars but un-escape entites.

This allows (generally harmless) entities like   to survive.

Parameters:
$html String to escape
Returns:
String: escaped input

Definition at line 994 of file Sanitizer.php.

Referenced by Linker::formatComment(), AllmessagesTablePager::formatValue(), and wfMsgExt().

static Sanitizer::escapeId ( id,
options = array() 
) [static]

Given a value, escape it so that it can be used in an id attribute and return it.

This will use HTML5 validation if $wgExperimentalHtmlIds is true, allowing anything but ASCII whitespace. Otherwise it will use HTML 4 rules, which means a narrow subset of ASCII, with bad characters escaped with lots of dots.

To ensure we don't have to bother escaping anything, we also strip ', ", & even if $wgExperimentalIds is true. TODO: Is this the best tactic? We also strip # because it upsets IE6.

See also:
http://www.w3.org/TR/html401/types.html#type-name Valid characters in the id and name attributes

http://www.w3.org/TR/html401/struct/links.html#h-12.2.3 Anchors with the id attribute

http://www.whatwg.org/specs/web-apps/current-work/multipage/elements.html#the-id-attribute HTML5 definition of id attribute

Parameters:
$id String: id to escape
$options Mixed: string or array of strings (default is array()): 'noninitial': This is a non-initial fragment of an id, not a full id, so don't pay attention if the first character isn't valid at the beginning of an id. Only matters if $wgExperimentalHtmlIds is false. 'legacy': Behave the way the old HTML 4-based ID escaping worked even if $wgExperimentalHtmlIds is used, so we can generate extra anchors and links won't break.
Returns:
String

Definition at line 935 of file Sanitizer.php.

Referenced by Title::escapeFragmentForURL(), VectorTemplate::execute(), MonoBookTemplate::execute(), ModernTemplate::execute(), Parser::formatHeadings(), HTMLRadioField::formatOptions(), AllmessagesTablePager::getRowAttrs(), and ImagePage::makeMetadataTable().

static Sanitizer::fixTagAttributes ( text,
element 
) [static]

Take a tag soup fragment listing an HTML element's attributes and normalize it to well-formed XML, discarding unwanted attributes.

Output is safe for further wikitext processing, with escaping of values that could trigger problems.

  • Normalizes attribute names to lowercase
  • Discards attributes not on a whitelist for the given element
  • Turns broken or invalid entities into plaintext
  • Double-quotes all attribute values
  • Attributes without values are given the name as attribute
  • Double attributes are discarded
  • Unsafe style attributes are discarded
  • Prepends space if there are attributes.

Parameters:
$text String
$element String
Returns:
String

Definition at line 835 of file Sanitizer.php.

static Sanitizer::getTagAttributeCallback ( set  )  [static, private]

Pick the appropriate attribute value from a match set from the MW_ATTRIBS_REGEX matches.

Parameters:
$set Array
Returns:
String

Definition at line 1056 of file Sanitizer.php.

static Sanitizer::hackDocType (  )  [static]

Hack up a private DOCTYPE with HTML's standard entity declarations.

PHP 4 seemed to know these if you gave it an HTML doctype, but PHP 5.1 doesn't.

Use for passing XHTML fragments to PHP's XML parsing functions

Returns:
String

Definition at line 1480 of file Sanitizer.php.

Referenced by Xml::isWellFormedXmlFragment(), and ParserTest::wellFormed().

static Sanitizer::hexCharReference ( codepoint  )  [static]

Definition at line 1173 of file Sanitizer.php.

static Sanitizer::mergeAttributes ( a,
b 
) [static]

Merge two sets of HTML attributes.

Conflicting items in the second set will override those in the first, except for 'class' attributes which will be combined (if they're both strings).

Todo:
implement merging for other attributes such as style
Parameters:
$a Array
$b Array
Returns:
array

Definition at line 713 of file Sanitizer.php.

Referenced by MathRenderer::_attribs(), Linker::linkAttribs(), Linker::makeKnownLinkObj(), and ImageGallery::toHTML().

static Sanitizer::normalizeAttributeValue ( text  )  [static, private]

Normalize whitespace and character references in an XML source- encoded text for an attribute value.

See http://www.w3.org/TR/REC-xml/#AVNormalize for background, but note that we're not returning the value, but are returning XML source fragments that will be slapped into output.

Parameters:
$text String
Returns:
String

Definition at line 1089 of file Sanitizer.php.

static Sanitizer::normalizeCharReferences ( text  )  [static]

Ensure that any entities and character references are legal for XML and XHTML specifically.

Any stray bits will be &-escaped to result in a valid text fragment.

a. any named char refs must be known in XHTML b. any numeric char refs must be legal chars, not invalid or forbidden c. use &x, not &X d. fix or reject non-valid attributes

Parameters:
$text String
Returns:
String
Access:
private

Definition at line 1116 of file Sanitizer.php.

Referenced by CoreParserFunctions::displaytitle(), Parser::parse(), and OutputPage::setPageTitle().

static Sanitizer::normalizeCharReferencesCallback ( matches  )  [static]

Parameters:
$matches String
Returns:
String

Definition at line 1126 of file Sanitizer.php.

static Sanitizer::normalizeEntity ( name  )  [static]

If the named entity is defined in the HTML 4.0/XHTML 1.0 DTD, return the named entity reference as is.

If the entity is a MediaWiki-specific alias, returns the HTML equivalent. Otherwise, returns HTML-escaped text of pseudo-entity source (eg &foo;)

Parameters:
$name String
Returns:
String

Definition at line 1153 of file Sanitizer.php.

static Sanitizer::normalizeWhitespace ( text  )  [static, private]

Definition at line 1095 of file Sanitizer.php.

static Sanitizer::removeHTMLcomments ( text  )  [static]

Remove '', and everything between.

To avoid leaving blank lines, when a comment is both preceded and followed by a newline (ignoring spaces), trim leading and trailing spaces and one of the newlines.

Access:
private
Parameters:
$text String
Returns:
string

Definition at line 550 of file Sanitizer.php.

static Sanitizer::removeHTMLtags ( text,
processCallback = null,
args = array(),
extratags = array(),
removetags = array() 
) [static]

Cleans up HTML, removes dangerous tags and attributes, and removes HTML comments.

Access:
private
Parameters:
$text String
$processCallback Callback to do any variable or parameter replacements in HTML attribute values
$args Array for the processing callback
$extratags Array for any extra tags to include
$removetags Array for any tags (default or extra) to exclude
Returns:
string

Definition at line 353 of file Sanitizer.php.

Referenced by CoreParserFunctions::displaytitle(), Parser::internalParse(), OutputPage::setPageTitle(), SanitizerTest::testSelfClosingTag(), and Parser::testSrvus().

static Sanitizer::safeEncodeAttribute ( text  )  [static]

Encode an attribute value for HTML tags, with extra armoring against further wiki processing.

Parameters:
$text String
Returns:
HTML-encoded text fragment

Definition at line 879 of file Sanitizer.php.

static Sanitizer::setupAttributeWhitelist (  )  [static]

Foreach array key (an allowed HTML element), return an array of allowed attributes.

Returns:
Array

Definition at line 1284 of file Sanitizer.php.

static Sanitizer::stripAllTags ( text  )  [static]

Take a fragment of (potentially invalid) HTML and return a version with any tags removed, encoded as plain text.

Warning: this return value must be further escaped for literal inclusion in HTML output as of 1.10!

Parameters:
$text String: HTML fragment
Returns:
String

Definition at line 1460 of file Sanitizer.php.

Referenced by CoreParserFunctions::displaytitle(), OutputPage::setPageTitle(), and Parser::stripAltText().

static Sanitizer::validateAttributes ( attribs,
whitelist 
) [static]

Take an array of attribute names and values and normalize or discard illegal values for the given whitelist.

  • Discards attributes not the given whitelist
  • Unsafe style attributes are discarded
  • Invalid id attributes are reencoded

Parameters:
$attribs Array
$whitelist Array: list of allowed attribute names
Returns:
Array
Todo:
Check for legal values where the DTD limits things.

Check for unique id attribute :P

Definition at line 620 of file Sanitizer.php.

static Sanitizer::validateCodepoint ( codepoint  )  [static, private]

Returns true if a given Unicode codepoint is a valid character in XML.

Parameters:
$codepoint Integer
Returns:
Boolean

Definition at line 1187 of file Sanitizer.php.

static Sanitizer::validateTagAttributes ( attribs,
element 
) [static]

Take an array of attribute names and values and normalize or discard illegal values for the given element type.

  • Discards attributes not on a whitelist for the given element
  • Unsafe style attributes are discarded
  • Invalid id attributes are reencoded

Parameters:
$attribs Array
$element String
Returns:
Array
Todo:
Check for legal values where the DTD limits things.

Check for unique id attribute :P

Definition at line 600 of file Sanitizer.php.

Referenced by MathRenderer::_attribs(), CoreTagHooks::pre(), and Parser::renderImageGallery().


The documentation for this class was generated from the following file:

Generated on Sat Apr 30 22:57:48 2011 for MediaWiki by  doxygen 1.5.9