jetpack / jetpack_vendor / automattic / jetpack-feature-flags / src / class-feature-flags.php

class-feature-flags.php in Jetpack – WP Security, Backup, Speed, & Growth 16.3-a.7, at jetpack_vendor/automattic/jetpack-feature-flags/src/class-feature-flags.php

139 lines 3.5 KB

Raw Download Zip

1	<?php
2	/**
3	* Lightweight feature flag registry.
4	*
5	* @package automattic/jetpack-feature-flags
6	*/
7
8	namespace Automattic\Jetpack\Feature_Flags;
9
10	/**
11	* Registers feature flag metadata and resolves flag state.
12	*/
13	class Feature_Flags {
14
15	const PACKAGE_VERSION = '0.2.0';
16
17	/**
18	* Registered feature flags.
19	*
20	* @var array<string, array>
21	*/
22	private static $flags = array();
23
24	/**
25	* Register a feature flag.
26	*
27	* Supported definition keys:
28	* - default: bool Whether the flag is enabled by default.
29	* - description: string Human-readable description.
30	* - owner: string Owning package, plugin, or product area.
31	*
32	* Flag names must match /^[a-z0-9][a-z0-9_-]*$/. This is enforced at lint
33	* time by the `Jetpack.FeatureFlags.FeatureFlagName` PHPCS sniff rather than
34	* at runtime, so registration stays allocation-free on the hot path.
35	*
36	* @param string $name Flag name.
37	* @param array $definition Flag definition.
38	* @return void
39	*/
40	public static function register( $name, array $definition = array() ) {
41	$definition = array_merge( self::default_definition( $name ), $definition );
42	$definition['default'] = (bool) $definition['default'];
43	$definition['name'] = $name;
44
45	self::$flags[ $name ] = $definition;
46	}
47
48	/**
49	* Return a registered flag definition.
50	*
51	* @param string $name Flag name.
52	* @return array\|null Flag definition, or null when the flag is unknown.
53	*/
54	public static function get( $name ) {
55	return self::$flags[ $name ] ?? null;
56	}
57
58	/**
59	* Return all registered flag definitions.
60	*
61	* @return array<string, array>
62	*/
63	public static function all() {
64	$flags = self::$flags;
65	ksort( $flags );
66
67	return $flags;
68	}
69
70	/**
71	* Return whether a feature flag is enabled.
72	*
73	* Unknown flags default to false but still pass through the global filter.
74	*
75	* @param string $name Flag name.
76	* @return bool Whether the flag is enabled.
77	*/
78	public static function is_enabled( $name ) {
79	$definition = self::get( $name );
80
81	if ( null === $definition ) {
82	$definition = self::default_definition( $name );
83	}
84
85	$default = (bool) $definition['default'];
86
87	/**
88	* Filters whether a Jetpack feature flag is enabled.
89	*
90	* @since 0.1.0
91	*
92	* @param bool $enabled Whether the flag is enabled. Defaults to the registered default.
93	* @param string $flag_name Feature flag name.
94	* @param array $definition Registered feature flag definition.
95	*/
96	$enabled = (bool) apply_filters( 'jetpack_feature_flag_enabled', $default, $name, $definition );
97
98	/**
99	* Filters whether a specific Jetpack feature flag is enabled.
100	*
101	* The dynamic portion of the hook name, `$name`, refers to the feature flag name.
102	* This mirrors the WordPress `option_{$option}` convention so a single flag can be
103	* toggled with a `__return_true`/`__return_false` one-liner.
104	*
105	* @since 0.1.0
106	*
107	* @param bool $enabled Whether the flag is enabled.
108	* @param array $definition Registered feature flag definition.
109	*/
110	return (bool) apply_filters( "jetpack_feature_flag_enabled_{$name}", $enabled, $definition );
111	}
112
113	/**
114	* Clear registered flags.
115	*
116	* Intended for tests.
117	*
118	* @return void
119	*/
120	public static function reset() {
121	self::$flags = array();
122	}
123
124	/**
125	* Build the default definition for a flag.
126	*
127	* @param string $name Flag name.
128	* @return array Default flag definition.
129	*/
130	private static function default_definition( $name ) {
131	return array(
132	'default' => false,
133	'description' => '',
134	'owner' => '',
135	'name' => $name,
136	);
137	}
138	}
139