function format_string

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 check_plain(). Use this as the default choice for anything displayed on a page on the site.
• %variable: Escaped to HTML and formatted using backdrop_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 check_plain() previously, or is expected to contain some limited HTML tags and has already been run through filter_xss() previously).

Return value

string: The provided string with the replacements made from the $args array.

See also

t()

Related topics

File

core/includes/bootstrap.inc, line 2125

Functions that need to be loaded on every Backdrop request.

Code

function format_string($string, array $args = array()) {
  // Transform arguments before inserting them.
  foreach ($args as $key => $value) {
    switch (substr($key, 0, 1)) {
      case '@':
        // Escaped only.
        $args[$key] = check_plain($value);
        break;

      case '%':
      default:
        // Escaped and placeholder.
        $args[$key] = backdrop_placeholder($value);
        break;

      case '!':
        // Pass-through.
    }
  }
  return strtr($string, $args);
}