ユーザにとってより読みやすい形式でデータを表示するために、formatter
アプリケーション・コンポーネント
を使ってデータをフォーマットすることが出来ます。デフォルトでは、フォーマッタは yii\i18n\Formatter によって実装されており、
これが、日付/時刻、数字、通貨、その他のよく使われる形式にデータをフォーマットする一連のメソッドを提供します。このフォーマッタは次のようにして使うことが出来ます。
$formatter = \Yii::$app->formatter;
// 出力: January 1, 2014
echo $formatter->asDate('2014-01-01', 'long');
// 出力: 12.50%
echo $formatter->asPercent(0.125, 2);
// 出力: <a href="mailto:cebe@example.com">cebe@example.com</a>
echo $formatter->asEmail('cebe@example.com');
// 出力: Yes
echo $formatter->asBoolean(true);
// it also handles display of null values:
// 出力: (not set)
echo $formatter->asDate(null);
ご覧のように、これらのメソッドは全て asXyz()
という名前を付けられており、Xyz
がサポートされている形式を表しています。
別の方法として、汎用メソッド format() を使ってデータをフォーマットすることも出来ます。
この方法を使うと望む形式をプログラム的に制御することが可能になりますので、yii\grid\GridView や yii\widgets\DetailView
などのウィジェットでは、こちらがよく使われています。例えば、
// 出力: January 1, 2014
echo Yii::$app->formatter->format('2014-01-01', 'date');
// 配列を使ってフォーマット・メソッドのパラメータを指定することも出来ます。
// `2` は asPercent() メソッドの $decimals パラメータの値です。
// 出力: 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 を参照してください。
フォーマッタは日付と時刻に関連した下記の出力形式をサポートしています。
January 01, 2014
。14:23
。January 01, 2014 14:23
。1412609982
1 hour ago
。1 day, 2 minutes
。date、time、datetime メソッドに使われるデフォルトの日時書式は、フォーマッタの $dateFormat、 $timeFormat、$datetimeFormat を構成することで、 グローバルにカスタマイズすることが出来ます。
日付と時刻のフォーマットは、ICU 構文 によって指定することが出来ます。
また、ICU 構文と区別するために php:
という接頭辞を付けて、PHP の date() 構文
を使うことも出来ます。例えば、
// ICU 形式
echo Yii::$app->formatter->asDate('now', 'yyyy-MM-dd'); // 2014-10-06
// PHP date() 形式
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."; // "On the 15th day of the month." と表示
U
、すなわち Unix エポックに対しては、timestamp 形式を使うことが出来ます。
複数の言語をサポートする必要があるアプリケーションを扱う場合には、ロケールごとに異なる日付と時刻のフォーマットを指定しなければならないことがよくあります。
この仕事を単純化するためには、(long
、short
などの) フォーマットのショートカットを代りに使うことが出来ます。
フォーマッタは、現在アクティブな locale に従って、フォーマットのショートカットを適切なフォーマットに変換します。
フォーマットのショートカットとして、次のものがサポートされています (例は en_GB
がアクティブなロケールであると仮定したものです)。
short
: 日付は 06/10/2014
、時刻は 15:58
を出力medium
: 6 Oct 2014
と 15:58:42
を出力long
: 6 October 2014
と 15:58:42 GMT
を出力full
: Monday, 6 October 2014
と 15:58:42 GMT
を出力情報: ja_JP ロケールでは、次のようになります。
short:
2014/10/06
と15:58
medium:2014/10/06
と15:58:42
long:2014年10月6日
と15:58:42 JST
full:2014年10月6日月曜日
と15時58分42秒 日本標準時
バージョン 2.0.7 以降では、さまざまな暦法に従って日付をフォーマットすることが可能です。 通常とは異なる暦法を使用する方法については、フォーマッタの $calendar プロパティの API ドキュメントを参照して下さい。
日時の値をフォーマットするときに、Yii はその値をターゲット・タイム・ゾーン に変換します。 フォーマットされる日付の値は、タイム・ゾーンが明示的に指定されるか、yii\i18n\Formatter::$defaultTimeZone が構成されるかしていない限り、 UTC であると見なされます。
次の例では、ターゲット・タイム・ゾーン が Europe/Berlin
に設定されているものとします。
// UNIX タイムスタンプを時刻としてフォーマット
echo Yii::$app->formatter->asTime(1412599260); // 14:41:00
// UTC の日付時刻文字列を時刻としてフォーマット
echo Yii::$app->formatter->asTime('2014-10-06 12:41:00'); // 14:41:00
// CEST の日付時刻文字列を時刻としてフォーマット
echo Yii::$app->formatter->asTime('2014-10-06 14:41:00 CEST'); // 14:41:00
Info: ターゲット・タイム・ゾーン が
Asia/Tokyo
である場合は、次のようになります。
echo Yii::$app->formatter->asTime(1412599260); // 21:41:00 echo Yii::$app->formatter->asTime('2014-10-06 12:41:00'); // 21:41:00 echo Yii::$app->formatter->asTime('2014-10-06 21:41:00 JST'); // 21:41:00
フォーマッタ・コンポーネントに対して タイム・ゾーン が明示的に設定されていない場合は、 アプリケーションで設定されたタイム・ゾーン (PHP の構成で設定されたタイム・ゾーンと同じ) が使用されます。
補足: タイム・ゾーンは世界中のさまざまな政府によって作られる規則に従うものであり、頻繁に変更されるものであるため、 あなたのシステムにインストールされたタイム・ゾーンのデータベースが最新の情報を持っていない可能性が大いにあります。 タイム・ゾーン・データベースの更新についての詳細は、 ICU マニュアル で参照することが出来ます。 PHP 環境を国際化のために設定する も参照してください。
フォーマッタは、数値に関連した下記の出力フォーマットをサポートしています。
42
。2,542.123
または 2.542,123
。42%
。4.2E4
。£420.00
。
この関数が正しく働くためには、en_GB
や en_US
のように、ロケールが国コードを含んでいる必要があります。
なぜなら、この場合は言語だけでは曖昧になるからです。410 キビバイト
。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 はよく使われるフォーマットをサポートしています。その中には、次のものが含まれます。
null
値が nullDisplay を使ってフォーマットされる以外は、何の効果もない擬似フォーマッタです。<p>
タグに囲まれた段落としてフォーマットされます。['html', ['Attr.AllowedFrameTargets' => ['_blank']]]
のような追加のオプションを渡すことが出来ます。mailto
リンクとしてフォーマットされます。image
タグとしてフォーマットされます。true
は Yes
、false
は No
とレンダリングされ、現在のアプリケーションの言語に翻訳されます。
この動作は yii\i18n\Formatter::$booleanFormat プロパティを構成して調整できます。null
値 ¶Null 値は特殊な方法でフォーマットされます。空文字列を表示する代りに、フォーマッタは null 値を事前定義された文字列
(そのデフォルト値は (not set)
です) に変換し、それを現在のアプリケーションの言語に翻訳します。
この文字列は nullDisplay プロパティを構成してカスタマイズすることが出来ます。
既に述べたように、フォーマッタは現在のアクティブな locale を使って、 ターゲットの国/地域にふさわしい値のフォーマットを決定することが出来ます。 例えば、同じ日時の値でも、ロケールによって異なる書式にフォーマットされます。
Yii::$app->formatter->locale = 'en-US';
echo Yii::$app->formatter->asDate('2014-01-01'); // 出力: January 1, 2014
Yii::$app->formatter->locale = 'de-DE';
echo Yii::$app->formatter->asDate('2014-01-01'); // 出力: 1. Januar 2014
Yii::$app->formatter->locale = 'ru-RU';
echo Yii::$app->formatter->asDate('2014-01-01'); // 出力: 1 января 2014 г.
Yii::$app->formatter->locale = 'ja-JP';
echo Yii::$app->formatter->asDate('2014-01-01'); // 出力: 2014/01/01
デフォルトでは、現在のアクティブな locale は yii\base\Application::$language の値によって決定されます。 これは yii\i18n\Formatter::$locale プロパティを明示的に指定することによってオーバーライドすることが出来ます。
補足: Yii のフォーマッタは、PHP intl 拡張 に依存してデータのフォーマットの ローカライズをサポートしています。PHP にコンパイルされた ICU ライブラリのバージョンによってフォーマットの結果が異なる場合がありますので、 あなたの全ての環境で、同じ ICU バージョンを使うことが推奨されます。 詳細については、PHP 環境を国際化のために設定する を参照してください。
intl 拡張がインストールされていない場合は、データはローカライズされません。
1901年より前、または、2038年より後の日時の値は、たとえ intl 拡張がインストールされていても、32-bit システムではローカライズされないことに注意してください。 これは、この場合、ICU ライブラリが日時の値に対して 32-bit の UNIX タイムスタンプを使用しているのが原因です。
Found a typo or you think this page needs improvement?
Edit it on github !
Signup or Login in order to comment.