Skip to main content
Version: 6.0 (Current)

Installer Events

Installer plugin events are triggered when some routines are performed during the install process of extensions or when their update sites are downloaded.

For an overview of how a number of these events fit into the installation process see Install Process. (Note that the onExtensionBeforeInstall and onExtensionAfterInstall events aren't covered here).

For background on Joomla transitioning to using classes for events see Joomla 4 and 5 changes, where you can also find explanations for accessing the arguments and returning values.

onInstallerAddInstallationTab​

Description​

This event is triggered when Joomla is building the form in the administrator Install / Extensions page.

Event Arguments​

The event class \Joomla\CMS\Event\Installer\AddInstallationTabEvent has no arguments.

Return Value​

Return the contents of the additional tab which you want to include in the options for install.

Examples​

The Joomla core uses this mechanism to create the tabs "Upload Package File", "Install from Folder" etc. You should look at these install plugins and follow them as exemplars.

onInstallerBeforePackageDownload​

Description​

This event will be executed before an installable package (zip file) of an extension (package, component, module, plugin, template, library) is downloaded. It allows plugins to modify the url or headers for the request.

Event Arguments​

The event class \Joomla\CMS\Event\Installer\BeforePackageDownloadEvent has the following arguments:

  • url - The url of the package.

  • headers - The headers which are sent with the request.

Return Value​

None.

Examples​

public function onInstallerBeforePackageDownload(\Joomla\CMS\Event\Installer\BeforePackageDownloadEvent $event): void
{
    $event->updateUrl($event->getUrl() . '?auth=foo');
}

onInstallerBeforeUpdateSiteDownload​

Description​

This event will be executed before an update site is downloaded. It allows to modify the url or headers for the request.

Event Arguments​

The event class \Joomla\CMS\Event\Installer\BeforeUpdateSiteDownloadEvent has the following arguments:

  • url - The url of the update site.

  • headers - The headers which are sent with the request.

Return Value​

None.

Examples​

public function onInstallerBeforeUpdateSiteDownload(\Joomla\CMS\Event\Installer\BeforeUpdateSiteDownloadEvent $event): void
{
    $event->updateUrl($event->getUrl() . '?auth=foo');
}

onInstallerBeforeInstallation​

Description​

This event is triggered at the beginning of an installation operation.

Event Arguments​

The event class \Joomla\CMS\Event\Installer\BeforeInstallationEvent has the following arguments:

  • subject - This will be the FQN of the install model class Joomla\Component\Installer\Administrator\Model\InstallModel

Note that there is no getter for the subject argument. Instead you should use:

public function onInstallerBeforeInstallation(\Joomla\CMS\Event\Installer\BeforeInstallationEvent $event): void
{
    $args = $event->getArguments();
    $subject = $args['subject'];
}
  • package - This is null.

Return Value​

A return value of true will cause the Joomla installer to exit with true (indicating that the extension was installed).

A return value of false will cause the Joomla installer to exit with false (indicating that the extension installation failed).

If you don't set a return value then the installation will continue as normal.

You can also set the package as described for the event onInstallerBeforeInstaller below.

onInstallerBeforeInstaller​

Description​

This event is triggered after the extension code has been obtained, and any extraction of zip files performed, but before Joomla has started to process the extension's installation files.

Event Arguments​

The event class \Joomla\CMS\Event\Installer\BeforeInstallerEvent has the following arguments:

  • subject - This will be the FQN of the install model class Joomla\Component\Installer\Administrator\Model\InstallModel

Note that there is no getter for the subject argument. Instead you should use:

public function onInstallerBeforeInstaller(\Joomla\CMS\Event\Installer\BeforeInstallerEvent $event): void
{
    $args = $event->getArguments();
    $subject = $args['subject'];
}

  • package - This is an array of 4 elements, which in the case of uploading a zip file will contain:

    • extractdir - the directory into which the zip file has been extracted
    • packagefile - the location of the zip file
    • dir - the directory containing the extension manifest file, and the other installation files
    • type - the type of extension (eg "plugin")

The array elements vary depending upon how the installation code is selected. For example, for "Install from Folder" the extractdir and packagefile elements will be null.

Return Value​

A return value of true will cause the Joomla installer to exit with true (indicating that the extension was installed).

A return value of false will cause the Joomla installer to exit with false (indicating that the extension installation failed).

If you don't set a return value then the installation will continue as normal.

You can also set the package to be installed, overriding what the administrator selected, eg:

public function onInstallerBeforeInstaller(\Joomla\CMS\Event\Installer\BeforeInstallerEvent $event): void
{
    $newpkg = array("dir" => $pathToExtensionDirectory, "type" => "plugin", "extractdir" => null, "packagefile" => null);
    $event->updatePackage($newpkg);
}

onInstallerAfterInstaller​

Description​

This event is triggered after extension has been installed.

Event Arguments​

The event class \Joomla\CMS\Event\Installer\AfterInstallerEvent has the following arguments:

  • subject - This will be the FQN of the install model class Joomla\Component\Installer\Administrator\Model\InstallModel

Note that there is no getter for the subject argument. Instead you should use:

public function onInstallerAfterInstaller(\Joomla\CMS\Event\Installer\AfterInstallerEvent $event): void
{
    $args = $event->getArguments();
    $subject = $args['subject'];
}

  • package - The package which has been installed, in the form described in onInstallerBeforeInstaller above.

  • installer - The installer class - Joomla sets this to "Joomla\CMS\Installer\Installer"

  • installerResult - true or false, depending upon whether the package was successfully installed or not

  • message - The message output to the administrator, eg "Installation of the plugin was successful."

Return Value​

You can set the installer result and message, eg:

public function onInstallerAfterInstaller(\Joomla\CMS\Event\Installer\AfterInstallerEvent $event): void
{
    $event->updateInstallerResult(false);
    $event->updateMessage("Some failure message");
}

However, at this stage the installation has been completed, so setting the installer result in this way has little impact.

If you set the message then it is output instead of the standard Joomla message.