介绍(Introduction) 入门(Getting Started) 应用结构(Application Structure) 请求处理(Handling Requests) 关键概念(Key Concepts) 配合数据库工作(Working with Databases) 接收用户数据(Getting Data from Users) 显示数据(Displaying Data) 安全(Security) 缓存(Caching) RESTful Web 服务(RESTful Web Services) 开发工具(Development Tools) 测试(Testing) 高级专题(Special Topics) 小部件(Widgets) 助手类(Helpers)

数据格式器(Data Formatting)

社区推荐:掘金是一个面向程序员的技术社区,从后端到架构,从 PHP 最佳实践到一线大厂经验分享,无论入门还是进阶,来掘金你不会错过后端开发的任何一个技术干货。

你可以使用 formatter application component 来格式化数据。 默认 fomatteryii\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(),这个 Xzy 就是所支持的格式化类型。 当然你也可以使用类方法 format() 来进行格式化,通过这个类方法,你可以更自由地控制格式化的数据,这时候,类方法通常配合 yii\grid\GridView 或者 yii\widgets\DetailView 来使用。

举个例子:

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

// 你可以在第二个参数指定一个数组,这个数组提供了一些配置的参数
// 例如这个 2 就是 asPercent() 方法的 $decimals 参数
// output: 12.50%
echo Yii::$app->formatter->format(0.125, ['percent', 2]); 

注意: formatter 组件用来格式化最终展示给用户的数据。 如果你想要将用户的输入进行格式化或者只是将一些别的日期数据进行格式化(这里的格式化说的是机器可读的格式化), 不要使用这个组件, 而应该使用 yii\validators\DateValidatoryii\validators\NumberValidator 进行用户输入格式化 对于机器可读的日期和时间格式之间的简单转换, PHP 方法 date() 就足够了。

配置 Formatter(Configuring Formatter)

可以对 formatter 组件在 application configuration 中进行配置。 例如,

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

可以参考 yii\i18n\Formatter 的配置

格式化时间/日期数据(Formatting Date and Time Values)

默认支持一下几种格式化格式

  • date:这个变量将被格式化为日期 January 01, 2014
  • time:这个变量将被格式化为时间 14:23
  • datetime:这个变量将被格式化为日期+时间 January 01, 2014 14:23
  • timestamp:这个变量将被格式化为 UNIX 时间戳 unix timestamp,例如 1412609982
  • relativeTime:这个变量将被格式化为人类可读的 当前相对时间 1 hour ago
  • duration:这个变量将被格式化为人类可读的时长 1 day, 2 minutes

时间/日期数据默认使用 date, timedatetime 方法进行格式化, 你可以对他们进行一些自己的配置,只需在配置文件里配置 dateFormat, timeFormat, 和 datetimeFormat 即可。

同时,你还可以配置它使用 ICU syntax, 同时你也可以配置它使用 PHP date() 语法,只需要加上 php: 前缀即可。 例如,

// 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

信息: Some letters of the PHP format syntax are not supported by ICU and thus the PHP intl extension and can not be used in Yii formatter. Most of these (w, t, L, B, u, I, Z) are not really useful for formatting dates but rather used when doing date math. S and U however may be useful. Their behavior can be achived by doing the following:

  • for S, which is the English ordinal suffix for the day of the month (e.g. st, nd, rd or th.), the following replacement can be used:

    $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."
    
  • for U, the Unix Epoch, you can use the timestamp format.

When working with applications that need to support multiple languages, you often need to specify different date and time formats for different locales. To simplify this task, you may use format shortcuts (e.g. long, short), instead. The formatter will turn a format shortcut into an appropriate format according to the currently active locale. The following format shortcuts are supported (the examples assume en_GB is the active locale):

  • short: will output 06/10/2014 for date and 15:58 for time;
  • medium: will output 6 Oct 2014 and 15:58:42;
  • long: will output 6 October 2014 and 15:58:42 GMT;
  • full: will output Monday, 6 October 2014 and 15:58:42 GMT.

