Software Licensing – Developer Customizations

Just like Easy Digital Downloads core, the Software Licensing extension includes a variety of action and filter hooks that you can use to tweak the behavior of the extension to better suit your needs. This documentation is written for advanced users who are already familiar with the WordPress Plugins API.

License Creation

License Length

By default, every license key is given a one year expiration date. This expiration length can easily be changed by using the edd_sl_license_exp_length filter. There are four parameters passed to the filter:

• $length (string) – The expiration length for this license. “+1 year” is default
• $payment_id (int) – The payment ID of the purchase this license was generated with
• $download_id (int) – The download/product ID this license is connected to
• $license_id (int) The ID of the newly created license

Here’s a quick example of how you might change the expiration length:

function pw_edd_sl_license_length( $length, $payment_id, $download_id, $license_id ) {
	return '+2 years'; // set length to two years from creation date
}
add_filter( 'edd_sl_license_exp_length', 'pw_edd_sl_license_length', 10, 4 );

Execute Functions After License Creation

The edd_sl_store_license action is fired just after the license key is created and all meta data is attached to it. The action takes three parameters:

• $license_id (int) – The ID of the newly created license
• $download_id (int) – The ID of the download/product this license is connected to
• $payment_id (int) – The ID of the purchase this license was created with

A sample function you might attach to this action could look something like this:

function pw_edd_sl_custom_admin_alert( $license_id, $download_id, $payment_id ) {
	
	// send admin alert

	wp_mail( get_bloginfo( 'admin_email' ), 'License Created', 'A new license key with the ID of ' . $license_id . ' has been created.' );

}
add_action( 'edd_sl_store_license', 'pw_edd_sl_custom_function', 10, 3 );

Execute Functions During License Activation

The edd_sl_activate_license action runs just after a license is activated via the API.

do_action( 'edd_sl_activate_license', $license_id, $download_id );

Execute Functions During License Checking

The edd_sl_check_license action runs just after a license is checked via the API.

do_action( 'edd_sl_activate_license', $license_id, $download_id );

Other Filters

edd_sl_license_response – applied to the response sent when remotely checking a download/product version.

edd_sl_get_license_logs – applied when the log entries for a license are retrieved.

edd_sl_encoded_package_url – applied when the encoded package URL for download packages is retrieved.

edd_sl_download_package_url – applied when the download package file for auto updates is retrieved.

edd_license_labels – applied to the post type labels when registering the edd_license post type.

Other Actions

edd_sl_before_package_download – executes just before the download file for auto upgrades is served to the browser.

Software Licensing version 3.5 and later includes an EDD_SL_License class for interacting with license key records. The EDD_SL_License class allows you to interact with license key data, update existing license keys, and create new license key records.

Instantiating Objects

To improve performance when accessing a license object you should use the wrapper method, which uses the WordPress core object caching layer. You can use either the License ID or License Key to instantiate an object. If no license exists for the provided information the wrapper method will return `false`:

// Instantiate a license via ID
$license = edd_software_licensing()->get_license( 2326422 );

// Instantiate a license via the license key
$license_by_key = edd_software_licensing->get_license( '9e21e9a885212f96cccb4d6186541332', true );

// If you pass in an invalid license ID or key you will get 'false' as a response.
$invalid_license = edd_software_licensing()->get_license( -1 );

EDD_SL_License can be instantiated with a license ID or no value when creating a new license. Here are some examples:

$license = new EDD_SL_License( 2326422 );

If you wish to create a new license:

$license = new EDD_SL_License();
$license->create( $download_id = 0, $payment_id = 0, $price_id = false, $cart_index = 0, $options = array() );

While you can directly instantiate a license with EDD_SL_License, it’s preferred to use the wrapper function for performance reasons.

The arguments necessary to create a new license will be covered below.

Available Properties

The EDD_SL_License class includes numerous accessible properties that hold information related to the license key record.

• ID – The ID number of the license record. This corresponds to the WP_Post object’s ID.
• parent – The post ID of the parent license, if any.
• name – The name of the license. This is a concatenation of the customer’s email address and the name of the product the license key is associated with.
• key – The license key itself. This is typically a 32 character string but can be anything.
• user_id – The ID of the WP_User the license key belongs to, if any.
• customer_id – The ID of the EDD_Customer the license belongs to.
• payment_id – The ID of the EDD_Payment that the license was created for.
• payment_ids – An array of payment IDs related to the license. Includes renewals and upgrades.
• cart_index – The numerical index in the cart items array of the product the license key is associated with.
• download – An EDD_SL_Download instance of the download product the license key is associated with.
• download_id – The post ID of the download product the license key is associated with.
• price_id – The ID of the price option of the download product assigned to the license key.
• activation_limit – The number of unique URLs / machines the license key can be activated on.
• sites – An array of the site URLs (or machine IDs) the license key is activated on.
• activation_count – The number of unique URLs / machines the license key is currently activated on.
• expiration – The expiration date of the license key.
• is_lifetime – Boolean flag indicating if the license is a lifetime (never expires) license.
• status – The current status of the license (active, inactive, expired).
• post_status – The post_status of the WP_Post object for the license.
• child_licenses – An array of child license keys, if any.

Each property can be accessed directly, like this:

// Access the price ID of the license
$price_id = $license->price_id;

Each property can also be updated by setting the value of the property, like so:

// Set the license activation limit
$license->activation_limit = 100;

Changes to object properties will be saved immediately without any need to call a save or update method.

Available Methods

The EDD_SL_License class includes public methods for accessing the object properties and several other help methods that may be used to access and interact with the license data.

$license->create( $download_id = 0, $payment_id = 0, $price_id = false, $cart_index = 0, $options = array() )

This method allows you to create a new license record for an existing download product and payment record.

• $download_id – This must be the ID of an existing download product
• $payment_id – This must be the ID of an existing payment record that included a purchase of $download_id
• $price_id – This is an optional price ID for $download_id if variable prices are enabled
• $cart_index – This is optional cart item index that identifies exactly which cart item this license corresponds to
• $options – An array of options for the license. Can include the following keys
  • parent_license_id
  • activation_limit
  • license_length
  • expiration_date
  • is_lifetime

The create() method can be used to create a new license key but typically will not be used manually except in very custom implementations.

$license->update( $data = array() )

This method allows you to update meta data for a license in bulk. The $data array should be a key/value pair of meta_key/meta_value.

$license->renew()

This method will trigger a renewal of a license key, extending the expiration date by one period and resetting the license status to either inactive or active.

$license->enable()

This method will re-enable a disabled license key.

$license->disable()

This method will disable a license key.

$license->get_meta( $meta_key = ”, $single = true )

This method will retrieve metadata for a license.

$license->update_meta( $meta_key = ”, $value = ”, $old_value = ” )

This method will update metadata for a license.

$license->get_renewal_url()

This method will retrieve the renewal URL for a license.

$license->is_site_active( $url )

This method will determine if the supplied URL is registered on the license.

$license->is_at_limit()

This method will check if the license has reached its activation limit.

$license->license_length()

This method will return the length of a single period for the license, such as lifetime or +1 year.

$license->add_site( $url )

This method can be used to register a new site URL on a license.

$license->remove_site( $url )

This method can be used to remove a site URL from a license.

$license->reset_activation_limit()

This method can be used to reset the activation limit on a license according to the settings on the download product.