Warning: Don't modify ANY Yii 2 configs until you finish this article - you might lose your changes!

Configuration files can be a pain. Most frameworks have only 1 and that means that settings local to the developer need to go into it (and not be checked into source control), as well as usernames and passwords etc. It is very easy for temporary configuration to accidentally get added to a production environment and potentially cause all manner of problems.

Yii 2 have solved this in a clever but slightly complicated way! You might notice, especially if you chose the "advanced template", that there are about 20 configuration files. Which ones are you supposed to modify?

There are really two types of config (ignoring parameters, which work in a similar way), local and non-local. They are both merged at runtime to produce the final configuration so you can change either and the result will be the same but.....

...local settings should NOT be checked into source control. In other words, any config with "-local" on the end should only be for local settings and not for anything that needs to be deployed or kept in source control. Examples of this include things you are just testing for now or perhaps access to Gii, which you can easily add locally and not need to deploy to the live site.

So once you have decided whether your config needs to be local or non-local, which file do you actually change? It depends on the template but let us consider the advanced one, since it is the most complicated.

The simplest answer is that if the config applies to the back AND front end, you change /common/config/main.php or main-local.php. If it only applies to the front end, you change frontend/config/main.php (or main-local.php) and likewise for back end. This, again, is useful if the backend is hosted privately and might need a higher privileged database connection string than the one deployed to the front end for instance.

OK so far? There is one more complication. It is still possible that something needs to be set in config but only in development, not in production. If you want to properly test the production deployment, you need to easily remove your local configuration settings and restore them again when you are developing again. You don't want to do this manually, otherwise you are likely to get something wrong.

If you have noticed the environments folder, this is what that's for. There are more configuration files under e.g. environments/dev/common/config and these are only for local config, that is config that is only used for you and no-one else but since there are separate folders for each environment, you can decide that some of your local settings only apply to a particular environment and only put them into one main-local file.

Why did I say not to change anything till you read all of this? If you do NOT use the environments capability of Yii 2, then you might as well just change the configs in /common, /frontend and /backend (it's quicker and easier) BUT if you DO use environments, the top level local files will be overwritten by the files underneath the environment variables when you run init. In other words, if you only changed /common/config/main-local.php and then use "init --env=Dev" on the command line, you will lose your change as it is overwritten by /enviroments/dev/config/common/main-local.php. To be sure, you should probably always change the main-local files under each environment and then run "init --env=whatever" to copy them into the relevant place!

A bit more hassle, and I'm yet to be convinced that this hassle is worth it for the times when configuration trips us over but it's fairly powerful so fill your boots!