dmhendricks/wordpress-mu-common-toolkit

A must use (MU) plugin for WordPress that contains helper functions, snippets and a configuration registry.

WordPress Common Toolkit MU Plugin

A simple MU plugin for WordPress that adds functionality that I use on web site projects, including a configuration registry.

• Installation
• Configuration
  • Sample
  • Caching JSON Config File
• Usage Examples
• Environment Filter
• Action Hook
• Shortcodes

Installation

Simply copy the common-toolkit.php file to your wp-content/mu-plugins directory (create one if it does not exist).

Requirements

• PHP 5.4+ (via JSON config file) and PHP 7.x (via array or JSON file)
• WordPress 4.7 or higher

Configuration

All variables are optional.

Variable	Description	Type	Default
environment	Environment of current instance (ex: 'production', 'development', 'staging')	string	"production"
environment_constant	Constant used to determine environment, environmental variable name for getenv().	string	"WP_ENV"
environment_production	The label used to match if production environment.	string	"production"
admin_bar_color	Change admin bar color in current environment	string	null
disable_emojis	Remove support for emojis	bool	false
disable_php_update_nag	Removes the "PHP Update Required" dashboard widget/notice	bool	false
disable_search	Disable WordPress site search	bool	false
disable_site_health	Disable site health notifications, widgets and menu	bool	false
disable_updates	Disable WordPress core, plugin and/or theme updates. Values: core, plugin, theme; true for all	bool/string/array	false
disable_xmlrpc	Disable XML-RPC	bool	false
feed_links	Include RSS feed links in page head	bool	true
heartbeat	Modify or disable the WordPress heartbeat. Set to integer to change, false to disable	bool/int	null
set_login_errors	Hide or change login error messages to mitigate brute force attacks and username phishing	bool/string	null
howdy_message	Change (string) or remove (false/null) Howdy message in WP admin bar	bool/string/null	true
meta_generator	Enable or change meta generator tags in page head and RSS feeds	bool/string	false
script_attributes	Enable support for additional attributes to script tags via wp_enqueue_script()	bool	flase
shortcodes	Enable custom shortcodes created by this class	bool	false
windows_live_writer	Enable Windows Live Writer support	bool	true

Sample

Via Configuration File (PHP 5.6 or higher)

This is the preferred method if you wish to avoid having a complex array in your wp-config.php:

// Load configuration from a file in webroot.
define( 'CTK_CONFIG', 'sample-config.json' );

// Load configuration from a file off of the parent directory of webroot
define( 'CTK_CONFIG', '../conf/sample-config.json' );

See sample-config.json for example.

Via Array (PHP 7 or higher)

Rather than using a JSON file for configuration, you can set CTK_CONFIG to an array of valyes in wp-config.php:

define( 'CTK_CONFIG', [ 'disable_emojis' => true, 'admin_bar_color' => '#336699', 'script_attributes' => true, 'meta_generator' => 'Atari 2600' ] );

Caching JSON Config File

If your WordPress Instance has caching enabled, you can configure this plugin to cache the contents of your configuration JSON file with a constant in wp-config.php:

define( 'CTK_CACHE_EXPIRE', 120 ); // In seconds

Getting Configuration Values

You can use the ctk_config filter to retrieve values from the config registry (including custom). Using sample-config.json as an example:

// Get meta generator value
$meta_generator = apply_filter( 'ctk_config', 'common_toolkit/meta_generator' );

// Get single custom variable
$ny_var = apply_filter( 'ctk_config', 'my_custom_variable' );

// Get an array of classic books
$classic_books = apply_filter( 'ctk_config', 'nested_example/books/classics' );

// Get entire config registry as associative array
$config = apply_filter( 'ctk_config', null );

You can add any variable you want to make available to your site's themes and plugins.

Usage Examples

WordPress Environment

You can set your instance environment using the following methods (in order of precedence; defaults to "production" if not set using any of the following methods):

1. Define a Constant in wp-config.php

define( 'WP_ENV', 'staging' );

If you wish to use a different constant name, you can set the environment_constant in the config:

define( 'MY_ENVIRONMENT', 'development' );
define( 'CTK_CONFIG', [ 'environment_constant' => 'MY_ENVIRONMENT' ] );

This will also change the name of the environmental variable used to retrieve the environment:

echo getenv( 'MY_ENVIRONMENT' ); // Result: development
// ...or:
echo apply_filters( 'ctk_environment', null ); // Result: development

2. Define environment Variable in Config

Setting:

define( 'CTK_CONFIG', [ 'environment' => 'staging' ] );

Getting:

echo getenv( 'WP_ENV' ); // Result: staging
// ...or:
echo apply_filters( 'ctk_environment', null ); // Result: staging

If not defined, "production" is returned.

Add Attributes to Enqueued Scripts

Examples:

