alleyinteractive/wp-experimental-features

WP Experimental Features

v1.2.0 2022-07-26 20:31 UTC

Requires (Dev)

• alleyinteractive/alley-coding-standards: ^0.3
• mantle-framework/testkit: ^0.4
• phpunit/phpunit: ^9.3.3

GPL-2.0-or-later

• Alley

README

A WordPress plugin that creates a feature flags system for beta testing experimental features in your themes or plugins.

Usage

Defining Feature Flags

Feature flags are defined using a filter:

/**
 * Define available feature flags.
 *
 * @param array $flags Feature flags that have been defined for the Experimental Features plugin.
 *
 * @return array The modified list of feature flags.
 */
function filter_experimental_features_flags( $flags ): array {
	$flags['my-cool-feature'] = __( 'My Cool Feature', 'my-textdomain' );

	return $flags;
}
add_filter(
	'experimental_features_flags',
	__NAMESPACE__ . '\filter_experimental_features_flags'
);

Checking the Value of Feature Flags

The value of a feature flag can be checked by running the feature flag slug through the experimental_features_flag filter. This allows for plugins and themes to not break if the Experimental Features plugin is deactivated, because the filter will simply return the default value.

$is_enabled = apply_filters(
	'experimental_features_flag',
	false,
	'my-cool-feature'
);

If the flag is not enabled, or if the Experimental Features plugin is not active, then the default value (first parameter, false in the example above) will be returned.

If you like, you could create a helper function for this in your plugin or theme:

/**
 * A helper function for determining if a feature flag is enabled.
 *
 * @param string $slug The feature flag slug to check.
 *
 * @return bool True if enabled, false if not.
 */
function my_theme_flag_enabled( string $slug ): bool {
	return (bool) apply_filters(
		'experimental_features_flag',
		false,
		$slug
	);
}

Toggling Feature Flags in the Admin

If you navigate to Settings > Experimental Features while logged in to the WordPress admin as an administrator (or a user with the manage_options capability) you can turn feature flags on and off via a simple checkbox interface.

Toggling Feature Flags in the Admin Bar

By default the admin bar will include links to toggle all available feature flags individually. This can be turned off using a filter:

add_action( 'experimental_features_show_admin_bar', '__return_false' )

Listening for Flag Changes

WordPress actions are fired when flags are enabled/disabled.

On Any Flag Update

add_action(
	'experimental_features_flags_updated',
	function( $enabled, $disabled ) {
		// ...
	},
	10,
	2,
);

When a Specific Flag is Enabled

add_action( 'experimental_features_flag_enabled_{feature-flag}', function() { ... } );

When a Specific Flag is Disabled

add_action( 'experimental_features_flag_disabled_{feature-flag}', function() { ... } );