Document `$database_charset` setting in `settings.php`
Backdrop allows the use of UTF8-MB4 database encoding (which allows for the use of Asian characters and emojis). This feature is documented online at this page.
It would be great to also see some documentation about this feature in the settings.php file, as a commented line, like all other features in this file.
At the time this feature was implemented, many MySQL/MariaDB installs did not have the required configuration set as defaults. Now they do. It would be nice if we could include this line as a not-commented out line. Like the default database connection and prefix. Right now the installer appends the line at the bottom of the file if the site supports UTF-8 MB4. Now that this is so widespread it'd be better IMO if we included it by default at the top of the file with the default of utf8mb4, and commented-out if necessary.
PR filed at https://github.com/backdrop/backdrop/pull/4259 that documents the $database_charset value and includes setting it to utf8mb4 by default now. When running the installer, it will update this line to be utf8 if utf8mb4 is not supported.
While updating the documentation for database connections, I also added a sentence about $database_prefix, and replaced the single instance of master/slave terminology with primary/replica (as is done in https://github.com/backdrop/backdrop-issues/issues/4451). Since we don't often update settings.php, I thought it would be a good opportunity to change this single instance.
To test:
- Start with an empty database and clean settings.php file from this PR.
- Visit
core/install.php. - Select English as the install language.
- Enter your database credentials.
- Install Backdrop.
- If your database supports UTF8MB4 the
$database,$config_directoriesand$settings['hash_salt']lines should be updated. The$database_charsetline should stay the same, since it is nowutf8mb4out of the box. - If your database does not support UTF8MB4, the
$database_charsetline should be rewritten by the installer to beutf8. - You can also confirm the line gets updated if your server does support UTF8MB4 by starting over, and set the line to
utf8before running install.php. After entering the database credentials, the line will be switched toutf8mb4.
Note that the settings.php file only gets automatically rewritten if you set the database string through the UI. If You specify a string directly in settings.php, the database settings UI portion of the installer is skipped, and whatever value is in settings.php for $database_charset is left unmodified. I think that's expected for anyone manually setting their database configuring in settings.php.
PHPCS flagged coding standards in settings.php. Although the flagged lines are not part of this PR's changes, it might be appropriate to make the changes here.
There is the question (in the PR) of whether to use primary/replica (as in https://github.com/backdrop/backdrop-issues/issues/4451) or primary/secondary (as in https://docs.backdropcms.org/documentation/database-configuration). If we use the former, we should update the docs page, and vice-versa. Which is preferred?