Merge branch '2.3' into 2.6

* 2.3:
  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

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

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

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