remaining installer events documented

[robbiejackson]

User description

This documents the remain onInstaller events.

The v4.4 documentation will be a bit different because some of these features weren't available then - I'll complete the other versions after this initial review.

---

PR Type

Documentation

---

Description

• Documents four remaining installer plugin events

• Adds overview links to installation process and Joomla 4/5 changes

• Includes event descriptions, arguments, return values, and code examples

• Covers onInstallerAddInstallationTab, onInstallerBeforeInstallation, onInstallerBeforeInstaller, and onInstallerAfterInstaller events

---

Diagram Walkthrough

flowchart LR
  A["Installer Events Documentation"] --> B["Overview & References"]
  A --> C["onInstallerAddInstallationTab"]
  A --> D["onInstallerBeforeInstallation"]
  A --> E["onInstallerBeforeInstaller"]
  A --> F["onInstallerAfterInstaller"]
  B --> G["Install Process Link"]
  B --> H["Joomla 4/5 Changes Link"]
  C --> I["Event Arguments & Examples"]
  D --> I
  E --> I
  F --> I

Loading

File Walkthrough

Relevant files

Documentation

installer.md Complete installer events documentation with examples        docs/building-extensions/plugins/plugin-events/installer.md Added introductory section with links to installation process overview and Joomla 4/5 event changes documentation Documented onInstallerAddInstallationTab event with description, arguments, return value, and core usage examples Documented onInstallerBeforeInstallation event with subject and package arguments, return value behavior, and code example Documented onInstallerBeforeInstaller event with detailed package array structure, return values, and example of package override Documented onInstallerAfterInstaller event with all arguments (subject, package, installer, installerResult, message), return value handling, and code example +157/-0

---

[qodo-merge-pro]

PR Compliance Guide 🔍

Below is a summary of compliance checks for this PR:

