PHPackages jamesrwilliams/wp-feature-flags - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. jamesrwilliams/wp-feature-flags Abandoned → [jamesrwilliams/flagpole](/?search=jamesrwilliams%2Fflagpole)ArchivedWordpress-plugin[Utility & Helpers](/categories/utility) jamesrwilliams/wp-feature-flags =============================== Easily register and work with feature flags in your theme. 0.1.4-beta(5y ago)1420.2k7[6 issues](https://github.com/jamesrwilliams/flagpole/issues)[3 PRs](https://github.com/jamesrwilliams/flagpole/pulls)MITPHP Since Feb 28Pushed 4y ago4 watchersCompare [ Source](https://github.com/jamesrwilliams/flagpole)[ Packagist](https://packagist.org/packages/jamesrwilliams/wp-feature-flags)[ Docs](https://github.com/jamesrwilliams/flagpole)[ GitHub Sponsors](https://github.com/jamesrwilliams)[ RSS](/packages/jamesrwilliams-wp-feature-flags/feed)WikiDiscussions develop Synced 1mo ago READMEChangelog (5)Dependencies (5)Versions (7)Used By (0) Flagpole ======== [](#flagpole) [![Maintainability](https://camo.githubusercontent.com/81e70a5691060cdd75496268dc62ab911c4289a0bc54569d7ebaaa62a3f78be8/68747470733a2f2f6170692e636f6465636c696d6174652e636f6d2f76312f6261646765732f35386539373961316265386437663763336436642f6d61696e7461696e6162696c697479)](https://codeclimate.com/github/jamesrwilliams/wp-feature-flags/maintainability) [![GitHub release](https://camo.githubusercontent.com/9ee71a70664d550e6d598009c323ddf359276a8b5f6f54df2c2c4ba232969958/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f72656c656173652d7072652f6a616d65737277696c6c69616d732f666c6167706f6c652e737667)](https://github.com/jamesrwilliams/flagpole/releases) [![PRs Welcome](https://camo.githubusercontent.com/64bf18976d2896c70fe318af3095e93e8ad75d7a11e46b953b5dcd7063eaf334/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5052732532302d77656c636f6d652d627269676874677265656e2e737667)](https://github.com/jamesrwilliams/flagpole/pulls) [![Packagist Downloads](https://camo.githubusercontent.com/99bdf5eb497c9a0a07bafbe00d7f9570b761453a092d5d9fc1010618aa66916a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646d2f6a616d65737277696c6c69616d732f666c6167706f6c65)](https://camo.githubusercontent.com/99bdf5eb497c9a0a07bafbe00d7f9570b761453a092d5d9fc1010618aa66916a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646d2f6a616d65737277696c6c69616d732f666c6167706f6c65) [![Known Vulnerabilities](https://camo.githubusercontent.com/022163f4d52132db716eb668aee5c2ed47fb9114314d81d364cd155a336ad845/68747470733a2f2f736e796b2e696f2f746573742f6769746875622f6a616d65737277696c6c69616d732f666c6167706f6c652f62616467652e7376673f74617267657446696c653d636f6d706f7365722e6c6f636b)](https://snyk.io/test/github/jamesrwilliams/flagpole?targetFile=composer.lock) 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](https://github.com/jamesrwilliams/flagpole/projects) or issues labeled with [enhancement](https://github.com/jamesrwilliams/flagpole/issues?q=is%3Aopen+is%3Aissue+label%3Aenhancement). Contents -------- [](#contents) 1. [Installation](#installation) 2. [Adding flags to themes](#register-a-flag) 3. [Enabling flags](#enabling-flags) 4. [Flag Groups](#flag-groups) 5. [Shortcodes](#shortcodes) 6. [Contributing](#contributing) Installation ------------ [](#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](https://packagist.org/packages/jamesrwilliams/flagpole) to use with [composer](https://getcomposer.org/). ``` 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](https://github.com/jamesrwilliams/flagpole/milestone/2). ### Required theme changes [](#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 --------------- [](#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 [](#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 [](#flag-optionsarguments) ParameterTypeDefaultDescriptionkey`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 -------------- [](#enabling-flags) There are three ways to have a flag enabled with Flagpole. These are: - **[Previewing](#previewing)** - Enable a flag only for the current logged-in user. - **[Publishing](#publishing)** - Enable a flag for every visitor on the site. - **[Enforcing](#enforcing)** - Flags which are enabled by default in the theme. ### Previewing [](#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](#flag-groups). ### Publishing [](#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) 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) 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 ---------- [](#shortcodes) This plugin adds a number of utility shortcodes to help debug the use of Flagpole flags. - [debugFlagpole\_flags](#debugFlagpole_flags) - [debugFlagpole\_groups](#debugFlagpole_groups) - [debugFlagpole\_db](#debugFlagpole_db) ### debugFlagpole\_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 [](#debugflagpole_groups) Use the following shortcode to get a debug output for Flag Groups. ``` echo do_shortcode('[debugFlagpole_groups]'); ``` ### debugFlagpole\_db [](#debugflagpole_db) Use the following shortcode to get a debug output for everything! ``` echo do_shortcode('[debugFlagpole_db]'); ``` Contributing ------------ [](#contributing) Any PRs and suggestions are very welcome, along with ideas and discussions on issues. ### Health Score 30 — LowBetter than 64% of packages Maintenance11 Infrequent updates — may be unmaintained Popularity34 Limited adoption so far Community16 Small or concentrated contributor base Maturity50 Maturing project, gaining track record Bus Factor1 Top contributor holds 95.6% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~196 days Total 5 Last Release 1852d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/be03b70ba6cf2d3d7ce43230d2f0ee569238398bfbb92eab09a00e2a876d93d1?d=identicon)[thejamesrwilliams](/maintainers/thejamesrwilliams) --- Top Contributors [![jamesrwilliams](https://avatars.githubusercontent.com/u/1438062?v=4)](https://github.com/jamesrwilliams "jamesrwilliams (130 commits)")[![peterhartree](https://avatars.githubusercontent.com/u/1412568?v=4)](https://github.com/peterhartree "peterhartree (4 commits)")[![philipjohn](https://avatars.githubusercontent.com/u/136342?v=4)](https://github.com/philipjohn "philipjohn (1 commits)")[![strayobject](https://avatars.githubusercontent.com/u/2257473?v=4)](https://github.com/strayobject "strayobject (1 commits)") --- Tags feature-flagsfeature-togglewordpresswordpress-deploymentwordpress-pluginwordpress-theme-developmentwordpressfeature-flags ### Code Quality TestsPHPUnit Code StylePHP\_CodeSniffer ### Embed Badge ![Health badge](/badges/jamesrwilliams-wp-feature-flags/health.svg) ``` [![Health](https://phpackages.com/badges/jamesrwilliams-wp-feature-flags/health.svg)](https://phpackages.com/packages/jamesrwilliams-wp-feature-flags) ``` ### Alternatives [roots/bedrock WordPress boilerplate with Composer, easier configuration, and an improved folder structure 6.5k441.8k2](/packages/roots-bedrock)[cedaro/gravity-forms-iframe Embed a Gravity Form on any site using an iframe. 1563.0k](/packages/cedaro-gravity-forms-iframe)[iceicetimmy/acf-post-type-selector Post type selector for Advanced Custom Fields. 559.0k](/packages/iceicetimmy-acf-post-type-selector) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)