Nextgen Bootstrap/Load Feature Project

The bootstrapping process of WordPress Core (affectionately called the “Bootstrap/Load” component around here) is a critical piece of the system, and everything else depends on it being reliable and performant. However, developers and system administrators also need it to be flexible enough to adapt to the requirements of their differing projects or environments. Large-scale WordPress installations often require substantial customizations to adjust for scalability and redundancy.

Considering the importance of this component, the documentation is not adequate, and very few people actually know what the exact flow is. More importantly, there isn’t a wide understanding of why specific decisions had been taken, and how later code depends on the bootstrap process.

This proposal aims to launch a feature project to work on the next iteration of the bootstrap component with a set of specific goals in mind.


To be able to guide the design process and have measurable success metrics, clear goals need to be defined.

Here’s an overview of what specific goals the project should aim for:

  1. The component has proper documentation for every step of the process.
    Documentation will include both clear comments in the source as well as an external documentation space that includes reference material, execution flow diagrams, best practices and examples of usage.
  2. The component models a modernized flow which still provides same sane defaults, but enables advanced use cases in a supported way.
    Customizing high-volume sites or specialized applications should be less “hacky”, and all of the major subsystems should provide reliable means of configuration/extension.
  3. The component adapts to differing contexts to optimize both performance and memory consumption where possible.
    The system should be able to intelligently load only the parts of the code that are strictly necessary for the current requests, through means of conditional execution flows, smart routing, proxy objects and autoloading. Special consideration should be given to the WP REST API endpoints to make them as fast and efficient as possible.
  4. The component offers a coherent way of supporting all versions of multisite (networks), reducing some of the idiosyncrasies that currently exist.
    The difference between single sites, networks of sites and networks of networks should be kept as small as possible so that less care needs to be taken to have the code work reliably with all of them.
  5. The component considers both backward compatibility as well as forward compatibility.
    It is of paramount importance that existing sites do not break due to the changes that will be proposed with this project. However, forward compatibility needs to be taken into account just as well, to create a next version of the bootstrap component that can easily grow with future requirements in a controlled way.

Project Phases

The project will have four different phases: Discovery, Design, Execution and Merge Proposal.

1. Discovery

The Discovery Phase aims to properly research and document the status quo. It will be a thorough analysis of source code, trac tickets and contributor discussions to decipher the reasoning behind the current implementation and what the requirements, strengths and weaknesses are. Documentation will be written in parallel, logging all findings and producing a better onboarding process for this component. Characterization tests will be written to be able to detect regressions when making changes in phase 3 later on.

2. Design

The Design phase will examine all the findings from phase one to design a new version of the bootstrap component that meets all the requirements and strengths while reducing some or all of the weaknesses and improving reliability, flexibility and performance.

We want to avoid having yet another component update that just grows organically. There should be strong principles in place that make sure that the new version is not only backward compatible but also forward compatible.

3. Execution

The Execution phase will create a modified fork/branch of WordPress Core, to allow for collaborative work on this new iteration of the bootstrap component.

Through automated tests, refactoring will be guided to implement the design from phase 2. The characterization tests from phase 1 will make sure that compatibility remains a given, even for “compatibility-enforced bugs”. Optional mechanisms to get saner results in such cases will be discussed on a case-by-case basis.

4. Merge Proposal

The Merge Proposal phase will be the final phase of the project, identifying a clean merge process and a proper migration path to merge the new version of the component into Core.

Metrics will need to be defined to have measurable and achievable goals that can objectively tell whether the Component is ready to be merged.


During the initial Discovery Phase, contributions in the following areas will prove to be useful:

Advanced Use Cases

We need lots of data about the types of customizations that people use for their projects: bootstrap modifications (WP-CLI), complex network hierarchies, folder rearrangements, specialized caches, etc.

Problems With Current Code

We need to know about all and any challenges and limitations that you have been experiencing with the current bootstrapping flow: setups that were difficult or impossible to achieve, settings that didn’t yield the expected results, etc.


Documentation will not only need to be written for the way the current code works, but also for all deprecated functionality, buggy behavior and unexpected side-effects. We are going for completeness, not ease-of-use here. Documentation should also cover best practices for modifying the bootstrap process.

Join us in #core-bootstrap to start contributing!

Thanks to Helen Hou-Sandì (@helen), Jeremy Felt (@jeremyfelt) and Aaron Jorbin (@jorbin) for their help in shaping this proposal.

#bootstrap-load, #core

Changed loading order for current user in 4.7

With the introduction of user locales it’s required to load the current user earlier in the bootstrap. Since WordPress 3.4 this is already the case for the customizer, see #24169 and the following simplified function stack:

{main}()                              .../customize.php:0
require_once( '/wp-admin/admin.php' ) .../customize.php:13
require_once( '/wp-load.php' )        .../admin.php:31
require_once( '/wp-config.php' )      .../wp-load.php:44
require_once( '/wp-settings.php' )    .../wp-config.php:118
do_action( 'plugins_loaded' )         .../wp-settings.php:295
_wp_customize_include()               .../plugin.php:524
WP_Customize_Manager->__construct()   .../theme.php:2086
WP_Customize_Widgets->__construct()   .../class-wp-customize-manager.php:266
current_user_can()                    .../class-wp-customize-widgets.php:97
wp_get_current_user()                 .../capabilities.php:448

