Feature Flag Documentation


Introduction


Feature flagging is a software best practice for controlling the release of features (sometimes called "gating"). Feature flagging is important because it allows you to turn features on/off without having to do a deploy.

There are many use cases for feature flagging, including:

Targeting features at individual users - Use feature flagging to release features to individual users. This is extremely useful for alpha and beta testing features.

Gradual roll-out to a percentage of users - Have a big release and want to be cautious? Using a percentage based roll-out you can slowly release your feature to your users and gather feedback along the way.

Disabling a problematic new feature - Did you just release something that's causing serious problems in production? Deactivate the feature without needing to do another deploy.

Monthly Active Users


Feature flags have the concept of "Monthly Active Users". A monthly active user is a user that is identified by you as being unique, and is given a set of feature flag states by Kernl. A user is active if they have requested flags for a product within the last 30 days. Kernl's different plans support a variety of needs for monthly active users. If you find you need more than our largest plan provides for, reach out to us and we'll be happy to work with you.

Feature Flag Types


There are 3 different types of feature flags that Kernl supports: on/off, individual, and percentage. Each of these flag types is useful for different situations.

On/Off - An on/off flag is useful for quickly turning a feature on or off for all of your users. This type of flag is often used to wrap new functionality, just in case something goes wrong. If there are performance problems or other serious issues, simply turn the flag off to disable the feature for all of your users.

Individual - Running an alpha or beta program? Have a set of users that you test with? Use individual targeting to turn a feature on for only selected people.

Percentage - Rolling out a feature to all of your users at once is scary. Use percentage based roll outs to turn a feature on for a defined percentage of your user base.


Performance & Reliability


Kernl's architecture is distributed, highly available, high performance, and already serves millions of requests a day to thousands of websites.

All feature flag requests are served directly from cache and generally return in under 100ms. If 100ms is too slow, consider memoizing the result or caching locally for even faster results. Our client libraries (coming soon!) will make local caching of flags extremely easy.


Feature Flag API


In order to use feature flags you need to be able to identify your users. The identifier is a string that you define which allows you to give different user's different flags. For instance, if you used an email address as an identifier it would be easy to target individual users. If you used an ID, it might be a little tougher.

/api/v2/public/feature-flags/[productKey]?identifier=[user identifier]

Performing a GET operation against this endpoint will return a list of all the flags available for this product and the state of each for the user you have identified. You should replace the "[productKey]" with the product key in the Feature Flag Products table in the Kernl interface. The "[user identifier]" should be replaced with a unique identifier for a given user. We reccomend using an email address.

GET https://kernl.us/api/v2/public/feature-flags/MyProductKey?identifier=jack@kernl.us

The above GET operation returns and array of feature flags, their state, and a status code of 200 if successful. A status code of 404 if the Feature Flag Product does not exist.

[
   {
      "flag": "CUSTOM_CHANGELOG_MESSAGES",
      "active": true
   },
   {
      "flag": "NEW_MARKETING_PAGE",
      "active": false
   }
]

WordPress Client Library


The WordPress library for Kernl Feature Flags makes integrating with our feature flag service easy and provides some WordPress specific performance optimizations.

Installation with Composer

If you are using Composer to manage your plugin or theme dependencies run:

composer require kernl/wp-feature-flags

Once the dependecies have finished installing, make sure to include the auto loader in your source file.

require __DIR__ . '/vendor/autoload.php';
Installation without Composer

If you prefer to just copy the source file into your plugin or theme, go to GitHub and download the WPFeatureFlags.php file.

Usage

Once the WordPress client library has been installed, using Kernl's feature flags is easy! A full example is below. If you don't use composer, ignore the autoload require statement.

require __DIR__ . '/vendor/autoload.php';
 
// Your product key is listed on the Feature Flag page
// in Kernl's web interface.
$kernlFeatureFlagProductKey = '58cb023bc9689c1fe811615d';
 
// This is how you identify users.  This can be anything
// you want, but I suggest making it something easy to understand.
$userIdentifier = 'jack@kernl.us';
 
// The flag name.  Each product can have multiple flags.
$featureFlagName = 'GITHUB_ON_OFF';
 
$kff = new kernl\WPFeatureFlags($kernlFeatureFlagProductKey, $userIdentifier);
 
// This is where the magic happens.  This says "For the user
// identified above, is this feature active?".
if ($kff->active($featureFlagName)) {
   add_action('admin_notices', 'feature_flag_active');
}
 
function feature_flag_active() {
   echo 'Great work!  The feature flag is active.';
}

A full example of this can found on GitHub.

Performance

All feature flags on Kernl are served from a cache, but sometimes you don't want to cross the network boundary if you don't have to. To solve this problem, the WordPress feature flag library stores feature flags locally using transients for 5 minutes before checking Kernl again to see if anything has changed. This keeps your plugin or theme fast, while still allowing the extreme flexibility and safety that feature flags enable.