Don't want to host your plugin in the WordPress.org Plugin Directory? Of course, you can decide not to—it's a free community after all. But you must host it somewhere so the plugin can be found, and you also should provide your users with updates to your plugin. 

Most people who decide not to host their plugins on WordPress.org tend to use GitHub, but WordPress doesn't know how to update GitHub-hosted plugins—it needs help. And today, we will help you help WordPress update your plugins with, you guessed it, a helper class.

In this part of the "Toolbox of the Smart WordPress Developer" series, we're going to go through WordPress GitHub Plugin Updater, a tool to handle the update process for WordPress plugins hosted on GitHub.

Why Use GitHub Instead of WordPress.org?

Like every other modular content management system, WordPress has its own plugin repository. And I wouldn't be wrong if I said the WordPress.org Plugin Directory has become the community standard for hosting free and open source WordPress plugins.

But as I said in the beginning, this is a free community. WordPress doesn't require us to host every plugin and theme we make in the WordPress.org Plugin Directory. People can choose to move away from it, and that's perfectly natural.

The first place people host their WordPress plugins after the WordPress.org Plugin Directory is GitHub. Utilizing the awesome revision control system called Git, GitHub is one of the best places to share your open source software with the rest of the world. And for the last couple of years, more and more WordPress developers have been publishing their new plugins over GitHub.

Advantages and Disadvantages of Switching From the WordPress.org Plugin Directory to GitHub

I think that there is a balance between the advantages and disadvantages of hosting WordPress plugins on GitHub instead of the WordPress.org Plugin Directory. I'm going to lay out the ones that come to my mind, but I'd love your input on this as well, so don't hesitate to shoot a comment in the Comments section after reading this.

When you host your plugins on WordPress.org:

• You have to use SVN.
• Your plugin has to be approved by a WordPress.org reviewer before you can upload it. (This is both an advantage and a disadvantage to me, as having a second set of eyes on the code is good for spotting security flaws.)
• You can only use GPL (version 2 or later) as licensing.
• Your plugin updates will be notified to your users rapidly.
• Emergency plugin updates (for security reasons) will be pushed automatically to the users.
• People can find your plugin straight from their admin panels, which is a huge plus.
• You can use the support forums of WordPress.org.

And when you decide to switch to GitHub:

• You will be able to use Git.
• You will have infinitely more freedom.
• You can use other types of licenses (like MIT or CC, even though CC isn't recommended for software).
• You can create a wiki, accept commits, and talk about issues with your users.
• You will not have any ratings for your plugins, which is bad for feedback.
• You will need to finish this tutorial in order to provide plugin updates more easily.

There's also a nice debate over on WordPress Tavern which—I think—you should also read.

Integrating the WordPress GitHub Plugin Updater Into Your Plugin

Ready to provide update notifications for your users?

First and obviously, you need to download the WordPress GitHub Plugin Updater from its GitHub repository. You'll only need the updater.php file, so don't worry about the others.

After that, you need to put the updater.php file somewhere in your plugin folder and include it in your plugin. For example, if you put the updater.php file in a folder named github-plugin-updater and you want to include it in your main plugin file, you need to add the following line to that file:

<?php

include_once( 'github-plugin-updater/updater.php' );

?>

You also need to initialize the WP_GitHub_Updater class with the correct arguments to connect your plugin to your GitHub repo:

<?php

if ( is_admin() ) {

	$config = array(
		'slug'					=> plugin_basename( __FILE__ ),
		'proper_folder_name'	=> 'plugin-name',
		'api_url'				=> 'https://api.github.com/repos/username/repository-name',
		'raw_url'				=> 'https://raw.github.com/username/repository-name/master',
		'github_url'			=> 'https://github.com/username/repository-name',
		'zip_url'				=> 'https://github.com/username/repository-name/zipball/master',
		'sslverify'				=> true,
		'requires'				=> '3.0',
		'tested'				=> '3.3',
		'readme'				=> 'README.md',
		'access_token'			=> ''
	);

	new WP_GitHub_Updater( $config );

}

?>

• slug: Your plugin's slug.
• proper_folder_name: The name of your plugin's folder.
• api_url: Your GitHub repo's API URL.
• raw_url: Your GitHub repo's raw URL.
• github_url: Your GitHub repo's URL.
• zip_url: Your GitHub repo's ZIP URL.
• sslverify: Whether to verify SSL or not.
• requires: The minimum WordPress version that your plugin requires.
• tested: The maximum WordPress version with which you tested your plugin.
• readme (deprecated): The README file to check the plugin version from.
• access_token: Your GitHub access token, if you're using a private repo.

In order to notify your users, all you have to do is change the version of the plugin in your main file's headers. (It seems that this tool used to check the README file for a line containing ~Current Version:X.X~ but as of version 1.6, it looks for the main plugin file first.)

And that's it! Following these steps will enable update notifications for your plugin.

Wrapping Up for Today

If you want to host your WordPress plugin on GitHub, and want to provide update notifications for your users, the WordPress GitHub Plugin Updater is one of the essential tools you should be making use of.

What do you think about this tool, or hosting WordPress plugins on GitHub in general? Share your thoughts with us by commenting in the Comments section below. And if you liked the article, don't forget to share it with your friends!