Skip to content

Update Doctrine UTF8 docs #6274

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Mar 17, 2016
Merged

Update Doctrine UTF8 docs #6274

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 49 additions & 4 deletions book/doctrine.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -131,10 +131,6 @@ for you:
$ php bin/console doctrine:database:drop --force
$ php bin/console doctrine:database:create

There's no way to configure these defaults inside Doctrine, as it tries to be
as agnostic as possible in terms of environment configuration. One way to solve
this problem is to configure server-level defaults.

Setting UTF8 defaults for MySQL is as simple as adding a few lines to
your configuration file (typically ``my.cnf``):

Expand All @@ -145,6 +141,55 @@ for you:
collation-server = utf8mb4_general_ci # Replaces utf8_general_ci
character-set-server = utf8mb4 # Replaces utf8
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

could/should we also just remove this section (134-142) now?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Shouldn't we keep this so that the MySQL settings are the same when accessing the database using other clients?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since the recommendation is to use utf8mb4 in all cases, I agree with @xabbuh that the purpose of this section is to help the user have the correct character set in all cases.


You can also change the defaults for Doctrine so that the generated SQL
uses the correct character set.

.. configuration-block::

.. code-block:: yaml

# app/config/config.yml
doctrine:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please add the filename to the top of the code block:

# app/config/config.yml

charset: utf8mb4
dbal:
default_table_options:
charset: utf8mb4
collate: utf8mb4_unicode_ci

.. code-block:: xml

<!-- app/config/config.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:doctrine="http://symfony.com/schema/dic/doctrine"
xsi:schemaLocation="http://symfony.com/schema/dic/services
http://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/doctrine
http://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd">

<doctrine:config>
<doctrine:dbal
charset="utf8mb4">
<doctrine:default-table-option name="charset">utf8mb4</doctrine:default-table-option>
<doctrine:default-table-option name="collate">utf8mb4_unicode_ci</doctrine:default-table-option>
</doctrine:dbal>
</doctrine:config>
</container>

.. code-block:: php

// app/config/config.php
$configuration->loadFromExtension('doctrine', array(
'dbal' => array(
'charset' => 'utf8mb4',
'default_table_options' => array(
'charset' => 'utf8mb4'
'collate' => 'utf8mb4_unicode_ci'
)
),
));

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`_.
Expand Down