Integrate automatic updates to free or commercial Joomla extensions and templates

Introduction

In this tutorial we'll show you how to integrate automatic updates with download key authorization to your free or commercial (paid) Joomla extensions. We'll take mod_helloworld Joomla module as example, but steps are the same for all Joomla components, plugins, templates or libraries. We will assume that you've already configured your UpdaterCloud update server, created a new Joomla product release and that the update channel for your Joomla extension is accessible. Alternatively, please check the Quickstart guide first.

The update server

To enable automatic updates in your Joomla module, first you have to define an update server in your mod_helloworld.xml file. The Joomla update system will automatically check this url for updates and notify the user whenever a new version is available.

{warning} Make sure to replace the server name, {{SUBDOMAIN}} and {{UPDATE_CHANNEL_ID}} with your own. The server name here must match the server parameter in your custom updatercloud_downloadkey field.

<updateservers>
    <server type="extension" name="Hello World Joomla Module Updates">https://@{{SUBDOMAIN}}.updatercloud.com/api/v1/update-channels/@{{UPDATE_CHANNEL_ID}}.xml</server>
</updateservers>

Download key custom field (commercial Joomla extensions only)

To identify the user requesting an update for their Joomla extension, we have to create a way for the user to enter his/hers download key in your Joomla extension. Joomla has an additional table column named extra_query in the #__update_sites database table that can be used to store additional parameters that will be added to the download URL defined in your product's update channel XML file. This way, the your UpdaterCloud update server can accept or reject the download, by validating the provided download key (e.g. check if the download key is valid and allows access to the requested product updates, etc). To make it easy to save the download key to the extra_query column in the #__update_sites database table, we can create a download key custom form field that you can use anywhere in your Joomla extension. The custom form field should look like this:

<field
    name="download_key"
    type="updatercloud_downloadkey"
    label="Download Key"
    description="Download key field description"
    default=""
    server="Hello World Joomla Module Updates"
    filter="string"
/>

Now let's create our custom download key form field class which will handle the actual saving of the entered download key to the extra_query column. Create a new file named downloadkey.php and place it somehwere in your extension package, usually /fields dir, so the path will look like /mod_helloworld/fields/downloadkey.php. Then copy the following code to your downloadkey.php file.

{warning} This code will not validate or activate the provided download key. To check or activate the download key, you need to make a GET request to the download key check or activate API endpoints before saving the download key to database.

defined('_JEXEC') or die();

jimport('joomla.form.formfield');
jimport('joomla.form.helper');
JFormHelper::loadFieldClass('text');

class JFormFieldUpdaterCloud_DownloadKey extends JFormFieldText
{
    // The form field type must be declared in the $type variable
    protected $type = 'updatercloud_downloadkey';

    public function getInput()
    {
        if ($this->value) {
            $extra_query = "'{$this->element['name']}={$this->value}'";

            $db = JFactory::getDbo();

            $query = $db
                ->getQuery(true)
                ->update('#__update_sites')
                ->set('extra_query = ' . $extra_query)
                ->where('name = "' . $this->element['server'] . '"');

            $db->setQuery($query);
            $db->execute();
        }

        // return the form field HTML
        return parent::getInput();
    }
}

Now that we have everything in place, let's add the custom field to our Joomla module configuration screen, so users can enter their download key. You can do that by editing the mod_helloworld.xml file.

<config>
    <fields name="params">
        <fieldset name="basic" addfieldpath="/modules/mod_helloworld/fields">
            // ...
            <field
                name="download_key"
                type="updatercloud_downloadkey"
                label="Download Key"
                description="Download key field description"
                default=""
                server="Hello World Joomla Module Updates"
                filter="string"
            />
            // ...
        </fieldset>
    </fields>
</config>

Sample Joomla extensions

We've put together some Joomla "Hello World" extensions, so you can use them as example for quickly integrating UpdaterCloud automatic updates to your premium/paid extensions. Each of the example extensions uses the custom updatercloud_downloadkey field approach described in this tutorial.