Using WordPress ‘pre_get_site_by_path’ PHP filter

pre_get_site_by_path is a WordPress PHP filter that allows you to short-circuit the default logic for determining a site by its domain and path.

You can replace it with a custom routine that is more optimal for your setup.

Usage

add_filter('pre_get_site_by_path', 'your_custom_function', 10, 5);

function your_custom_function($site, $domain, $path, $segments, $paths) {
    // your custom code here
    return $site;
}

Parameters

  • $site (null|false|WP_Site): Site value to return by path. Default is null to continue retrieving the site.
  • $domain (string): The requested domain.
  • $path (string): The requested path, in full.
  • $segments (int|null): The suggested number of paths to consult. Default is null, meaning the entire path was to be consulted.
  • $paths (string[]): The paths to search for, based on $path and $segments.

More information

See WordPress Developer Resources: https://developer.wordpress.org/reference/hooks/pre_get_site_by_path/

Examples

Custom Site Lookup

This example demonstrates how to use the pre_get_site_by_path filter to perform a custom site lookup using a different table in the database.

add_filter('pre_get_site_by_path', 'custom_site_lookup', 10, 5);

function custom_site_lookup($site, $domain, $path, $segments, $paths) {
    global $wpdb;

    // Replace 'your_custom_table' with your custom table name
    $custom_site = $wpdb->get_row($wpdb->prepare("SELECT * FROM your_custom_table WHERE domain = %s AND path = %s", $domain, $path));

    if ($custom_site) {
        // Convert the custom site object to a WP_Site object and return it
        return new WP_Site($custom_site);
    }

    // Return null to continue with the default site lookup
    return null;
}

Block Specific Domain

This example shows how to block a specific domain using the pre_get_site_by_path filter.

add_filter('pre_get_site_by_path', 'block_specific_domain', 10, 5);

function block_specific_domain($site, $domain, $path, $segments, $paths) {
    if ($domain == 'blocked.example.com') {
        return false;
    }
    return null;
}

Custom Path Segments

This example demonstrates how to use custom path segments with the pre_get_site_by_path filter.

add_filter('pre_get_site_by_path', 'custom_path_segments', 10, 5);

function custom_path_segments($site, $domain, $path, $segments, $paths) {
    if ($segments === null) {
        return null;
    }

    $custom_segments = 3; // Change this to your desired number of segments
    $new_paths = array_slice($paths, 0, $custom_segments);

    // Continue with the default site lookup using the custom paths
    return get_site_by_path($domain, $new_paths, $custom_segments);
}

Modify Site Object

This example shows how to modify a WP_Site object before returning it using the pre_get_site_by_path filter.

add_filter('pre_get_site_by_path', 'modify_site_object', 10, 5);

function modify_site_object($site, $domain, $path,$segments, $paths) {
if ($site instanceof WP_Site) {
// Modify the site object as needed, e.g., change the site name
$site->blogname = 'New Site Name';
}
return $site;
}

Fallback Site

This example demonstrates how to provide a fallback site when no site is found using the **pre_get_site_by_path** filter.

add_filter('pre_get_site_by_path', 'fallback_site', 10, 5);

function fallback_site($site, $domain, $path, $segments, $paths) {
    if ($site === false) {
        // Get the fallback site using its ID, replace 1 with the desired site ID
        $fallback_site = get_site(1);

        if ($fallback_site instanceof WP_Site) {
            return $fallback_site;
        }
    }
    return $site;
}