| 1 |
<?php |
| 2 |
/** |
| 3 |
* Settings functions used for Speculative Loading. |
| 4 |
* |
| 5 |
* @package speculation-rules |
| 6 |
* @since 1.0.0 |
| 7 |
*/ |
| 8 |
|
| 9 |
// @codeCoverageIgnoreStart |
| 10 |
if ( ! defined( 'ABSPATH' ) ) { |
| 11 |
exit; // Exit if accessed directly. |
| 12 |
} |
| 13 |
// @codeCoverageIgnoreEnd |
| 14 |
|
| 15 |
/** |
| 16 |
* Returns the available options for the Speculative Loading mode and their labels. |
| 17 |
* |
| 18 |
* @since 1.0.0 |
| 19 |
* |
| 20 |
* @return array{ prefetch: string, prerender: string } Associative array of `$mode => $label` pairs. |
| 21 |
*/ |
| 22 |
function plsr_get_mode_labels(): array { |
| 23 |
return array( |
| 24 |
'prefetch' => _x( 'Prefetch', 'setting label', 'speculation-rules' ), |
| 25 |
'prerender' => _x( 'Prerender', 'setting label', 'speculation-rules' ), |
| 26 |
); |
| 27 |
} |
| 28 |
|
| 29 |
/** |
| 30 |
* Returns the available options for the Speculative Loading eagerness and their labels. |
| 31 |
* |
| 32 |
* @since 1.0.0 |
| 33 |
* |
| 34 |
* @return array{ conservative: string, moderate: string, eager: string } Associative array of `$eagerness => $label` pairs. |
| 35 |
*/ |
| 36 |
function plsr_get_eagerness_labels(): array { |
| 37 |
return array( |
| 38 |
'conservative' => _x( 'Conservative (typically on click)', 'setting label', 'speculation-rules' ), |
| 39 |
'moderate' => _x( 'Moderate (typically on hover)', 'setting label', 'speculation-rules' ), |
| 40 |
'eager' => _x( 'Eager (on slightest suggestion)', 'setting label', 'speculation-rules' ), |
| 41 |
); |
| 42 |
} |
| 43 |
|
| 44 |
/** |
| 45 |
* Returns the default setting value for Speculative Loading configuration. |
| 46 |
* |
| 47 |
* @since 1.0.0 |
| 48 |
* |
| 49 |
* @return array{ mode: 'prerender', eagerness: 'moderate' } { |
| 50 |
* Default setting value. |
| 51 |
* |
| 52 |
* @type string $mode Mode. |
| 53 |
* @type string $eagerness Eagerness. |
| 54 |
* } |
| 55 |
*/ |
| 56 |
function plsr_get_setting_default(): array { |
| 57 |
return array( |
| 58 |
'mode' => 'prerender', |
| 59 |
'eagerness' => 'moderate', |
| 60 |
); |
| 61 |
} |
| 62 |
|
| 63 |
/** |
| 64 |
* Returns the stored setting value for Speculative Loading configuration. |
| 65 |
* |
| 66 |
* @since 1.4.0 |
| 67 |
* |
| 68 |
* @return array{ mode: 'prefetch'|'prerender', eagerness: 'conservative'|'moderate'|'eager' } { |
| 69 |
* Stored setting value. |
| 70 |
* |
| 71 |
* @type string $mode Mode. |
| 72 |
* @type string $eagerness Eagerness. |
| 73 |
* } |
| 74 |
*/ |
| 75 |
function plsr_get_stored_setting_value(): array { |
| 76 |
return plsr_sanitize_setting( get_option( 'plsr_speculation_rules' ) ); |
| 77 |
} |
| 78 |
|
| 79 |
/** |
| 80 |
* Sanitizes the setting for Speculative Loading configuration. |
| 81 |
* |
| 82 |
* @since 1.0.0 |
| 83 |
* @todo Consider whether the JSON schema for the setting could be reused here. |
| 84 |
* |
| 85 |
* @param mixed $input Setting to sanitize. |
| 86 |
* @return array{ mode: 'prefetch'|'prerender', eagerness: 'conservative'|'moderate'|'eager' } { |
| 87 |
* Sanitized setting. |
| 88 |
* |
| 89 |
* @type string $mode Mode. |
| 90 |
* @type string $eagerness Eagerness. |
| 91 |
* } |
| 92 |
*/ |
| 93 |
function plsr_sanitize_setting( $input ): array { |
| 94 |
$default_value = plsr_get_setting_default(); |
| 95 |
|
| 96 |
if ( ! is_array( $input ) ) { |
| 97 |
return $default_value; |
| 98 |
} |
| 99 |
|
| 100 |
// Ensure only valid keys are present. |
| 101 |
$value = array_intersect_key( array_merge( $default_value, $input ), $default_value ); |
| 102 |
|
| 103 |
// Constrain values to what is allowed. |
| 104 |
if ( ! in_array( $value['mode'], array_keys( plsr_get_mode_labels() ), true ) ) { |
| 105 |
$value['mode'] = $default_value['mode']; |
| 106 |
} |
| 107 |
if ( ! in_array( $value['eagerness'], array_keys( plsr_get_eagerness_labels() ), true ) ) { |
| 108 |
$value['eagerness'] = $default_value['eagerness']; |
| 109 |
} |
| 110 |
|
| 111 |
return $value; |
| 112 |
} |
| 113 |
|
| 114 |
/** |
| 115 |
* Registers setting to control Speculative Loading configuration. |
| 116 |
* |
| 117 |
* @since 1.0.0 |
| 118 |
* @access private |
| 119 |
*/ |
| 120 |
function plsr_register_setting(): void { |
| 121 |
register_setting( |
| 122 |
'reading', |
| 123 |
'plsr_speculation_rules', |
| 124 |
array( |
| 125 |
'type' => 'object', |
| 126 |
'description' => __( 'Configuration for the Speculation Rules API.', 'speculation-rules' ), |
| 127 |
'sanitize_callback' => 'plsr_sanitize_setting', |
| 128 |
'default' => plsr_get_setting_default(), |
| 129 |
'show_in_rest' => array( |
| 130 |
'schema' => array( |
| 131 |
'type' => 'object', |
| 132 |
'properties' => array( |
| 133 |
'mode' => array( |
| 134 |
'description' => __( 'Whether to prefetch or prerender URLs.', 'speculation-rules' ), |
| 135 |
'type' => 'string', |
| 136 |
'enum' => array_keys( plsr_get_mode_labels() ), |
| 137 |
), |
| 138 |
'eagerness' => array( |
| 139 |
'description' => __( 'The eagerness setting defines the heuristics based on which the loading is triggered. "Eager" will have the minimum delay to start speculative loads, "Conservative" increases the chance that only URLs the user actually navigates to are loaded.', 'speculation-rules' ), |
| 140 |
'type' => 'string', |
| 141 |
'enum' => array_keys( plsr_get_eagerness_labels() ), |
| 142 |
), |
| 143 |
), |
| 144 |
'additionalProperties' => false, |
| 145 |
), |
| 146 |
), |
| 147 |
) |
| 148 |
); |
| 149 |
} |
| 150 |
add_action( 'init', 'plsr_register_setting' ); |
| 151 |
|
| 152 |
/** |
| 153 |
* Adds the settings sections and fields for the Speculative Loading configuration. |
| 154 |
* |
| 155 |
* @since 1.0.0 |
| 156 |
* @access private |
| 157 |
*/ |
| 158 |
function plsr_add_setting_ui(): void { |
| 159 |
add_settings_section( |
| 160 |
'plsr_speculation_rules', |
| 161 |
__( 'Speculative Loading', 'speculation-rules' ), |
| 162 |
static function (): void { |
| 163 |
?> |
| 164 |
<p class="description"> |
| 165 |
<?php esc_html_e( 'This section allows you to control how URLs that your users navigate to are speculatively loaded to improve performance.', 'speculation-rules' ); ?> |
| 166 |
</p> |
| 167 |
<?php |
| 168 |
}, |
| 169 |
'reading', |
| 170 |
array( |
| 171 |
'before_section' => '<div id="speculative-loading">', |
| 172 |
'after_section' => '</div>', |
| 173 |
) |
| 174 |
); |
| 175 |
|
| 176 |
$fields = array( |
| 177 |
'mode' => array( |
| 178 |
'title' => __( 'Speculation Mode', 'speculation-rules' ), |
| 179 |
'description' => __( 'Prerendering will lead to faster load times than prefetching. However, in case of interactive content, prefetching may be a safer choice.', 'speculation-rules' ), |
| 180 |
), |
| 181 |
'eagerness' => array( |
| 182 |
'title' => __( 'Eagerness', 'speculation-rules' ), |
| 183 |
'description' => __( 'The eagerness setting defines the heuristics based on which the loading is triggered. "Eager" will have the minimum delay to start speculative loads, "Conservative" increases the chance that only URLs the user actually navigates to are loaded.', 'speculation-rules' ), |
| 184 |
), |
| 185 |
); |
| 186 |
foreach ( $fields as $slug => $args ) { |
| 187 |
add_settings_field( |
| 188 |
"plsr_speculation_rules_{$slug}", |
| 189 |
$args['title'], |
| 190 |
'plsr_render_settings_field', |
| 191 |
'reading', |
| 192 |
'plsr_speculation_rules', |
| 193 |
array_merge( |
| 194 |
array( 'field' => $slug ), |
| 195 |
$args |
| 196 |
) |
| 197 |
); |
| 198 |
} |
| 199 |
} |
| 200 |
add_action( 'load-options-reading.php', 'plsr_add_setting_ui' ); |
| 201 |
|
| 202 |
/** |
| 203 |
* Renders a settings field for the Speculative Loading configuration. |
| 204 |
* |
| 205 |
* @since 1.0.0 |
| 206 |
* @access private |
| 207 |
* |
| 208 |
* @param array{ field: 'mode'|'eagerness', title: non-empty-string, description: non-empty-string } $args { |
| 209 |
* Associative array of arguments. |
| 210 |
* |
| 211 |
* @type string $field The slug of the sub setting controlled by the field. |
| 212 |
* @type string $title The title for the field. |
| 213 |
* @type string $description Optional. A description to show for the field. |
| 214 |
* } |
| 215 |
*/ |
| 216 |
function plsr_render_settings_field( array $args ): void { |
| 217 |
$option = plsr_get_stored_setting_value(); |
| 218 |
|
| 219 |
switch ( $args['field'] ) { |
| 220 |
case 'mode': |
| 221 |
$choices = plsr_get_mode_labels(); |
| 222 |
break; |
| 223 |
case 'eagerness': |
| 224 |
$choices = plsr_get_eagerness_labels(); |
| 225 |
break; |
| 226 |
default: |
| 227 |
// Invalid (and this case should never occur). |
| 228 |
return; // @codeCoverageIgnore |
| 229 |
} |
| 230 |
|
| 231 |
$value = $option[ $args['field'] ]; |
| 232 |
?> |
| 233 |
<fieldset> |
| 234 |
<legend class="screen-reader-text"><?php echo esc_html( $args['title'] ); ?></legend> |
| 235 |
<?php foreach ( $choices as $slug => $label ) : ?> |
| 236 |
<p> |
| 237 |
<label> |
| 238 |
<input |
| 239 |
name="<?php echo esc_attr( "plsr_speculation_rules[{$args['field']}]" ); ?>" |
| 240 |
type="radio" |
| 241 |
value="<?php echo esc_attr( $slug ); ?>" |
| 242 |
<?php checked( $value, $slug ); ?> |
| 243 |
> |
| 244 |
<?php echo esc_html( $label ); ?> |
| 245 |
</label> |
| 246 |
</p> |
| 247 |
<?php endforeach; ?> |
| 248 |
|
| 249 |
<p class="description" style="max-width: 800px;"> |
| 250 |
<?php echo esc_html( $args['description'] ); ?> |
| 251 |
</p> |
| 252 |
</fieldset> |
| 253 |
<?php |
| 254 |
} |
| 255 |
|
| 256 |
/** |
| 257 |
* Adds a settings link to the plugin's action links. |
| 258 |
* |
| 259 |
* @since 1.2.1 |
| 260 |
* |
| 261 |
* @param string[]|mixed $links An array of plugin action links. |
| 262 |
* @return string[]|mixed The modified list of actions. |
| 263 |
*/ |
| 264 |
function plsr_add_settings_action_link( $links ) { |
| 265 |
if ( ! is_array( $links ) ) { |
| 266 |
return $links; |
| 267 |
} |
| 268 |
|
| 269 |
return array_merge( |
| 270 |
array( |
| 271 |
'settings' => sprintf( |
| 272 |
'<a href="%1$s">%2$s</a>', |
| 273 |
esc_url( admin_url( 'options-reading.php#speculative-loading' ) ), |
| 274 |
esc_html__( 'Settings', 'speculation-rules' ) |
| 275 |
), |
| 276 |
), |
| 277 |
$links |
| 278 |
); |
| 279 |
} |
| 280 |
add_filter( 'plugin_action_links_' . SPECULATION_RULES_MAIN_FILE, 'plsr_add_settings_action_link' ); |
| 281 |
|
