function format_string in Drupal 7

Same name and namespace in other branches

1. 8 core/includes/bootstrap.inc \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 drupal_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).

See also

t()

Related topics

256 calls to format_string()

AggregatorConfigurationTestCase::testSettingsPage in modules/aggregator/aggregator.test

Tests the settings form to ensure the correct default values are used.

AggregatorRenderingTestCase::testBlockLinks in modules/aggregator/aggregator.test

Adds a feed block to the page and checks its links.

AggregatorTestCase::createFeed in modules/aggregator/aggregator.test

Creates an aggregator feed.

AggregatorTestCase::updateFeedItems in modules/aggregator/aggregator.test

Updates the feed items.

BlockTestCase::moveBlockToRegion in modules/block/block.test

... See full list

1 string reference to 'format_string'

CommonXssUnitTest::testFormatStringAndT in modules/simpletest/tests/common.test

Test t() and format_string() replacement functionality.

File

includes/bootstrap.inc, line 1818

Functions that need to be loaded on every Drupal request.

Code

function format_string($string, array $args = array()) {

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

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

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