get_site_by_path( string $domain, string $path, int|null $segments = null ): WP_Site|false
- Since
- 3.9.0, 4.7.0
- Source
wp-includes/ms-load.php:163
Description
This will not necessarily return an exact match for a domain and path. Instead, it breaks the domain and path into pieces that are then used to match the closest possibility from a query.
The intent of this method is to match a site object during bootstrap for a requested site address
Compatibility
- WordPress
- since 4.7.0
- PHP
- 7.4–8.6-dev
- 6.7.7
- 6.8.8
- 6.9.7
- 7.0.4
- 7.1.0
Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.
Parameters
$domainstring- Domain to check.
$pathstring- Path to check.
$segmentsint|nulloptional- Path segments to use. Defaults to null, or the full path.Default:
null
Return value
WP_Site|false- Site object if successful. False when no site is found.
Performance profile
How much work a call to get_site_by_path() 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
- Light
- Scaling
- Scales with input
- Instructions
- 41–82
- Plugin surface
- 2 hooks
- Called by
- 1
Touches nothing outside its own arguments.
The body loops, so the work grows with what you pass in.
Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 110.
Third-party callbacks on 'site_by_path_segments_count', 'pre_get_site_by_path' 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
- hookthird-party callbacks
apply_filters()called directly
What one call costs · 8 distinct outcomes
One number would be a lie: the work depends on which branch runs. These are every distinct cost get_site_by_path() can have, taken from its control-flow graph on PHP 8.5.
| When | Instructions | Calls it makes |
|---|---|---|
!$path_segments && $pre !== null | 41–50 | explode(), array_filter(), apply_filters(), apply_filters() |
$segments !== null && $segments && !$path_segments && $pre !== null | 50–56 | explode(), array_filter(), apply_filters(), array_slice(), apply_filters() |
!$path_segments && $pre === null | 68–74 | explode(), array_filter(), apply_filters(), apply_filters(), array_shift(), array_shift(), get_sites(), array_shift() |
!$path_segments && $pre === null | 69–75 | explode(), array_filter(), apply_filters(), apply_filters(), array_shift(), get_sites(), array_shift() |
!$path_segments && $pre === null | 70–76 | explode(), array_filter(), apply_filters(), apply_filters(), get_sites(), array_shift() |
$segments !== null && $segments && !$path_segments && $pre === null | 77–80 | explode(), array_filter(), apply_filters(), array_slice(), apply_filters(), array_shift(), array_shift(), get_sites(), array_shift() |
$segments !== null && $segments && !$path_segments && $pre === null | 78–81 | explode(), array_filter(), apply_filters(), array_slice(), apply_filters(), array_shift(), get_sites(), array_shift() |
$segments !== null && $segments && !$path_segments && $pre === null | 79–82 | explode(), array_filter(), apply_filters(), array_slice(), apply_filters(), get_sites(), array_shift() |
Across PHP versions
| PHP | Compiled | Executed | Branches | Notes |
|---|---|---|---|---|
| 8.6-dev | 110 | 41–82 | 10 | |
| 8.5 | 110 | 41–82 | 10 | |
| 8.4 | 110 | 41–82 | 10 | 12 fewer instructions than PHP 8.3 |
| 8.3 | 122 | 44–91 | 10 | |
| 8.2 | 122 | 44–91 | 10 | |
| 8.1 | 122 | 44–91 | 10 | |
| 7.4 | 122 | 44–91 | 10 |
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 get_site_by_path() runs, in this order:
- apply_filters( site_by_path_segments_count )filterline 177 (+14 into the body)
Filters the number of path segments to consider when searching for a site.
- apply_filters( pre_get_site_by_path )filterline 212 (+49 into the body)
Determines a site by its domain and path.
Uses · 4
- apply_filters()Calls the callback functions that have been added to a filter hook.
- str_starts_with()Polyfill for `str_starts_with()` function added in PHP 8.0.
- get_sites()Retrieves a list of sites matching requested arguments.
- WP_Site::__construct()Creates a new WP_Site object.
Used by · 1
- ms_load_current_site_and_network()Identifies the network and site of a requested domain and path and populates the corresponding network and site global objects as part of the multisite bootstrap process.
Source code
function get_site_by_path( $domain, $path, $segments = null ) { $path_segments = array_filter( explode( '/', trim( $path, '/' ) ) ); /** * Filters the number of path segments to consider when searching for a site. * * @since 3.9.0 * * @param int|null $segments The number of path segments to consider. WordPress by default looks at * one path segment following the network path. The function default of * null only makes sense when you know the requested path should match a site. * @param string $domain The requested domain. * @param string $path The requested path, in full. */ $segments = apply_filters( 'site_by_path_segments_count', $segments, $domain, $path ); if ( null !== $segments && count( $path_segments ) > $segments ) { $path_segments = array_slice( $path_segments, 0, $segments ); } $paths = array(); while ( count( $path_segments ) ) { $paths[] = '/' . implode( '/', $path_segments ) . '/'; array_pop( $path_segments ); } $paths[] = '/'; /** * Determines a site by its domain and path. * * This allows one to short-circuit the default logic, perhaps by * replacing it with a routine that is more optimal for your setup. * * Return null to avoid the short-circuit. Return false if no site * can be found at the requested domain and path. Otherwise, return * a site object. * * @since 3.9.0 * * @param null|false|WP_Site $site Site value to return by path. Default null * to continue retrieving the site. * @param string $domain The requested domain. * @param string $path The requested path, in full. * @param int|null $segments The suggested number of paths to consult. * Default null, meaning the entire path was to be consulted. * @param string[] $paths The paths to search for, based on $path and $segments. */ $pre = apply_filters( 'pre_get_site_by_path', null, $domain, $path, $segments, $paths ); if ( null !== $pre ) { if ( false !== $pre && ! $pre instanceof WP_Site ) { $pre = new WP_Site( $pre ); } return $pre; } /* * @todo * Caching, etc. Consider alternative optimization routes, * perhaps as an opt-in for plugins, rather than using the pre_* filter. * For example: The segments filter can expand or ignore paths. * If persistent caching is enabled, we could query the DB for a path <> '/' * then cache whether we can just always ignore paths. */ /* * Either www or non-www is supported, not both. If a www domain is requested, * query for both to provide the proper redirect. */ $domains = array( $domain ); if ( str_starts_with( $domain, 'www.' ) ) { $domains[] = substr( $domain, 4 ); } $args = array( 'number' => 1, 'update_site_meta_cache' => false, );Changelog
Introduced in 3.9.0. Unchanged from 6.7.7 through 7.1.0.
Signature, return type and hooks compared across 5 parsed releases.
WP_Site object.from the docblockAbout this page
- Parsed data
- Generated from the wordpress-develop 7.1.0 tag, from
src/wp-includes/ms-load.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.