feature #13717 Deprecated precision option in favor of scale (WouterJ)

This PR was merged into the 2.7 branch.

Discussion
----------

Deprecated precision option in favor of scale

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | no
| BC breaks?    | no
| Deprecations? | yes
| Tests pass?   | yes
| Fixed tickets | #7383
| License       | MIT
| Doc PR        | https://github.com/symfony/symfony-docs/pull/5005

Scale is the number of digits to the right of the decimal point in a number, precision isn't. See the referenced ticket for more context.

Commits
-------

2a2f7e2 Deprecated precision option in favor of scale

UPGRADE-3.0.md

@@ -106,6 +106,24 @@ UPGRADE FROM 2.x to 3.0
 
 ### Form
 
+ * The option "precision" was renamed to "scale".
+
+   Before:
+
+   ```php
+   $builder->add('length', 'number', array(
+      'precision' => 3,
+   ));
+   ```
+
+   After:
+
+   ```php
+   $builder->add('length', 'number', array(
+      'scale' => 3,
+   ));
+   ```
+
  * The method `AbstractType::setDefaultOptions(OptionsResolverInterface $resolver)` and
    `AbstractTypeExtension::setDefaultOptions(OptionsResolverInterface $resolver)` have been
    renamed. You should use `AbstractType::configureOptions(OptionsResolver $resolver)` and

src/Symfony/Component/Form/CHANGELOG.md

@@ -4,6 +4,7 @@ CHANGELOG
 2.7.0
 -----
 
+ * deprecated option "precision" in favor of "scale"
  * deprecated the overwriting of AbstractType::setDefaultOptions() in favor of overwriting AbstractType::configureOptions().
  * deprecated the overwriting of AbstractTypeExtension::setDefaultOptions() in favor of overwriting AbstractTypeExtension::configureOptions().
 

src/Symfony/Component/Form/Extension/Core/DataTransformer/IntegerToLocalizedStringTransformer.php

@@ -22,11 +22,11 @@ class IntegerToLocalizedStringTransformer extends NumberToLocalizedStringTransfo
     /**
      * Constructs a transformer.
      *
-     * @param int  $precision    Unused.
+     * @param int  $scale        Unused.
      * @param bool $grouping     Whether thousands should be grouped.
      * @param int  $roundingMode One of the ROUND_ constants in this class.
      */