版本 2.0.7 起,支持格式化日期为不同的系统时钟, Please refer to the API documentation of the formatters $calendar-property on how to set a different calendar.

时区(Time Zones)

格式化时间/日期数据时,你会将他们转换成 time zone 这个时候,默认的时区为 UTC,除非你另外指定 yii\i18n\Formatter::$defaultTimeZone

下面使用 Europe/Berlin 作为默认 time zone

// 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

If the time zone is not set explicitly on the formatter component, the time zone configured in the application is used, which is the same time zone as set in the PHP configuration.

不同的政府和地区政策决定不同的时区, 你在你的时区数据库中可能拿不到最新的数据。 这时你可以戳 ICU manual 来查看如何更新时区。 同时,这篇也可以作为参考 Setting up your PHP environment for internationalization

格式化数字(Formatting Numbers)

formatter 支持如下的方法

  • integer: 这个变量将被格式化为整形 e.g. 42.
  •  例如:2,542.123 或 2.542,123

  • percent: 这个变量将被格式化为百分比 e.g. 42%.
  • scientific: 这个变量将被格式化为科学计数法 e.g. 4.2E4.
  •  例如:£420.00。 使用这个方法前请确认是否已经正确配置 locale

  • size: 这个变量将被格式化为人类可读的字节数 e.g. 410 kibibytes.
  • shortSize: 这个变量将被格式化为人类可读的字节数(缩写) size,例如:410 KiB

你可以使用 decimalSeparatorthousandSeparator 来进行调整。 他们都会根据当前的 locale 来进行格式化.

如果你想要进行更高级的配置, 可以使用 yii\i18n\Formatter::$numberFormatterOptionsyii\i18n\Formatter::$numberFormatterTextOptionsNumberFormatter class 来进行格式化。 例如,为了调整小数部分的最大值和最小值,你可以配置 yii\i18n\Formatter::$numberFormatterOptions 如下:

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

其他的格式化(Other Formats)

除了时间/日期和数字的格式化,Yii 还支持如下的常用格式化

  • raw: the value is outputted as is, this is a pseudo-formatter that has no effect except that null values will be formatted using nullDisplay.
  • text: the value is HTML-encoded. This is the default format used by the GridView DataColumn.
  • ntext: the value is formatted as an HTML-encoded plain text with newlines converted into line breaks.
  • paragraphs: the value is formatted as HTML-encoded text paragraphs wrapped into <p> tags.
  • html: the value is purified using HtmlPurifier to avoid XSS attacks. You can pass additional options such as ['html', ['Attr.AllowedFrameTargets' => ['_blank']]].
  • email: the value is formatted as a mailto-link.
  • image: the value is formatted as an image tag.
  • url: the value is formatted as a hyperlink.
  • boolean: the value is formatted as a boolean. By default true is rendered as Yes and false as No, translated to the current application language. You can adjust this by configuring the yii\i18n\Formatter::$booleanFormat property.

空值(Null Values)

空值(null)会被特殊格式化. fommater 默认会将空值格式化为 (not set) 对应的当前的语言. 你可以配置 nullDisplay 属性来进行个性化。

本地日期格式化(Localizing Data Format)

As aforementioned, the formatter may use the currently active locale to determine how to format a value that is suitable in the target country/region. For example, the same date value may be formatted differently for different locales:

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 г.

默认配置下,当前 locale 决定于 yii\base\Application::$language. 你可以覆盖 yii\i18n\Formatter::$locale 属性来满足不同的需要。

注意: Yii formatter 依赖 PHP intl extension 来进行本地数据格式化 因为不同的 ICU 库可能会导致不同的输出,所以请在你的所有机器上保持 ICU 库的一致性.。 请参阅 Setting up your PHP environment for internationalization

如果 intl 扩展没有被安装,数据格式化不会考虑本地化.

在 32 位系统中,1901 年前或者 2038 年后的日期数据将不会被本地化, 因为 ICU 使用的是 32 位的 UNIX 时间戳。

TPshop
发现错别字或您认为此页面需要改进?
点此进入 Github 编辑