Where can a module safely store Project Config settings?

Question

I can add a custom setting to the Project Config like so:

Craft::$app->getProjectConfig()->set('modules.module-name.settingName', true);

In the project.yaml file that would get saved at the top level:

config/project/project.yaml

dateModified: 1633752346
plugins:
    plugin-name:
        edition: pro
modules:
    module-name:
        settingName: true

Is this safe to do? Does Craft care if there are custom settings at the top level of the project.yaml file? Would Craft ever overwrite these during some other action?

Are there any naming or placement conventions I should follow if I have custom project config settings that don't fit into the 'plugins' category?

Answer 1

Manually updating the project.yaml file is not recommended, in my opinion, especially if adding your own custom settings. It is not intended for manual editing and can be rebuilt from the database, if prompted to.

There's also a risk that your code will not have any effect if project config is in read-only mode.

Instead, I would create a config settings file in the /config directory and pull in the settings, similar to how the plugins service does (another reason I prefer plugins over modules):

$settings = Craft::$app->getConfig()->getConfigFromFile($this->id);

This method is much easier to manage, changes are easier to track via version control, and it allows for environment-aware settings.

See: https://github.com/craftcms/cms/blob/d927d5662e9bfc61b9c3bc5d02dba8d24a7c36a5/src/services/Plugins.php#L965-L968