For other requests the stack looks like this:

{main}()                              .../index.php:0
require_once( '/wp-admin/admin.php' ) .../index.php:10
require_once( '/wp-load.php' )        .../admin.php:31
require_once( '/wp-config.php' )      .../wp-load.php:44
require_once( '/wp-settings.php' )    .../wp-config.php:118
WP->init()                            .../wp-settings.php:398
wp_get_current_user()                 .../class-wp.php:595

WP->init() runs between the after_setup_theme and the init action.

With WordPress 4.7 the function stack for admin requests will look like this:

{main}()                              .../index.php:0
require_once( '/wp-admin/admin.php' ) .../index.php:10
require_once( '/wp-load.php' )        .../admin.php:31
require_once( '/wp-config.php' )      .../wp-load.php:42
require_once( '/wp-settings.php' )    .../wp-config.php:127
load_default_textdomain()             .../wp-settings.php:389
get_user_locale()                     .../l10n.php:665
wp_get_current_user()                 .../l10n.php:92

That’s because load_default_textdomain() needs to know the locale of the current user. load_default_textdomain() is called after setup_theme and before after_setup_theme (which is before WP->init()).
If you compare this with the stack for the customizer then you’ll notice that wp_get_current_user() is still loaded much later.

get_user_locale() is also used in the other text domain loading functions like load_plugin_textdomain() or load_theme_textdomain(). For backward compatibility we’ve made sure that no fatal errors are thrown when one of them is called before WordPress is fully initialized, see [39127] and [39134].

Until recently BuddyPress and bbPress had a custom notice when a user was initialized without using WP->init(). This was fixed in #7305-buddypress and #2309-bbpress together with a new wp_roles_init filter in core. The new filter allows plugins to add their own custom roles whenever they’re initialized, see #23016.

#4-7, #bootstrap-load, #dev-notes

Global overloading in advanced-cache.php

As a part of the 4.6 release, a change is made to the order of loading files during the bootstrap process. This change included an attempt to protect sites from the overloading of the hook related globals in advanced-cache.php. This change was reverted with [38251]. This means that the 4.5 behavior where if an advanced-cache.php sets one of the globals to an empty array, previously entered records will not exist.

This is a general reminder to not directly touch the globals in WordPress and to always use API functions. The format that the globals are in is not guaranteed to stay consistent from version to version. If you need to interact with the Plugins API in advanced-cache.php, as of 4.6, you can use the Plugins API (add_action(), add_filter(), etc.).

How to know if you are using advanced-cache.php

advanced-cache.php is a drop-in. If you are using any drop-ins, you will see “Drop-ins” at the top of wp-admin/plugins.php as one of the filtering options. If advanced-cache.php is listed and no warning is displayed, your site is using it. This file lives in your wp-content directory as a peer to plugins and themes. Updates to it are not made like updates to plugins. You will never see a notice that there is an update pending. If you did not write this code yourself, you are encouraged to keep up to date with upstream updates.

#4-6, #bootstrap-load, #dev-notes

Bootstrap/Load updates in 4.6

Alert: A change was made to remove protection for overloading Plugin API related global variables in advanced-cache.php

Every time WordPress is loaded, it goes through the bootstrap or loading process. In WordPress 4.6, there will be a few changes to the process focused on making pieces available earlier. Many of these changes will have no effect whatsoever on the vast majority of WordPress sites. However, if you are the type that maintains your own advanced-cache.php drop-in, host/run large profile sites, or work on tools that bootstrap WordPress is odd ways than this article is for you!

Load plugin.php earlier in wp-settings.php

plugin.php contains the functions such as add_filter() and add_action() that form the foundation of the WordPress plugin system. The file (and thus those functions) are now being loaded earlier in wp-settings.php. This allows for some hooks to be placed earlier, but also for advance-cache.php drop-ins to use the plugins API rather than directly manipulating global variables. For more information, see #36819.

Reconcile wp-settings-cli.php with wp-settings.php

Any time WordPress made a change to wp-settings.php, it inevitably broke WP-CLI. In order to allow WP-CLI to no longer need to maintain a custom fork, a handful of new hooks were added to the bootstrap process. These hooks happen before plugins load. They are designed more for non-web uses such as WP-CLI. For more information about these hooks, see #34936.

is_ssl() is now located in wp-includes/load.php

Many advanced-cache.php drop-ins duplicate is_ssl(). They will no longer need to do that as it will be available earlier in the bootstrap process. See #35844 for more info on this change.

ABSPATH can now be safely defined before WordPress is loaded

Defining ABSPATH in an auto_prepend_file will no longer cause notices to be generated. This can lead to less complexity for some WordPress specific hosts. See #26592 for more info on this change.

In conclusion

The bootstrap process provides the foundation for WordPress. It’s not pure, but dang zimit, it works. These changes are all expected to be backward compatible. Please test and report any regressions on Trac.

Thanks to the following people who contributed to the Bootstrap component this release. @jorbin @danielbachhuber @DrewAPicture @ocean90 @barry @SergeyBiryukov @johnjamesjacoby

#4-6, #bootstrap-load, #dev-notes