文字列整形用関数 format_string() t() st() とそのキーの接頭辞による効果まとめ

こんにちは。社内で「脱・大野」と言うスローガンで大野に頼らずに仕事を進められるようにする動きがあって皆の成長を感じる一方でちょっぴり寂しい大野です。

さて今回は Drupal 内で文字列を処理する関数についてまとめてみたいと思います。自分でも記憶が曖昧でいざ使う時にその都度調べ直したりしているので備忘録としてまとめてみました。

文字列関数とその種類

Drupal ではテキストを整形処理するための関数が3つ存在しますが、普段よく目にするのは t() 関数です。これはほぼ全てのコア・コントリビュートモジュールで標準的に使われているのでモジュールのソースコードに触れたことがある方なら見たことがある関数だと思います。この関数は Drupal の翻訳システムを利用するために使う関数ですが詳しい解説は後述します。その他にも単純な文字列の整形だけを行う format_string() 関数やモジュールインストール時のみに使う st() 関数が用意されています。

この3つの関数のパラメーターはほぼ同一で同じように利用することができます。format_string() を例に基本的な使い方を見てみましょう。 Drupal 7 の format_string() のパラメーターは以下の様に定義されています。

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

• $string: 表示したい文字列を代入します。文字列内に置換用のキーを含むことで第二パラメーターの内容で文字列を置換することができます。
• $args: 置換キーと置換内容がペアになった配列を代入します。キーの接頭辞によって文字列をフィルター処理することができます。

簡単に言うと $args の配列に代入されたキーが $string 内にあればキーの値で文字列の置換を行なってくれると言うことです。

$args で使用される接頭辞の種類

$args に代入する配列のサンプルを以下に示します。

$args = array(
  '@replacement1' => '置換内容',
  '%replacement2' => '置換内容',
  '!replacement3' => '置換内容',
);

配列のキーの接頭辞に @ や % 、 ! などの記号が含まれていますね。Drupal ではこのキーの接頭辞に応じて置換内容の文字列にフィルターを掛けることができるようになっています。以下に接頭辞の違いを解説します。

キーの接頭辞: @

HTMLで使用される特殊記号を check_plain() 関数を利用してエスケープ処理します。ユーザーが入力した値を直接表示する様なケースに利用します。

<?php
$text = 'I love <strong>Drupal</strong>';
print format_string('<p>Result: @replacement</p>', array('@replacement' => $text));

出力されるHTML:

<p>Result: I love &lt;strong&gt;Drupal&lt;/strong&gt;</p>;

$text 内の HTML がエスケープ処理されていることに注目してください。

キーの接頭辞: %

@ 接頭辞と同様にHTMLの特殊記号をエスケープし、尚且つ対象の文字列をプレースホルダーとして扱います。 drupal_placeholder() 関数によって <em> タグで囲って置換されます。ユーザーが入力した値が何であったかを明確に表示したい時に利用するといいでしょう。

<?php
$text = 'I love <strong>Drupal</strong>';
print format_string('<p>Result: %replacement</p>', array('@replacement' => $text));

出力されるHTML:

<p>Result: <em>I love &lt;strong&gt;Drupal&lt;/strong&gt;</em></p>;

$text 内の HTML がエスケープされて <em> タグでマークアップされています。

キーの接頭辞: !

与えられた値をそのまま表示します。任意の HTML を扱いたい場合や l() 関数などで予めサニタイズされていることが解っている値を使用する場合に利用します。

<?php
$text = 'I love <strong>Drupal</strong>';
print format_string('<p>Result: %replacement</p>', array('@replacement' => $text));

出力されるHTML:

<p>Result: I love <strong>Drupal</strong></p>;

$text 内のタグが何も処理されずに出力されています。

文字列を整形するための3つの関数

冒頭でも述べましたが Drupal には文字列を整形処理するための関数が3つ、 format_string() と t(), st() が存在します。以下にその違いを見てみましょう。

format_string() 関数

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

上記のパラメーターの解説でも登場した関数で、単純に文字列内の特定のキーだけ安全に置換したい場合に利用する Drupal のユーティリティ関数です。PHP の sprintf() を文字列の置換に特化したイメージでしょうか。

Drupal API - function format_string

t() 関数

t($string, array $args = array(), array $options = array())

基本的な諸動作は format_string() と同様ですが、 第一パラメーターの文字列は翻訳の対象となります。 Drupal では翻訳システムの基礎言語が英語になっているため、ここに代入するテキストは英語である必要があります。

format_string() とは違い第三パラメーターが存在し、翻訳に関するオプションを設定します。詳しくは t() のページを御覧ください。

最終的な戻り値は format_string() 関数を介して出力されるので、翻訳対応版の format_string() と思って良いでしょう。また、第一引数で扱われる文字列はデータベースを利用するためインストール時には使用することができません。

英語以外のテキストを扱う場合や翻訳の必要がない文字列は format_string() を利用してください。

Drupal API - function t

st() 関数

st($string, array $args = array(), array $options = array())

機能は t() 関数とほぼ同じですが、インストール時にのみ利用する関数です。 Drupal はこの関数を利用した場合、翻訳データをデータベースからではなく翻訳ファイルから探しにいきます。

考えてみると当たり前のことなのですが Drupal のインストール前はデータベースやテーマ、翻訳システムが作動していないため、データベースから翻訳データを検索することができません。そのためこの様なファイルから翻訳データを取り扱うための関数が用意されています。また、その理由からここで扱われる文字列は翻訳の管理画面から編集することもできません。

Drupal API - function st

get_t() 関数

この関数は文字列を処理するための関数ではありませんが、上記の2つの t() と st() 関数に関係があるのでご紹介します。

インストール時とインストール後の両方で同一の翻訳が必要な場合に t もしくは st の適切な関数名を返します。

Drupal API - function get_t にも書かれていますが、以下の様な使い方をします。

// $t にはその時に利用できる翻訳関数名 t または st の値が入る
$t = get_t();
$translated = $t('translate this');

いかがでしたでしょうか。

一般的なウェブシステムではユーザーからの入力に対し一部だけテキストを変更して表示することが多々あるかと思いますが、これらの仕組みを上手く使うことでクリーンなコードで簡単にテキストをサニタイズすることができます。その一方で適切な置換キーの接頭辞が設定されていない場合は、ユーザーからの不正な入力を受け付けてしまうことになってしまうので注意して利用しましょう。