データフォーマット ¶

ユーザーにとってより読みやすい形式でデータを表示するには、formatter アプリケーションコンポーネント を使用してフォーマットできます。デフォルトでは、フォーマッタは yii\i18n\Formatter によって実装されており、日付/時刻、数値、通貨、およびその他一般的に使用される形式としてデータをフォーマットするための一連のメソッドが提供されています。次のようにフォーマッタを使用できます。

$formatter = \Yii::$app->formatter;

// output: January 1, 2014
echo $formatter->asDate('2014-01-01', 'long');
 
// output: 12.50%
echo $formatter->asPercent(0.125, 2);
 
// output: <a href="mailto:cebe@example.com">cebe@example.com</a>
echo $formatter->asEmail('cebe@example.com'); 

// output: Yes
echo $formatter->asBoolean(true); 
// it also handles display of null values:

// output: (not set)
echo $formatter->asDate(null); 

ご覧のとおり、これらのメソッドはすべて asXyz() という名前で、Xyz はサポートされている形式を表します。または、ジェネリックメソッド format() を使用してデータをフォーマットすることもできます。これにより、プログラムで目的の形式を制御でき、yii\grid\GridView や yii\widgets\DetailView などのウィジェットで一般的に使用されます。たとえば、次のようになります。

// output: January 1, 2014
echo Yii::$app->formatter->format('2014-01-01', 'date'); 

// you can also use an array to specify parameters for the format method:
// `2` is the value for the $decimals parameter of the asPercent()-method.
// output: 12.50%
echo Yii::$app->formatter->format(0.125, ['percent', 2]); 

注意：フォーマッターコンポーネントは、エンドユーザーに表示するために値をフォーマットするように設計されています。ユーザー入力を機械可読な形式に変換したい場合、または機械可読な形式で日付をフォーマットしたい場合は、フォーマッターは適切なツールではありません。日付および数値のユーザー入力を変換するには、それぞれ yii\validators\DateValidator および yii\validators\NumberValidator を使用できます。機械可読な日付と時刻の形式間の単純な変換には、PHP の date() 関数で十分です。

フォーマッターの設定 ¶

アプリケーション構成で formatter コンポーネントを設定することにより、フォーマットルールをカスタマイズできます。例：

return [
    'components' => [
        'formatter' => [
            'dateFormat' => 'dd.MM.yyyy',
            'decimalSeparator' => ',',
            'thousandSeparator' => ' ',
            'currencyCode' => 'EUR',
       ],
    ],
];

構成できるプロパティについては、yii\i18n\Formatter を参照してください。

日付と時刻の値のフォーマット ¶

フォーマッターは、日付と時刻に関連する次の出力形式をサポートしています。

• date: 値が日付としてフォーマットされます。例: 2014年1月1日。
• time: 値が時刻としてフォーマットされます。例: 14:23。
• datetime: 値が日付と時刻としてフォーマットされます。例: 2014年1月1日 14:23。
• timestamp: 値が UNIX タイムスタンプとしてフォーマットされます。例: 1412609982。
• relativeTime: 値が、日付と現在時刻の間の時間間隔を人間が読める形式でフォーマットされます。例: 1時間前。
• duration: 値が人間が読める形式で期間としてフォーマットされます。例: 1日、2分。

date、time、および datetime メソッドで使用されるデフォルトの日付および時刻形式は、グローバルにカスタマイズできます。
dateFormat、timeFormat、および datetimeFormat を構成します。

日付と時刻の形式は、ICU 構文を使用して指定できます。また、PHP date() 構文にプレフィックス php: を付けて、ICU 構文と区別することもできます。例：

// ICU format
echo Yii::$app->formatter->asDate('now', 'yyyy-MM-dd'); // 2014-10-06

// PHP date()-format
echo Yii::$app->formatter->asDate('now', 'php:Y-m-d'); // 2014-10-06

