Same name and namespace in other branches
  1. 8.9.x core/lib/Drupal/Component/Render/FormattableMarkup.php \Drupal\Component\Render\FormattableMarkup
  2. 9 core/lib/Drupal/Component/Render/FormattableMarkup.php \Drupal\Component\Render\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 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

Expanded class hierarchy of FormattableMarkup

See also

\Drupal\Core\StringTranslation\TranslatableMarkup

\Drupal\Core\StringTranslation\PluralTranslatableMarkup

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

97 files declare their use of FormattableMarkup
AssertContentTrait.php in core/tests/Drupal/KernelTests/AssertContentTrait.php
AssertMailTrait.php in core/lib/Drupal/Core/Test/AssertMailTrait.php
BanMiddleware.php in core/modules/ban/src/BanMiddleware.php
BookJavascriptTest.php in core/modules/book/tests/src/FunctionalJavascript/BookJavascriptTest.php
BrokenHandlerTrait.php in core/modules/views/src/Plugin/views/BrokenHandlerTrait.php

... See full list

File

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

Namespace

Drupal\Component\Render
View source
class FormattableMarkup implements MarkupInterface, \Countable {

  /**
   * The string containing placeholders.
   *
   * @var string
   */
  protected $string;

  /**
   * The arguments to replace placeholders with.
   *
   * @var array
   */
  protected $arguments = [];

  /**
   * Constructs a new class instance.
   *
   * @param string $string
   *   A string containing placeholders. The string itself will not be escaped,
   *   any unsafe content must be in $args and inserted via placeholders.
   * @param array $arguments
   *   An array with placeholder replacements, keyed by placeholder. See
   *   \Drupal\Component\Render\FormattableMarkup::placeholderFormat() for
   *   additional information about placeholders.
   *
   * @see \Drupal\Component\Render\FormattableMarkup::placeholderFormat()
   */
  public function __construct($string, array $arguments) {
    $this->string = (string) $string;
    $this->arguments = $arguments;
  }

  /**
   * {@inheritdoc}
   */
  public function __toString() {
    return static::placeholderFormat($this->string, $this->arguments);
  }

  /**
   * Returns the string length.
   *
   * @return int
   *   The length of the string.
   */

  #[\ReturnTypeWillChange]
  public function count() {
    return mb_strlen($this->string);
  }

  /**
   * Returns a representation of the object for use in JSON serialization.
   *
   * @return string
   *   The safe string content.
   */

  #[\ReturnTypeWillChange]
  public function jsonSerialize() {
    return $this
      ->__toString();
  }

  /**
   * Replaces placeholders in a string with values.
   *
   * @param 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.
   * @param 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.
   *   Null args[] values are deprecated in Drupal 9.5 and will fail in
   *   Drupal 11.0. 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 <em>
   *     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
   *       <em class="placeholder">text output here.</em>
   *     @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('<a href=":url">@variable</a>', [':url' => $url, '@variable' => $variable]);
   *     // Insecure (without quotes):
   *     $this->placeholderFormat('<a href=:url>@variable</a>', [':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 string
   *   A formatted HTML string with the placeholders replaced.
   *
   * @ingroup sanitization
   *
   * @see \Drupal\Core\StringTranslation\TranslatableMarkup
   * @see \Drupal\Core\StringTranslation\PluralTranslatableMarkup
   * @see \Drupal\Component\Utility\Html::escape()
   * @see \Drupal\Component\Utility\UrlHelper::stripDangerousProtocols()
   * @see \Drupal\Core\Url::fromUri()
   */
  protected static function placeholderFormat($string, array $args) {

    // Transform arguments before inserting them.
    foreach ($args as $key => $value) {
      if (is_null($value)) {

        // It's probably a bug to provide a null value for the placeholder arg,
        // and in D11 this will no longer be allowed. When this trigger_error
        // is removed, also remove isset $value checks inside the switch{}
        // below.
        // phpcs:ignore Drupal.Semantics.FunctionTriggerError
        @trigger_error(sprintf('Deprecated NULL placeholder value for key (%s) in: "%s". This will throw a PHP error in drupal:11.0.0. See https://www.drupal.org/node/3318826', (string) $key, (string) $string), E_USER_DEPRECATED);
        $value = '';
      }
      switch ($key[0]) {
        case '@':

          // Escape if the value is not an object from a class that implements
          // \Drupal\Component\Render\MarkupInterface, for example strings will
          // be escaped.
          // Strings that are safe within HTML fragments, but not within other
          // contexts, may still be an instance of
          // \Drupal\Component\Render\MarkupInterface, so this placeholder type
          // must not be used within HTML attributes, JavaScript, or CSS.
          $args[$key] = static::placeholderEscape($value);
          break;
        case ':':

          // Strip URL protocols that can be XSS vectors.
          $value = UrlHelper::stripDangerousProtocols($value);

          // Escape unconditionally, without checking whether the value is an
          // instance of \Drupal\Component\Render\MarkupInterface. This forces
          // characters that are unsafe for use in an "href" HTML attribute to
          // be encoded. If a caller wants to pass a value that is extracted
          // from HTML and therefore is already HTML encoded, it must invoke
          // \Drupal\Component\Render\OutputStrategyInterface::renderFromHtml()
          // on it prior to passing it in as a placeholder value of this type.
          // @todo Add some advice and stronger warnings.
          //   https://www.drupal.org/node/2569041.
          $args[$key] = Html::escape($value);
          break;
        case '%':

          // Similarly to @, escape non-safe values. Also, add wrapping markup
          // in order to render as a placeholder. Not for use within attributes,
          // per the warning above about
          // \Drupal\Component\Render\MarkupInterface and also due to the
          // wrapping markup.
          $args[$key] = '<em class="placeholder">' . static::placeholderEscape($value) . '</em>';
          break;
        default:
          if (!ctype_alnum($key[0])) {

            // Warn for random placeholders that won't be replaced.
            trigger_error(sprintf('Placeholders must begin with one of the following "@", ":" or "%%", invalid placeholder (%s) with string: "%s"', $key, $string), E_USER_WARNING);
          }

          // No replacement possible therefore we can discard the argument.
          unset($args[$key]);
          break;
      }
    }
    return strtr($string, $args);
  }

  /**
   * Escapes a placeholder replacement value if needed.
   *
   * @param string|\Drupal\Component\Render\MarkupInterface $value
   *   A placeholder replacement value.
   *
   * @return string
   *   The properly escaped replacement value.
   */
  protected static function placeholderEscape($value) {
    return $value instanceof MarkupInterface ? (string) $value : Html::escape($value);
  }

}

Members

Namesort descending Modifiers Type Description Overrides
FormattableMarkup::$arguments protected property The arguments to replace placeholders with.
FormattableMarkup::$string protected property The string containing placeholders.
FormattableMarkup::count public function 1
FormattableMarkup::jsonSerialize public function
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. 1
FormattableMarkup::__toString public function Returns markup. Overrides MarkupInterface::__toString