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.
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 customupdatercloud_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>
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>
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.