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:


dateModified: 1633752346
        edition: pro
        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?

1 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

  • Still improving my understanding here but it seems that if you save settings to project config using Craft::$app->getProjectConfig()->set('modules.module-name.settingName', true) that key/value pair does get added to the projectconfig table in the db and get rebuilt when I hit "Rebuild" in the project config utility. Nov 12, 2021 at 19:07
  • 1
    Yes, it looks like it does get added to the DB and therefore persists, since the rebuild() method starts off with the loaded project config and overrides certain things, but leaves your changes in place: github.com/craftcms/cms/blob/… I still believe that a config settings file is a much more appropriate place to store what appears to be a setting, and have updated my answer with some further reasons.
    – Ben Croker
    Nov 13, 2021 at 9:54

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.