Create a WordPress MU-Plugin for Actions and Filters
Learn how to make your own MU-plugin for actions and filters.
You can create a Must-Use (MU) plugin for actions or filters on your Pantheon WordPress site. Actions and filters you create can run even when a theme's functions.php isn't invoked by a request, or before plugins are loaded by WordPress.
MU-plugins are activated by default by adding a PHP file to the wp-content/mu-plugins directory. It affects the whole site, including all sites under a WordPress Multisite installation.
PHP loads MU-plugins in alphabetical order, before normal plugins. This means API hooks added to an MU-plugin apply to all other plugins even if they run hooked-functions in the global namespace.
Why use MU-Plugins?
Although you can add code in the wp-config.php file for site-wide behavior, actions and filters should not be added to this file. Your WordPress site will throw a fatal PHP error because the add_action() and add_filter() functions are not yet defined if actions and filters are added above the require_once ABSPATH . 'wp-settings.php'; statement.
If actions and filters are added below the require_once ABSPATH . 'wp-settings.php'; statement, the actions and filters will not be applied, or will be applied last when the entirety of the WordPress site has loaded.
Create Your MU-Plugin
-
Create a PHP file (for example:
your-file.php) in themu-pluginsfolder (code/wp-content/mu-plugins/your-file.php). -
Provide details for the plugin, such as name, description, URI, and other descriptors:
-
Add the custom functions and the filters or actions that you want to run. Use the following script as a starting point for creating your own plugin:
Use wp_get_environment_type for Environment-specific Actions
WordPress 5.5 introduced the wp_get_environment_type function. The Platform automatically defines wp_get_environment_type based on the environment variables set by the platform.
Note that the environment variables used by WordPress differ from the names used on Pantheon:
| Pantheon Environment | wp_get_environment_type |
|---|---|
| dev / Multidev | development |
| test | staging |
| live | production |
You can instruct an MU-plugin to run or perform environment-specific actions. Use wp_get_environment_type to look up the current environment in a platform-neutral way.
Example Code Snippets
Create a custom MU-plugin with actions or filters to resolve issues you may encounter with the following plugins, themes, or use cases.
Cache Control
Set Cache-Control: max-age=0 by hooking into send_headers. This will override max-age configured within the Pantheon Cache plugin for all matching requests:
Cross-Origin Resource Sharing (CORS)
The following code sample adds the correct header and enables requests from specific URLs for sites that need to provide services with Cross-Origin Resource Sharing (CORS):
Custom Cookies
You can aslo set custom cookies in an MU-plugin like the example below. Refer to Working with Cookies on Pantheon for more cookie manipulation examples.
Custom Login Message
To customize the text displayed on /wp-login.php when accessing the site from a Platform Domain, add the following filter:
You can also disable the Return to Pantheon button on platform domain login pages, and overwrite the default login text:
Please note that overwriting login_message changes the text displayed on all login pages, regardless of the domain used to access the pages.
Exclude Plugins from Redis Cache
A page load with 2,000 Redis calls can be two full seconds of object cache transactions. If a plugin you're using is erroneously creating a huge number of cache keys, you might be able to mitigate the problem by disabling cache persistence for the plugin's group.
For example, if you have a custom plugin that sets the cache with:
You can exclude that in Redis with:
We can add multiple plugins to the function as well:
To verify, you can use the Redis CLI to flush all keys and see that the related objects are no longer added to the cache:
Refer to How do I disable the persistent object cache for a bad actor? for more information.
Redirects
In addition to PHP redirects, it's possible to add custom redirects, like path or domain specific redirects, in an MU-plugin.
WP-CFM Compatibility
WP-CFM can work with Multidev environments, but a Must-Use plugin must be configured:
WP REST API (wp-json) Endpoints Cache
For WP REST API endpoints, you can use the rest_post_dispatch filter and create a specific function to apply specific headers for each path or endpoint.
Troubleshooting
Error contacting Pantheon API
Issue: You receive the error below in your PHP logs when trying to use an MU-Plugin.
Error contacting Pantheon API: Operation timed out after 1001 milliseconds with 0 bytes received
Solution: Verify that your MU-Plugin is up to date. An outdated MU-Plugin (particularly those earlier than the bundled 5.8) can cause this error.