Software Licensing - Updater Implementation for WordPress Plugins

Software Licensing is an extension for Easy Digital Downloads that makes it easy to license your digital products. Learn more at the main Easy Digital Downloads website.

Adding support for automatic upgrades to your WordPress plugins with the Software Licensing add-on is really simple. After you have setup your product in Easy Digital Downloads and configured the licensing options, there is just a small code snippet and one file that you need to include in your WordPress plugin.

Included with your download of the Software Licensing add-on is a sample plugin. It is highly recommended that you open this up and look at its entirety.

There are two components to the updater:

  1. The EDD_SL_Plugin_Updater.php file. This contains the class that makes the magic happen.
  2. The code snippet that you place somewhere in your plugin that loads the updater provided by the EDD_SL_PLugin_Updater.php class file.

Step 1 - Define the updater constants

In your main plugin file, preferably near the top, or where you have other constants defined, add the following code:

// this is the URL our updater / license checker pings. This should be the URL of the site with EDD installed
define( 'EDD_SL_STORE_URL', 'http://yoursite.com' ); // IMPORTANT: change the name of this constant to something unique to prevent conflicts with other plugins using this system
// the name of your product. This is the title of your product in EDD and should match the download title in EDD exactly
define( 'EDD_SL_ITEM_NAME', 'Sample Plugin' ); // IMPORTANT: change the name of this constant to something unique to prevent conflicts with other plugins using this system

EDD_SL_STORE_URL must be set to the URL of your site that has Easy Digital Downloads installed on.

EDD_SL_ITEM_NAME must be set to the name of your product in EDD. For example, if your Download in EDD is named "Love It Pro", set this to "Love It Pro" as well.

Step 2 - Include the updater class

The update system itself is contained within the file called "EDD_SL_Plugin_Updater.php". This file can be found in the Software Licensing plugin folder inside samples/edd-sample-plugin/ .  You need to copy this file into your own plugin's folder.  It can be in the same main folder as your plugin file, or in a sub directory like /includes/ .  Either way you simply need to refer to it properly in the code below, like so:

if( !class_exists( 'EDD_SL_Plugin_Updater' ) ) {
	// load our custom updater if it doesn't already exist 
	include( dirname( __FILE__ ) . '/EDD_SL_Plugin_Updater.php' );
}

You may need to adjust the file path, depending on where you have decided to place the file within your plugin's folder structure.

Step 3 - Initiate the updater class

We now instantiate our updater class like this:

// retrieve our license key from the DB
$license_key = trim( get_option( 'edd_sample_license_key' ) ); 
// setup the updater
$edd_updater = new EDD_SL_Plugin_Updater( EDD_SL_STORE_URL, __FILE__, array(
	'version' 	=> '1.0',		// current version number
	'license' 	=> $license_key,	// license key (used get_option above to retrieve from DB)
	'item_name'     => EDD_SL_ITEM_NAME,	// name of this plugin
	'author' 	=> 'Pippin Williamson',	// author of this plugin
	'url'           => home_url(),
        'beta'          => false // set to true if you wish customers to receive update notifications of beta releases
) );

The license key in this example is stored in an option called "edd_sample_license_key". You will need to adjust this to retrieve the license key from the option you have setup for your plugin. If you need help setting up an option to store the license key in, take a look at the sample plugin as it includes a fully functional settings page.

There are several parameters we pass to the EDD_SL_Plugin_Updater class:

  • $api_url - this is the URL of your site that is running Easy Digital Downloads (and the Software Licensing add-on). Pass the EDD_SL_STORE_URL constant we defined earlier here.
  • $plugin_file - this is the main plugin file. I suggest you use the __FILE__ magic constant provided by PHP. Note, to do this, you must have this snippet placed in your main plugin file.
  • $api_args - this is an array of options to pass to the updater:
    • version - this is the current version of the plugin that is installed. It is not the latest available version.
    • license - this is the license key retrieved from the database.
    • item_name - this is the name of our product in Easy Digital Downloads. Just pass the EDD_SL_ITEM_NAME constant we defined earlier here.
    • author - this is the name of the person or company that wrote the plugin (you!)
    • url - this is the URL of the site the plugin is activated on. Usually this will never be changed.
    • beta - this allows you to indicate if customers should receive update notifications for beta version. See Releasing beta versions for more information.

The complete code for the updater will look something like this:

Step 4 - Create settings page

In order for a plugin to receive one-click updates, the license key needs to be activated. To activate a license key the customer will need to enter the key an a field within your plugin settings and then that key needs to be sent to the Software Licensing API on your store's site.

The sample plugin included with Software Licensing uses a simple settings page with a single input field. This can work quite well but is meant primarily for demonstrative purposes. It is recommended that you integrate the license key field on your existing settings pages.

Here's sample code for creating a simple settings page:

This code sets up submenu to the Plugins menu called "Plugin License".

There are two lines at the top of the code:
$license = get_option( 'edd_sample_license_key' );
$status = get_option( 'edd_sample_license_status' );

The first is the license itself and the second is the status of the license. Once we have activated our license, we will change the status (on our local site) to "active". This is so that we can show an "Activate License" button if the license has not yet been activated, and hide the button if it has. See the screenshot below:

The idea here is that we first enter a license key and click "Save Changes", which causes the license key to be stored in our plugin/theme options. Once the option is stored, we click the "Activate License" button to trigger the API call.

The activate button is just a simple input field with a type of "submit" and a name attribute that is different than our save button. The names  must be different so that we can know when the activate license button was clicked.

Step 5 - Activate the license key

To activate a license key, we "listen" for the Activate License button to be clicked then grab the value entered in the license key field and send an activation request to the Software Licensing API. That process looks like this:

Note: this is purely a sample and may look slightly different in your own implementation.

If everything runs okay after clicking the "Activate License" button, the activate button will be replaced with the word "active", and the license status will reflect the newly activated state in your EDD store's dashboard. If there is an error when activating the license key, the page will be reloaded and an error and message parameter will be added to the URL. We can then use the admin_notices hook (or any other applicable method) to display the error to the customer:

For example, if a customer enters an invalid license key, an error message will be displayed:

That's it!

Important notes

  • The code shown on this page is purely for demonstrative purposes and is not meant to be used as is. Do not copy and paste it into your plugin and expect it to work as is.
  • All function names added to your plugin need to get a unique prefix. We have used edd_sample_ throughout this example. Do not keep edd_sample_ in your own plugin, replace it with your own unique prefix.
  • The names of the constants must be changed. Do not keep them as EDD_SL_ITEM_NAME and EDD_SL_STORE_URL. Use your own unique constants.