Monday 3rd April 2023

Developing for WordPress multisite – tips for developers.

WordPress Multisite is an excellent tool for building networks of related sites. I’ve been working with WordPress multisite for a long time, in fact since it was a fork of WordPress called WordPress MU which merged back into WordPress in 3.0 and was released in 2010. Over that time I’ve worked on WordPress multisite projects ranging from simple networks of micro-sites through to fully fledged SaaS products where each user gets their own “site” as an instance of the application. Along the way, I’ve noticed some quirks and differences which catch developers out, as well as some opportunities that developers may not be aware of.

Common issues developers encounter working with multisite.

Problems with taxonomy queries across sites

This is probably the most common cause of confusion for developers new to multisite. Taxonomies must be registered in the site you are switching from as well as the site you are switching to when you are making a query across blogs. The taxonomy only needs to be populated in the site(s) you are switching to. This is because switch_to_blog() doesn’t load the code for the site you are switching to – it just changes how the database is queried. I tend to register taxonomies that need to be queried across sites in a must-use plugin and hide them from the UI for individual sites if need be. The same is also true of trying to call functions in plugins or themes on the switched-to site.

Problems with users activating / wp-activate.php

By default, when a user signs up to a WordPress multisite site, they receive an email which directs them to wp-activate.php. If you are getting errors which you are struggling to debug on this page it’s usually because you are relying on some functionality in a plugin somewhere. wp-activate.php sets the WP_INSTALLING constant, which – amongst other things – prevents plugins from loading. The reasons for this are documented in Trac ticket #23197 – which was first raised over 10 years ago, so don’t expect this to get fixed anytime soon. The solution is to ensure that you aren’t reliant on any plugins in your theme, wrap the code in function_exists() or class_exists(), or you could try including the plugin directly.

Changes in UI behaviour when a multisite network grow to a large number of sites of users.

If your WordPress multisite network has a large number of users or sites, you may notice some seemingly strange changes to the UI in the admin areas of the site. For example, autocomplete stops working in various parts of the user interface – such as when typing an email address to add a user; and the user counts for sites may no longer seem to be up to date.

By default, this is triggered when a network has more than 10,000 users or 10,000 sites. It is filterable, via the wp_is_large_network filter. For projects which are likely to grow to this size, filter this with __return_true to keep behaviour consistent and make sure we catch any issues during development.

It’s worth noting, this behaviour now occurs in non-multisite installs of WordPress as of 6.0 as per this dev note.

Differences to capabilities for administrator in WordPress multisite

Aside from the creation of the Super Admin role, there are changes to the capabilities for Administrator which can sometimes catch people out. On multisite, administrator users lose the following capabilities by default: update_core, update_plugins, update_themes, install_plugins, install_themes, delete_themes, delete_plugins, edit_plugins, edit_themes, edit_files, edit_users, add_users, create_users, delete_users, unfiltered_html. It is usually the lack of ability to edit users that causes issues. These are documented on the WordPress site, but often missed. It’s also worth noting that the “Plugins” menu item can be hidden on multisite (see Network Settings in the network admin).

WordPress Super Admin permissions checks (nearly) always pass.

It’s also worth remembering that on multisite, a super admin has all capabilities which haven’t been specifically denied – this means functions like current_user_can() and user_can() will always return true for a super admin user. This can often catch developers out, especially when testing capability checks.

This comes from this code in /wp-includes/class-wp-user.php

// Multisite super admin has all caps by definition, Unless specifically denied.
if ( is_multisite() && is_super_admin( $this->ID ) ) {
	if ( in_array( 'do_not_allow', $caps, true ) ) {
		return false;
	}
	return true;
}

“Cookies are blocked or not supported by your browser. You must enable cookies to use WordPress.”

This usually happens when using domain mapping; you’ll need to add the following lines to your wp-config.php files:

define('ADMIN_COOKIE_PATH', '/'); 
define('COOKIEPATH', ''); 
define('SITECOOKIEPATH', ''); 
define('COOKIE_DOMAIN', false);

Other tips for developing with WordPress multisite

Don’t use the primary site as a regular site.

We tend to avoid using the first site in the multisite network for content. It also makes your life a little easier if you need to work directly with the database as the primary site and network tables are saved with the same prefix. If you need to convert an existing site to Multisite I highly recommend setting up a blank site, converting that to Multisite and importing the existing site into a non-root site using a tool such as the excellent MU Migration WPI CLI package by 10up.

Create a site for shared resources/content.

It’s also often useful to create a site for shared resource/content which will appear across sites. This could be media or boilerplate content – terms and conditions/policies which you can either fetch from there or distribute to the other sites.

Take control of user signups

If your multisite network will have a large number of users, it is inevitable you will run into problems with users activating their accounts. The WP User Signups plugin is excellent for managing user activations, and will save you a huge amount of time on sites with a large number of users (even more so if you give your client access to it too by giving their role some or all of the the create_signups, edit_signups, manage_signups, activate_signup, delete_signup, edit_signup, resend_signup capabilities).

Disable password change notification emails

Admin notifications that a user has changed their password can quickly become a pain on sites with lots of users; fortunately this can be disabled by overwriting the pluggable function that sends it. I do recommend keeping a log of password changes somewhere – we use Stream for this.

if ( ! function_exists( 'wp_password_change_notification' ) ) {
	/**
	 * Prevents the site admin email getting notifications when a
	 * user resets their password by overwriting the function in
	 * pluggable.php; this does not affect emails sent to the user.
	 */
	function wp_password_change_notification( $user ) {
		return;
	}
}

On the subject of password changes, it’s worth noting that password resets will take place on the primary site – so although the frontend may not beed to be accessible, users will need to be able to reach and use the login page to reset their passwords. If user accounts require activation, this also happens here.

Looking for help with a WordPress multisite build, we can help you! If you are a developer and need some support or a sounding board – take a look at how we can support in-house WordPress developers.

We design and develop all kinds of great stuff using WordPress, WooCommerce & LearnDash.

If you are looking for a new WordPress website, WooCommerce store or LearnDash LMS or want to improve an existing one, give us a call on 0114 303 8181 or click the button below to get the ball rolling.