Skip to main content

3. The gotcha that costs everyone a day: manifest filename vs. packagename

This is the single most expensive bug in the whole chain, because everything else about your install works perfectly with it in place — installation succeeds, update detection succeeds, the package's name resolves correctly in Extension Manager. Only one specific thing silently fails: the Download Key field never appears on the Update Sites page, no matter how correct your <dlid> tag is.

Here's the mechanism, straight from Joomla core (libraries/src/Installer/Adapter/PackageAdapter.php):

public function getElement($element = null)
{
    if (!$element) {
        $element = (string) $this->getManifest()->packagename;
        $element = 'pkg_' . InputFilter::getInstance()->clean($element, 'cmd');
    }
    return $element;
}

Joomla always derives your package's #__extensions.element value as pkg_ + your <packagename>. There is no way around this — it's not configurable. So if your manifest declares <packagename>yourpackage</packagename>, your installed extension's element is pkg_yourpackage, full stop.

But when Joomla copies your manifest file into administrator/manifests/packages/, it uses a completely different rule (same file, finaliseInstall()):

$manifest['dest'] = JPATH_MANIFESTS . '/packages/' . basename($this->parent->getPath('manifest'));

That's whatever your manifest file was named inside your zip — nothing to do with <packagename>at all. If you named your manifest file yourpackage.xml (which feels natural, since it matches the packagename), it gets installed as administrator/manifests/packages/yourpackage.xml.

Now here's where it breaks. The Download Key lookup (administrator/components/com_installer/src/Helper/InstallerHelper.php) constructs the path it looks for using the element, not the packagename:

case 'package':
    $path = JPATH_ADMINISTRATOR . '/manifests/packages/' . $element . '.xml';
    break;

It looks for pkg_yourpackage.xml. Your file is named yourpackage.xml. The lookup returns null, getDownloadKey() short-circuits to 'supported' => false before it ever reads your <dlid>tag, and the Update Sites page simply shows nothing — no error, no warning, nothing to grep for in a log.

THE FIXName the manifest file itself pkg_yourpackage.xml inside your zip — matching the element Joomla will derive, not the packagename. Leave <packagename>yourpackage</packagename> unchanged inside the file's content; that value is still needed elsewhere, to name the manifests/packages/yourpackage/ subfolder where your bundled sub-extension zips get staged during install.

This is genuinely confusing because two different, unrelated things both get called "package name" in casual conversation, and Joomla itself uses one convention for the filename-on-disk and a different, hardcoded convention for the database element. We only found the exact mechanism by reading three separate core files back to back: PackageAdapter.phpInstallerHelper.php, and the model behind the Update Sites list.