The HTML a translation value may contain, decided in one place for the shipped files (cleaned in Setup's build with a warning, see ShippedTranslations) and for every local write path (rejected, see findInvalidValues()). More...

Collaboration diagram for ILIAS\Language\ComponentTranslation\TranslationMarkupPolicy:

Private Attributes
const array	ALLOWED_ATTRIBUTES
	tag => allowed attributes (lowercase) More...

const array	URL_SCHEMES
	URL attribute => schemes it may use besides a relative URL. More...

const array	STYLE_PROPERTIES
	CSS properties a `style` attribute may set (lowercase) More...

const array	STYLE_FUNCTIONS = ['rgb', 'rgba', 'hsl', 'hsla']
	CSS functions a value in a `style` attribute may use (lowercase), for colours. More...

const array	OPTIONAL_END_TAGS
	Elements whose end tag HTML5 allows to omit: one left open by a value is valid HTML, no imbalance. More...

const array	SURROUNDING_ELEMENTS
	The elements collectUnbalancedMarkup() puts around a value, outermost first: an end tag in the value closing one of them would close that element of the page. More...

const string	SURROUNDING_MARK = 'data-il-surrounding'
	Marks the surrounding elements with their index in SURROUNDING_ELEMENTS (an attribute no allowed value can carry) and the element after the value (a tag no allowed value contains) More...

const string	END_MARK_TAG = 'il-value-end'

const string	CSS_WHITESPACE = "\t\n\f\r "
	White space in a `style` attribute value and between the parts of a tag. More...

const string	HTML_NAMESPACE = 'http://www.w3.org/1999/xhtml'

Detailed Description

The HTML a translation value may contain, decided in one place for the shipped files (cleaned in Setup's build with a warning, see ShippedTranslations) and for every local write path (rejected, see findInvalidValues()).

Allowed are the tags of ALLOWED_ATTRIBUTES with their listed attributes (names case-insensitive); href/src only with a relative URL (including #...) or a scheme of URL_SCHEMES; style only with declarations of STYLE_PROPERTIES whose values use no function but STYLE_FUNCTIONS (no url(, expression(), no CSS escapes and no comments. An attribute value must not contain "<". Comments, a value ending inside an unfinished tag and unbalanced markup (leaving an element open unless HTML5 allows omitting its end tag, or closing an element around the value in the page, see collectUnbalancedMarkup()) are violations, too. Text that is no tag to an HTML parser (a <= b, <<) stays allowed.

A value with a "<" longer than MAX_CHECKED_LENGTH bytes is not parsed and never allowed.

A value is checked, never rewritten: an allowed value is returned byte-identical by sanitize() (no normalisation of <br>, entities or quoting); only a value with violations is rebuilt.

It is parsed by PHP's HTML5 parser (Dom\HTMLDocument) like a browser, no regular expressions. Such a parser ignores some start tags depending on the context (a <td> outside a table; the attributes of a <body> move to the page's body) and translations are inserted in many places, so the value is parsed twice: as the content of a body (catches <body>/<html> attributes) and of a table (every other start tag becomes an element); what either shows counts. Start tags ignored in both (<head>, <frame>, <frameset> after content, <!DOCTYPE>) are ignored by a browser in a page as well and stay allowed. A third parse inside a chain of surrounding elements checks the balance. Content of raw-text contexts (<textarea>, <script>) is text to a browser and to this check; the enclosing tag is a violation anyway.

Every tree walk is iterative and every parsed tree belongs to a document (see parseInto()), so deeply nested values cannot exhaust the call stack.

HTMLPurifier is deliberately not used: it always re-serialises (an allowed value could not stay byte-identical) and its lexer does not tokenise like a browser (e.g. a > inside a quoted attribute value).

Definition at line 60 of file TranslationMarkupPolicy.php.

Field Documentation

◆ ALLOWED_ATTRIBUTES

const array ILIAS\Language\ComponentTranslation\TranslationMarkupPolicy::ALLOWED_ATTRIBUTES

private

Initial value:

= [
        'a' => ['href', 'target', 'rel', 'title'],
        'b' => [],
        'bdo' => [],
        'br' => [],
        'code' => [],
        'div' => ['align'],
        'em' => [],
        'gap' => [],
        'h3' => [],
        'i' => [],
        'img' => ['src', 'alt'],
        'li' => [],
        'ol' => [],
        'p' => ['align'],
        'pre' => [],
        's' => [],
        'small' => [],
        'span' => ['class', 'style'],
        'strike' => [],
        'strong' => [],
        'sub' => [],
        'sup' => [],
        'u' => [],
        'ul' => [],
    ]

tag => allowed attributes (lowercase)

Definition at line 65 of file TranslationMarkupPolicy.php.

◆ CSS_WHITESPACE

const string ILIAS\Language\ComponentTranslation\TranslationMarkupPolicy::CSS_WHITESPACE = "\t\n\f\r "

private

White space in a style attribute value and between the parts of a tag.

Definition at line 148 of file TranslationMarkupPolicy.php.

◆ END_MARK_TAG

const string ILIAS\Language\ComponentTranslation\TranslationMarkupPolicy::END_MARK_TAG = 'il-value-end'

private

Definition at line 143 of file TranslationMarkupPolicy.php.

◆ HTML_NAMESPACE

const string ILIAS\Language\ComponentTranslation\TranslationMarkupPolicy::HTML_NAMESPACE = 'http://www.w3.org/1999/xhtml'

private

Definition at line 150 of file TranslationMarkupPolicy.php.

◆ OPTIONAL_END_TAGS

const array ILIAS\Language\ComponentTranslation\TranslationMarkupPolicy::OPTIONAL_END_TAGS

private

Initial value:

= [
        'body', 'caption', 'colgroup', 'dd', 'dt', 'head', 'html', 'li', 'optgroup', 'option', 'p', 'rp', 'rt',
        'tbody', 'td', 'tfoot', 'th', 'thead', 'tr',
    ]

Elements whose end tag HTML5 allows to omit: one left open by a value is valid HTML, no imbalance.

Definition at line 120 of file TranslationMarkupPolicy.php.

◆ STYLE_FUNCTIONS

const array ILIAS\Language\ComponentTranslation\TranslationMarkupPolicy::STYLE_FUNCTIONS = ['rgb', 'rgba', 'hsl', 'hsla']

private

CSS functions a value in a style attribute may use (lowercase), for colours.

Definition at line 115 of file TranslationMarkupPolicy.php.

◆ STYLE_PROPERTIES

const array ILIAS\Language\ComponentTranslation\TranslationMarkupPolicy::STYLE_PROPERTIES

private

Initial value:

= [
        'background-color',
        'color',
        'font-style',
        'font-weight',
        'text-align',
        'text-decoration',
    ]

CSS properties a style attribute may set (lowercase)

Definition at line 103 of file TranslationMarkupPolicy.php.

◆ SURROUNDING_ELEMENTS

const array ILIAS\Language\ComponentTranslation\TranslationMarkupPolicy::SURROUNDING_ELEMENTS

private

Initial value:

= [
        'table', 'tbody', 'tr', 'td', 'div', 'ol', 'li', 'ul', 'li', 'h3', 'pre',
        'span', 'b', 'i', 'u', 's', 'strike', 'strong', 'em', 'small', 'sub', 'sup', 'code', 'bdo', 'gap',
    ]

The elements collectUnbalancedMarkup() puts around a value, outermost first: an end tag in the value closing one of them would close that element of the page.

Table and block elements first, then <pre> (a bare <li> in the value stops there instead of closing the surrounding <li>), then inline elements. Without <p> (every block start tag of the value would close it) and <a> (every link would close it): a stray </p> or </a> is not detected. End tags of disallowed tags are reported by collectEndTagsOfDisallowedTags().

Definition at line 133 of file TranslationMarkupPolicy.php.

◆ SURROUNDING_MARK

const string ILIAS\Language\ComponentTranslation\TranslationMarkupPolicy::SURROUNDING_MARK = 'data-il-surrounding'

private

Marks the surrounding elements with their index in SURROUNDING_ELEMENTS (an attribute no allowed value can carry) and the element after the value (a tag no allowed value contains)

Definition at line 142 of file TranslationMarkupPolicy.php.

◆ URL_SCHEMES

const array ILIAS\Language\ComponentTranslation\TranslationMarkupPolicy::URL_SCHEMES

private

Initial value:

= [
        'href' => ['http', 'https', 'mailto'],
        'src' => ['http', 'https'],
    ]

URL attribute => schemes it may use besides a relative URL.

Definition at line 95 of file TranslationMarkupPolicy.php.

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

components/ILIAS/Language/src/ComponentTranslation/TranslationMarkupPolicy.php

Private Attributes

Detailed Description

Field Documentation

◆ ALLOWED_ATTRIBUTES

◆ CSS_WHITESPACE

◆ END_MARK_TAG

◆ HTML_NAMESPACE

◆ OPTIONAL_END_TAGS

◆ STYLE_FUNCTIONS

◆ STYLE_PROPERTIES

◆ SURROUNDING_ELEMENTS

◆ SURROUNDING_MARK

◆ URL_SCHEMES