How many Updater & installer issues are in this guide?

This guide covers 16 catalog entries with before/after replacements.

Joomla Updater & installer changes: Joomla 3 → 4, 5 and 6

16 issues in this guide

Installers and update servers punish old manifests. This guide groups 16 entries: plugins/content/foo.php (1.5 layout), JAdapter, JAdapterInstance, JExtensionHelper, JInstallerComponent, JInstaller, JInstallerHelper, JInstallerScript, JLibraryHelper::_load(), JUpdate, and 6 more. The replacement pattern is namespaced Installer and Updater classes, a namespace element in the manifest, a services/provider.php where the extension type needs it, plugin folders with XML beside PHP (not a lone plugins/content/foo.php), and client values as site / administrator strings. preflight/postflight must handle uninstall and update, not only install. Update JUpdate XML consumers to Joomla\CMS\Updater\Update. LibraryHelper::loadLibrary() replaces JLibraryHelper::_load(). Hop mix: 8 at Joomla 3 → 4; 8 at Joomla 5 → 6. These breaks split across hops: discover and manifest structure on J3→J4, class aliases on J5→J6. Read each catalog entry before you ship the next update package. Catalog replacements in this guide include plugins/content/foo.php (1.5 layout) → plugins/content/foo/foo.php + foo.xml (1.6+ layout); JAdapter → Joomla\CMS\Adapter\Adapter; JAdapterInstance → Joomla\CMS\Adapter\AdapterInstance; JExtensionHelper → Joomla\CMS\Extension\ExtensionHelper. Open each h2 anchor for the full before/after, fix list, and error strings shipped in the reference data.

DISCOVER-15-001

plugins/content/foo.php (1.5 layout)

Joomla 1.5 plugin folder / discover install

Discover-install of 1.5 plugin paths was removed in Joomla 4.

plugins/content/foo.php (1.5 layout) → plugins/content/foo/foo.php + foo.xml (1.6+ layout)

Dies at Joomla 3 → 4

Dies at Joomla 3 → 4J3: Works nativelyJ4: Removed — fatalJ6: Removed — fatalBC plugin: no — already dead on J4You rewrite thisManifest / installer

What you will see

Unable to discover extension

Symptoms people search

discover install finds nothing · 1.5 plugin

Replace this code

Swap plugins/content/foo.php (1.5 layout) for plugins/content/foo/foo.php + foo.xml (1.6+ layout).

Joomla 3

Remove or stop calling this

plugins/system/mysys.php

Joomla 4 / 6

Use this instead

plugins/system/mysys/mysys.php
plugins/system/mysys/mysys.xml

How to fix it

1Put each plugin in its own folder with XML.
2Do not zip a single php file at the group root.

Also known as

discover install · 1.5 plugin

There is no 1:1 swap for this one. The architecture changed. If you cannot rewrite it, Infyways can.

Scan a ZIP for this Ask Infyways to fix it

JADAPTER-CLASS-001

JAdapter

JAdapter class name

JAdapter is a Joomla 3 global class. Joomla 4 still has an alias. Joomla 5 needs the Behaviour – Backward Compatibility plugin. Native Joomla 6 does not load that alias — you get Class "JAdapter" not found.

JAdapter → Joomla\CMS\Adapter\Adapter

Dies at Joomla 5 → 6

Dies at Joomla 5 → 6J3: Works nativelyJ4: Alias (old name still resolves)J6: Removed — fatalBC plugin: covers the class nameMechanical renameJoomla API

What you will see

Class "JAdapter" not found
Class 'JAdapter' not found
Failed to open stream: JAdapter

Symptoms people search

white screen after disabling compatibility plugin · class not found on Joomla 6 · works on Joomla 5 until I turn off backward compatibility

Replace this code

Swap JAdapter for Joomla\CMS\Adapter\Adapter.

Joomla 3

Remove or stop calling this

JAdapter::getInstance();
// or new JAdapter()

Joomla 4 / 6

Use this instead

use Joomla\CMS\Adapter\Adapter;

// Call the namespaced class. Do not keep the J prefix.

How to fix it