情報： PHP の形式構文の一部の文字は ICU ではサポートされていないため、PHP intl 拡張機能と Yii フォーマッターでは使用できません。これらのほとんど（w、t、L、B、u、I、Z）は、日付をフォーマットするためではなく、日付計算を行うときに使用されます。ただし、S と U は役立つ場合があります。これらの動作は、次のようにすることで実現できます。

• S（月の日の英語の序数接尾辞（例：st、nd、rd、または th））の場合、次の置換を使用できます。

  $f = Yii::$app->formatter;
  $d = $f->asOrdinal($f->asDate('2017-05-15', 'php:j'));
  echo "On the $d day of the month.";  // prints "On the 15th day of the month."
  

• U（UNIX エポック）の場合、timestamp 形式を使用できます。

複数の言語をサポートする必要があるアプリケーションを操作する場合、ロケールごとに異なる日付と時刻の形式を指定する必要があることがよくあります。このタスクを簡略化するために、形式ショートカット（例：long、short）を使用できます。フォーマッターは、現在アクティブな ロケールに応じて、形式ショートカットを適切な形式に変換します。次の形式ショートカットがサポートされています（例では、en_GB がアクティブなロケールであると仮定します）。

• short: 日付の場合は 2014/10/06、時刻の場合は 15:58 が出力されます。
• medium: 2014年10月6日 と 15:58:42 が出力されます。
• long: 2014年10月6日 と 15:58:42 GMT が出力されます。
• full: 2014年10月6日 月曜日 と 15:58:42 GMT が出力されます。

バージョン 2.0.7 以降では、異なるカレンダーシステムで日付をフォーマットすることもできます。異なるカレンダーを設定する方法については、フォーマッターの $calendar プロパティの API ドキュメントを参照してください。

タイムゾーン ¶

日付と時刻の値をフォーマットするとき、Yii はそれらをターゲットの タイムゾーンに変換します。フォーマットされる値は、タイムゾーンが明示的に指定されている場合、または yii\i18n\Formatter::$defaultTimeZone が設定されている場合を除き、UTC であると見なされます。

次の例では、ターゲットの タイムゾーンが Europe/Berlin に設定されていると仮定します。

// formatting a UNIX timestamp as a time
echo Yii::$app->formatter->asTime(1412599260); // 14:41:00

// formatting a datetime string (in UTC) as a time 
echo Yii::$app->formatter->asTime('2014-10-06 12:41:00'); // 14:41:00

// formatting a datetime string (in CEST) as a time
echo Yii::$app->formatter->asTime('2014-10-06 14:41:00 CEST'); // 14:41:00

フォーマッターコンポーネントに タイムゾーンが明示的に設定されていない場合、アプリケーションで構成されたタイムゾーンが使用されます。これは、PHP 構成で設定されたタイムゾーンと同じです。

注意：タイムゾーンは世界中の政府によって作成された規則に従うため、頻繁に変更される可能性があります。システムにインストールされているタイムゾーンデータベースに最新情報がない可能性があります。タイムゾーンデータベースの更新の詳細については、ICU マニュアルを参照してください。国際化のために PHP 環境をセットアップするも参照してください。

数値のフォーマット ¶

フォーマッターは、数値に関連する次の出力形式をサポートしています。

• integer: 値が整数としてフォーマットされます。例: 42。
• decimal: 値が、小数点区切り文字と桁区切り文字を考慮した小数点数としてフォーマットされます。例: 2,542.123 または 2.542,123。
• percent: 値がパーセント数値としてフォーマットされます。例: 42%。
• scientific: 値が科学的な形式でフォーマットされます。例: 4.2E4。
• currency: 値が通貨値としてフォーマットされます。例: £420.00。この関数が適切に機能するためには、ロケールに国の一部が含まれている必要があります。例: en_GB または en_US。言語のみではこの場合あいまいになるためです。
• size: バイト数である値が、人間が読めるサイズとしてフォーマットされます。例: 410 キビバイト。
• shortSize: size の短いバージョンです。例: 410 KiB。

