Merge branch '2.8'

weaverryan · weaverryan · commit c1cbb9afe28f · 2015-05-03T18:16:30.000-04:00
* 2.8:
  Rewrite utf8mb4 cautions, add comment into sample configuration
  Add backticks for code-styling
  Indenting caution block to nest it inside the sidebar
  Revert "Fix example name to avoid breaking collision with standard data-collectors"
  Revert "Add a cautionary note telling users where the "standard" data-collector names can be found."
  Add a cautionary note telling users where the "standard" data-collector names can be found.
  Fix example name to avoid breaking collision with standard data-collectors
  Change MySQL UTF-8 examples to use utf8mb4, which is closer to the standard most people would expect
  [Cookbook] Custom compile steps on Heroku
  Added information about the Symfony Demo application
  Renamed precision option to scale
diff --git a/best_practices/introduction.rst b/best_practices/introduction.rst
@@ -69,15 +69,23 @@ what you already know.
 The Application
 ---------------
 
-In addition to this guide, you'll find a sample application developed with
-all these best practices in mind. **The application is a simple blog engine**,
-because that will allow us to focus on the Symfony concepts and features without
-getting buried in difficult details.
+In addition to this guide, a sample application has been developed with all these
+best practices in mind. This project, called the Symfony Demo application, can
+be obtained through the Symfony Installer. First, `download and install`_ the
+installer and then execute this command to download the demo application:
 
-Instead of developing the application step by step in this guide, you'll find
-selected snippets of code through the chapters. Please refer to the last chapter
-of this guide to find more details about this application and the instructions
-to install it.
+.. code-block:: bash
+
+    # Linux and Mac OS X
+    $ symfony demo
+
+    # Windows
+    c:\> php symfony demo
+
+**The demo application is a simple blog engine**, because that will allow us to
+focus on the Symfony concepts and features without getting buried in difficult
+implementation details. Instead of developing the application step by step in
+this guide, you'll find selected snippets of code through the chapters.
 
 Don't Update Your Existing Applications
 ---------------------------------------
@@ -95,3 +103,4 @@ practices**. The reasons for not doing it are various:
   your tests or adding features that provide real value to the end users.
 
 .. _`Fabien Potencier`: https://connect.sensiolabs.com/profile/fabpot
+.. _`download and install`: http://symfony.com/download
diff --git a/book/doctrine.rst b/book/doctrine.rst
@@ -141,8 +141,13 @@ for you:
     .. code-block:: ini
 
         [mysqld]
-        collation-server = utf8_general_ci
-        character-set-server = utf8
+        # Version 5.5.3 introduced "utf8mb4", which is recommended
+        collation-server     = utf8mb4_general_ci # Replaces utf8_general_ci
+        character-set-server = utf8mb4            # Replaces utf8
+
+    We recommend against MySQL's ``utf8`` character set, since it does not
+    support 4-byte unicode characters, and strings containing them will be
+    truncated. This is fixed by the `newer utf8mb4 character set`_.
 
 .. note::
 
@@ -1422,3 +1427,4 @@ For more information about Doctrine, see the *Doctrine* section of the
 .. _`migrations`: http://symfony.com/doc/current/bundles/DoctrineMigrationsBundle/index.html
 .. _`DoctrineFixturesBundle`: http://symfony.com/doc/current/bundles/DoctrineFixturesBundle/index.html
 .. _`FrameworkExtraBundle documentation`: http://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/converters.html
+.. _`newer utf8mb4 character set`: https://dev.mysql.com/doc/refman/5.5/en/charset-unicode-utf8mb4.html
diff --git a/cookbook/deployment/heroku.rst b/cookbook/deployment/heroku.rst
@@ -235,6 +235,85 @@ You should be seeing your Symfony application in your browser.
     AcmeDemoBundle is only loaded in the dev environment (check out your
     ``AppKernel`` class). Try opening ``/app/example`` from the AppBundle.
 