1Add a use statement for Joomla\CMS\Adapter\Adapter.
2Replace every JAdapter with the short class name from that use line.
3Disable Behaviour – Backward Compatibility on a Joomla 5 staging site. If it fatals, this class is still in the code.

Also known as

JAdapter · Joomla\CMS\Adapter\Adapter · class alias · J prefix

Scan a ZIP for this Ask Infyways to fix it

JADAPTERINSTANCE-CLASS-001

JAdapterInstance

JAdapterInstance class name

JAdapterInstance is a Joomla 3 global class. Joomla 4 still has an alias. Joomla 5 needs the Behaviour – Backward Compatibility plugin. Native Joomla 6 does not load that alias — you get Class "JAdapterInstance" not found.

JAdapterInstance → Joomla\CMS\Adapter\AdapterInstance

Dies at Joomla 5 → 6

Dies at Joomla 5 → 6J3: Works nativelyJ4: Alias (old name still resolves)J6: Removed — fatalBC plugin: covers the class nameMechanical renameJoomla API

What you will see

Class "JAdapterInstance" not found
Class 'JAdapterInstance' not found
Failed to open stream: JAdapterInstance

Symptoms people search

white screen after disabling compatibility plugin · class not found on Joomla 6 · works on Joomla 5 until I turn off backward compatibility

Replace this code

Swap JAdapterInstance for Joomla\CMS\Adapter\AdapterInstance.

Joomla 3

Remove or stop calling this

JAdapterInstance::getInstance();
// or new JAdapterInstance()

Joomla 4 / 6

Use this instead

use Joomla\CMS\Adapter\AdapterInstance;

// Call the namespaced class. Do not keep the J prefix.

How to fix it

1Add a use statement for Joomla\CMS\Adapter\AdapterInstance.
2Replace every JAdapterInstance with the short class name from that use line.
3Disable Behaviour – Backward Compatibility on a Joomla 5 staging site. If it fatals, this class is still in the code.

Also known as

JAdapterInstance · Joomla\CMS\Adapter\AdapterInstance · class alias · J prefix

Scan a ZIP for this Ask Infyways to fix it

JEXTENSIONHELPER-CLASS-001

JExtensionHelper

JExtensionHelper class name

JExtensionHelper is a Joomla 3 global class. Joomla 4 still has an alias. Joomla 5 needs the Behaviour – Backward Compatibility plugin. Native Joomla 6 does not load that alias — you get Class "JExtensionHelper" not found.

JExtensionHelper → Joomla\CMS\Extension\ExtensionHelper

Dies at Joomla 5 → 6

Dies at Joomla 5 → 6J3: Works nativelyJ4: Alias (old name still resolves)J6: Removed — fatalBC plugin: covers the class nameMechanical renameJoomla API

What you will see

Class "JExtensionHelper" not found
Class 'JExtensionHelper' not found
Failed to open stream: JExtensionHelper

Symptoms people search

white screen after disabling compatibility plugin · class not found on Joomla 6 · works on Joomla 5 until I turn off backward compatibility

Replace this code

Swap JExtensionHelper for Joomla\CMS\Extension\ExtensionHelper.

Joomla 3

Remove or stop calling this

JExtensionHelper::getInstance();
// or new JExtensionHelper()

Joomla 4 / 6

Use this instead

use Joomla\CMS\Extension\ExtensionHelper;

// Call the namespaced class. Do not keep the J prefix.

How to fix it

1Add a use statement for Joomla\CMS\Extension\ExtensionHelper.
2Replace every JExtensionHelper with the short class name from that use line.
3Disable Behaviour – Backward Compatibility on a Joomla 5 staging site. If it fatals, this class is still in the code.

Also known as

JExtensionHelper · Joomla\CMS\Extension\ExtensionHelper · class alias · J prefix

Scan a ZIP for this Ask Infyways to fix it

JINSTALLER-ADAPTER-001

JInstallerComponent

JInstallerComponent (old adapter class names)

Installer adapter class names changed in Joomla 4. The old JInstallerComponent name is gone.

JInstallerComponent → InstallerAdapterComponent (and module/plugin/template adapters)

