class FormattableMarkup

Formats a string for HTML display by replacing variable placeholders.

When cast to a string, this object replaces variable placeholders in the string with the arguments passed in during construction and escapes the values so they can be safely displayed as HTML. See the documentation of \Drupal\Component\Render\FormattableMarkup::placeholderFormat() for details on the supported placeholders and how to use them securely. Incorrect use of this class can result in security vulnerabilities.

In most cases, you should use TranslatableMarkup or PluralTranslatableMarkup rather than this object, since they will translate the text (on non-English-only sites) in addition to formatting it. Variables concatenated without the insertion of language-specific words or punctuation are some examples where translation is not applicable and using this class directly directly is appropriate.

This class is designed for formatting messages that are mostly text, not as an HTML template language. As such:

• The passed in string should contain no (or minimal) HTML.
• Variable placeholders should not be used within the "<" and ">" of an HTML tag, such as in HTML attribute values. This would be a security risk. Examples:

    // Insecure (placeholder within "<" and ">"):
    $this->placeholderFormat('<@variable>text</@variable>', ['@variable' => $variable]);
    // Insecure (placeholder within "<" and ">"):
    $this->placeholderFormat('<a @variable>link text</a>', ['@variable' => $variable]);
    // Insecure (placeholder within "<" and ">"):
    $this->placeholderFormat('<a title="@variable">link text</a>', ['@variable' => $variable]);
  

Only the "href" attribute is supported via the special ":variable" placeholder, to allow simple links to be inserted:

    // Secure (usage of ":variable" placeholder for href attribute):
    $this->placeholderFormat('<a href=":variable">link text</a>', [':variable' , $variable]);
    // Secure (usage of ":variable" placeholder for href attribute):
    $this->placeholderFormat('<a href=":variable" title="static text">link text</a>', [':variable' => $variable]);
    // Insecure (the "@variable" placeholder does not filter dangerous
    // protocols):
    $this->placeholderFormat('<a href="@variable">link text</a>', ['@variable' => $variable]);
    // Insecure ("@variable" placeholder within "<" and ">"):
    $this->placeholderFormat('<a href=":url" title="@variable">link text</a>', [':url' => $url, '@variable' => $variable]);
  

To build non-minimal HTML, use an HTML template language such as Twig, rather than this class.

Hierarchy

• class \Drupal\Component\Render\FormattableMarkup implements \Countable, MarkupInterface

See also

\Drupal\Core\StringTranslation\TranslatableMarkup

\Drupal\Core\StringTranslation\PluralTranslatableMarkup

\Drupal\Component\Render\FormattableMarkup::placeholderFormat()

Related topics

Sanitization functions

Functions to sanitize values.

File

core/lib/Drupal/Component/Render/FormattableMarkup.php, line 62

Namespace

Drupal\Component\Render

Members

Name	Modifiers	Type	Description
FormattableMarkup::$arguments	protected	property	The arguments to replace placeholders with.
FormattableMarkup::count	public	function	Returns the string length.
FormattableMarkup::jsonSerialize	public	function	Returns a representation of the object for use in JSON serialization.
FormattableMarkup::placeholderEscape	protected static	function	Escapes a placeholder replacement value if needed.
FormattableMarkup::placeholderFormat	protected static	function	Replaces placeholders in a string with values.
FormattableMarkup::__construct	public	function	Constructs a new class instance.
FormattableMarkup::__toString	public	function	Returns markup. Overrides MarkupInterface::__toString