UPGRADE and CHANGELOG notes for the Formatter changes

docs/guide/output-data-widgets.md

@@ -141,7 +141,7 @@ Data column is for displaying and sorting data. It is default column type so spe
 using it.
 
 The main setting of the data column is its format. It could be specified via `format` attribute. Its values are
-corresponding to methods in `format` application component that is [[\yii\base\Formatter|Formatter]] by default:
+corresponding to methods in `format` application component that is [[\yii\i18n\Formatter|Formatter]] by default:
 
 ```php
 <?= GridView::widget([
@@ -158,8 +158,8 @@ corresponding to methods in `format` application component that is [[\yii\base\F
 ]); ?>
 ```
 
-In the above `text` corresponds to [[\yii\base\Formatter::asText()]]. The value of the column is passed as the first
-argument. In the second column definition `date` corresponds to [[\yii\base\Formatter::asDate()]]. The value of the
+In the above `text` corresponds to [[\yii\i18n\Formatter::asText()]]. The value of the column is passed as the first
+argument. In the second column definition `date` corresponds to [[\yii\i18n\Formatter::asDate()]]. The value of the
 column is, again, passed as the first argument while 'Y-m-d' is used as the second argument value.
 
 Here's the bundled formatters list:

docs/guide/output-formatter.md

@@ -1,16 +1,46 @@
-Formatter
-=========
+Data Formatter
+==============
+
+For formatting of outputs Yii provides a formatter class to make date more readable for users.
+[[yii\i18n\Formatter]] is a helper class that is registered as an [application component](concept-components.md) name `formatter` by default.
+
+It provides a set of methods for data formatting purpose such as date/time values, numbers and other commonly used formats in a localized way.
+The formatter can be used in two different ways.
+
+1. Using the formatting methods(all formatter methods prefixed with `as`) directly:
+
+   ```php
+   echo Yii::$app->formatter->asDate('2014-01-01', 'long'); // output: January 1, 2014
+   echo Yii::$app->formatter->asPercent(0.125, 2); // output: 12.50%
+   echo Yii::$app->formatter->asEmail('cebe@example.com'); // output: <a href="mailto:cebe@example.com">cebe@example.com</a>
+   echo Yii::$app->formatter->asBoolean(true); // output: Yes
+   ```
+
+2. Using the [[yii\i18n\Formatter::format()|format()]] method using the format name.
+   This method is used by classes like GridView and DetailView where you can specify the data format of a column in the
+   widget config.
+
+   ```php
+   echo Yii::$app->formatter->format('2014-01-01', 'date'); // output: January 1, 2014
+   // 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.
+   echo Yii::$app->formatter->format(0.125, ['percent', 2]); // output: 12.50%
+   ```
+
+All output of the formatter is localized when the [PHP intl extension](http://php.net/manual/en/book.intl.php) is installed.
+You can configure the [[yii\i18n\Formatter::locale|locale]] property of the formatter for this. If not configured, the
+application [[language]] is used as the locale. See the [Section on internationaization](tutorial-i18n.md) for more details.
+
+ * > Note that formatting may differ between different versions of the ICU library compiled with PHP.
+ * > You
+ *
+
 
 Formatter is a helper component to format machine readable data of type date, time, different number types 
 in user readable formats. Most of this types are in countries differently formatted (eg. date: US -> '10/31/2014,
 or DE -> '31.10.2014' or ISO -> '2014-10-31'). Same with decimals and currency values (eg. currency: US-> '$ 13,250.22' or
-de-DE -> '13.250,22 €' or de-CH ->'CHF 13'250.22')
-
-Formatter supports unformatting also. A localized formatted date or number can be unformatted into a machine readable
-type (eg. '13.250,22 €' -> '13250.22')
+de-DE -> '13.250,22 <EFBFBD>' or de-CH ->'CHF 13'250.22')
 
-This formatter version is merged from old `yii\base\formatter` and `yii\i18n\formatter` which supports localized formatting
-and "english only" formatting.
 
 Formatter uses the php extension "intl" if the extension is loaded. "Intl" uses [ICU standard](http://site.icu-project.org/) driven
 by IBM. "intl" internally knows all formats of all countries and it translates month or day names into the corrcect language. 

docs/guide/structure-application-components.md

@@ -94,7 +94,7 @@ if you do not specify its class, the default one will be used.
   Please refer to the [Data Access Objects](db-dao.md) section for more details.
 * [[yii\base\Application::errorHandler|errorHandler]]: handles PHP errors and exceptions.
   Please refer to the [Handling Errors](tutorial-handling-errors.md) section for more details.
-* [[yii\base\Formatter|formatter]]: formats data when they are displayed to end users. For example, a number
+* [[yii\i18n\Formatter|formatter]]: formats data when they are displayed to end users. For example, a number
   may be displayed with thousand separator, a date may be formatted in long format.
   Please refer to the [Data Formatting](output-formatting.md) section for more details.
 * [[yii\i18n\I18N|i18n]]: supports message translation and formatting.

docs/guide/structure-extensions.md

@@ -308,7 +308,7 @@ content to end users, you should try to [internationalize and localize](tutorial
 - If the extension displays messages intended for end users, the messages should be wrapped into `Yii::t()`
   so that they can be translated. Messages meant for developers (such as internal exception messages) do not need
   to be translated.
-- If the extension displays numbers, dates, etc., they should be formatted using [[yii\base\Formatter]] with
+- If the extension displays numbers, dates, etc., they should be formatted using [[yii\i18n\Formatter]] with
   appropriate formatting rules.
 
 For more details, please refer to the [Internationalization](tutorial-i18n.md) section.

docs/guide/tutorial-i18n.md

@@ -478,23 +478,4 @@ put there file for russian language as follows `views/site/ru-RU/index.php`.
 i18n formatter
 --------------
 
-i18n formatter component is the localized version of formatter that supports formatting of date, time and numbers based
-on current locale. In order to use it you need to configure formatter application component as follows:
-
-```php
-return [
-    // ...
-    'components' => [
-        'formatter' => [
-            'class' => 'yii\i18n\Formatter',
-        ],
-    ],
-];
-```
-
-After configuring the component can be accessed as `Yii::$app->formatter`.
-
-Note that in order to use i18n formatter you need to install and enable
-[intl](http://www.php.net/manual/en/intro.intl.php) PHP extension.
-
-In order to learn about formatter methods refer to its API documentation: [[yii\i18n\Formatter]].
+See the [Date Formatter section](output-formatter.md) for details.

framework/CHANGELOG.md

@@ -214,7 +214,6 @@ Yii Framework 2 Change Log
 - Enh: Added param `hideOnSinglePage` to `yii\widgets\LinkPager` (arturf)
 - Enh: Added support for array attributes in `in` validator (creocoder)
 - Enh: Improved `yii\helpers\Inflector::slug` to support more cases for Russian, Hebrew and special characters (samdark)
-
 - Enh: ListView now uses the widget ID in the base tag, consistent to gridview (cebe)
 - Enh: Added `yii\web\Response::enableCsrfCookie` to support storing CSRF tokens in session (qiangxue)
 - Chg #2287: Split `yii\db\ColumnSchema::typecast()` into two methods `phpTypecast()` and `dbTypecast()` to allow specifying PDO type explicitly (cebe)

framework/UPGRADE.md

@@ -213,3 +213,34 @@ new ones save the following code as `convert.php` that should be placed in the s
 * `Html::radio()`, `Html::checkbox()`, `Html::radioList()`, `Html::checkboxList()` no longer generate the container
   tag around each radio/checkbox when you specify labels for them. You should manually render such container tags,
   or set the `item` option for `Html::radioList()`, `Html::checkboxList()` to generate the container tags.
+
+* The formatter class has been refactored to have only one class regardless whether PHP intl extension is installed or not.
+  Functionality of `yii\base\Formatter` has been merged into `yii\i18n\Formatter` and `yii\base\Formatter` has been
+  removed so you have to replace all usage of `yii\base\Formatter` with `yii\i18n\Formatter` in your code.
+  Also the API of the Formatter class has changed in many ways.
+  The signature of the following Methods has changed:
+
+  - `asDate`
+  - `asTime`
+  - `asDateTime`
+  - `asSize` has been split up into `asSize` and `asShortSize`
+  - `asCurrency`
+  - `asDecimal`
+  - `asPercent`
+  - `asScientific`
+
+  The following methods have been removed, this also means that the corresponding format which may be used by a
+  GridView or DetailView is not available anymore:
+
+  - `asNumber`
+  - `asDouble`
+
+  Also due to these changes some formatting defaults have changes so you have to check all your GridView and DetailView
+  configuration and make sure the formatting is displayed correctly.
+
+  The configuration for `asSize()` has changed. It now uses the configuration for the number formatting from intl
+  and only the base is configured using `$sizeFormatBase`.
+
+  The specification of the date and time formats is now using the ICU pattern format even if PHP intl extension is not installed.
+  You can prefix a date format with `php:` to use the old format of the PHP `date()`-function.
+

framework/base/Application.php

@@ -22,7 +22,7 @@ use Yii;
  * @property \yii\db\Connection $db The database connection. This property is read-only.
  * @property \yii\web\ErrorHandler|\yii\console\ErrorHandler $errorHandler The error handler application
  * component. This property is read-only.
- * @property \yii\base\Formatter $formatter The formatter application component. This property is read-only.
+ * @property \yii\i18n\Formatter $formatter The formatter application component. This property is read-only.
  * @property \yii\i18n\I18N $i18n The internationalization application component. This property is read-only.
  * @property \yii\log\Dispatcher $log The log dispatcher application component. This property is read-only.
  * @property \yii\mail\MailerInterface $mailer The mailer application component. This property is read-only.
@@ -514,7 +514,7 @@ abstract class Application extends Module
 
     /**
      * Returns the formatter component.
-     * @return \yii\base\Formatter the formatter application component.
+     * @return \yii\i18n\Formatter the formatter application component.
      */
     public function getFormatter()
     {
@@ -612,7 +612,7 @@ abstract class Application extends Module
         return [
             'log' => ['class' => 'yii\log\Dispatcher'],
             'view' => ['class' => 'yii\web\View'],
-            'formatter' => ['class' => 'yii\base\Formatter'],
+            'formatter' => ['class' => 'yii\i18n\Formatter'],
             'i18n' => ['class' => 'yii\i18n\I18N'],
             'mailer' => ['class' => 'yii\swiftmailer\Mailer'],
             'urlManager' => ['class' => 'yii\web\UrlManager'],

framework/classes.php

@@ -28,7 +28,6 @@ return [
   'yii\base\Event' => YII2_PATH . '/base/Event.php',
   'yii\base\Exception' => YII2_PATH . '/base/Exception.php',
   'yii\base\ExitException' => YII2_PATH . '/base/ExitException.php',
-  'yii\base\Formatter' => YII2_PATH . '/base/Formatter.php',
   'yii\base\InlineAction' => YII2_PATH . '/base/InlineAction.php',
   'yii\base\InvalidCallException' => YII2_PATH . '/base/InvalidCallException.php',
   'yii\base\InvalidConfigException' => YII2_PATH . '/base/InvalidConfigException.php',

framework/grid/DataColumn.php

@@ -63,7 +63,7 @@ class DataColumn extends Column
      * @var string|array in which format should the value of each data model be displayed as (e.g. "raw", "text", "html",
      * ['date', 'Y-m-d']). Supported formats are determined by the [[GridView::formatter|formatter]] used by
      * the [[GridView]]. Default format is "text" which will format the value as an HTML-encoded plain text when
-     * [[\yii\base\Formatter::format()]] or [[\yii\i18n\Formatter::format()]] is used.
+     * [[\yii\i18n\Formatter::format()]] or [[\yii\i18n\Formatter::format()]] is used.
      */
     public $format = 'text';
     /**

framework/grid/GridView.php

@@ -9,7 +9,7 @@ namespace yii\grid;
 
 use Yii;
 use Closure;
-use yii\base\Formatter;
+use yii\i18n\Formatter;
 use yii\base\InvalidConfigException;
 use yii\helpers\Url;
 use yii\helpers\Html;

framework/i18n/Formatter.php

@@ -950,7 +950,7 @@ class Formatter extends Component
             return $f->format($value);
         } else {
             if ($decimals !== null) {
-                return sprintf("%.{$decimals}E", $value); // TODO
+                return sprintf("%.{$decimals}E", $value);
             } else {
                 return sprintf("%.E", $value);
             }

framework/widgets/DetailView.php

@@ -9,7 +9,7 @@ namespace yii\widgets;
 
 use Yii;
 use yii\base\Arrayable;
-use yii\base\Formatter;
+use yii\i18n\Formatter;
 use yii\base\InvalidConfigException;
 use yii\base\Model;
 use yii\base\Widget;