function format_string

You are here

7 bootstrap.inc format_string($string, array $args = array())
8 bootstrap.inc format_string($string, array $args = array())

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

237 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 1527
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 '!':
        // Pass-through.
    }
  }
  return strtr($string, $args);
}

Comments

Why not use an example?

Example how to use this to sanitize data from $_GET (in my case exposed filter values).

$dates = array('@min' => $_GET['date']['min']['date'], '@max' => $_GET['date']['min']['date']);
print format_string('Selected date range: @min to @max', $dates);

For the record: it was introduced in version 7.8: see Change notice

This function does not exist in 7.8. It is introduced in 7.9
http://drupal.org/node/1342480

See the release notes for Drupal 7.9: https://drupal.org/node/1322736

PHP 5.3.6-13ubuntu3.9 with Suhosin-Patch (cli) (built: Sep 12 2012 19:00:27)

!variables treated as "%/default". It seems that PHP checks each 'case' condition sequentially and as soon as its hits 'default' it does not go to '!'

Corrected version:

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 '!':
         // Pass-through.
         break;

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