is_network_admin() is not checking if the context install is a multisite - documentation improvement

[svovaf]

The multisite-related function is_network_admin() will return true when visiting /wp-admin/network/* URLs regardless if the site is regular or a multisite network. That behavior is confusing and unexpected, and in some edge-cases, can lead to bugs (yes, we were those lucky ones).

My suggestion is to simply add a comment to the documentation of the function making it clear that it:

Does not check if the site is a multisite network; Use is_multisite() for checking if the site is a multisite network or not.

[jeremyfelt]

Hi @svovaf, thanks for opening a ticket.

Another line further describing the context in which the function is used would be useful.

Do you have details on the possible bugs that arose from this? The /wp-admin/network/* pages show notices if is_multisite() is false, and is_network_admin() will always return false if not on one of those pages.

[svovaf]

Starting from WP 5.2, where the error catch mechanism was introduced, we have started to receive complaints about get_blog_list() as a non-defined function:

Fatal error: Uncaught Error: Call to undefined function get_blog_list()

After troubleshooting a few live sites that encountered the issue we found that something in core's background logic (could be the updates mechanism or some WP Cron) is triggering a call to the network-level path, even though the sites were not set to work as a multi-site network. Since some of our code's logic assumed that is_network_admin() can only return true when running within a network environment, the following logic eventually have fallen back to use get_blog_list() which like the rest of the network functions are not defined as ms-blogs.php and ms-deprecated.php aren't included into the execution sequence on a non-network environment:

<?php
            if ( function_exists( 'get_sites' ) ) {
                // For WP 4.6 and above.
                return get_sites( $args );
            } else if ( function_exists( 'wp_get_sites' ) ) {
                // For WP 3.7 to WP 4.5.
                return wp_get_sites( $args );
            } else {
                // For WP 3.6 and below.
                return get_blog_list( 0, 'all' );
            }

Hope it helps.

[tazotodua]

modified description (with a required asterisk on new line)

[SergeyBiryukov]

In 45672:

Docs: Clarify that is_network_admin() does not check if the site is a Multisite network; is_multisite() should be used for that.

Props svovaf, dilipbheda, tazotodua.
Fixes #47415.