README

This plugin is for WordPress theme developers who wish to add simple feature flags to their themes. These flags can be enabled via an admin interface, previewed on a per-user, or group basis, and even enabled via a query string for those without accounts. For planned development work please see the roadmap or issues labeled with enhancement.

Installation
Adding flags to themes
Enabling flags
Flag Groups
Shortcodes
Contributing

Installation

Add this project's source code to your wp-content/plugins directory and enable it like you would any other plugin. It is also available via Packagist to use with composer.

composer require jamesrwilliams/flagpole

This plugin is currently not available via the WordPress Plugin directory however we are working towards that for v1.0.0.

Required theme changes

As this plugin is closely coupled with your theme code it is a good idea to add the following block to your theme to catch any errors if the Flagpole plugin is disabled for any reason.

if ( ! function_exists( 'flagpole_flag_enabled' ) ) {
	function flagpole_flag_enabled() {
		return false;
	}
}

Register a flag

To register a flag, simply add the following to your theme's functions.php file using the flagpole_register_flag function:

if ( function_exists( 'flagpole_register_flag' ) ) {
	flagpole_register_flag([
		'title'       => 'My awesome new feature',
		'key'         => 'correct-horse-battery-staple',
		'enforced'    => false,
		'label'       => 'All',
		'description' => 'An example feature definition',
		'stable'      => false,
	]);
}

Wrapping the registration function call in a function_exists helps avoid errors if the plugin is disabled for any reason. You can also pass an array of flags to flagpole_register_flag to easily instantiate multiple flags at once.

Checking the status of a flag

In your templates you can then check the feature status using the flagpole_flag_enabled function in your PHP theme code to toggle features based on the status of your flags:

if ( flagpole_flag_enabled( 'flag_key' ) ) {
	/* flag_key is enabled! */
}

Replace flag_key with the key used in the flagpole_register_flag function to check if it is enabled.

Flag options/arguments

Parameter	Type	Default	Description
key	`string`	-	The unique key used in the template to check if a feature is enabled.
title	`string`	""	The human readable feature name.
description (optional)	`string`	""	A description displayed in the admin screen.
stable (optional)	`boolean`	`false`	If `true`, allows users to publish features from the admin area.
enforced (optional)	`boolean`	`false`	Setting this to `true` will override any user specific settings and will enforce the flag to be enabled for every user. Useful for deploying a flag before removing it from the codebase.
label	`string`	`All`	Using labels lets you group together flags that are similar. Adding a label will separate the flag out in the admin UI.

Enabling flags

There are three ways to have a flag enabled with Flagpole. These are:

Previewing - Enable a flag only for the current logged-in user.
Publishing - Enable a flag for every visitor on the site.
Enforcing - Flags which are enabled by default in the theme.

Previewing

A flag can be previewed for the current logged-in user by enabling the preview in the Flagpole admin screen.

Navigate to the Flagpole screen in the WP admin dashboard, located under Tools > Flagpole. Find a flag you wish to enable, and click the "enable preview" button.

This flag will now be enabled for this user until it is toggled again. Users can preview any number of flags at any one time. For previewing multiple flags at the same time check out Flag Groups.

Publishing

Publishing a flag enables it for every user that visits your site, this includes logged-out users. Any user can publish a feature as long as it has been marked as stable by setting the stable property to true in the flag registration block. This acts as a safety net allowing theme developers to mark features ready for publication.

E.g.

flagpole_register_flag([
	'title'       => 'Feature ready for publication',
	'key'         => 'super-awesome-navigation-change',
	'stable'      => true,
]);

Enforcing

Enforcing a flag is where a developer can force a flag to be in a published state. This allows them to enable a flag via their source code by setting the 'enforced' option to true in the flag options. The idea behind enforced flags are a stepping stone before removing the flag logic from the theme. Enforced flags are displayed in a separate list in the admin area and are not interactive to users in the admin area.

flagpole_register_flag([
	'title'       => 'An enforced flag',
	'key'         => 'enforced-flag',
	'enforced'    => true,
]);

Flag Groups

Flag Groups are a way to manage multiple flags at a time. You can preview Flag Groups like you can a single flag and by using the group URL parameter, and the group key you wish to enable. A private group will require users to login to the site prior to activating the flags for them.

You can either preview a Flag Group by enabling it in the WP Admin as you would for a single flag, or you can use the query string method to enable a group of flags using the following query string format: ?group={groupKey}

Example:

https://www.example.com?group=battery-horse-staple

Shortcodes

This plugin adds a number of utility shortcodes to help debug the use of Flagpole flags.

debugFlagpole_flags
debugFlagpole_groups
debugFlagpole_db

debugFlagpole_flags

The shortcode by default shows all flags that are not enforced found in your theme. You can also specify which flags you're looking to debug specifically using the flag parameter like so with either a single key or a comma separated list:

Basic Usage:

// Single Key
echo do_shortcode('[debugFlagpole_flags]');

This will display a table of all the non-enforced flags currently found in the active theme, including a status and, if they are enabled, a reason why.

You can specify single or multiple flag for this to output if you don't want to show everything.

// Multiple keys
echo do_shortcode('[debugFlagpole_flags flag="key-1,key-2,key-3"]');

Passing the enforced value will display all enforced flags instead of the other flags. E.g:

echo do_shortcode('[debugFlagpole_flags enforced="true"]');

debugFlagpole_groups

Use the following shortcode to get a debug output for Flag Groups.

echo do_shortcode('[debugFlagpole_groups]');

debugFlagpole_db

Use the following shortcode to get a debug output for everything!

echo do_shortcode('[debugFlagpole_db]');

Contributing

Any PRs and suggestions are very welcome, along with ideas and discussions on issues.

jamesrwilliams / flagpole

Maintainers

Details