# 數據格式器
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）