Skip to content

Backgrounds

How-to Guides

Technical References

Multisites /

sunrise.php

When developing for a WordPress multisite, it is often necessary to load some custom code very early in the WordPress application’s loading sequence, e.g. to implement some custom domain mapping functionality. This can be accomplished by adding custom code to the WordPress Core drop-in file sunrise.php.

To load additional code in sunrise.php on VIP:

  1. Create a client-sunrise.php file in your site’s repository in the root vip-config folder. It will be loaded automatically.

To achieve the same behavior on a local development environment:

  1. Copy or symlink wp-content/mu-plugins/lib/sunrise/sunrise.php to wp-content/sunrise.php.
  2. Add define('SUNRISE', true) to wp-config.php.
  3. Copy or symlink vip-config/client-sunrise.php to ABSPATH / vip-config/client-sunrise.php

WordPress Reference

Before discussing how, it’s important to note that sunrise.php loads very early in WordPress, and most of its functions won’t be available. Further, sunrise.php loads before mu-plugins, any active plugins, and the active theme. As such, what can be done in sunrise.php is limited, and largely confined to using pure PHP to set constants that override WordPress Core behavior.

Guidelines

As already mentioned, the purpose of vip-config/client-sunrise.php is to execute PHP early in the WordPress cycle, before most of WordPress, including any theme or plugin code, loads. Typical uses for this file therefore share a few characteristics:

  • The problem being solved requires early execution (e.g. for performance reasons or to override aspects of the request very early on). Code that can run later in execution should typically be written in the plugin or theme context and leverage WordPress’ Plugin API.
  • The problem can be solved with (mostly) pure PHP.
  • The problem being solved does not require database access or access to any persistent data, but often makes decisions or performs actions based on intrinsic characteristics of the request, such as the domain or URI.  Because it executes on every single request handled by WordPress, make sure your use of sunrise.php does not introduce the kinds of performance penalties associated with queries or other expensive operations.
  • The scope of the problem being solved is well understood and minimized. Code executed within sunrise.php is kind of like a sledgehammer, and can have far-reaching effects. Do as much as you can to limit the conditions under which the code executes (such as limiting it to only certain URLs or certain domains) to reduce the probability of unintended side-effects.

Last updated: May 27, 2021

Related Topics