jamesrwilliams / flagpole
Easily register and work with feature flags in your theme.
Fund package maintenance!
jamesrwilliams
Installs: 100 552
Dependents: 1
Suggesters: 0
Security: 0
Stars: 21
Watchers: 5
Forks: 8
Open Issues: 15
Type:wordpress-plugin
Requires
- composer/installers: ~1.0
Requires (Dev)
This package is auto-updated.
Last update: 2022-09-12 15:52:57 UTC
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.
Contents
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
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.