Add new InstallerScriptTrait (PR #44381)

[bembelimen]

User description

PR for new InstallerScriptTrait feature: https://github.com/joomla/joomla-cms/pull/44381

---

PR Type

Documentation, Enhancement

---

Description

• Document usage of new InstallerScriptTrait in script files.

• Update example to demonstrate trait integration and properties.

• Show how to override preflight and postflight with custom methods.

• Add code comments for minimum version checks and dashboard menu module.

---

Changes walkthrough 📝

Relevant files

Documentation

install-process.md Add InstallerScriptTrait usage and update install script example docs/building-extensions/install-update/installation/install-process.md Added documentation for using InstallerScriptTrait in script files. Updated code example to include the trait and its properties. Replaced standard preflight/postflight with custom methods for extensibility. Provided comments on minimum PHP/Joomla version checks and dashboard menu module. +40/-21

---

Need help?

Type /help how to ... in the comments thread for any questions about Qodo Merge usage.

Check out the documentation for more information.

[qodo-code-review[bot]]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 2 🔵🔵⚪⚪⚪

🧪 No relevant tests

🔒 No security concerns identified

⚡ Recommended focus areas for review Syntax Error Missing closing quote in the minimumJoomla property declaration which would cause a PHP syntax error if copied directly. protected $minimumJoomla = '6.0.0; Method Naming The custom preflight and postflight methods are introduced but it's not clear how they relate to the standard preflight/postflight methods from the InstallerScriptInterface. Documentation should clarify how these custom methods are invoked. public function customPreflight(string $type, InstallerAdapter $parent): bool { // Your custom preflight code // Custom Dashboard Menu Module // $this->addDashboardMenuModule('example', 'example'); return true; } public function customPostflight(string $type, InstallerAdapter $parent): bool { // Your custom postflight code return true; }

[qodo-code-review[bot]]

PR Code Suggestions ✨

Latest suggestions up to fd69391

Category	Suggestion	Impact
Possible issue	Fix unrealistic version requirements The specified minimum PHP version (8.4) and Joomla version (6.0.0) are future versions that don't exist yet. This will cause installations to fail on all current systems. Use realistic minimum version requirements that match currently available versions. docs/building-extensions/install-update/installation/install-process.md [93-105] /** * Minimum PHP version required to install the extension * * @var string */ -protected $minimumPhp = '8.4'; +protected $minimumPhp = '8.1'; /** * Minimum Joomla! version required to install the extension * * @var string */ -protected $minimumJoomla = '6.0.0'; +protected $minimumJoomla = '4.3.0'; [ ] Apply this suggestion Suggestion importance[1-10]: 9 __ Why: The suggestion correctly identifies that the specified PHP 8.4 and Joomla 6.0.0 are future versions that don't exist yet, which would cause all current installations to fail. Changing to realistic current versions (PHP 8.1 and Joomla 4.3.0) is a critical fix for the example code to be functional.	High
[ ] Update

---

Previous suggestions

✅ Suggestions up to commit 27cef1b

Category	Suggestion	Impact
Possible issue	✅ Fix syntax error Suggestion Impact: The commit fixed the syntax error by adding the missing closing quote to the $minimumJoomla property declaration, exactly as suggested code diff: - protected $minimumJoomla = '6.0.0; + protected $minimumJoomla = '6.0.0'; Fix the missing closing quote in the $minimumJoomla property declaration. The string is not properly terminated. docs/building-extensions/install-update/installation/install-process.md [105] -protected $minimumJoomla = '6.0.0; +protected $minimumJoomla = '6.0.0'; [Suggestion has been applied] Suggestion importance[1-10]: 10 __ Why: The suggestion correctly identifies a critical syntax error where the closing quote is missing in the $minimumJoomla property declaration. This would cause a PHP syntax error that would prevent the code from executing properly. Fixing this issue is essential for the code to function.	High

[qodo-code-review[bot]]

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 Error Handling Objective: To prevent the leakage of sensitive system information through error messages while providing sufficient detail for internal debugging. 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 logging: The added example code invokes installer lifecycle methods without demonstrating any audit logging of critical actions, but as documentation code this may intentionally omit logging for brevity. Referred Code public function preflight(string $type, InstallerAdapter $parent): bool { // Run trait preflight code $this->iScriptTraitPre(); // Your custom preflight code // Custom Dashboard Menu Module // $this->addDashboardMenuModule('example', 'example'); return true; } public function postflight(string $type, InstallerAdapter $parent): bool { // Run trait postflight code $this->iScriptTraitPost(); // Your custom postflight code return true; 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: Minimal handling: The example preflight/postflight methods always return true and do not show handling or reporting of potential failures, which may be acceptable for illustrative documentation but lacks robustness. Referred Code public function preflight(string $type, InstallerAdapter $parent): bool { // Run trait preflight code $this->iScriptTraitPre(); // Your custom preflight code // Custom Dashboard Menu Module // $this->addDashboardMenuModule('example', 'example'); return true; } public function postflight(string $type, InstallerAdapter $parent): bool { // Run trait postflight code $this->iScriptTraitPost(); // Your custom postflight code return true; ... (clipped 1 lines) Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Security-First Input Validation and Data Handling Objective: Ensure all data inputs are validated, sanitized, and handled securely to prevent vulnerabilities Status: No validation: The example adds hooks and trait usage without demonstrating validation of external inputs or safe handling where installer parameters might be processed, which may be omitted intentionally in docs. Referred Code public function preflight(string $type, InstallerAdapter $parent): bool { // Run trait preflight code $this->iScriptTraitPre(); // Your custom preflight code // Custom Dashboard Menu Module // $this->addDashboardMenuModule('example', 'example'); return true; } public function postflight(string $type, InstallerAdapter $parent): bool { // Run trait postflight code $this->iScriptTraitPost(); // Your custom postflight code return true; Learn more about managing compliance generic rules or creating your own custom rules

Compliance status legend

🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

[softforge]

Thank you @bembelimen much appreciated