Setting up update streams

ARS comes with integrated update stream provisioning. Update streams are, in short, a machine-readable representation of your repository. They can be used by remote clients to figure out if there is an update available and optionally ask the user to download it and install it. ARS can serve two types of update streams:

INI format
This is a custom format, designed with portability in mind. The update information is rendered as a standard INI format text file. The downside of this format is that only the latest version is displayed in the stream.

XML format
Joomla! comes with a built-in extensions updater. For it to work, it requires developers to supply update information in a Joomla-specific XML format. There are actually three type of XML files Joomla! understands. The extensionset document serves as the master update stream. It contains links to one or more repositories, one for each extension type Joomla! understands, i.e. components, plugins, modules, libraries, packages, templates and files. The second form of an extensionset document is the main index of extensions of a specific type (called category) known to this server, e.g. a list of components. Each item on that list points to an updates XML document. This third and final XML format contains the history of an extension. It tells us the version history, details about the extension, links to an information page and, most importantly, tells us where to download the extension from.

This is an overly complex system and maintaining such files manually can be a drag. ARS handles all three types of documents for you, automatically. In order to add updates support to your Joomla! extension, all you have to do is to add the following lines just before the closing </extension> tag in your extension's manifest XML file:

    <updateservers>
        <server type="extension" priority="1"
            name="Whatever you want to call it"><![CDATA[link_to_your_update_stream_xml]]></server>
    </updateservers>

The name attribute can be anything you want. Usually it should be something like "Name Of Extension Updates", e.g. "Akeeba Backup Core Updates". The link in the CDATA section (link_to_your_update_stream_xml) is the XML link provided by ARS.

Important

In Joomla! versions 1.7 to 3.2 inclusive your URL must end with .xml for Joomla! to be able to use it. This means that the long, non-SEF form of the URL, e.g. http://www.example.com/index.php?option=com_ars&view=update&task=stream&format=xml&id=1 mentioned in the XML link on the Update Streams page will not work. Just append &dummy=extension.xml to it and it will work, e.g. http://www.example.com/index.php?option=com_ars&view=update&task=stream&format=xml&id=1&dummy=extension.xml for the example above. ARS will do that automatically for you when generating the Main Joomla! XML Update stream.

Warning

You MUST NOT leave a space or put a newline between the server open/close tag and its contents. Anything between those tags, including newlines and spaces, are considered part of the update URL and will cause problems with Joomla!'s integrated update system.

Note

When using the main XML stream instead of the extension's versions stream you should use type="collection" instead of type="extension"

Tip

It is not necessary to use CDATA if you escape ampersands (&) to & per the XML standard.

To set up update streams, please click on the Update Streams button in ARS Control Panel.

On the very top of the page you will find a link to your main Joomla! update stream (the first type of extensionset XML document). You can use that link in your Joomla! extensions' XML files.

The grid below is a standard Joomla! administrator table. Clicking on a stream name allows you to edit it.

The most important column is the Links column. It provides direct links to the publicly accessible formats of your update stream.

The INI link will take you to the INI format update stream. This is a deprecated format. We currently only use it for our standalone and WordPress software. This is not necessary or particularly usable for distributing updates to Joomla software.

The XML link will take you to the Joomla! XML update document for that stream. This is the XML file we recommend you put in your extension manifest files, inside the CDATA section mentioned above. You can also use this URL as your extension's download URL in the Joomla Extension Directory's "Joomla integration options" area to allow the Install from Web feature to work for publicly available downloads. If your download requires registration or payment you should follow the JED rules and put your registration or purchase URL, choosing the appropriate type as well.

The D/L link is a special link which you can use in the Joomla! Extension Directory or anywhere you want to provide a direct link to the latest version of the item in the update stream. This URL will start the download if the latest version of the item specified in this update stream.

Editing or adding an update stream

Editing or adding an update stream will present you with an editor page. Please note that update streams look for similarly named files (using a pattern) across all releases inside a specific category. You are called to provide this relationship in this page.

You will see the following fields in the update stream editor page.

Stream Name
A name for the update stream. It can be anything you want and is only used in the Joomla! XML format streams.

Warning

This is what Joomla! will also display in the Extension Name when it lists new available updates. Keep it smart.

