A quick explainer about when to use config files in recipes, vs. config actions.

config-files-vs-actions.md

Recipe Dojo: config files vs. config actions

Recipes have two ways to affect site configuration:

1. They can have a config directory containing YAML files, like you'd find in a config/install directory or config export.
2. They can use config actions in their recipe.yml.

These techniques have different purposes and generally aren't interchangeable, but it's not always obvious which one to use. Well, I'm going to compare and contrast them, hopefully giving you a few rules of thumb.

Let's start with this:

Use config/*.yml files when you want your recipe to create new configuration that doesn't exist yet.

Use config actions when you want to make changes to config that already exists.

To put it another way:

Config files never change your site's config; they can only create it.

Config actions always change your site's config.

If you're familiar with recipes already, you might be wondering about the create and createIfNotExists config actions. Yes, they exist, and they are capable of creating config. But you know what? There are occasionally reasons to use them, but 95% of the time, you don't need to. So honestly, don't worry about it. Bug me on Slack if you really want to know more.

Here's another important distinction:

Config files respect the config:strict flag in recipe.yml. (strict: false means that the YAML files will not clash with your site's existing config; the existing config will "win".)

Config actions don't care what config:strict has to say. They will always do what they promise to, every time.

Another point worth making:

Config files can only create config.

Config actions can do just about anything.

Config actions are, at heart, fancy PHP functions that take two arguments: the name of a config object, and some arbitrary value. Internally, they can do anything they want.

Core has a shortcut (the #[ActionMethod] attribute) that makes methods of config entities available as config actions. But that's still just a slick, declarative way to...call PHP functions.

The final point I want to make:

Config files are for creating full config objects.

Config actions are for making small, well-targeted, guaranteed changes to existing config.

So, which should you use when building a recipe?

• If you want to supply a whole config entity, or set of config entities -- a classic example would be a content type, all of its fields, and a view to list that content -- use config files.
• If you want to make changes to existing config, use config actions.

Of course, recipes can (and should) use both techniques, and hopefully you have a better sense of how to choose. Now, go cook.