backdrop
Improve the database configuration comments in settings.php.
It's been suggested that we add some description of the array format for database configuration in settings.php. See discussion starting here (and links therein):
https://github.com/backdrop/backdrop-issues/issues/2231#issuecomment-1904857316
Currently in the docblock for $database, there is a link to "advanced database documentation" at https://api.backdropcms.org/database-configuration. However, this currently redirects to https://docs.backdropcms.org/documentation/database-configuration, and so at the very least, we should update the link.
As for whether to add some commentary about the array format directly (rather than relying on click-through to the advanced docs), reasonable minds may differ, but I think the penalty of the extra reading material would be worth increasing people's awareness of the existence of of the array format. So perhaps giving a single example of the array format in the docblock, then directing the reader to the documentation page for the details.
Thanks for opening this issue. This is the type of information that it doesn't hurt to have in more than one place and right now it's nowhere easy to find.
I'd like to see something in the settings.php file along these lines:
/**
* Like D7, each database connection can be specified as an array of settings.
* This may be useful to override default MySQL utf8mb4_general_ci collation.
* Note: localhost, because it is a socket, may be faster than TCP/IP 127.0.0.1
*
* $databases['default']['default'] = array(
* 'driver' => 'mysql',
* 'database' => 'databasename',
* 'username' => 'username',
* 'password' => 'password',
* 'host' => 'localhost',
* 'charset' => 'utf8mb4',
* 'collation' => 'utf8mb4_unicode_ci',
* );
*/
The line noting that localhost is a socket is true for both methods and maybe belongs somewhere earlier in the file.
Also from my comment in the other issue, the array syntax works with Backdrop. as is. However, a fresh install issues a warning with php 8.1.10 as follows:
Deprecated function: md5(): Passing null to parameter #1 ($string) of type string is deprecated in backdrop_install_config_directories() (line 806 of \core\includes\install.inc).
Maybe this needs to be a separate issue?
Also, before using the array syntax, I thought to try $database_collation = 'utf8mb4_unicode_ci'; in settings.php only to discover it is not currently part of Backdrop core. This could be another separate issue.
This is probably better wording:
/**
* Alternatively, database connection can be specified as an array of settings.
* This may be useful to override default MySQL utf8mb4_general_ci collation.
*/
The other line, if it is a known fact can appear earlier:
* advanced database documentation at
* https://api.backdropcms.org/database-configuration
*
* Note: localhost, because it is a socket, may be faster than TCP/IP 127.0.0.1
*/
Which is better?
1. * This may be useful to override default MySQL utf8mb4_general_ci collation.
2. * This may be useful to override default MySQL collation, utf8mb4_general_ci.
@izmeez @bugfolder - please note the discussion regarding level of documentation in settings.php
https://github.com/backdrop/backdrop-issues/issues/2231#issuecomment-2333618035
@yorkshire-pudding Thanks for bringing the issue to the dev meeting for discussion and for providing a link to the time. Following the discussion I am wondering where this leaves things. Is it just a matter of improving the comments in settings.php file as opposed to switching to a simplified array? In other words should this issue and #2231 be combined? Either way I think the additional comment in settings.php should include a brief comment that this may be needed for passwords with special characters and the utf8mb charset and collation lines should be included and a link to the documentation page. The "like D7" stuff can be dropped and replaced with "Alternatively,".
@yorkshire-pudding Thanks for bringing the issue to the dev meeting for discussion and for providing a link to the time. Following the discussion I am wondering where this leaves things. Is it just a matter of improving the comments in settings.php file as opposed to switching to a simplified array? In other words should this issue and #2231 be combined? Either way I think the additional comment in settings.php should include a brief comment that this may be needed for passwords with special characters and the utf8mb charset and collation lines should be included and a link to the documentation page. The "like D7" stuff can be dropped and replaced with "Alternatively,".
@izmeez - I will be reviving my old PR as it will need rebasing. We will be moving towards the simplified array and providing short documentation but looking to improve the online documentation.
Going forward, the installer will write to the simplified array rather than the db URL string, which, even with encoding, can still cause issues with certain passwords..
Backdrop will support three different methods, the string, the simplified array and the D7-like array, which will be needed if people have secondary databases. The D7-like array is used internally anyway.
Hope that helps. It might be simpler to focus on one issue so all the changes happen at the same time
The PR uses a more verbose comment than that suggested in #2231. However, I would suggest that providing more information in the comment may require less time for users to address their needs, while providing a link to the documentation for more advanced configuration.