-    public function __construct($precision = 0, $grouping = false, $roundingMode = self::ROUND_DOWN)
+    public function __construct($scale = 0, $grouping = false, $roundingMode = self::ROUND_DOWN)
     {
         if (null === $roundingMode) {
             $roundingMode = self::ROUND_DOWN;

src/Symfony/Component/Form/Extension/Core/DataTransformer/MoneyToLocalizedStringTransformer.php

@@ -23,17 +23,17 @@ class MoneyToLocalizedStringTransformer extends NumberToLocalizedStringTransform
 {
     private $divisor;
 
-    public function __construct($precision = 2, $grouping = true, $roundingMode = self::ROUND_HALF_UP, $divisor = 1)
+    public function __construct($scale = 2, $grouping = true, $roundingMode = self::ROUND_HALF_UP, $divisor = 1)
     {
         if (null === $grouping) {
             $grouping = true;
         }
 
-        if (null === $precision) {
+        if (null === $scale) {
-            $precision = 2;
+            $scale = 2;
         }
 
-        parent::__construct($precision, $grouping, $roundingMode);
+        parent::__construct($scale, $grouping, $roundingMode);
 
         if (null === $divisor) {
             $divisor = 1;

src/Symfony/Component/Form/Extension/Core/DataTransformer/NumberToLocalizedStringTransformer.php

@@ -93,13 +93,16 @@ class NumberToLocalizedStringTransformer implements DataTransformerInterface
      */
     const ROUND_HALFDOWN = \NumberFormatter::ROUND_HALFDOWN;
 
+    /**
+     * @deprecated since version 2.7, will be replaced by a $scale private property in 3.0.
+     */
     protected $precision;
 
     protected $grouping;
 
     protected $roundingMode;
 
-    public function __construct($precision = null, $grouping = false, $roundingMode = self::ROUND_HALF_UP)
+    public function __construct($scale = null, $grouping = false, $roundingMode = self::ROUND_HALF_UP)
     {
         if (null === $grouping) {
             $grouping = false;
@@ -109,7 +112,7 @@ class NumberToLocalizedStringTransformer implements DataTransformerInterface
             $roundingMode = self::ROUND_HALF_UP;
         }
 
-        $this->precision = $precision;
+        $this->precision = $scale;
         $this->grouping = $grouping;
         $this->roundingMode = $roundingMode;
     }
@@ -240,7 +243,7 @@ class NumberToLocalizedStringTransformer implements DataTransformerInterface
     }
 
     /**
-     * Rounds a number according to the configured precision and rounding mode.
+     * Rounds a number according to the configured scale and rounding mode.
      *
      * @param int|float $number A number.
      *
@@ -249,7 +252,7 @@ class NumberToLocalizedStringTransformer implements DataTransformerInterface
     private function round($number)
     {
         if (null !== $this->precision && null !== $this->roundingMode) {
-            // shift number to maintain the correct precision during rounding
+            // shift number to maintain the correct scale during rounding
             $roundingCoef = pow(10, $this->precision);
             $number *= $roundingCoef;
 

src/Symfony/Component/Form/Extension/Core/DataTransformer/PercentToLocalizedStringTransformer.php

@@ -33,22 +33,22 @@ class PercentToLocalizedStringTransformer implements DataTransformerInterface
 
     private $type;
 
-    private $precision;
+    private $scale;
 
     /**
      * Constructor.
      *
      * @see self::$types for a list of supported types
      *
-     * @param int    $precision The precision
+     * @param int    $scale The scale
-     * @param string $type      One of the supported types
+     * @param string $type  One of the supported types
      *
      * @throws UnexpectedTypeException if the given value of type is unknown
      */
-    public function __construct($precision = null, $type = null)
+    public function __construct($scale = null, $type = null)
     {
-        if (null === $precision) {
+        if (null === $scale) {
-            $precision = 0;
+            $scale = 0;
         }
 
         if (null === $type) {
@@ -60,7 +60,7 @@ class PercentToLocalizedStringTransformer implements DataTransformerInterface
         }
 
         $this->type = $type;
-        $this->precision = $precision;
+        $this->scale = $scale;
     }
 
     /**
@@ -142,7 +142,7 @@ class PercentToLocalizedStringTransformer implements DataTransformerInterface
     {
         $formatter = new \NumberFormatter(\Locale::getDefault(), \NumberFormatter::DECIMAL);
 
-        $formatter->setAttribute(\NumberFormatter::FRACTION_DIGITS, $this->precision);
+        $formatter->setAttribute(\NumberFormatter::FRACTION_DIGITS, $this->scale);
 
         return $formatter;
     }

src/Symfony/Component/Form/Extension/Core/Type/IntegerType.php

@@ -14,6 +14,7 @@ namespace Symfony\Component\Form\Extension\Core\Type;
 use Symfony\Component\Form\AbstractType;
 use Symfony\Component\Form\FormBuilderInterface;
 use Symfony\Component\Form\Extension\Core\DataTransformer\IntegerToLocalizedStringTransformer;
+use Symfony\Component\OptionsResolver\Options;
 use Symfony\Component\OptionsResolver\OptionsResolver;
 
 class IntegerType extends AbstractType
@@ -25,7 +26,7 @@ class IntegerType extends AbstractType
     {
         $builder->addViewTransformer(
             new IntegerToLocalizedStringTransformer(
-                $options['precision'],
+                $options['scale'],
                 $options['grouping'],
                 $options['rounding_mode']
         ));
@@ -36,9 +37,19 @@ class IntegerType extends AbstractType
      */
     public function configureOptions(OptionsResolver $resolver)
     {
+        $scale = function (Options $options) {
+            if (null !== $options['precision']) {
+                trigger_error('The form option "precision" is deprecated since version 2.7 and will be removed in 3.0. Use "scale" instead.', E_USER_DEPRECATED);
+            }
+
+            return $options['precision'];
+        };
+
         $resolver->setDefaults(array(
-            // default precision is locale specific (usually around 3)
+            // deprecated as of Symfony 2.7, to be removed in Symfony 3.0.
             'precision' => null,
+            // default scale is locale specific (usually around 3)
+            'scale' => $scale,
             'grouping' => false,
             // Integer cast rounds towards 0, so do the same when displaying fractions
             'rounding_mode' => IntegerToLocalizedStringTransformer::ROUND_DOWN,
@@ -54,6 +65,8 @@ class IntegerType extends AbstractType
             IntegerToLocalizedStringTransformer::ROUND_UP,
             IntegerToLocalizedStringTransformer::ROUND_CEILING,
         ));
+
+        $resolver->setAllowedTypes('scale', array('null', 'int'));
     }
 
     /**

src/Symfony/Component/Form/Extension/Core/Type/MoneyType.php

@@ -16,6 +16,7 @@ use Symfony\Component\Form\FormInterface;
 use Symfony\Component\Form\FormBuilderInterface;
 use Symfony\Component\Form\Extension\Core\DataTransformer\MoneyToLocalizedStringTransformer;
 use Symfony\Component\Form\FormView;
+use Symfony\Component\OptionsResolver\Options;
 use Symfony\Component\OptionsResolver\OptionsResolver;
 
 class MoneyType extends AbstractType
@@ -29,7 +30,7 @@ class MoneyType extends AbstractType
     {
         $builder
             ->addViewTransformer(new MoneyToLocalizedStringTransformer(
-                $options['precision'],
+                $options['scale'],
                 $options['grouping'],
                 null,
                 $options['divisor']
@@ -50,13 +51,27 @@ class MoneyType extends AbstractType
      */
     public function configureOptions(OptionsResolver $resolver)
     {
+        $scale = function (Options $options) {
+            if (null !== $options['precision']) {
+                trigger_error('The form option "precision" is deprecated since version 2.7 and will be removed in 3.0. Use "scale" instead.', E_USER_DEPRECATED);
+
+                return $options['precision'];
+            }
+
+            return 2;
+        };
+
         $resolver->setDefaults(array(
-            'precision' => 2,
+            // deprecated as of Symfony 2.7, to be removed in Symfony 3.0
+            'precision' => null,
+            'scale' => $scale,
             'grouping' => false,
             'divisor' => 1,
             'currency' => 'EUR',
             'compound' => false,
         ));
+
+        $resolver->setAllowedTypes('scale', 'int');
     }
 
     /**

src/Symfony/Component/Form/Extension/Core/Type/NumberType.php

@@ -14,6 +14,7 @@ namespace Symfony\Component\Form\Extension\Core\Type;
 use Symfony\Component\Form\AbstractType;
 use Symfony\Component\Form\FormBuilderInterface;
 use Symfony\Component\Form\Extension\Core\DataTransformer\NumberToLocalizedStringTransformer;
+use Symfony\Component\OptionsResolver\Options;
 use Symfony\Component\OptionsResolver\OptionsResolver;
 
 class NumberType extends AbstractType
@@ -24,7 +25,7 @@ class NumberType extends AbstractType
     public function buildForm(FormBuilderInterface $builder, array $options)
     {
         $builder->addViewTransformer(new NumberToLocalizedStringTransformer(
-            $options['precision'],
+            $options['scale'],
             $options['grouping'],
             $options['rounding_mode']
         ));
@@ -35,9 +36,19 @@ class NumberType extends AbstractType
      */
     public function configureOptions(OptionsResolver $resolver)
     {
+        $scale = function (Options $options) {
+            if (null !== $options['precision']) {
+                trigger_error('The form option "precision" is deprecated since version 2.7 and will be removed in 3.0. Use "scale" instead.', E_USER_DEPRECATED);
+            }
+
+            return $options['precision'];
+        };
+
         $resolver->setDefaults(array(
-            // default precision is locale specific (usually around 3)
+            // deprecated as of Symfony 2.7, to be removed in Symfony 3.0
             'precision' => null,
+            // default scale is locale specific (usually around 3)
+            'scale' => $scale,
             'grouping' => false,
             'rounding_mode' => NumberToLocalizedStringTransformer::ROUND_HALF_UP,
             'compound' => false,
@@ -52,6 +63,8 @@ class NumberType extends AbstractType
             NumberToLocalizedStringTransformer::ROUND_UP,
             NumberToLocalizedStringTransformer::ROUND_CEILING,
         ));
+
+        $resolver->setAllowedTypes('scale', array('null', 'int'));
     }
 
     /**

src/Symfony/Component/Form/Extension/Core/Type/PercentType.php

@@ -14,6 +14,7 @@ namespace Symfony\Component\Form\Extension\Core\Type;
 use Symfony\Component\Form\AbstractType;
 use Symfony\Component\Form\FormBuilderInterface;
 use Symfony\Component\Form\Extension\Core\DataTransformer\PercentToLocalizedStringTransformer;
+use Symfony\Component\OptionsResolver\Options;
 use Symfony\Component\OptionsResolver\OptionsResolver;
 
 class PercentType extends AbstractType
@@ -23,7 +24,7 @@ class PercentType extends AbstractType
      */
     public function buildForm(FormBuilderInterface $builder, array $options)
     {
-        $builder->addViewTransformer(new PercentToLocalizedStringTransformer($options['precision'], $options['type']));
+        $builder->addViewTransformer(new PercentToLocalizedStringTransformer($options['scale'], $options['type']));
     }
 
     /**
@@ -31,8 +32,20 @@ class PercentType extends AbstractType
      */
     public function configureOptions(OptionsResolver $resolver)
     {
+        $scale = function (Options $options) {
+            if (null !== $options['precision']) {
+                trigger_error('The form option "precision" is deprecated since version 2.7 and will be removed in 3.0. Use "scale" instead.', E_USER_DEPRECATED);
+
+                return $options['precision'];
+            }
+
+            return 0;
+        };
+
         $resolver->setDefaults(array(
-            'precision' => 0,
+            // deprecated as of Symfony 2.7, to be removed in Symfony 3.0.
+            'precision' => null,
+            'scale' => $scale,
             'type' => 'fractional',
             'compound' => false,
         ));
@@ -41,6 +54,8 @@ class PercentType extends AbstractType
             'fractional',
             'integer',
         ));
+
+        $resolver->setAllowedTypes('scale', 'int');
     }
 
     /**

src/Symfony/Component/Form/Tests/Extension/Core/DataTransformer/NumberToLocalizedStringTransformerTest.php

@@ -74,7 +74,7 @@ class NumberToLocalizedStringTransformerTest extends \PHPUnit_Framework_TestCase
         $this->assertSame($to, $transformer->transform($from));
     }
 
-    public function testTransformWithPrecision()
+    public function testTransformWithScale()
     {
         $transformer = new NumberToLocalizedStringTransformer(2);
 
@@ -174,14 +174,14 @@ class NumberToLocalizedStringTransformerTest extends \PHPUnit_Framework_TestCase
     /**
      * @dataProvider transformWithRoundingProvider
      */
-    public function testTransformWithRounding($precision, $input, $output, $roundingMode)
+    public function testTransformWithRounding($scale, $input, $output, $roundingMode)
     {
-        $transformer = new NumberToLocalizedStringTransformer($precision, null, $roundingMode);
+        $transformer = new NumberToLocalizedStringTransformer($scale, null, $roundingMode);
 
         $this->assertEquals($output, $transformer->transform($input));
     }
 
-    public function testTransformDoesNotRoundIfNoPrecision()
+    public function testTransformDoesNotRoundIfNoScale()
     {
         $transformer = new NumberToLocalizedStringTransformer(null, null, NumberToLocalizedStringTransformer::ROUND_DOWN);
 
@@ -327,14 +327,14 @@ class NumberToLocalizedStringTransformerTest extends \PHPUnit_Framework_TestCase
     /**
      * @dataProvider reverseTransformWithRoundingProvider
      */
-    public function testReverseTransformWithRounding($precision, $input, $output, $roundingMode)
+    public function testReverseTransformWithRounding($scale, $input, $output, $roundingMode)
     {
-        $transformer = new NumberToLocalizedStringTransformer($precision, null, $roundingMode);
+        $transformer = new NumberToLocalizedStringTransformer($scale, null, $roundingMode);
 
         $this->assertEquals($output, $transformer->reverseTransform($input));
     }
 
-    public function testReverseTransformDoesNotRoundIfNoPrecision()
+    public function testReverseTransformDoesNotRoundIfNoScale()
     {
         $transformer = new NumberToLocalizedStringTransformer(null, null, NumberToLocalizedStringTransformer::ROUND_DOWN);
 

src/Symfony/Component/Form/Tests/Extension/Core/DataTransformer/PercentToLocalizedStringTransformerTest.php

@@ -53,7 +53,7 @@ class PercentToLocalizedStringTransformerTest extends \PHPUnit_Framework_TestCas
         $this->assertEquals('16', $transformer->transform(15.9));
     }
 
-    public function testTransformWithPrecision()
+    public function testTransformWithScale()
     {
         $transformer = new PercentToLocalizedStringTransformer(2);
 
@@ -87,7 +87,7 @@ class PercentToLocalizedStringTransformerTest extends \PHPUnit_Framework_TestCas
         $this->assertEquals(200, $transformer->reverseTransform('200'));
     }
 
-    public function testReverseTransformWithPrecision()
+    public function testReverseTransformWithScale()
     {
         $transformer = new PercentToLocalizedStringTransformer(2);
 

src/Symfony/Component/Form/Tests/Extension/Core/Type/NumberTypeTest.php

@@ -44,9 +44,9 @@ class NumberTypeTest extends TestCase
         $this->assertSame('12.345,679', $view->vars['value']);
     }
 
-    public function testDefaultFormattingWithPrecision()
+    public function testDefaultFormattingWithScale()
     {
-        $form = $this->factory->create('number', null, array('precision' => 2));
+        $form = $this->factory->create('number', null, array('scale' => 2));
         $form->setData('12345.67890');
         $view = $form->createView();
 
@@ -55,7 +55,7 @@ class NumberTypeTest extends TestCase
 
     public function testDefaultFormattingWithRounding()
     {
-        $form = $this->factory->create('number', null, array('precision' => 0, 'rounding_mode' => \NumberFormatter::ROUND_UP));
+        $form = $this->factory->create('number', null, array('scale' => 0, 'rounding_mode' => \NumberFormatter::ROUND_UP));
         $form->setData('12345.54321');
         $view = $form->createView();