sunrise.php: The File That Lets You Override WordPress Multisite Routing

Most WordPress developers never touch sunrise.php.

Many don’t even know it exists.

But in multisite environments, this file is one of the most powerful—and least documented—entry points in the entire system.

It allows you to intercept and override how WordPress determines the current site before it fully boots.

This is how advanced setups implement domain mapping, SaaS routing, and custom network logic.

What is sunrise.php?

sunrise.php is an optional file located in:

wp-content/sunrise.php

It is loaded very early in the multisite bootstrap process—but only if explicitly enabled.

Enable sunrise.php

<?php
define( 'SUNRISE', true );

This must be added to wp-config.php.

Once enabled, WordPress loads sunrise.php before resolving the current site.

Where It Runs in the Boot Process

wp-load.php
└── wp-config.php
    └── wp-settings.php
        └── ms-settings.php
            ├── sunrise.php ← YOU ARE HERE
            └── Site resolution continues

This is before WordPress determines which site is being requested.

You are effectively intercepting routing logic itself.

The Core Concept: Site Resolution

In multisite, WordPress determines the active site using:

• Domain
• Path

It populates two critical globals:

• $current_site
• $current_blog

sunrise.php allows you to override these before WordPress sets them.

Basic Example: Manual Site Mapping

<?php
// wp-content/sunrise.php

$domain = $_SERVER['HTTP_HOST'];

if ( $domain === 'example-client.com' ) {
    $current_blog = (object) [
        'blog_id' => 3,
        'domain'  => $domain,
        'path'    => '/'
    ];

    $current_site = (object) [
        'id'     => 1,
        'domain' => $domain,
        'path'   => '/'
    ];
}

This forces WordPress to load a specific site based on a custom domain.

Domain Mapping (Real-World Use Case)

Domain mapping is the most common use of sunrise.php.

Instead of:

site1.network.com

You can serve:

clientdomain.com

Example: Database-Driven Mapping

<?php

global $wpdb;

$domain = $_SERVER['HTTP_HOST'];

$mapping = $wpdb->get_row(
    $wpdb->prepare(
        "SELECT blog_id FROM domain_map WHERE domain = %s",
        $domain
    )
);

if ( $mapping ) {
    $blog_id = (int) $mapping->blog_id;

    $details = \get_blog_details( $blog_id );

    $current_blog = $details;
    $current_site = \get_site( $details->site_id );
}

This enables fully dynamic domain routing.

current_blog Manipulation (Advanced Control)

$current_blog determines:

• Which database tables are used
• Which options are loaded
• Which content is served

By modifying it, you control the entire request context.

Example: Force a Maintenance Site

<?php

if ( strpos( $_SERVER['REQUEST_URI'], '/maintenance') !== false ) {
    $current_blog = \get_blog_details( 5 ); // maintenance site
}

This reroutes requests dynamically.

Early Routing Logic (Before WordPress Knows Anything)

At this stage:

• No plugins loaded
• No themes loaded
• Minimal core available

This makes sunrise.php extremely powerful—but also dangerous if misused.

Advanced Use Cases

1. SaaS Platform Routing

Map customer domains to specific sites dynamically.

2. Geo-Based Routing

<?php

$country = $_SERVER['HTTP_CF_IPCOUNTRY'] ?? 'US';

if ( $country === 'DE' ) {
    $current_blog = \get_blog_details(7);
}

3. A/B Testing at Routing Level

<?php

if ( rand(0, 1) ) {
    $current_blog = \get_blog_details( 2 );
}

4. Blue-Green Deployments

Switch traffic between environments instantly.

Limitations and Caveats

• No plugin APIs available yet
• Limited WordPress functions
• Must handle globals carefully
• Debugging is harder

Incorrect usage can break the entire network.

Performance Implications

Because it runs early:

• No plugin overhead
• No unnecessary queries (if optimized)
• Fast routing decisions

This is ideal for high-scale multisite environments.

Key Insight Most Developers Miss

sunrise.php is not a configuration file—it’s a routing override layer.

You are not modifying WordPress behavior.

You are deciding which WordPress site will even load.

This is one of the deepest control points available.

FAQ