数値フォーマットの形式は、decimalSeparator と thousandSeparator を使用して調整できます。どちらも、アクティブな ロケールに従ってデフォルト値が設定されます。

より高度な構成については、yii\i18n\Formatter::$numberFormatterOptions と yii\i18n\Formatter::$numberFormatterTextOptions を使用して、フォーマッターを実装するために内部で使用される NumberFormatter クラスを構成できます。たとえば、小数部の最大値と最小値を調整するには、次のように yii\i18n\Formatter::$numberFormatterOptions プロパティを構成できます。

'numberFormatterOptions' => [
    NumberFormatter::MIN_FRACTION_DIGITS => 0,
    NumberFormatter::MAX_FRACTION_DIGITS => 2,
]

その他の形式 ¶

Yii は、日付/時刻および数値の形式に加えて、次のような一般的に使用される形式もサポートしています。

• raw: 値はそのまま出力されます。これは、null 値が nullDisplay を使用してフォーマットされることを除き、効果のない疑似フォーマッターです。
• text: 値は HTML エンコードされます。これは、GridView DataColumn で使用されるデフォルトの形式です。
• ntext: 値は、改行が改行に変換された HTML エンコードされたプレーンテキストとしてフォーマットされます。
• paragraphs: 値は、<p> タグで囲まれた HTML エンコードされたテキスト段落としてフォーマットされます。
• html: 値は、XSS 攻撃を避けるために HtmlPurifier を使用して浄化されます。['html', ['Attr.AllowedFrameTargets' => ['_blank']]] などの追加オプションを渡すことができます。
• email: 値は mailto リンクとしてフォーマットされます。
• image: 値は画像タグとしてフォーマットされます。
• url: 値はハイパーリンクとしてフォーマットされます。
• boolean: 値はブール値としてフォーマットされます。デフォルトでは、true は はい、false は いいえ としてレンダリングされ、現在のアプリケーション言語に翻訳されます。これは、yii\i18n\Formatter::$booleanFormat プロパティを構成することで調整できます。

Null 値 ¶

null 値は特別にフォーマットされます。フォーマッターは空の文字列を表示する代わりに、プリセットされた文字列に変換します。デフォルトでは、現在のアプリケーション言語に翻訳された (設定されていません) になります。この文字列をカスタマイズするには、nullDisplay プロパティを構成できます。

データ形式のローカライズ ¶

前述のように、フォーマッターは現在アクティブな ロケールを使用して、ターゲットの国/地域で適切な値をフォーマットする方法を決定できます。たとえば、同じ日付の値でも、ロケールが異なれば異なる形式でフォーマットされる可能性があります。

Yii::$app->formatter->locale = 'en-US';
echo Yii::$app->formatter->asDate('2014-01-01'); // output: January 1, 2014

Yii::$app->formatter->locale = 'de-DE';
echo Yii::$app->formatter->asDate('2014-01-01'); // output: 1. Januar 2014

Yii::$app->formatter->locale = 'ru-RU';
echo Yii::$app->formatter->asDate('2014-01-01'); // output: 1 января 2014 г.

デフォルトでは、現在アクティブな ロケールは、yii\base\Application::$language の値によって決定されます。明示的に yii\i18n\Formatter::$locale プロパティを設定することで、これを上書きできます。

注意：Yii フォーマッターは、ローカライズされたデータ形式をサポートするために PHP intl 拡張機能に依存しています。PHP でコンパイルされた ICU ライブラリのバージョンが異なると、フォーマット結果が異なる可能性があるため、すべての環境で同じ ICU バージョンを使用することをお勧めします。詳細については、国際化のために PHP 環境をセットアップするを参照してください。

intl 拡張機能がインストールされていない場合、データはローカライズされません。

1901 年より前または 2038 年以降の日付値については、intl 拡張機能がインストールされていても、32 ビットシステムではローカライズされないことに注意してください。これは、この場合、ICU が 32 ビットの UNIX タイムスタンプを日付値に使用するためです。