1. class
  2. Drupal
  3. \
  4. Component
  5. \
  6. Render
  7. \
  8. FormattableMarkup

FormattableMarkup

class FormattableMarkup implements MarkupInterface, Countable (View source)

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:

Properties

protected string $string

The string containing placeholders.
protected array $arguments

The arguments to replace placeholders with.

Methods

__construct(string $string, array $arguments)

Constructs a new class instance.

string
__toString()

Returns markup.

int
count()

Returns the string length.

string
jsonSerialize()

Returns a representation of the object for use in JSON serialization.

static string
placeholderFormat(string $string, array $args)

Replaces placeholders in a string with values.

static string
placeholderEscape(string|MarkupInterface $value)

Escapes a placeholder replacement value if needed.

Details

at line 90
__construct(string $string, array $arguments)

Constructs a new class instance.

Parameters

string $string

A string containing placeholders. The string itself will not be escaped, any unsafe content must be in $args and inserted via placeholders.
array $arguments

An array with placeholder replacements, keyed by placeholder. See \Drupal\Component\Render\FormattableMarkup::placeholderFormat() for additional information about placeholders.

See also

FormattableMarkup::placeholderFormat

at line 98
string __toString()

Returns markup.

Return Value

string

The markup.

at line 108
int count()

Returns the string length.

Return Value

int

The length of the string.

at line 119
string jsonSerialize()

Returns a representation of the object for use in JSON serialization.

Return Value

string

The safe string content.

at line 196
static protected string placeholderFormat(string $string, array $args)

Replaces placeholders in a string with values.

Parameters

string $string

A string containing placeholders. The string itself is expected to be safe and correct HTML. Any unsafe content must be in $args and inserted via placeholders.
array $args

An associative array of replacements. Each array key should be the same as a placeholder in $string. The corresponding value should be a string or an object that implements \Drupal\Component\Render\MarkupInterface. The value replaces the placeholder in $string. Sanitization and formatting will be done before replacement. The type of sanitization and formatting depends on the first character of the key:

  • @variable: When the placeholder replacement value is:
    • A string, the replaced value in the returned string will be sanitized using \Drupal\Component\Utility\Html::escape().
    • A MarkupInterface object, the replaced value in the returned string will not be sanitized.
    • A MarkupInterface object cast to a string, the replaced value in the returned string be forcibly sanitized using \Drupal\Component\Utility\Html::escape(). @code $this->placeholderFormat('This will force HTML-escaping of the replacement value: @text', ['@text' => (string) $safe_string_interface_object)); @endcode Use this placeholder as the default choice for anything displayed on the site, but not within HTML attributes, JavaScript, or CSS. Doing so is a security risk.
  • %variable: Use when the replacement value is to be wrapped in tags. A call like: @code $string = "%output_text"; $arguments = ['%output_text' => 'text output here.']; $this->placeholderFormat($string, $arguments); @endcode makes the following HTML code: @code text output here. @endcode As with @variable, do not use this within HTML attributes, JavaScript, or CSS. Doing so is a security risk.
  • :variable: Return value is escaped with \Drupal\Component\Utility\Html::escape() and filtered for dangerous protocols using UrlHelper::stripDangerousProtocols(). Use this when using the "href" attribute, ensuring the attribute value is always wrapped in quotes: @code // Secure (with quotes): $this->placeholderFormat('@variable', [':url' => $url, '@variable' => $variable]); // Insecure (without quotes): $this->placeholderFormat('@variable', [':url' => $url, '@variable' => $variable]); @endcode When ":variable" comes from arbitrary user input, the result is secure, but not guaranteed to be a valid URL (which means the resulting output could fail HTML validation). To guarantee a valid URL, use Url::fromUri($user_input)->toString() (which either throws an exception or returns a well-formed URL) before passing the result into a ":variable" placeholder.

Return Value

string

A formatted HTML string with the placeholders replaced.

See also

TranslatableMarkup
PluralTranslatableMarkup
Html::escape
UrlHelper::stripDangerousProtocols
Url::fromUri

at line 261
static protected string placeholderEscape(string|MarkupInterface $value)

Escapes a placeholder replacement value if needed.

Parameters

string|MarkupInterface $value

A placeholder replacement value.

Return Value

string

The properly escaped replacement value.