Security Compliance
🟢	No security concerns identified No security vulnerabilities detected by AI analysis. Human verification advised for critical code.
Ticket Compliance
⚪	🎫 No ticket provided Create ticket/issue
Codebase Duplication Compliance
⚪	Codebase context is not defined Follow the guide to enable codebase context checks.
Custom Compliance
🟢	Generic: Meaningful Naming and Self-Documenting Code Objective: Ensure all identifiers clearly express their purpose and intent, making code self-documenting Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Logging Practices Objective: To ensure logs are useful for debugging and auditing without exposing sensitive information like PII, PHI, or cardholder data. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
⚪	Generic: Comprehensive Audit Trails Objective: To create a detailed and reliable record of critical system actions for security analysis and compliance. Status: No runtime code: The PR only adds documentation text and examples, not application logic, so it neither implements nor violates audit logging; verification requires broader project context. Referred Code For an overview of how a number of these events fit into the installation process see [Install Process](../../install-update/installation/install-process.md). (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](../joomla-4-and-5-changes.md), where you can also find explanations for [accessing the arguments](../joomla-4-and-5-changes.md#summary---accessing-event-arguments) and [returning values](../joomla-4-and-5-changes.md#summary---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. ... (clipped 192 lines) Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Robust Error Handling and Edge Case Management Objective: Ensure comprehensive error handling that provides meaningful context and graceful degradation Status: Example lacks errors: The added examples show happy-path event handlers without error handling or edge-case management, which may be acceptable for documentation but cannot confirm robustness. Referred Code 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 ... (clipped 48 lines) </details> > Learn more about managing compliance <a href='https://qodo-merge-docs.qodo.ai/tools/compliance/#configuration-options'>generic rules</a> or creating your own <a href='https://qodo-merge-docs.qodo.ai/tools/compliance/#custom-compliance'>custom rules</a> </details></td></tr> <tr><td><details> <summary><strong>Generic: Secure Error Handling</strong></summary><br> **Objective:** To prevent the leakage of sensitive system information through error messages while <br>providing sufficient detail for internal debugging.<br> **Status:** <br><a href='https://github.com/joomla/Manual/pull/551/files#diff-5a95310ffe99bcb7b34f2202208fef74162a7c76cd59e0176e9fb258b66cb5f9R213-R221'><strong>Message guidance</strong></a>: The example sets installer messages (lines 219–220) without guidance on avoiding sensitive <br>details, so security of user-facing errors cannot be confirmed from the docs.<br> <details open><summary>Referred Code</summary> ```markdown You can set the installer result and message, eg: ```php public function onInstallerAfterInstaller(\Joomla\CMS\Event\Installer\AfterInstallerEvent $event): void { $event->updateInstallerResult(false); $event->updateMessage("Some failure message"); } </details> > Learn more about managing compliance <a href='https://qodo-merge-docs.qodo.ai/tools/compliance/#configuration-options'>generic rules</a> or creating your own <a href='https://qodo-merge-docs.qodo.ai/tools/compliance/#custom-compliance'>custom rules</a> </details></td></tr> <tr><td><details> <summary><strong>Generic: Security-First Input Validation and Data Handling</strong></summary><br> **Objective:** Ensure all data inputs are validated, sanitized, and handled securely to prevent <br>vulnerabilities<br> **Status:** <br><a href='https://github.com/joomla/Manual/pull/551/files#diff-5a95310ffe99bcb7b34f2202208fef74162a7c76cd59e0176e9fb258b66cb5f9R171-R221'><strong>No input validation</strong></a>: The examples demonstrate updating installer state and messages without illustrating <br>validation or sanitization of inputs, which cannot confirm security posture in practice.<br> <details open><summary>Referred Code</summary> ```markdown You can also set the package to be installed, overriding what the administrator selected, eg: ```php 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 ... (clipped 30 lines) </details> > Learn more about managing compliance <a href='https://qodo-merge-docs.qodo.ai/tools/compliance/#configuration-options'>generic rules</a> or creating your own <a href='https://qodo-merge-docs.qodo.ai/tools/compliance/#custom-compliance'>custom rules</a> </details></td></tr> <tr><td align="center" colspan="2"> <!-- placeholder --> <!-- /compliance --update_compliance=true --> </td></tr></tbody></table> <details><summary>Compliance status legend</summary> 🟢 - Fully Compliant<br> 🟡 - Partial Compliant<br> 🔴 - Not Compliant<br> ⚪ - Requires Further Human Verification<br> 🏷️ - Compliance label<br> </details>

[qodo-merge-pro]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
Possible issue	Correct the event return value documentation Correct the onInstallerBeforeInstallation documentation to use $event->stopInstallation() instead of returning a boolean, as the method signature is void, and remove the incorrect text about setting a package. docs/building-extensions/plugins/plugin-events/installer.md [122-128] -A return value of true will cause the Joomla installer to exit with true (indicating that the extension was installed). +You can stop the installation by using the `stopInstallation()` method on the event object. You can optionally provide a boolean success status and a message. -A return value of false will cause the Joomla installer to exit with false (indicating that the extension installation failed). +```php +public function onInstallerBeforeInstallation(\Joomla\CMS\Event\Installer\BeforeInstallationEvent $event): void +{ + // Stop installation, marking it as failed, with a custom message. + $event->stopInstallation(false, 'Installation has been stopped by the plugin.'); +} +``` -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. - Apply / Chat Suggestion importance[1-10]: 9 __ Why: The suggestion correctly identifies a significant contradiction between the documented return value and the void return type in the function signature, which would cause developer confusion and errors.	High
High-level	Verify event argument access patterns The documentation presents inconsistent methods for accessing event arguments. It's recommended to verify these access patterns against the event class implementations and document the correct, consistent approach, favoring specific getters over the generic getArguments() method if they exist. Examples: docs/building-extensions/plugins/plugin-events/installer.md [108-116] Note that there is no getter for the subject argument. Instead you should use: ```php public function onInstallerBeforeInstallation(\Joomla\CMS\Event\Installer\BeforeInstallationEvent $event): void { $args = $event->getArguments(); $subject = $args['subject']; } </details> <details> <summary> <a href="https://github.com/joomla/Manual/pull/551/files#diff-5a95310ffe99bcb7b34f2202208fef74162a7c76cd59e0176e9fb258b66cb5f9R143-R151">docs/building-extensions/plugins/plugin-events/installer.md [143-151]</a> </summary> ```markdown Note that there is no getter for the subject argument. Instead you should use: ```php public function onInstallerBeforeInstaller(\Joomla\CMS\Event\Installer\BeforeInstallerEvent $event): void { $args = $event->getArguments(); $subject = $args['subject']; } </details> ### Solution Walkthrough: #### Before: ```markdown ## onInstallerBeforeInstallation ... ### Event Arguments ... - **`subject`** - ... Note that there is no getter for the subject argument. Instead you should use: ```php public function onInstallerBeforeInstallation(...) { $args = $event->getArguments(); $subject = $args['subject']; } #### After: ```markdown ## onInstallerBeforeInstallation ... ### Event Arguments ... - **`subject`** - ... Note that there is no getter for the subject argument. Instead you should use: ```php public function onInstallerBeforeInstallation(...) { // Option 1: Using getArguments() $args = $event->getArguments(); $subject = $args['subject']; // Option 2: Using getArgument('subject') $subject = $event->getArgument('subject'); } <details><summary>Suggestion importance[1-10]: 8</summary> __ Why: This suggestion correctly identifies a potential major inconsistency in the documentation regarding event argument access, which is critical for developers using these events. </details></details></td><td align=center>Medium </td></tr><tr><td rowspan=1>General</td> <td> <details><summary>Clarify impact of changing installer result</summary> ___ **Clarify the documentation for <code>onInstallerAfterInstaller</code> to explain that setting <br>the installer result to <code>false</code> is important for signaling post-installation <br>failures, rather than having "little impact".** [docs/building-extensions/plugins/plugin-events/installer.md [223-225]](https://github.com/joomla/Manual/pull/551/files#diff-5a95310ffe99bcb7b34f2202208fef74162a7c76cd59e0176e9fb258b66cb5f9R223-R225) ```diff -However, at this stage the installation has been completed, so setting the installer result in this way has little impact. +However, at this stage the core installation has been completed. If your plugin performs post-installation checks or actions and they fail, it is important to set the installer result to `false`. This will correctly flag the overall installation as failed. If you set the message then it is output instead of the standard Joomla message. Apply / Chat Suggestion importance[1-10]: 7 __ Why: The suggestion correctly points out that describing the impact of changing the installer result as "little" is misleading and clarifies the importance of this action for post-installation failure handling.	Medium
More