wpseek.com
A WordPress-centric search engine for devs and theme authors

function wp_get_speculation_rules_configuration(): ?array {
	// By default, speculative loading is only enabled for sites with pretty permalinks when no user is logged in.
	if ( ! is_user_logged_in() && get_option( 'permalink_structure' ) ) {
		$config = array(
			'mode'      => 'auto',
			'eagerness' => 'auto',
		);
	} else {
		$config = null;
	}

	/**
	 * Filters the way that speculation rules are configured.
	 *
	 * The Speculation Rules API is a web API that allows to automatically prefetch or prerender certain URLs on the
	 * page, which can lead to near-instant page load times. This is also referred to as speculative loading.
	 *
	 * There are two aspects to the configuration:
	 * * The "mode" (whether to "prefetch" or "prerender" URLs).
	 * * The "eagerness" (whether to speculatively load URLs in an "eager", "moderate", or "conservative" way).
	 *
	 * By default, the speculation rules configuration is decided by WordPress Core ("auto"). This filter can be used
	 * to force a certain configuration, which could for instance load URLs more or less eagerly.
	 *
	 * For logged-in users or for sites that are not configured to use pretty permalinks, the default value is `null`,
	 * indicating that speculative loading is entirely disabled.
	 *
	 * @since 6.8.0
	 * @see https://developer.chrome.com/docs/web-platform/prerender-pages
	 *
	 * @param array<string, string>|null $config Associative array with 'mode' and 'eagerness' keys, or `null`. The
	 *                                           default value for both of the keys is 'auto'. Other possible values
	 *                                           for 'mode' are 'prefetch' and 'prerender'. Other possible values for
	 *                                           'eagerness' are 'eager', 'moderate', and 'conservative'. The value
	 *                                           `null` is used to disable speculative loading entirely.
	 */
	$config = apply_filters( 'wp_speculation_rules_configuration', $config );

	// Allow the value `null` to indicate that speculative loading is disabled.
	if ( null === $config ) {
		return null;
	}

	// Sanitize the configuration and replace 'auto' with current defaults.
	$default_mode      = 'prefetch';
	$default_eagerness = 'conservative';
	if ( ! is_array( $config ) ) {
		return array(
			'mode'      => $default_mode,
			'eagerness' => $default_eagerness,
		);
	}
	if (
		! isset( $config['mode'] ) ||
		'auto' === $config['mode'] ||
		! WP_Speculation_Rules::is_valid_mode( $config['mode'] )
	) {
		$config['mode'] = $default_mode;
	}
	if (
		! isset( $config['eagerness'] ) ||
		'auto' === $config['eagerness'] ||
		! WP_Speculation_Rules::is_valid_eagerness( $config['eagerness'] ) ||
		// 'immediate' is a valid eagerness, but for safety WordPress does not allow it for document-level rules.
		'immediate' === $config['eagerness']
	) {
		$config['eagerness'] = $default_eagerness;
	}

	return array(
		'mode'      => $config['mode'],
		'eagerness' => $config['eagerness'],
	);
}