Archive, package and update server

During development the files lived right on the site. For anyone to be able to install the extension, it is packed into a ZIP archive with the manifest in the root. Several extensions are combined into a package, and sites learn about new versions through an update server.

The module archive

In a separate working folder assemble a copy of the module files. The files from media/mod_hello of the site go into a media subfolder:

mod_hello/
├── mod_hello.xml
├── language/
├── media/
│   ├── joomla.asset.json
│   ├── css/style.css
│   └── js/hello.js
├── services/provider.php
├── src/
└── tmpl/

This matches the manifest: the files section lists folders next to it, and the media section with the folder="media" attribute lists the contents of the media subfolder.

cd mod_hello
zip -r ../mod_hello-1.0.0.zip .

The command creates an archive with the manifest in its root. A plugin is packed the same way.

The component archive

The parts of a component are laid out in the folders named by the folder attributes of the manifest:

com_hello/
├── hello.xml                        the manifest — in the archive root
├── script.php
├── administrator/                   → administrator/components/com_hello
│   ├── access.xml
│   ├── config.xml
│   ├── forms/
│   ├── services/
│   ├── sql/
│   ├── src/
│   └── tmpl/
├── api/                             → api/components/com_hello
│   └── src/
└── site/                            → components/com_hello
    ├── src/
    └── tmpl/

Checking

Install the archive on a clean Joomla site: System → Install → Extensions → Upload Package File. If the extension works there the same way as on the development site, the manifest lists every file it needs. A forgotten folder shows up exactly here.

A new version

Raise the number in the version tag of the manifest: 1.1.0.
Add a database update file if tables changed.
Build a new archive.

Thanks to method="upgrade" the archive installs over the old version, and settings and data are kept.

A package

A package is an archive that holds extension archives and its own manifest:

pkg_hello/
├── pkg_hello.xml
└── packages/
    ├── com_hello.zip
    ├── mod_hello.zip
    └── plg_content_hello.zip

<?xml version="1.0" encoding="UTF-8"?>
<!-- pkg_hello/pkg_hello.xml -->
<extension type="package" method="upgrade">
    <name>pkg_hello</name>
    <packagename>hello</packagename>
    <version>1.1.0</version>
    <description>Hello blog: component, module and plugin</description>
 
    <files folder="packages">
        <file type="component" id="com_hello">com_hello.zip</file>
        <file type="module" id="mod_hello" client="site">mod_hello.zip</file>
        <file type="plugin" id="hello" group="content">plg_content_hello.zip</file>
    </files>
</extension>

Pack the pkg_hello folder into a ZIP and install it: Joomla installs all three extensions in one step, and uninstalling the package removes them together.

The update server

For sites to learn about new versions, the manifest names the address of a file with the list of updates:

<!-- mod_hello.xml -->
<updateservers>
    <server type="extension" name="Hello Updates">https://example.com/updates/mod_hello.xml</server>
</updateservers>

At that address you publish an XML file:

<?xml version="1.0" encoding="UTF-8"?>
<updates>
    <update>
        <name>Hello</name>
        <element>mod_hello</element>
        <type>module</type>
        <client>site</client>
        <version>1.1.0</version>
        <downloads>
            <downloadurl type="full" format="zip">https://example.com/downloads/mod_hello-1.1.0.zip</downloadurl>
        </downloads>
        <targetplatform name="joomla" version="[45]\.[0-9]+" />
        <php_minimum>8.1</php_minimum>
    </update>
</updates>

Joomla reads this file periodically. If the version in it is newer than the installed one, the extension appears in System → Update → Extensions, and the administrator updates it with one button. targetplatform is a regular expression for the Joomla versions the update fits: here 4 and 5.

Common mistake

Extra things end up in the archive: .git and node_modules folders, drafts, files with keys. Everything inside the folders listed in the files section lands on your users' sites. Build the archive from a clean copy or with a script that takes only the needed files, and look through its contents before publishing.

Thanks for reading!