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

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

© 2001–2016 by the original authors
Licensed under the GNU General Public License, version 2 and later.
Drupal is a registered trademark of Dries Buytaert.
https://api.drupal.org/api/drupal/core!lib!Drupal!Component!Render!FormattableMarkup.php/class/FormattableMarkup/8.1.x