Dies at Joomla 3 → 4

Dies at Joomla 3 → 4J3: Works nativelyJ4: Removed — fatalJ6: Removed — fatalBC plugin: no — already dead on J4You rewrite thisJoomla API

What you will see

Class "JInstallerComponent" not found
Class "JInstallerPlugin" not found
Class "JInstallerModule" not found
Class "JInstallerTemplate" not found
Class "JInstallerLanguage" not found
Class "JInstallerLibrary" not found
Class "JInstallerPackage" not found

Symptoms people search

custom installer adapter fatal · custom installer adapter 500

Replace this code

Swap JInstallerComponent for InstallerAdapterComponent (and module/plugin/template adapters).

Joomla 3

Remove or stop calling this

class JInstallerComponent extends JAdapterInstance {}

Joomla 4 / 6

Use this instead

Use Joomla\CMS\Installer\Adapter\ComponentAdapter. Do not subclass the J3 names.

How to fix it

1Update custom install adapters to the new namespace.
2Use script.php installer script APIs.

Also known as

JInstallerComponent · JInstallerPlugin · JInstallerModule · JInstallerTemplate · JInstallerLanguage · JInstallerLibrary · JInstallerPackage · InstallerAdapter · InstallerAdapterComponent

There is no 1:1 swap for this one. The architecture changed. If you cannot rewrite it, Infyways can.

Scan a ZIP for this Ask Infyways to fix it

JINSTALLER-CLASS-001

JInstaller

JInstaller class name

JInstaller is a Joomla 3 global class. Joomla 4 still has an alias. Joomla 5 needs the Behaviour – Backward Compatibility plugin. Native Joomla 6 does not load that alias — you get Class "JInstaller" not found.

JInstaller → Joomla\CMS\Installer\Installer

Dies at Joomla 5 → 6

Dies at Joomla 5 → 6J3: Works nativelyJ4: Alias (old name still resolves)J6: Removed — fatalBC plugin: covers the class nameMechanical renameJoomla API

What you will see

Class "JInstaller" not found
Class 'JInstaller' not found
Failed to open stream: JInstaller

Symptoms people search

white screen after disabling compatibility plugin · class not found on Joomla 6 · works on Joomla 5 until I turn off backward compatibility

Replace this code

Swap JInstaller for Joomla\CMS\Installer\Installer.

Joomla 3

Remove or stop calling this

JInstaller::getInstance();
// or new JInstaller()

Joomla 4 / 6

Use this instead

use Joomla\CMS\Installer\Installer;

// Call the namespaced class. Do not keep the J prefix.

How to fix it

1Add a use statement for Joomla\CMS\Installer\Installer.
2Replace every JInstaller with the short class name from that use line.
3Disable Behaviour – Backward Compatibility on a Joomla 5 staging site. If it fatals, this class is still in the code.

Also known as

JInstaller · Joomla\CMS\Installer\Installer · class alias · J prefix

Scan a ZIP for this Ask Infyways to fix it

JINSTALLERHELPER-CLASS-001

JInstallerHelper

JInstallerHelper class name

JInstallerHelper is a Joomla 3 global class. Joomla 4 still has an alias. Joomla 5 needs the Behaviour – Backward Compatibility plugin. Native Joomla 6 does not load that alias — you get Class "JInstallerHelper" not found.

JInstallerHelper → Joomla\CMS\Installer\InstallerHelper

Dies at Joomla 5 → 6

Dies at Joomla 5 → 6J3: Works nativelyJ4: Alias (old name still resolves)J6: Removed — fatalBC plugin: covers the class nameMechanical renameJoomla API

What you will see

Class "JInstallerHelper" not found
Class 'JInstallerHelper' not found
Failed to open stream: JInstallerHelper

Symptoms people search

white screen after disabling compatibility plugin · class not found on Joomla 6 · works on Joomla 5 until I turn off backward compatibility

Replace this code

Swap JInstallerHelper for Joomla\CMS\Installer\InstallerHelper.

Joomla 3

Remove or stop calling this

JInstallerHelper::getInstance();
// or new JInstallerHelper()

