Document new error handling in Joomla 6.0 onwards

[Hackwar]

User description

This is the documentation PR for joomla/joomla-cms#44098

---

PR Type

Documentation

---

Description

• Add comprehensive documentation for new error handling in Joomla 6.0+

  • Explain transition from legacy error handling to exceptions
  • Provide migration guidance for third-party developers
  • Include before/after code examples for error handling in views

• Update sidebar position for compatibility plugin documentation

---

Changes walkthrough 📝

Relevant files

Documentation

errorhandling.md Add documentation for new error handling and migration in Joomla 6.0+ migrations/54-60/errorhandling.md Add new documentation page detailing error handling changes in Joomla 6.0+ Explain the transition from legacy error handling to exceptions Provide migration advice and code examples for developers Outline core migration plans and recommendations for third parties +117/-0  compat-plugin.md Adjust sidebar position for compatibility plugin doc          migrations/54-60/compat-plugin.md Update sidebar position metadata from 4 to 5 +1/-1

---

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-merge-pro]

Qodo Merge was enabled for this repository. To continue using it, please link your Git account with your Qodo account here.

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 Code Example Improvement The PHP code examples don't include proper syntax highlighting hints. Adding language identifiers to the code blocks (php instead of just ) would improve readability and syntax highlighting in the documentation. if ($errorConditionEvaluatingToFalse) { $this->setError($table->getError()); return false; } Missing Information The documentation doesn't clearly explain what happens when exceptions are thrown but not caught by third-party code that expects the legacy error handling. Consider adding guidance on backward compatibility concerns. ## What should third party developers do? The above examples from the core look quite complex and cumbersome. Fortunately third party developers can go a much simpler route by simply switching to exceptions right away. Remember that the core needs to support both code which does and doesn't supports exceptions at the same time. As a third party developer, you can simply switch all of your code to exceptions at once and only have to make sure that the core classes, which you are extending from, also throw exceptions. For this, you can simply call `$this->setUseExceptions(true);` in the constructor of your object to directly force exceptions. This will allow you to do one refactoring of your code to use exceptions anywhere in the release cycle of Joomla 6 and you only have to touch this somewhere before Joomla 8 to remove the `$this->setUseExceptions(true);` again.

[qodo-merge-pro]

PR Code Suggestions ✨

Latest suggestions up to 4fc8134

Category	Suggestion	Impact
General	Clarify dual behavior Clarify that when setError() throws an exception, it will still set the error message in the legacy system. This dual behavior is important for backward compatibility during the transition period. migrations/54-60/errorhandling.md [40-42] -**To ease the transition to exceptions, `setError()` will also throw the error as exception when the flag is set.** -Ideally, you should use error-specific exceptions, which is why the core will use this more complex solution. `setError()` -just throws a generic `Exception` exception. +**To ease the transition to exceptions, `setError()` will also throw the error as exception when the flag is set, while still setting the error message in the legacy system.** Ideally, you should use error-specific exceptions, which is why the core will use this more complex solution. `setError()` just throws a generic `Exception` exception. Apply this suggestion Suggestion importance[1-10]: 6 __ Why: The suggestion correctly identifies a point in the documentation that could benefit from clarification. Explicitly stating that setError() maintains its legacy behavior alongside throwing an exception when the flag is set improves the accuracy and completeness of the migration guide.	Low
More

---

Previous suggestions

✅ Suggestions up to commit 4b61b19

Category	Suggestion	Impact
General	✅ Fix method name typo There's a typo in the method name shouldUseException() which should be shouldUseExceptions() to match the correct method name used elsewhere in the document. Consistency in method naming is important for documentation clarity. migrations/54-60/errorhandling.md [50-52] At that point in time, the Joomla core would be entirely transitioned to exceptions. It is still up for discussion if -the calls to `shouldUseException()` should then also default to `true` instead of `false` like right now. The trait itself +the calls to `shouldUseExceptions()` should then also default to `true` instead of `false` like right now. The trait itself is planned to be dropped in Joomla 8.0. [Suggestion has been applied] Suggestion importance[1-10]: 4 __ Why: The suggestion correctly identifies and fixes a typo (shouldUseException() instead of shouldUseExceptions()) in the documentation text. This improves the accuracy and consistency of the document.	Low

✅ Suggestions up to commit 7a4ac33

Category	Suggestion	Impact
General	✅ Add syntax highlighting Suggestion Impact: The suggestion was implemented by adding 'php' language identifier to code blocks in the documentation, enabling proper syntax highlighting code diff: -``` +```php The code example is missing PHP syntax highlighting. Add the 'php' language identifier to the code block to ensure proper syntax highlighting in the documentation. migrations/54-60/errorhandling.md [20-26] -``` +```php if ($errorConditionEvaluatingToFalse) { $this->setError($table->getError()); return false; } `[Suggestion has been applied]` <details><summary>Suggestion importance[1-10]: 3</summary> __ Why: The suggestion correctly identifies a missing language identifier (`php`) for a code block in the markdown documentation. Adding it improves readability through syntax highlighting. The impact is minor as it only affects documentation formatting. </details></details></td><td align=center>Low </td></tr><tr><td> <details><summary>Specify full exception namespace</summary> ___ **The documentation should specify the full namespace for the generic Exception <br>class. This avoids confusion and ensures developers understand exactly which <br>exception class is being used.** [migrations/54-60/errorhandling.md [40-42]](https://github.com/joomla/Manual/pull/455/files#diff-940fe1b9e3d00b7f86118424c637e5e61e45a4aef98072d8fe033db7a08c67deR40-R42) ```diff **To ease the transition to exceptions, `setError()` will also throw the error as exception when the flag is set.** Ideally, you should use error-specific exceptions, which is why the core will use this more complex solution. `setError()` -just throws a generic `Exception` exception. +just throws a generic `\Exception` exception. Suggestion importance[1-10]: 2 __ Why: The suggestion proposes adding a leading backslash to Exception (making it \Exception) for explicit namespacing in the documentation. While technically correct and slightly clearer, the improvement in a documentation context is minimal, as Exception typically implies the root namespace.	Low