+Custom Compile Steps
+~~~~~~~~~~~~~~~~~~~~
+
+If you wish to execute additional custom commands during a build, you can leverage
+Heroku's `custom compile steps`_. Imagine you want to remove the ``dev`` front controller
+from your production environment on Heroku in order to avoid a potential vulnerability.
+Adding a command to remove ``web/app_dev.php`` to Composer's `post-install-commands`_ would
+work, but it also removes the controller in your local development environment on each
+``composer install`` or ``composer update`` respectively. Instead, you can add a
+`custom Composer command`_ named ``compile`` (this key name is a Heroku convention) to the
+``scripts`` section of your ``composer.json``. The listed commands hook into Heroku's deploy
+process:
+
+.. code-block:: json
+
+    {
+        "scripts": {
+            "compile": [
+                "rm web/app_dev.php"
+            ]
+        }
+    }
+
+This is also very useful to build assets on the production system, e.g. with Assetic:
+
+.. code-block:: json
+
+    {
+        "scripts": {
+            "compile": [
+                "app/console assetic:dump"
+            ]
+        }
+    }
+
+.. sidebar:: Node.js Dependencies
+
+    Building assets may depend on node packages, e.g. ``uglifyjs`` or ``uglifycss``
+    for asset minification. Installing node packages during the deploy requires a node
+    installation. But currently, Heroku compiles your app using the PHP buildpack, which
+    is auto-detected by the presence of a ``composer.json`` file, and does not include a
+    node installation. Because the Node.js buildpack has a higher precedence than the PHP
+    buildpack (see `Heroku buildpacks`_), adding a ``package.json`` listing your node
+    dependencies makes Heroku opt for the Node.js buildpack instead:
+
+    .. code-block:: json
+
+        {
+            "name": "myApp",
+            "engines": {
+                "node": "0.12.x"
+            },
+            "dependencies": {
+                "uglifycss": "*",
+                "uglify-js": "*"
+            }
+        }
+
+    With the next deploy, Heroku compiles your app using the Node.js buildpack and
+    your npm packages become installed. On the other hand, your ``composer.json`` is
+    now ignored. To compile your app with both buildpacks, Node.js *and* PHP, you can
+    use a special `multiple buildpack`_. To override buildpack auto-detection, you
+    need to explicitly set the buildpack URL:
+
+    .. code-block:: bash
+
+        $ heroku buildpack:set https://github.com/ddollar/heroku-buildpack-multi.git
+
+    Next, add a ``.buildpacks`` file to your project, listing the buildpacks you need:
+
+    .. code-block:: text
+
+        https://github.com/heroku/heroku-buildpack-nodejs.git
+        https://github.com/heroku/heroku-buildpack-php.git
+
+    With the next deploy, you can benefit from both buildpacks. This setup also enables
+    your Heroku environment to make use of node based automatic build tools like
+    `Grunt`_ or `gulp`_.
+
 .. _`the original article`: https://devcenter.heroku.com/articles/getting-started-with-symfony2
 .. _`signup with Heroku`: https://signup.heroku.com/signup/dc
 .. _`Heroku Toolbelt`: https://devcenter.heroku.com/articles/getting-started-with-php#local-workstation-setup
@@ -244,3 +323,9 @@ You should be seeing your Symfony application in your browser.
 .. _`verified that the RSA key fingerprint is correct`: https://devcenter.heroku.com/articles/git-repository-ssh-fingerprints
 .. _`post-install-commands`: https://getcomposer.org/doc/articles/scripts.md
 .. _`config vars`: https://devcenter.heroku.com/articles/config-vars