Joomla 4 / 6

Use this instead

use Joomla\CMS\Installer\InstallerHelper;

// Call the namespaced class. Do not keep the J prefix.

How to fix it

1Add a use statement for Joomla\CMS\Installer\InstallerHelper.
2Replace every JInstallerHelper with the short class name from that use line.
3Disable Behaviour – Backward Compatibility on a Joomla 5 staging site. If it fatals, this class is still in the code.

Also known as

JInstallerHelper · Joomla\CMS\Installer\InstallerHelper · class alias · J prefix

Scan a ZIP for this Ask Infyways to fix it

JINSTALLERSCRIPT-CLASS-001

JInstallerScript

JInstallerScript class name

JInstallerScript is a Joomla 3 global class. Joomla 4 still has an alias. Joomla 5 needs the Behaviour – Backward Compatibility plugin. Native Joomla 6 does not load that alias — you get Class "JInstallerScript" not found.

JInstallerScript → Joomla\CMS\Installer\InstallerScript

Dies at Joomla 5 → 6

Dies at Joomla 5 → 6J3: Works nativelyJ4: Alias (old name still resolves)J6: Removed — fatalBC plugin: covers the class nameMechanical renameJoomla API

What you will see

Class "JInstallerScript" not found
Class 'JInstallerScript' not found
Failed to open stream: JInstallerScript

Symptoms people search

white screen after disabling compatibility plugin · class not found on Joomla 6 · works on Joomla 5 until I turn off backward compatibility

Replace this code

Swap JInstallerScript for Joomla\CMS\Installer\InstallerScript.

Joomla 3

Remove or stop calling this

JInstallerScript::getInstance();
// or new JInstallerScript()

Joomla 4 / 6

Use this instead

use Joomla\CMS\Installer\InstallerScript;

// Call the namespaced class. Do not keep the J prefix.

How to fix it

1Add a use statement for Joomla\CMS\Installer\InstallerScript.
2Replace every JInstallerScript with the short class name from that use line.
3Disable Behaviour – Backward Compatibility on a Joomla 5 staging site. If it fatals, this class is still in the code.

Also known as

JInstallerScript · Joomla\CMS\Installer\InstallerScript · class alias · J prefix

Scan a ZIP for this Ask Infyways to fix it

JLIBRARYHELPER-LOAD-001

JLibraryHelper::_load()

JLibraryHelper::_load

The underscored loader was removed.

JLibraryHelper::_load() → LibraryHelper::loadLibrary()

Dies at Joomla 3 → 4

Dies at Joomla 3 → 4J3: Works nativelyJ4: Removed — fatalJ6: Removed — fatalBC plugin: no — already dead on J4Mechanical renameJoomla API

What you will see

Call to undefined method ...::_load

Symptoms people search

library not loading

Replace this code

Swap JLibraryHelper::_load() for LibraryHelper::loadLibrary().

Joomla 3

Remove or stop calling this

JLibraryHelper::_load('foo');

Joomla 4 / 6

Use this instead

LibraryHelper::loadLibrary('foo');

How to fix it

1Call loadLibrary().

Also known as

JLibraryHelper

Scan a ZIP for this Ask Infyways to fix it

JUPDATE-CLASS-001

JUpdate

JUpdate class name

JUpdate is a Joomla 3 global class. Joomla 4 still has an alias. Joomla 5 needs the Behaviour – Backward Compatibility plugin. Native Joomla 6 does not load that alias — you get Class "JUpdate" not found.

JUpdate → Joomla\CMS\Updater\Update

Dies at Joomla 5 → 6

Dies at Joomla 5 → 6J3: Works nativelyJ4: Alias (old name still resolves)J6: Removed — fatalBC plugin: covers the class nameMechanical renameJoomla API

What you will see

Class "JUpdate" not found
Class 'JUpdate' not found
Failed to open stream: JUpdate

Symptoms people search

white screen after disabling compatibility plugin · class not found on Joomla 6 · works on Joomla 5 until I turn off backward compatibility

Replace this code

Swap JUpdate for Joomla\CMS\Updater\Update.

Joomla 3

Remove or stop calling this

