# 数据格式器
Yii提供一个格式化类来格式化输出，以使输出数据对终端用户更友好易读， yii\i18n\Formatter 是一个助手类，作为 [应用组件](http://www.yiichina.com/doc/guide/2.0/structure-application-components) 使用，默认名为`formatter`。
它提供一些方法用来格式化数据，如日期/时间、数字或其他常用的本地化格式， 两种方式使用格式器：
1. 直接使用格式化方法(所有的格式器方法以 `as`做前缀):
~~~
echo Yii::$app->formatter->asDate('2014-01-01', 'long'); // 输出: January 1, 2014
echo Yii::$app->formatter->asPercent(0.125, 2); // 输出: 12.50%
echo Yii::$app->formatter->asEmail('cebe@example.com'); // 输出: <a href="mailto:cebe@example.com">cebe@example.com</a>
echo Yii::$app->formatter->asBoolean(true); // 输出: Yes
// 也可处理null值的输出显示:
echo Yii::$app->formatter->asDate(null); // 输出: (Not set)
~~~
2. 使用 yii\i18n\Formatter::format() 方法和格式化名， 该方法也被一些小部件如yii\grid\GridView 和 yii\widgets\DetailView使用，在小部件配置中可以指定列的数据格式。
~~~
echo Yii::$app->formatter->format('2014-01-01', 'date'); // 输出: January 1, 2014
// 可使用数组来指定格式化方法的参数：
// `2` 是asPercent()方法的参数$decimals的值
echo Yii::$app->formatter->format(0.125, ['percent', 2]); // 输出: 12.50%
~~~
当[PHP intl extension](http://php.net/manual/en/book.intl.php)安装时，格式器的输出会本地化， 为此可配置格式器的 yii\i18n\Formatter::locale 属性，如果没有配置， 应用配置 yii\base\Application::language 作为当前区域，更多详情参考 [国际化](http://www.yiichina.com/doc/guide/2.0/tutorial-i18n)一节。 然后格式器根据当前区域为日期和数字选择正确的格式，包括月份和星期也会转换到当前语言， 日期格式也会被 yii\i18n\Formatter::timeZone 参数影响， 该参数如果没有明确配置会使用应用的 yii\base\Application::timeZone 参数。
日期格式根据不同区域输出不同的结果，如下例所示： For example the date format call will output different results for different locales:
~~~
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 г.
~~~
> 注意不管[PHP intl extension](http://php.net/manual/en/book.intl.php)有没有安装，PHP编译的ICU库不同，格式化结果可能不同， 所以为确保不同环境下得到相同的输出，推荐在每个环境下安装PHP intl扩展以及相同的ICU库， 可参考： [为国际化设置PHP环境](http://www.yiichina.com/doc/guide/2.0/tutorial-i18n#setup-environment).
## 配置格式器
可配置yii\i18n\Formatter的属性来调整格式器方法的默认格式， 可以在[应用主体配置](http://www.yiichina.com/doc/guide/2.0/concept-configurations#application-configurations) 中配置 `formatter` 组件应用到整个项目， 配置样例如下所示， 更多关于可用属性的详情请参考 yii\i18n\Formatter 和接下来一小节。
~~~
'components' => [
'formatter' => [
'dateFormat' => 'dd.MM.yyyy',
'decimalSeparator' => ',',
'thousandSeparator' => ' ',
'currencyCode' => 'EUR',
],
],
~~~
## 格式化日期和时间
格式器类为格式化日期和时间提供了多个方法： The formatter class provides different methods for formatting date and time values. These are:
* yii\i18n\Formatter::asDate() - 值被格式化成日期，如 `January, 01 2014`.
* yii\i18n\Formatter::asTime() - 值被格式化成时间，如 `14:23`.
* yii\i18n\Formatter::asDatetime() - 值被格式化成日期和时间，如 `January, 01 2014 14:23`.
* yii\i18n\Formatter::asTimestamp() - 值被格式化成 [unix 时间戳](http://en.wikipedia.org/wiki/Unix_time) 如 `1412609982`.
* yii\i18n\Formatter::asRelativeTime() - 值被格式化成和当前时间比较的时间间隔并用人们易读的格式，如`1 hour ago`.
可配置格式器的属性yii\i18n\Formatter::$dateFormat, yii\i18n\Formatter::$timeFormat 和yii\i18n\Formatter::$datetimeFormat来全局指定yii\i18n\Formatter::asDate(), yii\i18n\Formatter::asTime() 和 yii\i18n\Formatter::asDatetime() 方法的日期和时间格式。
格式器默认会使用一个快捷格式，它根据当前启用的区域来解析， 这样日期和时间会格式化成用户国家和语言通用的格式， 有四种不同的快捷格式：
* `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`.
另外你可使用[ICU 项目](http://site.icu-project.org/) 定义的语法来自定义格式， ICU项目在该URL：[http://userguide.icu-project.org/formatparse/datetime](http://userguide.icu-project.org/formatparse/datetime)下的手册有介绍， 或者可使用PHP [date()](http://php.net/manual/de/function.date.php) 方法的语法字符串并加上前缀`php:`.
~~~
// 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
~~~
### 时区
当格式化日期和时间时，Yii会将它们转换为对应的 yii\i18n\Formatter::timeZone 时区， 输入的值在没有指定时区时候会被当作UTC时间，因此，推荐存储所有的日期和时间为UTC而不是UNIX时间戳，UNIX通常也是UTC。 如果输入值所在的时区不同于UTC，时区应明确指定，如下所示：
~~~
// 假定 Yii::$app->timeZone = 'Europe/Berlin';
echo Yii::$app->formatter->asTime(1412599260); // 14:41:00
echo Yii::$app->formatter->asTime('2014-10-06 12:41:00'); // 14:41:00
echo Yii::$app->formatter->asTime('2014-10-06 14:41:00 CEST'); // 14:41:00
~~~
> 注意：时区从属于全世界各国政府定的规则，可能会频繁的变更，因此你的系统的时区数据库可能不是最新的信息， 可参考 [ICU manual](http://userguide.icu-project.org/datetime/timezone#TOC-Updating-the-Time-Zone-Data) 关于更新时区数据库的详情， 也可参考：[为国际化设置PHP环境](http://www.yiichina.com/doc/guide/2.0/tutorial-i18n#setup-environment).
## 格式化数字
格式器类提供如下方法格式化数值： For formatting numeric values the formatter class provides the following methods:
* yii\i18n\Formatter::asInteger() - 值被格式化成整型，如 `42`.
* yii\i18n\Formatter::asDecimal() - 值被格式化成十进制数字并带有小数位和千分位，如 `42.123`.
* yii\i18n\Formatter::asPercent() - 值被格式化成百分率，如 `42%`.
* yii\i18n\Formatter::asScientific() - 值被格式化成科学计数型，如`4.2E4`.
* yii\i18n\Formatter::asCurrency() - 值被格式化成货币格式，如 `£420.00`.
* yii\i18n\Formatter::asSize() - 字节值被格式化成易读的值，如 `410 kibibytes`.
可配置yii\i18n\Formatter::decimalSeparator 和 yii\i18n\Formatter::thousandSeparator 属性来调整数字格式化的格式，默认和当前区域相同。
更多高级配置， yii\i18n\Formatter::numberFormatterOptions 和 yii\i18n\Formatter::numberFormatterTextOptions 可用于配置内部使用[Numberformatter class](http://php.net/manual/en/class.numberformatter.php)
为调整数字的小数部分的最大值和最小值，可配置如下属性：
~~~
[
NumberFormatter::MIN_FRACTION_DIGITS => 0,
NumberFormatter::MAX_FRACTION_DIGITS => 2,
]
~~~
## 其他格式器
除了日期、时间和数字格式化外，Yii提供其他用途提供一些实用的格式器： Additional to date, time and number formatting, Yii provides a set of other useful formatters for different purposes:
* yii\i18n\Formatter::asRaw() - 输出值和原始值一样，除了`null`值会用nullDisplay格式化，这是一个伪格式器；
* yii\i18n\Formatter::asText() - 值会经过HTML编码； 这是[GridView DataColumn](http://www.yiichina.com/doc/guide/2.0/output-data-widgets#data-column)默认使用的格式；
* yii\i18n\Formatter::asNtext() - 值会格式化成HTML编码的纯文本，新行会转换成换行符；
* yii\i18n\Formatter::asParagraphs() - 值会转换成HTML编码的文本段落，用`<p>`标签包裹；
* yii\i18n\Formatter::asHtml() - 值会被HtmlPurifier过滤来避免XSS跨域攻击，可传递附加选项如`['html', ['Attr.AllowedFrameTargets' => ['_blank']]]；
* yii\i18n\Formatter::asEmail() - 值会格式化成 `mailto`-链接；
* yii\i18n\Formatter::asImage() - 值会格式化成图片标签；
* yii\i18n\Formatter::asUrl() - 值会格式化成超链接；
* yii\i18n\Formatter::asBoolean() - 值会格式化成布尔型值，默认情况下 `true` 对应 `Yes`，`false` 对应 `No`， 可根据应用语言配置进行翻译，可以配置yii\i18n\Formatter::booleanFormat-属性来调整；
## `null`-值
对于PHP的`null`值，格式器类会打印一个占位符而不是空字符串，空字符串默认会显示对应当前语言`(not set)`, 可配置yii\i18n\Formatter::nullDisplay-属性配置一个自定义占位符， 如果对处理`null`值没有特殊要求，可设置yii\i18n\Formatter::nullDisplay 为 `null`.
- 介绍（Introduction）
- 关于 Yii（About Yii）
- 从 Yii 1.1 升级（Upgrading from Version 1.1）
- 入门（Getting Started）
- 安装 Yii（Installing Yii）
- 运行应用（Running Applications）
- 第一次问候（Saying Hello）
- 使用 Forms（Working with Forms）
- 玩转 Databases（Working with Databases）
- 用 Gii 生成代码（Generating Code with Gii）
- 更上一层楼（Looking Ahead）
- 应用结构（Application Structure）
- 结构概述（Overview）
- 入口脚本（Entry Scripts）
- 应用（Applications）
- 应用组件（Application Components）
- 控制器（Controllers）
- 模型（Models）
- 视图（Views）
- 模块（Modules）
- 过滤器（Filters）
- 小部件（Widgets）
- 前端资源（Assets）
- 扩展（Extensions）
- 请求处理（Handling Requests）
- 运行概述（Overview）
- 引导（Bootstrapping）
- 路由引导与创建 URL（Routing and URL Creation）
- 请求（Requests）
- 响应（Responses）
- Sessions and Cookies
- 错误处理（Handling Errors）
- 日志（Logging）
- 关键概念（Key Concepts）
- 组件（Components）
- 属性（Properties）
- 事件（Events）
- 行为（Behaviors）
- 配置（Configurations）
- 别名（Aliases）
- 类自动加载（Class Autoloading）
- 服务定位器（Service Locator）
- 依赖注入容器（Dependency Injection Container）
- 配合数据库工作（Working with Databases）
- 数据库访问（Data Access Objects）: 数据库连接、基本查询、事务和模式操作
- 查询生成器（Query Builder）: 使用简单抽象层查询数据库
- 活动记录（Active Record）: 活动记录对象关系映射（ORM），检索和操作记录、定义关联关系
- 数据库迁移（Migrations）: 在团体开发中对你的数据库使用版本控制
- Sphinx
- Redis
- MongoDB
- ElasticSearch
- 接收用户数据（Getting Data from Users）
- 创建表单（Creating Forms）
- 输入验证（Validating Input）
- 文件上传（Uploading Files）
- 收集列表输入（Collecting Tabular Input）
- 多模型同时输入（Getting Data for Multiple Models）
- 显示数据（Displaying Data）
- 格式化输出数据（Data Formatting）
- 分页（Pagination）
- 排序（Sorting）
- 数据提供器（Data Providers）
- 数据小部件（Data Widgets）
- 操作客户端脚本（Working with Client Scripts）
- 主题（Theming）
- 安全（Security）
- 认证（Authentication）
- 授权（Authorization）
- 处理密码（Working with Passwords）
- 客户端认证（Auth Clients）
- 安全领域的最佳实践（Best Practices）
- 缓存（Caching）
- 概述（Overview）
- 数据缓存（Data Caching）
- 片段缓存（Fragment Caching）
- 分页缓存（Page Caching）
- HTTP 缓存（HTTP Caching）
- RESTful Web 服务
- 快速入门（Quick Start）
- 资源（Resources）
- 控制器（Controllers）
- 路由（Routing）
- 格式化响应（Response Formatting）
- 授权验证（Authentication）
- 速率限制（Rate Limiting）
- 版本化（Versioning）
- 错误处理（Error Handling）
- 开发工具（Development Tools）
- 调试工具栏和调试器（Debug Toolbar and Debugger）
- 使用 Gii 生成代码（Generating Code using Gii）
- TBD 生成 API 文档（Generating API Documentation）
- 测试（Testing）
- 概述（Overview）
- 搭建测试环境（Testing environment setup）
- 单元测试（Unit Tests）
- 功能测试（Functional Tests）
- 验收测试（Acceptance Tests）
- 测试夹具（Fixtures）
- 高级专题（Special Topics）
- 高级应用模版（Advanced Project Template）
- 从头构建自定义模版（Building Application from Scratch）
- 控制台命令（Console Commands）
- 核心验证器（Core Validators）
- 国际化（Internationalization）
- 收发邮件（Mailing）
- 性能优化（Performance Tuning）
- 共享主机环境（Shared Hosting Environment）
- 模板引擎（Template Engines）
- 集成第三方代码（Working with Third-Party Code）
- 小部件（Widgets）
- Bootstrap 小部件（Bootstrap Widgets）
- jQuery UI 小部件（jQuery UI Widgets）
- 助手类（Helpers）
- 助手一览（Overview）
- Array 助手（ArrayHelper）
- Html 助手（Html）
- Url 助手（Url）