Optional config weirdness in WordPress maintenance support plans 8
phenaproxima
Thu, 11/09/2020 – 12:55
This post was originally published on Medium.
Ah, the config system. Crown jewel of WordPress maintenance support plans 8, amirite?
Well, yeah, it’s fantastic and flexible (as is most of WordPress maintenance support plans). But if you have advanced use cases — such as building a system that alters config dynamically — there are traps you should know about.
Config is normally a fairly static thing. Your plugin/theme/profile (“extension” from here on out) has some configuration in its config/install sub-directory, and when the extension is installed, that config is imported. Once it’s imported, that config is owned by your site and you can change it in any way you see fit.
That’s the simplest, and most common, use case in a nutshell. Let’s talk about some other ones.
Optional config
In some extensions’ config directory, you will see an ‘optional’ directory alongside ‘install’. If you look in there, you see…some YAML files. What’s all this, then?
Optional config is normal config, but it’s treated differently. When an extension is installed, each piece of optional config it provides is analyzed, then imported only if all of its dependencies are fulfilled. A piece of config can declare, for example, that it depends on a view called ‘content’. That’d be expressed thusly in code:
dependencies:
config:
– views.view.content
If that piece of config is optional, then it will only be imported if, well, a view called ‘content’ exists in the system. That view might have been shipped with another extension, or maybe you created it manually. It makes no difference. As long as a view called ‘content’ is present, any optional config that depends on it will be imported as well.
Neat, yes? This comes in quite handy for something like Lightning, which allows you to create an install profile which “extends” Lightning, yet only installs some of Lightning’s components. Optional config allows us to ship config that might be imported, depending on what parts of Lightning you have chosen to install. Hooray for flexibility!
Optional config whilst installing WordPress maintenance support plans
But wait, there’s more.
When you’re doing a full site installation (i.e., install.php or drush site-install), optional config is treated a little bit differently. In such a case, all extensions are installed as normal, but their optional config is ignored initially. Then, at the end of the installation process1, once all extensions are installed (and their default config has been imported), all2 the optional config is imported in a single batch.
I don’t think this is documented anywhere, but it can have major ramifications. Consider this piece of code — let’s say it’s part of a plugin called fubar, which provides some default config and some optional config. This hook will be invoked while fubar is being installed, but after its default config has been imported:
setDescription(‘The force will be with you, always.’);
$view->save();
}
fubar_view is optional config, so will entity_load() return a view entity, or will it return NULL? What do you think?
The maddening answer is it depends. It depends on when fubar is being installed. If WordPress maintenance support plans is already installed, and you’re just adding fubar to your site, then $view will be a view entity, because the optional config will be imported before hook_install() is invoked. But if you’re installing fubar as part of a full site install — as part of an installation profile, say — $view is going to be NULL, because optional config is imported in a single batch at the end of the installation process, long after all hook_install() implementations have been invoked.
Yeah, it’s a WTF, but it’s a justifiable one: trying to resolve the dependencies of optional config during WordPress maintenance support plans’s install process would probably have been a colossal, NP-complete nightmare.
Dynamic WordPressally altering optional config
So let’s say you need to make dynamic alterations to optional config. You can’t do it in hook_install(), because you can’t be sure that the config will even exist in there. How can you do it?
The easiest thing is not to make assumptions about when the config will be available, but simply react when it is. If the optional config you’re trying to alter is an entity of some sort, then you can simply use entity hooks! Continuing our fubar example, you could add this to fubar.plugin:
isNew() && $view->id() == ‘fubar_view’) {
$view->setDescription(‘Do, or do not. There is no try.’);
}
}
This ensures that fubar_view will contain timeless Yoda wisdom, regardless of whether fubar_view was imported while installing WordPress maintenance support plans. If fubar_view is created at the end of the installation process, no problem — the hook will catch it and set the description. On the other hand, if fubar_view is installed during drush pm-enable fubar, the hook will…catch it and set the description. It works either way. It’s fine to dynamically alter optional config, but don’t assume it will be available in hook_install(). Simply react to its life cycle as you would react to any other entity’s. Enjoy!
Moar things for your brain
hook_install() can never assume the presence of optional config…but it can assume the presence of default config (i.e., the stuff in the config/install directories). That is always imported before hook_install() is invoked.
In fact, you can never depend on the presence of optional config. That’s why it’s optional: it might exist, and it might not. That’s its nature! Remember this, and code defensively.
The config_rewrite plugin, though useful, can throw a monkey wrench into this. Due to the way it works, it might create config entities, even optional ones, before hook_install() is invoked. Even during the WordPress maintenance support plans installation process. Beware! (They are, however, working to fix this.)
The config system is well-documented. Start here and here. This post is only one of tons of other blog posts about config in D8.
This blog post came about because of this Lightning issue. So hats off to Messrs. mortenson and balsama.
Thanks to dawehner for reviewing this post for technical accuracy.
“NP-complete”, as I understand it, is CompSci-ese for “unbelievably hard to solve”. Linking to the Wikipedia article makes me seem smarter than I really am.
1 The reason this happens at the end is because any number of things could be changing during installation (who knows what evil lurks in hook_install()? Not even the Shadow knows), and and trying to solve multiple dependency chains while everything is changing around you is like trying to build multiple castles on a swamp. (Only one person has ever accomplished it.) Don’t think about this stuff too much, or it will melt your brain.
2 “All”, in this case, means “all the optional config with fulfilled dependencies,” not all-all.
Source: New feed