Add doc page for settings.php example uses

[izmeez]

There are many things that can be done with the settings.php or settings.local.php file. It would be helpful to have these ideas collected and available on a docs page.

1. Where would a suitable location for such a page? Possible added to https://docs.backdropcms.org/documentation/advanced-installation

2. What are some examples of content?

Taken from the zulipchat where this originated, https://backdrop.zulipchat.com/#narrow/channel/218635-Backdrop/topic/IP.20Ban.20not.20always.20banning.3F/near/530134654 here is one example from @quicksketch

If you really need to block all traffic for banned IP's even on cached pages and don't have another tool provided by your hosting provider, then you can make Backdrop execute hook_boot() by adding this line to settings.php:

$settings['page_cache_invoke_hooks'] = TRUE;

That will make Ban module work as you might expect, but with the trade-off that all cached pages may be returned slightly slower.

[yorkshire-pudding]

We could search the code for settings_get

[izmeez]

https://docs.backdropcms.org/api/backdrop/core%21includes%21bootstrap.inc/function/settings_get/1

[yorkshire-pudding]

I think this list will cover all the ones in core:
https://docs.backdropcms.org/api/backdrop/core%21includes%21bootstrap.inc/function/calls/settings_get/1

It might take a while to write explainers for each use, but could be good to start.

A question, should this include the items within settings.php that already have documentation so that everything about advanced settings.php setup can be in one place?

[swampopus]

I have no idea if this is possible-- but with the api module, is there any way to document a specific setting key, so that it shows up in the api pages? Similar to how Globals show up here: https://docs.backdropcms.org/api/backdrop/globals

I assume that is just parsing the actual source code to get the descriptions. If that can be set up, keeping a settings.api.php file in core (or whatever) might be a good place to keep this information; then it can be parsed into the API site automatically without adding nodes to docs.backdropcms.org.

[quicksketch]

Yes, it's totally possible since API module is just a bunch of custom parsers. Though sometimes it might make sense to elaborate on documentation beyond what's in settings.php. And sometimes docs are easier for people to update if they don't need to go through the core review process just to update documentation.

Still, it would help and it would be automatic, so improving API module is a good potential idea.