298 | * $settings = array(
299 | * 'typography' => array(
300 | * 'fontFamilies' => array(
301 | * array(
302 | * 'slug' => 'sansSerif',
303 | * 'fontFamily' => '"Helvetica Neue", sans-serif',
304 | * ),
305 | * array(
306 | * 'slug' => 'serif',
307 | * 'colors' => 'Georgia, serif',
308 | * )
309 | * ),
310 | * ),
311 | * );
312 | * $meta = array(
313 | * 'path' => array( 'typography', 'fontFamilies' ),
314 | * 'value_key' => 'fontFamily',
315 | * );
316 | * $values_by_slug = get_settings_values_by_slug();
317 | * // $values_by_slug === array(
318 | * // 'sans-serif' => '"Helvetica Neue", sans-serif',
319 | * // 'serif' => 'Georgia, serif',
320 | * // );
321 | *
322 | *
323 | * @since 5.9.0
324 | *
325 | * @param array $settings Settings to process.
326 | * @param array $preset_metadata One of the PRESETS_METADATA values.
327 | *
328 | * @return array Array of presets where each key is a slug and each value is the preset value.
329 | */
330 | private static function get_settings_values_by_slug( $settings, $preset_metadata ) {
331 | $preset_per_origin = _wp_array_get( $settings, $preset_metadata['path'], [] );
332 |
333 | $result = [];
334 |
335 | if ( isset( $preset_per_origin[ self::DEFAULT_ORIGIN ] ) ) {
336 | foreach ( $preset_per_origin[ self::DEFAULT_ORIGIN ] as $preset ) {
337 | $slug = _wp_to_kebab_case( $preset['slug'] );
338 |
339 | $value = '';
340 | if ( isset( $preset_metadata['value_key'], $preset[ $preset_metadata['value_key'] ] ) ) {
341 | $value_key = $preset_metadata['value_key'];
342 | $value = $preset[ $value_key ];
343 | } elseif (
344 | isset( $preset_metadata['value_func'] ) &&
345 | is_callable( $preset_metadata['value_func'] )
346 | ) {
347 | $value_func = $preset_metadata['value_func'];
348 | $value = call_user_func( $value_func, $preset );
349 | } else {
350 | // If we don't have a value, then don't add it to the result.
351 | continue;
352 | }
353 |
354 | $result[ $slug ] = $value;
355 | }
356 | }
357 |
358 | return $result;
359 | }
360 |
361 | /**
362 | * Transforms a slug into a CSS Custom Property.
363 | *
364 | * @since 5.9.0
365 | *
366 | * @param string $input String to replace.
367 | * @param string $slug Slug value to use to generate the custom property.
368 | *
369 | * @return string CSS Custom Property. Something along the lines of `--wp--preset--color--black`.
370 | */
371 | private static function replace_slug_in_string( $input, $slug ) {
372 | return strtr( $input, array( '$slug' => $slug ) );
373 | }
374 |
375 | /**
376 | * Get the CSS selector for a block using the block name
377 | *
378 | * This method is only used for WordPress versions below 6.3. After 6.3, we have a built in
379 | * way of accessing this selector. This will be deprecated once 6.3 is available for a
380 | * majority of VIP sites.
381 | *
382 | * @param string $block_name Name of the block.
383 | * @param array $blocks_registered Blocks that are allowed via the block registry.
384 | *
385 | * @return string the css selector for the block.
386 | */
387 | private static function get_css_selector_for_block( $block_name, $blocks_registered ) {
388 | $block = $blocks_registered[ $block_name ];
389 | if (
390 | isset( $block->supports['__experimentalSelector'] ) &&
391 | is_string( $block->supports['__experimentalSelector'] )
392 | ) {
393 | return $block->supports['__experimentalSelector'];
394 | } else {
395 | return '.wp-block-' . str_replace( '/', '-', str_replace( 'core/', '', $block_name ) );
396 | }
397 | }
398 | }
399 |
--------------------------------------------------------------------------------
/governance/rest/rest-api.php:
--------------------------------------------------------------------------------
1 | 'GET',
39 | 'permission_callback' => [ __CLASS__, 'permission_callback' ],
40 | 'callback' => [ __CLASS__, 'get_governance_rules_for_rule_type' ],
41 | 'args' => [
42 | 'role' => [
43 | 'validate_callback' => function ( $param ) {
44 | $all_roles = array_keys( wp_roles()->roles );
45 | $roles = [ strval( $param ) ];
46 | return array_intersect( $all_roles, $roles );
47 | },
48 | 'sanitize_callback' => function ( $param ) {
49 | return strval( $param );
50 | },
51 | ],
52 | 'postType' => [
53 | 'validate_callback' => function ( $param ) {
54 | $post_types = [ strval( $param ) ];
55 | return array_intersect( get_post_types(), $post_types );
56 | },
57 | 'sanitize_callback' => function ( $param ) {
58 | return strval( $param );
59 | },
60 | ],
61 | ],
62 | ] );
63 | }
64 |
65 | /**
66 | * Restrict the users that can access this rest API to be who can manage options only.
67 | *
68 | * @return bool True, if they are allow or false otherwise.
69 | *
70 | * @access private
71 | */
72 | public static function permission_callback() {
73 | return current_user_can( 'manage_options' );
74 | }
75 |
76 | /**
77 | * Get the governance rules specifically for a role.
78 | *
79 | * @param array $params Rest parameters.
80 | *
81 | * @return array Response containing the rules.
82 | *
83 | * @access private
84 | */
85 | public static function get_governance_rules_for_rule_type( $params ) {
86 | $role = isset( $params['role'] ) ? [ $params['role'] ] : [];
87 | $post_type = $params['postType'] ?? '';
88 |
89 | try {
90 | $parsed_governance_rules = GovernanceUtilities::get_parsed_governance_rules();
91 |
92 | if ( is_wp_error( $parsed_governance_rules ) ) {
93 | return new WP_Error( 'vip-governance-rules-error', 'Error: Governance rules could not be loaded.', [ 'status' => 400 ] );
94 | } else {
95 | return GovernanceUtilities::get_rules_by_type( $parsed_governance_rules, $role, $post_type );
96 | }
97 | } catch ( Exception | Error $e ) {
98 | return new WP_Error( 'vip-governance-rules-error', 'Error: Governance rules could not be loaded due to a plugin error.', [ 'status' => 500 ] );
99 | }
100 | }
101 | }
102 |
103 | RestApi::init();
104 |
--------------------------------------------------------------------------------
/governance/rules-parser.php:
--------------------------------------------------------------------------------
1 | 'roles',
22 | 'postType' => 'postTypes',
23 | ];
24 | // Keep this order this way, as it's used for determing the priority of rules in governance-utilities.
25 | public const RULE_TYPES = [ 'postType', 'role', 'default' ];
26 | private const RULE_KEYS_GENERAL = [ 'allowedFeatures', 'allowedBlocks', 'blockSettings' ];
27 |
28 | /**
29 | * Parses and validates governance rules.
30 | *
31 | * @param string $rules_content Contents of rules file.
32 | *
33 | * @return array|WP_Error
34 | *
35 | * @access private
36 | */
37 | public static function parse( $rules_content ) {
38 | if ( empty( $rules_content ) ) {
39 | // Allow an empty file to be valid for no rules.
40 | return [];
41 | }
42 |
43 | // Parse JSON from rules file.
44 | $rules_parsed = self::parse_rules_from_json( $rules_content );
45 |
46 | if ( is_wp_error( $rules_parsed ) ) {
47 | return $rules_parsed;
48 | } elseif ( empty( $rules_parsed ) ) {
49 | // Allow an empty object to be valid for no rules.
50 | return [];
51 | }
52 |
53 | // Validate governance rule logic.
54 | $rule_validation_result = self::validate_rule_logic( $rules_parsed );
55 |
56 | if ( is_wp_error( $rule_validation_result ) ) {
57 | return $rule_validation_result;
58 | }
59 |
60 | return $rules_parsed['rules'];
61 | }
62 |
63 | /**
64 | * Given a JSON string, return an array of structured rules, or a WP_Error if parsing fails.
65 | *
66 | * @param string $rules_content Contents of rules file.
67 | *
68 | * @return array|WP_Error
69 | */
70 | private static function parse_rules_from_json( $rules_content ) {
71 | $rules_parsed = json_decode( $rules_content, true );
72 |
73 | if ( null === $rules_parsed && JSON_ERROR_NONE !== json_last_error() ) {
74 | // PHP's JSON parsing failed. Use JsonParser to get a more detailed error.
75 | $parser = new JsonParser();
76 | $result = $parser->lint( $rules_content, JsonParser::DETECT_KEY_CONFLICTS | JsonParser::PARSE_TO_ASSOC );
77 |
78 | if ( $result instanceof ParsingException ) {
79 | /* translators: %s: Technical data - JSON parsing error */
80 | $error_message = sprintf( __( 'There was an error parsing JSON: %s', 'vip-governance' ), $result->getMessage() );
81 | return new WP_Error( 'parsing-error-from-json', $error_message, $result->getDetails() );
82 | } else {
83 | // If the parser failed to return an error, return default PHP error message.
84 |
85 | /* translators: %s: Technical data - JSON parsing error */
86 | $error_message = sprintf( __( 'There was an error decoding JSON: %s', 'vip-governance' ), json_last_error_msg() );
87 | return new WP_Error( 'parsing-error-generic', $error_message );
88 | }
89 | }
90 |
91 | if ( empty( $rules_parsed ) ) {
92 | // If parsed rules contain an empty object, treat this as a valid form of no rules.
93 | return [];
94 | }
95 |
96 | return $rules_parsed;
97 | }
98 |
99 |
100 | /**
101 | * Evaluate parsed rules for logic errors, like multiple default rules or missing required keys.
102 | * Returns true if validation succeeds, or a WP_Error indicating a logic error.
103 | *
104 | * @param array $rules_parsed Parsed contents of a governance rules file.
105 | *
106 | * @return true|WP_Error
107 | */
108 | private static function validate_rule_logic( $rules_parsed ) {
109 | if ( ! isset( $rules_parsed['version'] ) || WPCOMVIP__GOVERNANCE__RULES_SCHEMA_VERSION !== $rules_parsed['version'] ) {
110 | /* translators: %s: Latest schema version, e.g. 0.2.0 */
111 | $error_message = sprintf( __( 'Governance JSON should have a root-level "version" key set to "%s".', 'vip-governance' ), WPCOMVIP__GOVERNANCE__RULES_SCHEMA_VERSION );
112 | return new WP_Error( 'logic-missing-version', $error_message );
113 | } elseif ( ! isset( $rules_parsed['rules'] ) ) {
114 | // If parsed rules contain values but no 'rules' key, return an error.
115 | return new WP_Error( 'logic-missing-rules', __( 'Governance JSON should have a root-level "rules" key.', 'vip-governance' ) );
116 | } elseif ( ! is_array( $rules_parsed['rules'] ) ) {
117 | return new WP_Error( 'logic-non-array-rules', __( 'Governance JSON "rules" key should be an array.', 'vip-governance' ) );
118 | }
119 |
120 | $rules = $rules_parsed['rules'];
121 | $default_rule_index = null;
122 |
123 | foreach ( $rules as $rule_index => $rule ) {
124 | $rule_type = $rule['type'] ?? null;
125 | $rule_ordinal = self::format_number_with_ordinal( $rule_index + 1 );
126 |
127 | if ( null === $rule_type || ! in_array( $rule_type, self::RULE_TYPES ) ) {
128 | $rule_types = self::format_array_to_keys( self::RULE_TYPES );
129 | /* translators: 1: Ordinal number of rule, e.g. 1st 2: Comma-separated list of rule types */
130 | $error_message = sprintf( __( '%1$s rule should have a "type" key set to one of these values: %2$s.', 'vip-governance' ), $rule_ordinal, $rule_types );
131 | return new WP_Error( 'logic-incorrect-rule-type', $error_message );
132 | }
133 |
134 | if ( 'default' === $rule_type ) {
135 | if ( null === $default_rule_index ) {
136 | $verify_rule_result = self::verify_default_rule( $rule );
137 | $default_rule_index = $rule_index;
138 | } else {
139 | // There's already a default rule defined, bubble an error.
140 |
141 | /* translators: 1: Ordinal number of rule, e.g. 1st */
142 | $error_message = sprintf( __( 'Only one default rule is allowed, but the %s rule already contains a default rule.', 'vip-governance' ), self::format_number_with_ordinal( $default_rule_index + 1 ) );
143 | $verify_rule_result = new WP_Error( 'logic-rule-default-multiple', $error_message );
144 | }
145 | } else {
146 | $verify_rule_result = self::verify_type_rule( $rule );
147 | }
148 |
149 | if ( is_wp_error( $verify_rule_result ) ) {
150 | // Add rule index to error message.
151 | /* translators: 1: Ordinal number of rule, e.g. 1st 2: Error message for failed rule */
152 | $error_message = sprintf( __( 'Error parsing %1$s rule: %2$s', 'vip-governance' ), $rule_ordinal, $verify_rule_result->get_error_message() );
153 | return new WP_Error( $verify_rule_result->get_error_code(), $error_message );
154 | }
155 | }
156 |
157 | return true;
158 | }
159 |
160 | /**
161 | * Format the number with ordinal suffix, without the PHP number formatter. That doesn't work on all systems.
162 | *
163 | * Taken from https://stackoverflow.com/a/3110033.
164 | *
165 | * @param int $number Number to format.
166 | * @return string Formatted number with ordinal suffix.
167 | */
168 | private static function format_number_with_ordinal( $number ) {
169 | $ends = array( 'th', 'st', 'nd', 'rd', 'th', 'th', 'th', 'th', 'th', 'th' );
170 | if ( ( $number % 100 ) >= 11 && ( $number % 100 ) <= 13 ) {
171 | return $number . 'th';
172 | } else {
173 | return $number . $ends[ $number % 10 ];
174 | }
175 | }
176 |
177 | /**
178 | * Returns true if the given 'default'-type rule is valid, or a WP_Error otherwise.
179 | *
180 | * @param array $rule Parsed rule.
181 | *
182 | * @return true|WP_Error
183 | */
184 | private static function verify_default_rule( $rule ) {
185 | if ( count( $rule ) === 1 ) {
186 | $rule_keys = self::format_array_to_keys( self::RULE_KEYS_GENERAL );
187 |
188 | /* translators: %s: Comma-separate list of valid rule keys */
189 | $error_message = sprintf( __( 'This default rule is empty. Add additional keys (%s) to make it functional.', 'vip-governance' ), $rule_keys );
190 | return new WP_Error( 'logic-rule-empty', $error_message );
191 | }
192 |
193 | foreach ( self::TYPE_TO_RULES_MAP as $type => $types ) {
194 | if ( isset( $rule[ $types ] ) ) {
195 | /* translators: %s: Comma-separate list of valid rule keys */
196 | $error_message = sprintf( __( '"default"-type rule should not contain "%1$s" key. Default rules apply to all %2$s.', 'vip-governance' ), $types, $type );
197 | return new WP_Error( 'logic-rule-default-type', $error_message );
198 | }
199 | }
200 |
201 | return true;
202 | }
203 |
204 | /**
205 | * Returns true if the given type rule is valid, or a WP_Error otherwise.
206 | *
207 | * @param array $rule Parsed rule.
208 | *
209 | * @return true|WP_Error
210 | */
211 | private static function verify_type_rule( $rule ) {
212 | $type_to_be_checked = self::TYPE_TO_RULES_MAP[ $rule['type'] ];
213 |
214 | if ( ! isset( $rule[ $type_to_be_checked ] ) || ! is_array( $rule[ $type_to_be_checked ] ) || empty( $rule[ $type_to_be_checked ] ) ) {
215 | $rule_keys = self::format_array_to_keys( self::RULE_KEYS_GENERAL );
216 |
217 | /* translators: %s: Comma-separate list of valid rule keys */
218 | $error_message = sprintf( __( '"%1$s"-type rules require a "%2$s" key containing an array of applicable "%3$s".', 'vip-governance' ), $rule['type'], $type_to_be_checked, $type_to_be_checked );
219 | return new WP_Error( 'logic-rule-type-missing-valid-types', $error_message );
220 | }
221 |
222 | if ( count( $rule ) === 2 ) {
223 | $rule_keys = self::format_array_to_keys( self::RULE_KEYS_GENERAL );
224 |
225 | /* translators: %s: Comma-separate list of valid rule keys */
226 | $error_message = sprintf( __( 'This rule doesn\'t apply any settings to the given type. Add additional keys (%s) to make it functional.', 'vip-governance' ), $rule_keys );
227 | return new WP_Error( 'logic-rule-empty', $error_message );
228 | }
229 |
230 | return true;
231 | }
232 |
233 | /**
234 | * Format an array into a quoted, comma-separated list of keys for display.
235 | * e.g. [ 'default', 'role' ] => '"default", "role"'.
236 | *
237 | * @param array $input_array Parsed rule.
238 | *
239 | * @return string Comma-separated list of quoted keys.
240 | */
241 | private static function format_array_to_keys( $input_array ) {
242 | return implode( ', ', array_map( function ( $item ) {
243 | return sprintf( '"%s"', $item );
244 | }, $input_array ) );
245 | }
246 | }
247 |
--------------------------------------------------------------------------------
/governance/settings/settings-view.php:
--------------------------------------------------------------------------------
1 | %s', esc_html( $line ) );
15 | }, explode( "\n", trim( $governance_rules_json ) ))) : false;
16 |
17 | ?>
18 |
19 | Rules for a type like roles work by combining the type's governance rules with default rules. Use this tool to view rules using the role/post type and debug permissions issues.
68 | 74 | 75 | 81 | 82 | 83 | 84 | 85 | 86 |93 | 97 |
98 |