+.. _`custom compile steps`: https://devcenter.heroku.com/articles/php-support#custom-compile-step
+.. _`custom Composer command`: https://getcomposer.org/doc/articles/scripts.md#writing-custom-commands
+.. _`Heroku buildpacks`: https://devcenter.heroku.com/articles/buildpacks
+.. _`multiple buildpack`: https://github.com/ddollar/heroku-buildpack-multi.git
+.. _`Grunt`: http://gruntjs.com
+.. _`gulp`: http://gulpjs.com
diff --git a/reference/forms/types/integer.rst b/reference/forms/types/integer.rst
@@ -16,7 +16,7 @@ integers. By default, all non-integer values (e.g. 6.78) will round down (e.g. 6
 | Rendered as | ``input`` ``number`` field                                            |
 +-------------+-----------------------------------------------------------------------+
 | Options     | - `grouping`_                                                         |
-|             | - `precision`_                                                        |
+|             | - `scale`_                                                            |
 |             | - `rounding_mode`_                                                    |
 +-------------+-----------------------------------------------------------------------+
 | Inherited   | - `data`_                                                             |
@@ -42,7 +42,7 @@ Field Options
 
 .. include:: /reference/forms/types/options/grouping.rst.inc
 
-.. include:: /reference/forms/types/options/precision.rst.inc
+.. include:: /reference/forms/types/options/scale.rst.inc
 
 rounding_mode
 ~~~~~~~~~~~~~
diff --git a/reference/forms/types/money.rst b/reference/forms/types/money.rst
@@ -17,7 +17,7 @@ how the input and output of the data is handled.
 | Options     | - `currency`_                                                       |
 |             | - `divisor`_                                                        |
 |             | - `grouping`_                                                       |
-|             | - `precision`_                                                      |
+|             | - `scale`_                                                          |
 +-------------+---------------------------------------------------------------------+
 | Inherited   | - `data`_                                                           |
 | options     | - `disabled`_                                                       |
@@ -73,14 +73,18 @@ be set back on your object.
 
 .. include:: /reference/forms/types/options/grouping.rst.inc
 
-precision
-~~~~~~~~~
+scale
+~~~~~
+
+.. versionadded:: 2.7
+    The ``scale`` option was introduced in Symfony 2.7. Prior to Symfony 2.7,
+    it was known as ``precision``.
 
 **type**: ``integer`` **default**: ``2``
 
-For some reason, if you need some precision other than 2 decimal places,
+For some reason, if you need some scale other than 2 decimal places,
 you can modify this value. You probably won't need to do this unless,
-for example, you want to round to the nearest dollar (set the precision
+for example, you want to round to the nearest dollar (set the scale
 to ``0``).
 
 Inherited Options
diff --git a/reference/forms/types/number.rst b/reference/forms/types/number.rst
@@ -5,14 +5,14 @@ number Field Type
 =================
 
 Renders an input text field and specializes in handling number input. This
-type offers different options for the precision, rounding, and grouping that
-you want to use for your number.
+type offers different options for the scale, rounding and grouping that you
+want to use for your number.
 
 +-------------+----------------------------------------------------------------------+
 | Rendered as | ``input`` ``text`` field                                             |
 +-------------+----------------------------------------------------------------------+
 | Options     | - `grouping`_                                                        |
-|             | - `precision`_                                                       |
+|             | - `scale`_                                                           |
 |             | - `rounding_mode`_                                                   |
 +-------------+----------------------------------------------------------------------+
 | Inherited   | - `data`_                                                            |
@@ -38,14 +38,14 @@ Field Options
 
 .. include:: /reference/forms/types/options/grouping.rst.inc
 
-.. include:: /reference/forms/types/options/precision.rst.inc
+.. include:: /reference/forms/types/options/scale.rst.inc
 
 rounding_mode
 ~~~~~~~~~~~~~
 
 **type**: ``integer`` **default**: ``NumberToLocalizedStringTransformer::ROUND_HALFUP``
 
-If a submitted number needs to be rounded (based on the ``precision``
+If a submitted number needs to be rounded (based on the `scale`_
 option), you have several configurable options for that rounding. Each
 option is a constant on the :class:`Symfony\\Component\\Form\\Extension\\Core\\DataTransformer\\NumberToLocalizedStringTransformer`:
     
diff --git a/reference/forms/types/options/precision.rst.inc b/reference/forms/types/options/precision.rst.inc
diff --git a/reference/forms/types/options/scale.rst.inc b/reference/forms/types/options/scale.rst.inc
@@ -0,0 +1,13 @@
+scale
+~~~~~
+
+.. versionadded:: 2.7
+    The ``scale`` option was introduced in Symfony 2.7. Prior to Symfony 2.7,
+    it was known as ``precision``.
+
+**type**: ``integer`` **default**: Locale-specific (usually around ``3``)
+
+This specifies how many decimals will be allowed until the field rounds
+the submitted value (via ``rounding_mode``). For example, if ``scale`` is set
+to ``2``, a submitted value of ``20.123`` will be rounded to, for example,
+``20.12`` (depending on your `rounding_mode`_).
diff --git a/reference/forms/types/percent.rst b/reference/forms/types/percent.rst
@@ -15,7 +15,7 @@ This field adds a percentage sign "``%``" after the input box.
 +-------------+-----------------------------------------------------------------------+
 | Rendered as | ``input`` ``text`` field                                              |
 +-------------+-----------------------------------------------------------------------+
-| Options     | - `precision`_                                                        |
+| Options     | - `scale`_                                                            |
 |             | - `type`_                                                             |
 +-------------+-----------------------------------------------------------------------+
 | Inherited   | - `data`_                                                             |
@@ -39,13 +39,17 @@ This field adds a percentage sign "``%``" after the input box.
 Field Options
 -------------
 
-precision
-~~~~~~~~~
+scale
+~~~~~
+
+.. versionadded:: 2.7
+    The ``scale`` option was introduced in Symfony 2.7. Prior to Symfony 2.7,
+    it was known as ``precision``.
 
 **type**: ``integer`` **default**: ``0``
 
-By default, the input numbers are rounded. To allow for more decimal
-places, use this option.
+By default, the input numbers are rounded. To allow for more decimal places,
+use this option.
 
 type
 ~~~~