JUpdate::getInstance();
// or new JUpdate()

Joomla 4 / 6

Use this instead

use Joomla\CMS\Updater\Update;

// Call the namespaced class. Do not keep the J prefix.

How to fix it

1Add a use statement for Joomla\CMS\Updater\Update.
2Replace every JUpdate with the short class name from that use line.
3Disable Behaviour – Backward Compatibility on a Joomla 5 staging site. If it fatals, this class is still in the code.

Also known as

JUpdate · Joomla\CMS\Updater\Update · class alias · J prefix

Scan a ZIP for this Ask Infyways to fix it

JUPDATER-CLASS-001

JUpdater

JUpdater class name

JUpdater is a Joomla 3 global class. Joomla 4 still has an alias. Joomla 5 needs the Behaviour – Backward Compatibility plugin. Native Joomla 6 does not load that alias — you get Class "JUpdater" not found.

JUpdater → Joomla\CMS\Updater\Updater

Dies at Joomla 5 → 6

Dies at Joomla 5 → 6J3: Works nativelyJ4: Alias (old name still resolves)J6: Removed — fatalBC plugin: covers the class nameMechanical renameJoomla API

What you will see

Class "JUpdater" not found
Class 'JUpdater' not found
Failed to open stream: JUpdater

Symptoms people search

white screen after disabling compatibility plugin · class not found on Joomla 6 · works on Joomla 5 until I turn off backward compatibility

Replace this code

Swap JUpdater for Joomla\CMS\Updater\Updater.

Joomla 3

Remove or stop calling this

JUpdater::getInstance();
// or new JUpdater()

Joomla 4 / 6

Use this instead

use Joomla\CMS\Updater\Updater;

// Call the namespaced class. Do not keep the J prefix.

How to fix it

1Add a use statement for Joomla\CMS\Updater\Updater.
2Replace every JUpdater with the short class name from that use line.
3Disable Behaviour – Backward Compatibility on a Joomla 5 staging site. If it fatals, this class is still in the code.

Also known as

JUpdater · Joomla\CMS\Updater\Updater · class alias · J prefix

Scan a ZIP for this Ask Infyways to fix it

MANIFEST-NAMESPACE-001

<extension> without namespace

Missing <namespace> in the manifest

Joomla 3 extensions lived as class FooController in a flat folder. Joomla 4+ components need a namespace and usually a service provider so MVC Factory can find classes.

<extension> without namespace → <namespace path="src">Vendor\Component\Name</namespace>

Dies at Joomla 3 → 4

Dies at Joomla 3 → 4J3: Works nativelyJ4: Changed behaviourJ6: Changed behaviourBC plugin: not applicableYou rewrite thisManifest / installer

What you will see

Class ... not found
Failed to create MVC factory

Symptoms people search

extension installs but every view 500s · no namespace in XML

Replace this code

Swap <extension> without namespace for <namespace path="src">Vendor\Component\Name</namespace>.

Joomla 3

Remove or stop calling this

<extension type="component" version="3.9" method="upgrade">

Joomla 4 / 6

Use this instead

<extension type="component" method="upgrade">
  <namespace path="src">Acme\Component\Lms</namespace>
  <!-- plus services/provider.php -->

How to fix it

1Add <namespace path="src">Your\Vendor\Component</namespace>.
2Move PHP into src/ matching PSR-4.
3Add services/provider.php for components, modules, and plugins.

Also known as

namespace · services/provider.php · PSR-4

Scan a ZIP for this Ask Infyways to fix it

MANIFEST-PROVIDER-001

No service provider

services/provider.php (DI)

Without a provider, Joomla 4+ cannot construct namespaced MVC or plugins. This is the #1 “installs, then every view 500s” after you add a namespace.

No service provider → services/provider.php registering MVCFactory / plugin

Dies at Joomla 3 → 4

Dies at Joomla 3 → 4J3: Removed — fatalJ4: Works nativelyJ6: Works nativelyBC plugin: not applicableYou rewrite thisManifest / installer

What you will see

Could not create MVC
Service not found
Failed to start application

Symptoms people search

