How to Build a Multisite Compatible WordPress Plugin

WordPress Multisite is a fairly less explored topic. If you’re an avid WordPress follower, you will be aware that only a chosen few blogs cover this subject in detail. Even when it comes to articles which talk about plugin development, its rare to find one which mentions multisite compatibility. I believe it’s because people presume, that working with WP multisite, is complicated. But is that really true?

Well, the short answer is ‘No’. To explain, ‘If you understand how WordPress Multisite works, making a plugin multisite compatible, should NOT involve a substantial amount of effort.’

But this does not mean that a plugin you develop, will automatically function well on a multisite deployment. You might have to make a few minor changes, especially if your plugin deals with writing data to the database. This is due to the difference in the way, information is structured in a multisite.

[space]

How does WordPress Multisite Work

As compared to a single site deployment, a multisite network is a collection of sites for a single WordPress installation. In a multisite, several sites use the same database, and share the same plugins and themes. Although, they do have distinct paths to store uploads, and have separate tables to store individual site related data.

Tables in WordPress Multisite

For single site WordPress, the tables created have the same prefix, “wp_” (by default). Thus the tables created usually are ‘wp_posts’, ‘wp_options’, ‘wp_postmeta’, etc. Thus if you were to use the below query to retrieve the count of all comments on your blog, it would work just fine.

[pre]$comments_count = $wpdb->get_var(“SELECT COUNT(*) FROM wp_comments”);[/pre]

But this same query would not work as expected in a multisite, or might result in an error. This is because of the difference in the table names for WordPress multisite.

In a multisite deployment, WordPress creates a set of tables for each site, with a unique prefix. For example, if you have three sites in your network, the comments table for each site would be, wp_1_comments, wp_2_comments, and wp_3_comments. Remember, this would depend on the prefix WordPress assigns. Hence you cannot assume any table names here.

But (irrespective of whether your plugin was meant for a single site or multisite), a golden rule to always remember when making database queries, is to never use hard coded table names. Instead, you should use the $wpdb object, to refer to a particular table. Thus our above query should be rewritten as,

[pre]$comments_count = $wpdb->get_var(“SELECT COUNT(*) FROM $wpdb->comments”);[/pre]

Here, $wpdb->comments, will return the current site’s comments table, in a multisite.

Creating Tables

If your plugin creates tables, then a table has to be created for every site in your multisite network. We will cover this in the following topic.

[space]

Changing Site Specific Data

Internally, WordPress handles all database related operations using $wpdb object. This means, that depending on the prefix held by $wpdb, the related table will be updated. For example, if $wpdb->prefix is ‘wp_2_’, the tables belonging to the second site in your network will be updated.

To make sure, that the intended values get changed, we need to be aware of which blog is currently being indexed, or we need to update the index to the desired blog. For this, WordPress provides us with the switch_to_blog function.

Switch to Blog Function

The switch_to_blog is a vital function, for developers of multisite compatible plugins. You will need it when doing most operations.
[pre]switch_to_blog($new_blog)[/pre]

where $new_blog is the id, of the blog (site) you want to switch to. After you call this function, and switch to a particular site, any WordPress functions you use, will work on that particular site.

If you look into the working of the switch_to_blog function, it updates the current blog id, and the $wpbd object to refer to the specified blog.

[pre]$wpdb->set_blog_id( $new_blog );[/pre]

This means, to perform functions such as update_post_meta, or to create tables for all blogs, or update plugin options, you wouldn’t need to use different functions. You need to just remember to call the switch_to_bog function, before placing the code.

For example, to create tables for each site from your plugin, your plugin code would have to be as follows:

[pre]function wdm_activate(){
global $wpdb;
// check if it is a multisite network
if (is_multisite()) {
// check if the plugin has been activated on the network or on a single site
if (is_plugin_active_for_network(__FILE__)) {
// get ids of all sites
$blogids = $wpdb->get_col(“SELECT blog_id FROM $wpdb->blogs”);
foreach ($blogids as $blog_id) {
switch_to_blog($blog_id);
// create tables for each site
wdm_perform_activation($blog_id);
restore_current_blog();
}
}
else
{
// activated on a single site, in a multi-site
wdm_perform_activation($wpdb->blogid);
}
}
else
{
// activated on a single site
wdm_perform_activation($wpdb->blogid);
}
}
register_activation_hook( __FILE__, ‘wdm_activate’ );[/pre]

The code to create the table, will have to be placed in the  wdm_perform_activation function. To learn about how to create a table, you can refer: Creating a Custom Table with Plugins.

To query a custom table, you will then have to use $wpdb->prefix.’table_name’. Remember, when a site is deleted, the table created by your plugin for the site, should be deleted as well.

Restore Current Blog Function

If you notice, in the above code, we have used the restore_current_blog function. This function should always be used, when using switch_to_blog. Both these functions push and pop the data into the ‘_wp_switched_stack’ Global stack. The switch blog function affects the wp_upload_dir function. The wp_upload_dir function, builds URLs for your site. Thus if you do not switch back, incorrect URLs might be generated.

[space]

Using Multisite Specific Functions

Every function meant to be used in a multisite, should be called only after verifying a multisite deployment, using is_multisite function.

For example;

[pre]if( is_multisite()) {
echo network_home_url();
}[/pre]

Actions can be added to a particular site, using add_blog_action function. Similarly, the get_blog_option and the update_blog_option functions can be used to change the options for a particular site.

[space]

Conclusion

If you realize, our core plugin functions remained the same. What we needed to do, was simply add a few checks, and ensure that the operations are being performed on the relevant site. Thus building a plugin for a WordPress Multisite installation, is not very different than building one for a single site, you only need to use the tips mentioned above.