Investigate new file structure for Multisite functionality

[flixos90]

Currently core multisite functionality resides in the following files:

Loaded early:

• class-wp-site-query.php
• class-wp-network-query.php
• ms-blogs.php

Bootstrap File:

• ms-settings.php

Loaded by bootstrap file:

• class-wp-network.php
• class-wp-site.php
• ms-load.php
• ms-default-constants.php

Loaded after WordPress Core stuff:

• ms-functions.php
• ms-default-filters.php
• ms-deprecated.php

This structure and loading order is problematic for several reasons.

1. The functionality is not clearly separated. File names (particularly ms-blogs.php and ms-functions.php provide no idea (or confusion about) what they contain. For example ms-blogs.php contains read functionality for sites and networks plus a bit of updating site functions (the old *_blog_details() stuff), ms-functions.php contains functions for creating sites and users.
2. Future improvements (such as #37923 and #25344) run into problems since they need to declare new functions in ms-blogs.php which require other functions that are declared in Core files that are loaded after it.
3. While ms-settings.php is the multisite bootstrap file just as wp-settings.php loads the regular Core functionality, ms-settings.php is loaded before most parts of Core, which feels weird to me and may cause problems (see 2. above).

I think we should find a way to improve this through a more clarifying file structure and loading order. Some ideas I have:

• Introduce files ms-site.php and ms-network.php and move all basic API functions for that specific area into them (those files would be similar like post.php and taxonomy.php for example). ms-site.php should for example contain things like get_site(), get_sites(), related cache functions, functions such as those created in #40364, *_site_meta() functions (if #37923 makes it into Core); ms-network.php would contain get_network(), get_networks(), related cache functions, *_network_meta() functions (if #25344 makes it into Core) etc. I think we should only put "new" functions into those files (with "new" I mean more recent things that follow the current naming conventions in Multisite). We might also add an ms-user.php file.
• Load all Multisite functionality after Core functionality. This would solve issues where Core functionality needed is not available in early-loaded files, and also that other Multisite functionality is not available (for example you shouldn't currently call ms-functions.php functions from ms-blogs.php. We have to be careful with BC, edge-cases and all the other things that might come up when changing loading order - so not sure whether this is possible, but it's something to think about.

Let's think about it.

[flixos90]

After playing around with the loading order, I already have to revert my initial idea: Loading the files after all the rest is not a great idea since some areas require the current site and network to be set up prior.

However we could move the three files that are loaded late into the initial block. That would already provide some benefits, for example deprecated functions that were previously available in ms-blogs.php and have been moved to ms-deprecated.php should still be available early, and by that tweak they would be.

I encountered a further problem: Some functions in ms-blogs.php assume that the current site and network area already set up. However, those functions can be called prior to that (for example in a custom sunrise.php), and they should properly handle the case that null is returned by get_site() or get_network(). There is an ms-loaded hook in ms-settings.php that we could use to easily check whether the multisite bootstrap process has already been completed.
An alternative would be to think about a file structure, where we only make a selected list of functions available early (before ms-settings.php) and move the rest to a later loading point, however this might become very complicated for BC because people might have been using some of these "not-recommended" functions.

[flixos90]

40623.diff​ moves some functions from the general ms-blogs.php to more specific ms-site.php and ms-network.php files respectively. All functions follow the new naming conventions except clean_blog_cache(), I moved that function because it actually belongs to the site API (if we ever introduce a replacement, that function can be deprecated and moved out of there).
The two files are loaded from ms-blogs.php to provide full BC even for the edge-case that someone loads that file manually. If we come to the conclusion that this is not necessary, it would probably be better to load the two new files from wp-settings.php directly.

I think this change is a good first step into the right direction, which we could easily merge without BC concerns (correct me if I'm wrong!). This would give a better overview over the existing site and network APIs and also provide dedicated files for enhancements such as #40364.

[flixos90]

I just opened #40646 and #40647 for two smaller tasks that we can start work on now. It also gives a much better overview of our goals than this cluttered ticket - sorry. :)

[flixos90]

Closing this ticket as invalid because it bundles way too many separate tasks, which I split into smaller pieces:

• #40646 for a more small-step, testable multisite bootstrap process
• #40647 for introducing ms-site.php and ms-network.php files for a clear file structure
• #40948 for loading the Meta API early in the core bootstrap process to be available during multisite bootstrap