provider.php missing · DI container · MVC factory

Replace this code

Swap No service provider for services/provider.php registering MVCFactory / plugin.

Joomla 3

Remove or stop calling this

// Joomla 3: classes in controllers/ models/ views/ autoloaded by name

Joomla 4 / 6

Use this instead

// services/provider.php
return new class implements ServiceProviderInterface {
    public function register(Container $container): void {
        $container->registerServiceProvider(new MVCFactory('Acme\\Component\\Lms'));
    }
};

How to fix it

1Add services/provider.php for components, modules, and plugins.
2Register MVCFactory / PluginDispatcherTrait services as core does.

Also known as

services/provider.php · ServiceProviderInterface · MVCFactory · DI

There is no 1:1 swap for this one. The architecture changed. If you cannot rewrite it, Infyways can.

Scan a ZIP for this Ask Infyways to fix it

MANIFEST-SCRIPT-UNINSTALL-001

preflight($type) assuming install only

script.php preflight only on install

Joomla 4 runs installer scripts on uninstall for all extension types. Plugin SQL vs script order also flipped to script-then-SQL.

preflight($type) assuming install only → Handle uninstall/update in preflight and postflight

Dies at Joomla 3 → 4

Dies at Joomla 3 → 4J3: Works nativelyJ4: Changed behaviourJ6: Changed behaviourBC plugin: not applicableYou rewrite thisManifest / installer

Symptoms people search

uninstall 500 in script.php · plugin sql order

Replace this code

Swap preflight($type) assuming install only for Handle uninstall/update in preflight and postflight.

Joomla 3

Remove or stop calling this

public function preflight($type, $parent) {
    // ran on install only in some J3 types
}

Joomla 4 / 6

Use this instead

public function preflight($type, $parent) {
    if ($type === 'uninstall') { /* also runs on J4+ */ }
}

How to fix it

1Guard preflight/postflight by $type.
2Do not assume uninstall SQL ran before the script.

Also known as

script.php · preflight · postflight · uninstall

Scan a ZIP for this Ask Infyways to fix it

MANIFEST-UPDATER-CLIENT-001

<client>0</client>

Updater client 0 / 1 integers

Joomla 3 update servers used integer clients. Joomla 4 wants the words site and administrator.

<client>0</client> → site / administrator strings

Dies at Joomla 3 → 4

Dies at Joomla 3 → 4J3: Works nativelyJ4: Changed behaviourJ6: Changed behaviourBC plugin: not applicableMechanical renameManifest / installer

What you will see

Invalid client

Symptoms people search

update does not show in Joomla · live update broken

Replace this code

Swap <client>0</client> for site / administrator strings.

Joomla 3

Remove or stop calling this

<client>0</client>

Joomla 4 / 6

Use this instead

<client>site</client>
<!-- or administrator -->

How to fix it

1Change 0 → site, 1 → administrator in the update XML.

Also known as

update server · client 0 · client 1

Scan a ZIP for this Ask Infyways to fix it

WEBLINKS-CORE-001

com_weblinks in core

Weblinks (and other) moved out of core

Joomla 4 removed several core extensions. A 3→4 upgrade will drop them unless you install the separate package.

com_weblinks in core → Install from JED / TED if you still need it

Dies at Joomla 3 → 4

Dies at Joomla 3 → 4J3: Works nativelyJ4: Removed — fatalJ6: Removed — fatalBC plugin: no — already dead on J4Architecture change — no auto-fixManifest / installer

Symptoms people search

weblinks missing after upgrade · com_weblinks

Replace this code

Swap com_weblinks in core for Install from JED / TED if you still need it.

Joomla 3

Remove or stop calling this

Joomla 3 core Weblinks component

Joomla 4 / 6

Use this instead

Install the Weblinks package for Joomla 4+. Same for some other former-core extensions.

How to fix it

1Inventory core components you used.
2Install the J4+ package before cutover or accept data loss.

Also known as

com_weblinks · TED · core extension removed

There is no 1:1 swap for this one. The architecture changed. If you cannot rewrite it, Infyways can.

Scan a ZIP for this Ask Infyways to fix it