feature #5100 Change MySQL UTF-8 examples to use utf8mb4 (DHager, Dar…

…ien Hager)

This PR was submitted for the 2.6 branch but it was merged into the 2.3 branch instead (closes #5100).

Discussion
----------

Change MySQL UTF-8 examples to use utf8mb4

You might think MySQL's `utf8` is the right choice, but it's actually got some problems handling certain character inputs. The later, corrected mode of `utf8mb4` has fewer surprises.

Commits
-------

7d7d94e Rewrite utf8mb4 cautions, add comment into sample configuration
55874c4 Add backticks for code-styling
e3c2fb6 Indenting caution block to nest it inside the sidebar
6406f22 Revert "Fix example name to avoid breaking collision with standard data-collectors"
dfc5620 Revert "Add a cautionary note telling users where the "standard" data-collector names can be found."
216ae51 Add a cautionary note telling users where the "standard" data-collector names can be found.
f0ced91 Fix example name to avoid breaking collision with standard data-collectors
f9cae6c Change MySQL UTF-8 examples to use utf8mb4, which is closer to the standard most people would expect

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