public static function String::format

Formats a string for HTML display by replacing variable placeholders.

This function replaces variable placeholders in a string with the requested values and escapes the values so they can be safely displayed as HTML. It should be used on any unknown text that is intended to be printed to an HTML page (especially text that may have come from untrusted users, since in that case it prevents cross-site scripting and other security problems).

In most cases, you should use t() rather than calling this function directly, since it will translate the text (on non-English-only sites) in addition to formatting it.

Parameters

$string: A string containing placeholders.

$args: An associative array of replacements to make. Occurrences in $string of any key in $args are replaced with the corresponding value, after optional sanitization and formatting. The type of sanitization and formatting depends on the first character of the key:

• @variable: Escaped to HTML using String::checkPlain(). Use this as the default choice for anything displayed on a page on the site.
• %variable: Escaped to HTML and formatted using String::placeholder(), which makes it display as <em>emphasized</em> text.
• !variable: Inserted as is, with no sanitization or formatting. Only use this for text that has already been prepared for HTML display (for example, user-supplied text that has already been run through String::checkPlain() previously, or is expected to contain some limited HTML tags and has already been run through filter_xss() previously).

Return value

mixte The formatted string with placeholders inserted, or FALSE if no args specified.

See also

t()

Related topics

File

drupal/core/lib/Drupal/Component/Utility/String.php, line 89

Contains \Drupal\Component\Utility\String.

Class

String

Provides helpers to operate on strings.

Namespace

Code

public static function format($string, array $args = array()) {

  // Transform arguments before inserting them.
  foreach ($args as $key => $value) {
    switch ($key[0]) {
      case '@':

        // Escaped only.
        $args[$key] = static::checkPlain($value);
        break;
      case '%':
      default:

        // Escaped and placeholder.
        $args[$key] = static::placeholder($value);
        break;
      case '!':
    }
  }
  return strtr($string, $args);
}