class FormattableMarkup

Same name in other branches
  1. 9 core/lib/Drupal/Component/Render/FormattableMarkup.php \Drupal\Component\Render\FormattableMarkup
  2. 10 core/lib/Drupal/Component/Render/FormattableMarkup.php \Drupal\Component\Render\FormattableMarkup
  3. 11.x 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 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()

Related topics

312 files declare their use of FormattableMarkup
AccessDeniedTest.php in core/modules/system/tests/src/Functional/System/AccessDeniedTest.php
AggregatorAdminTest.php in core/modules/aggregator/tests/src/Functional/AggregatorAdminTest.php
AggregatorRenderingTest.php in core/modules/aggregator/tests/src/Functional/AggregatorRenderingTest.php
AggregatorTestBase.php in core/modules/aggregator/src/Tests/AggregatorTestBase.php
AggregatorTestBase.php in core/modules/aggregator/tests/src/Functional/AggregatorTestBase.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.
     */
    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.
     */
    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. 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) {
            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:
                    // We do not trigger an error for placeholder that start with an
                    // alphabetic character.
                    // @todo https://www.drupal.org/node/2807743 Change to an exception
                    //   and always throw regardless of the first character.
                    if (!ctype_alpha($key[0])) {
                        // We trigger an error as we may want to introduce new placeholders
                        // in the future without breaking backward compatibility.
                        trigger_error('Invalid placeholder (' . $key . ') in string: ' . $string, E_USER_ERROR);
                    }
                    elseif (strpos($string, $key) !== FALSE) {
                        trigger_error('Invalid placeholder (' . $key . ') in string: ' . $string, E_USER_DEPRECATED);
                    }
                    // 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

Title Sort descending Modifiers Object type Summary Overriden Title Overrides
FormattableMarkup::$arguments protected property The arguments to replace placeholders with.
FormattableMarkup::$string protected property The string containing placeholders.
FormattableMarkup::count public function Returns the string length. 1
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. 1
FormattableMarkup::__toString public function Returns markup. Overrides MarkupInterface::__toString

Buggy or inaccurate documentation? Please file an issue. Need support? Need help programming? Connect with the Drupal community.