wp_get_speculation_rules(): WP_Speculation_Rules|null
- Since
- 6.8.0
- Source
wp-includes/speculative-loading.php:195
Description
Plugins with features that rely on frontend URLs to exclude from prefetching or prerendering should use the 'wp_speculation_rules_href_exclude_paths' filter to ensure those URL patterns are excluded.
Additional speculation rules other than the default rule from WordPress Core can be provided by using the 'wp_load_speculation_rules' action and amending the passed WP_Speculation_Rules object.
Compatibility
- WordPress
- since 6.8.0
- PHP
- 7.4–8.6-dev
- 6.7.7
- 6.8.8
- 6.9.7
- 7.0.4
- 7.1.0
Present in 4 of the 5 tracked releases, added in 6.8.0, and compiles on PHP 7.4 through 8.6-dev.
Return value
WP_Speculation_Rules|null- Object representing the speculation rules to use, or null if speculative loading is disabled in the current context.
Performance profile
How much work a call to wp_get_speculation_rules() does, and what it touches: the algorithmic scaling, the Zend instruction count per call across PHP versions, the hooks it hands control to, and the core code that calls it. Measured from the compiled opcodes, not a stopwatch, so every number is identical on any machine running the same PHP version, and every function in core is ranked by cost.
- Cost class
- Moderate
- Scaling
- Constant
- Instructions
- 7
- Plugin surface
- 2 hooks
- Called by
- 1
Reads stored settings via get_option(), cached per request but not free on a cold cache.
No loop in the body: the same number of instructions runs whatever you pass in.
Executed per call on PHP 8.5. The body compiles to 139.
Third-party callbacks on 'wp_speculation_rules_href_exclude_paths', 'wp_load_speculation_rules' run inside this call, and their cost is not bounded by anything here.
1 place in core call this, so the cost is paid more often than your own code shows.
What it touches
- optionoption read or write
get_option()called directly - hookthird-party callbacks
apply_filters()called directly - cacheobject cache
wp_cache_get()one call below wp_get_speculation_rules() - serializeserialisation
maybe_unserialize()one call below wp_get_speculation_rules()
Further down the call graph this can also reach query and transient. Those are the worst case, several calls deep and usually down an error path, not what a normal call pays.
What one call costs · 1 distinct outcome
One number would be a lie: the work depends on which branch runs. These are every distinct cost wp_get_speculation_rules() can have, taken from its control-flow graph on PHP 8.5.
| When | Instructions | Calls it makes |
|---|---|---|
| always | 7 | ->prefix_path_pattern() |
Across PHP versions
Compiles the same on PHP 7.4, 8.1, 8.2, 8.3, 8.4, 8.5 and 8.6-dev: 139 instructions, 7 executed per call, 3 branches. The work does not change between versions.
An instruction is not a fixed amount of time, so a matching count is not necessarily the same speed; what it rules out is a difference in the work itself.
Hooks and filters fired · 2
2 hooks fire while wp_get_speculation_rules() runs, in this order:
- apply_filters( wp_speculation_rules_href_exclude_paths )filterline 241 (+46 into the body)
Filters the paths for which speculative loading should be disabled.
- do_action( wp_load_speculation_rules )actionline 317 (+122 into the body)
Fires when speculation rules data is loaded, allowing to amend the rules.
Uses · 6
- wp_get_speculation_rules_configuration()Returns the speculation rules configuration.
- get_option()Retrieves an option value based on an option name.
- apply_filters()Calls the callback functions that have been added to a filter hook.
- do_action()Calls the callback functions that have been added to an action hook.
- WP_URL_Pattern_Prefixer::__construct()Constructor.
- WP_Speculation_Rules::__construct()
Used by · 1
- wp_print_speculation_rules()Prints the speculation rules.
Source code
function wp_get_speculation_rules(): ?WP_Speculation_Rules { $configuration = wp_get_speculation_rules_configuration(); if ( null === $configuration ) { return null; } $mode = $configuration['mode']; $eagerness = $configuration['eagerness']; $prefixer = new WP_URL_Pattern_Prefixer(); $base_href_exclude_paths = array( $prefixer->prefix_path_pattern( '/wp-*.php', 'site' ), $prefixer->prefix_path_pattern( '/wp-admin/*', 'site' ), $prefixer->prefix_path_pattern( '/*', 'uploads' ), $prefixer->prefix_path_pattern( '/*', 'content' ), $prefixer->prefix_path_pattern( '/*', 'plugins' ), $prefixer->prefix_path_pattern( '/*', 'template' ), $prefixer->prefix_path_pattern( '/*', 'stylesheet' ), ); /* * If pretty permalinks are enabled, exclude any URLs with query parameters. * Otherwise, exclude specifically the URLs with a `_wpnonce` query parameter or any other query parameter * containing the word `nonce`. */ if ( get_option( 'permalink_structure' ) ) { $base_href_exclude_paths[] = $prefixer->prefix_path_pattern( '/*\\?(.+)', 'home' ); } else { $base_href_exclude_paths[] = $prefixer->prefix_path_pattern( '/*\\?*(^|&)*nonce*=*', 'home' ); } /** * Filters the paths for which speculative loading should be disabled. * * All paths should start in a forward slash, relative to the root document. The `*` can be used as a wildcard. * If the WordPress site is in a subdirectory, the exclude paths will automatically be prefixed as necessary. * * Note that WordPress always excludes certain path patterns such as `/wp-login.php` and `/wp-admin/*`, and those * cannot be modified using the filter. * * @since 6.8.0 * * @param string[] $href_exclude_paths Additional path patterns to disable speculative loading for. * @param string $mode Mode used to apply speculative loading. Either 'prefetch' or 'prerender'. */ $href_exclude_paths = (array) apply_filters( 'wp_speculation_rules_href_exclude_paths', array(), $mode ); $href_exclude_paths = array_filter( $href_exclude_paths, 'is_string' ); // Ensure that: // 1. There are no duplicates. // 2. The base paths cannot be removed. // 3. The array has sequential keys (i.e. array_is_list()). $href_exclude_paths = array_values( array_unique( array_merge( $base_href_exclude_paths, array_map( static function ( string $href_exclude_path ) use ( $prefixer ): string { return $prefixer->prefix_path_pattern( $href_exclude_path ); }, $href_exclude_paths ) ) ) ); $speculation_rules = new WP_Speculation_Rules(); $main_rule_conditions = array( // Include any URLs within the same site. array( 'href_matches' => $prefixer->prefix_path_pattern( '/*' ), ), // Except for excluded paths. array( 'not' => array( 'href_matches' => $href_exclude_paths, ), ),Changelog
Introduced in 6.8.0. Unchanged from 6.8.8 through 7.1.0.
Signature, return type and hooks compared across 4 parsed releases.
About this page
- Parsed data
- Generated from the wordpress-develop 7.1.0 tag, from
src/wp-includes/speculative-loading.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it. - Corrections
- Something wrong on this page? Report it and it gets fixed in the next regeneration.