wp_enqueue_script( 'script-async-with-preload-example', get_template_directory_uri() . '/assets/js/script.js#async,preload' );
wp_enqueue_script( 'script-defer-example', get_template_directory_uri() . '/assets/js/script.js#defer' );
wp_enqueue_script( 'script-custom-attributes', 'https://cdn.ampproject.org/v0/amp-audio-0.1.js?custom_attribute[]=custom-element|amp-audio#async' );

wp_enqueue_style( 'stylesheet-with-preload', get_template_directory_uri() . '/assets/css/style.css#preload' );

Result:

<link href="https://example.com/wp-content/themes/my-theme/assets/js/script.js?ver=5.0.0" rel="preload" as="script" />
<script async src="https://example.com/wp-content/themes/my-theme/assets/js/script.js?ver=5.0.0"></script>
<script defer src="https://example.com/wp-content/themes/my-theme/assets/js/script.js?ver=5.0.0"></script>
<script async custom-element="amp-audio" src="https://cdn.ampproject.org/v0/amp-audio-0.1.js?ver=5.0.0"></script>

<link href="https://example.com/wp-content/themes/my-theme/assets/css/style.css?ver=5.0.0" rel="preload" as="style" />
<link rel="stylesheet" id="stylesheet-with-preload-css" href="https://example.com/wp-content/themes/my-theme/assets/css/style.css?ver=5.0.0" type="text/css" />

Change Admin Bar Color

Useful for distinguishing browser windows among different environments. Defined in wp-config.php:

define( 'CTK_CONFIG', [ 'admin_bar_color' => '#336699' ] );

Build URL Parsed With parsed_url()

This function reverses the result of parse_url():

$parse_uri = parse_url( 'https://example.com/?hello=world#hash );
$parse_uri['fragment'] = 'newhash';
$uri = \MU_Plugins\CommonToolkit::build_url( $parse_uri );

Disable WordPress Core, Plugin and/or Theme Updates

You can disable any of the update notifications or specific. It accepts string, boolean or an array of values. Examples:

// Disable all update notifications
define( 'CTK_CONFIG', [ 'disable_updates' => true ] ); // boolean

// Disable WordPress core and theme updates only (not plugins)
define( 'CTK_CONFIG', [ 'disable_updates' => [ 'core', 'theme' ] ] ); // array

// Disable only plugin updates updates
define( 'CTK_CONFIG', [ 'disable_updates' => 'plugin' ] ); // string

Hide or Change Login Errors

To help prevent user enumeration/phishing for brute for attacks, you can change the WordPress login errors to something more generic by defining set_login_errors. This value can be a string or boolean:

Value	Result
null	Leaves the default WordPress messages in place
false	Hide/disables login error messages completely
true	Changes the login messages to a generic "Login failed." (English only)
string	Changes the login message to your own string, particularly useful if your default language is not English.

📌 You can use %s in your string, which will be replaced with the reset password URL. Example:

define( 'CTK_CONFIG', [ 'set_login_errors' => '<strong>ERROR</strong>: Invalid credentials. <a href="%s">Lost your password</a>?' ] );

Environment Filter

You can alternately retrieve the current environment using the ctk_environment filter:

echo apply_filters( 'ctk_environment', null ); // 'production', 'staging', etc

You can also pass is_production to determine if we're currently in production more. It compares the value of your environment (defined above) with the value of common_toolkit/environment_production (which defaults to "production"). In this way, you can set your production label/string value to whatever you like.

Determining if in production mode using defaults:

if( apply_filters( 'ctk_environment', 'is_production' ) ) {
   // Do something intended only for production
} else {
   // Do something else
}

As noted above, you can change the string comparison of what is considered production in config. For example, if you wanted to use "live" instead of "production":

define( 'CTK_CONFIG', [ 'environment_production' => 'live' ] );

// Result: true
define( 'WP_ENV', 'live' ); // wp-config.php
var_dump( apply_filters( 'ctk_environment', 'is_production' ) );

// Result: false
define( 'WP_ENV', 'staging' ); // wp-config.php
var_dump( apply_filters( 'ctk_environment', 'is_production' ) );

This special filter value is provided solely for convenience. You may, of course, do a manual comparison:

if( getenv( 'WP_ENV' ) == 'production' ) { // Replace variable with value of `environment_constant`, if set
   // Do something intended only for production
} else {
   // Do something else
}

Action Hook

If you want to perform some logic only if this script is loaded, you can use the common_toolkit_loaded action hook (which executes during the init phase).

add_action( 'common_toolkit_loaded', function() {
	// Do something if common toolkit is loaded ...
	var_dump( apply_filters( 'ctk_config', null ) );
});

Shortcodes

[get_datetime]

Returns a formatted date in WordPress configured timezone. Defaults to current date/time in MySQL format. Enabling:

define( 'CTK_CONFIG', [ 'shortcodes' => true ] );

Usage:

Copyright ©[get_datetime format="Y"] Your Company
Current date/time: [get_datetime]

See PHP's date() function for formatting options.