Skip to content

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

License

Notifications You must be signed in to change notification settings

dmhendricks/wordpress-mu-common-toolkit

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

47 Commits
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Author License DigitalOcean Twitter BrowserStack

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

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 &copy;[get_datetime format="Y"] Your Company
Current date/time: [get_datetime]

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

Analytics