Alias
Used to construct the SEF URL to the XML update stream in the front-end. Keep it short.

Updates category
The ARS Category whose items participate in this update stream.

Note

You can have more than one update streams per category. However, a single update stream can only look inside a single category.

Extension type
This is used by the Joomla! XML format update stream. This must match the Joomla extension type you are distributing.

If you are providing updates for non-Joomla software select Files. Since this is the simplest extension type in Joomla, it doesn't carry any special handling and also works with non-Joomla software. Moreover, the fact it's called "Files" makes it more human-friendly than the equally usable Libraries type.

Element
This is required for Joomla! update streams. It needs to match the extension name Joomla uses for this extension type. The naming conventions are:

• Components. com_example
• Libraries. lib_example
• Modules. mod_example and applies to both Administrator and Site modules.
• Packages. pkg_example
• Plugins. plg_folder_example where folder is the plugin folder. Example: a system plugin called example has an element name plg_system_example.
• Files. file_example
• Templates. tpl_example and applies to both Administrator and Site templates.

Package naming pattern
An update stream looks for files following a specific naming convention. You have to supply a "shell pattern" in here. This is fancy wording for saying that you provide a filename and use a single question mark (?) to match any single character or a single start (*) to match any number of characters. It's what you already use on your operating system. Only items whose File or URL field matches this pattern will be included in the update stream.

For instance, all Akeeba Release System installation packages are named pkg_ars-VERSIONNUMBER.zip, where only VERSIONNUMBER changes, e.g. pkg_ars-7.0.0.zip. Therefore the naming pattern for Akeeba Release System's files is pkg_ars-*.zip.

Site area (client_id) Only displayed when the Extension type is set to Modules or Templates.

You need to tell us if it's a frontend (Site) or backend (Administrator) module/template.

Folder (for plugins) Only displayed when the Extension type is set to Plugins.

Set this to the plugin type. For example, if you have a system plugin, type system in here. If you have a content plugin, type content in here. And so on and so forth. In other words, this is the name of Joomla's plugins folder's subdirectory where the plugin is installed to.

Enabled
Should this Update Stream be available in the frontend of your site?

The INI update format

The INI update format was designed with portability in mind. It is a deliberately simple format so that it can be parsed by PHP or any other programming language, such as but not only: Ruby, Python, Flutter, JavaScript, TypeScript, Delphi, Pascal, C/C++, C# etc. A typical stream looks like this:

; Live Update provision file
software="Foo Bar"
version="1.2.3"
link="http://www.example.com/downloads/foobar/1.2.3/pkg_example-1.2.3.zip"
date="2010-10-10"
releasenotes="Some release notes here"
infourl="http://www.example.com/downloads/foobar/1.2.3.html"
platforms="joomla/3.9,joomla/3.10,joomla/4.0,php/7.4,php/8.0"

This an INI file. Lines starting with ; are comments and must be ignored. Empty lines must be ignored. The rest of the lines are the keyname followed by any number of whitespaces, the equals sign followed by any number of whitespaces and then the value surrounded by double quotes ("). If there are double quotes inside the value they are escaped as \". Likewise any backslashes in the value are escaped as \\. After the final double quote surrounding the vlaue there might be any number of whitespace characters, possibly followed by a carriage return and finally a newline character marking the end of line.

The following keys are included in the INI update streams:

• software is the name of the Update Stream.
• version is the latest version published.
• link is the download link to the item linked to that update stream for the version reported above.
• date is the release date of the latest version in YYYY-MM-DD format. This date is always in the GMT timezone.
• releasenotes are the release notes of the latest Release whose version is provided above. The release notes are in HTML format.
• infourl is the URL to the page of the Release on your site.
• platforms is a comma separated list of the XML Title fields of the Environments of the download Item matched by this update stream.

Do note that only the latest release is listed in an INI update stream.

The XML update format

Akeeba Release System creates XML update files compatible with Joomla's Update Server definition.

For Extension XML update streams the targetplatform and php_minimum fields are populated by parsing the Environments of each download Item listed in the XML file. More specifically, the targetplatform is populated by parsing the Environments whose XML Title begins with the string joomla/ and is followed by a Joomla version number, whereas the php_minimum is populated by parsing the Environments whose XML Title begins with the string php/ and is followed by a PHP version number.