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 |
Please login to continue.