get_site_by_path

Retrieves the closest matching site object by its domain and path.

Description

(WP_Site|false) get_site_by_path( (string) $domain, (string) $path, (null) $segments = null ); 

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

Returns (WP_Site|false)

Site object if successful. False when no site is found.

Parameters (3)

0. $domain (string)
Domain to check.
1. $path (string)
Path to check.
2. $segments — Optional. (null) => null
Path segments to use. Defaults to null, or the full path.

Usage

  1. if ( !function_exists( 'get_site_by_path' ) ) { 
  2. require_once ABSPATH . WPINC . '/ms-load.php'; 
  3.  
  4. // Domain to check. 
  5. $domain = ''; 
  6.  
  7. // Path to check. 
  8. $path = ''; 
  9.  
  10. // Path segments to use. Defaults to null, or the full path. 
  11. $segments = null; 
  12.  
  13. // NOTICE! Understand what this does before running. 
  14. $result = get_site_by_path($domain, $path, $segments); 
  15.  

Defined (1)

The function is defined in the following location(s).

/wp-includes/ms-load.php  
  1. function get_site_by_path( $domain, $path, $segments = null ) { 
  2. $path_segments = array_filter( explode( '/', trim( $path, '/' ) ) ); 
  3.  
  4. /** 
  5. * Filters the number of path segments to consider when searching for a site. 
  6. * @since 3.9.0 
  7. * @param int|null $segments The number of path segments to consider. WordPress by default looks at 
  8. * one path segment following the network path. The function default of 
  9. * null only makes sense when you know the requested path should match a site. 
  10. * @param string $domain The requested domain. 
  11. * @param string $path The requested path, in full. 
  12. */ 
  13. $segments = apply_filters( 'site_by_path_segments_count', $segments, $domain, $path ); 
  14.  
  15. if ( null !== $segments && count( $path_segments ) > $segments ) { 
  16. $path_segments = array_slice( $path_segments, 0, $segments ); 
  17.  
  18. $paths = array(); 
  19.  
  20. while ( count( $path_segments ) ) { 
  21. $paths[] = '/' . implode( '/', $path_segments ) . '/'; 
  22. array_pop( $path_segments ); 
  23.  
  24. $paths[] = '/'; 
  25.  
  26. /** 
  27. * Determine a site by its domain and path. 
  28. * This allows one to short-circuit the default logic, perhaps by 
  29. * replacing it with a routine that is more optimal for your setup. 
  30. * Return null to avoid the short-circuit. Return false if no site 
  31. * can be found at the requested domain and path. Otherwise, return 
  32. * a site object. 
  33. * @since 3.9.0 
  34. * @param null|bool|WP_Site $site Site value to return by path. 
  35. * @param string $domain The requested domain. 
  36. * @param string $path The requested path, in full. 
  37. * @param int|null $segments The suggested number of paths to consult. 
  38. * Default null, meaning the entire path was to be consulted. 
  39. * @param array $paths The paths to search for, based on $path and $segments. 
  40. */ 
  41. $pre = apply_filters( 'pre_get_site_by_path', null, $domain, $path, $segments, $paths ); 
  42. if ( null !== $pre ) { 
  43. if ( false !== $pre && ! $pre instanceof WP_Site ) { 
  44. $pre = new WP_Site( $pre ); 
  45. return $pre; 
  46.  
  47. /** 
  48. * @todo 
  49. * caching, etc. Consider alternative optimization routes,  
  50. * perhaps as an opt-in for plugins, rather than using the pre_* filter. 
  51. * For example: The segments filter can expand or ignore paths. 
  52. * If persistent caching is enabled, we could query the DB for a path <> '/' 
  53. * then cache whether we can just always ignore paths. 
  54. */ 
  55.  
  56. // Either www or non-www is supported, not both. If a www domain is requested,  
  57. // query for both to provide the proper redirect. 
  58. $domains = array( $domain ); 
  59. if ( 'www.' === substr( $domain, 0, 4 ) ) { 
  60. $domains[] = substr( $domain, 4 ); 
  61.  
  62. $args = array( 
  63. 'domain__in' => $domains,  
  64. 'path__in' => $paths,  
  65. 'number' => 1,  
  66. ); 
  67.  
  68. if ( count( $domains ) > 1 ) { 
  69. $args['orderby']['domain_length'] = 'DESC'; 
  70.  
  71. if ( count( $paths ) > 1 ) { 
  72. $args['orderby']['path_length'] = 'DESC'; 
  73.  
  74. $result = get_sites( $args ); 
  75. $site = array_shift( $result ); 
  76.  
  77. if ( $site ) { 
  78. return $site; 
  79.  
  80. return false;