Update migration notes for backward compatibility removal

[softforge]

User description

Document removal of deprecated classes and changes to versioning system. Include details on migration and alternatives for affected extensions.

joomla/joomla-cms#42884
joomla/joomla-cms#44638
joomla/joomla-cms#45436
joomla/joomla-cms#45515

---

PR Type

Documentation

---

Description

• Document removal of deprecated BaseApplication and CLI classes

• Add migration notes for JPATH_PLATFORM constant changes

• Document UpdateController fetchExtensionCompatibility method removal

• Add versioning system changes documentation

---

Diagram Walkthrough

flowchart LR
  A["Deprecated Classes"] --> B["Migration Notes"]
  C["JPATH_PLATFORM"] --> B
  D["UpdateController"] --> B
  E["Versioning System"] --> B
  B --> F["Developer Documentation"]

Loading

File Walkthrough

Relevant files

Documentation

removed-backward-incompatibility.md Add backward compatibility removal documentation                  migrations/54-60/removed-backward-incompatibility.md Add documentation for BaseApplication and CLI class removal Document JPATH_PLATFORM constant migration to compat plugin Add notes for UpdateController fetchExtensionCompatibility removal Document versioning system changes and history table updates +27/-0

---

[qodo-merge-pro]

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 Incomplete Docs Several sections explicitly note “more detail needed” (migration examples, code examples and alternatives, replacement approach, schema differences). These gaps should be filled before merge to ensure actionable guidance for developers. **(more detail needed: migration examples)** ## Move JPATH_PLATFORM constant to compat plugin - PR: https://github.com/joomla/joomla-cms/pull/44638 - Description: The `JPATH_PLATFORM` constant is no longer globally defined. It is only available if the Backward Compatibility plugin is enabled. Extensions should avoid using this constant. **(more detail needed: code examples and alternatives)** ## Remove fetchExtensionCompatibility in UpdateController - PR: https://github.com/joomla/joomla-cms/pull/45436 - File: `administrator/components/com_installer/src/Controller/UpdateController.php` - Description: The `fetchExtensionCompatibility` method has been removed. Extensions or scripts that called this method will break and need to be updated to use the new update handling logic. **(more detail needed: replacement approach)** ## Extend versioning, save related information in history table and restore historical data - PR: https://github.com/joomla/joomla-cms/pull/45515 - Description: The versioning system now stores additional related data in the history table. Restoring historical versions also restores linked metadata. Extensions interacting with `#__ucm_history` may require schema or API updates. **(more detail needed: schema differences and migration examples)** Actionable Guidance The removal of fetchExtensionCompatibility references a “new update handling logic” but doesn’t link or outline the replacement API/workflow, which may block migrations. ## Remove fetchExtensionCompatibility in UpdateController - PR: https://github.com/joomla/joomla-cms/pull/45436 - File: `administrator/components/com_installer/src/Controller/UpdateController.php` - Description: The `fetchExtensionCompatibility` method has been removed. Extensions or scripts that called this method will break and need to be updated to use the new update handling logic. **(more detail needed: replacement approach)** Cross-Refs Sections reference removed classes/constants without linking to alternative classes’ docs or examples; adding links/snippets will improve usability and reduce confusion. ## Remove deprecated BaseApplication and CLI classes - PR: https://github.com/joomla/joomla-cms/pull/42884 - Files: `libraries/src/Application/BaseApplication.php`, `libraries/src/Application/CLI.php` - Description: These legacy classes have been removed. Use `\Joomla\CMS\Application\ConsoleApplication` or framework equivalents instead. **(more detail needed: migration examples)** ## Move JPATH_PLATFORM constant to compat plugin - PR: https://github.com/joomla/joomla-cms/pull/44638 - Description: The `JPATH_PLATFORM` constant is no longer globally defined. It is only available if the Backward Compatibility plugin is enabled. Extensions should avoid using this constant. **(more detail needed: code examples and alternatives)**

[qodo-merge-pro]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
General	Provide concrete migration examples Replace the placeholder with concrete migration snippets to prevent user confusion and broken upgrades. Show before/after code demonstrating how to instantiate and access the application in CLI contexts. This ensures developers can quickly adapt without guesswork. migrations/54-60/removed-backward-incompatibility.md [277-282] ## Remove deprecated BaseApplication and CLI classes - PR: https://github.com/joomla/joomla-cms/pull/42884 - Files: `libraries/src/Application/BaseApplication.php`, `libraries/src/Application/CLI.php` - Description: These legacy classes have been removed. - Use `\Joomla\CMS\Application\ConsoleApplication` or framework equivalents instead. - **(more detail needed: migration examples)** + Use `\Joomla\CMS\Application\ConsoleApplication` or framework equivalents instead. +Migration examples: +- Before (legacy CLI): + ```php + use Joomla\CMS\Application\CLI; + + $app = CLI::getInstance('MyCliApp'); + $app->execute(); + ``` +- After (ConsoleApplication): + ```php + use Joomla\CMS\Application\ConsoleApplication; + use Joomla\Console\Application as FrameworkConsole; + use Joomla\Console\Command\AbstractCommand; + + final class MyCommand extends AbstractCommand + { + protected static $defaultName = 'my:task'; + + protected function doExecute(\Joomla\Console\Input\Input $input, \Joomla\Console\Output\Output $output): int + { + // command logic + return 0; + } + } + + $app = new ConsoleApplication('MyCliApp'); + $app->addCommand(new MyCommand()); + $app->execute(); + ``` + Apply / Chat Suggestion importance[1-10]: 7 __ Why: The suggestion correctly identifies a placeholder (more detail needed: migration examples) and provides valuable, concrete code examples, significantly improving the quality and usefulness of the documentation.	Medium
	Add safe alternatives to removed constant Replace the placeholder with safe detection and alternatives to prevent fatal errors when the constant is undefined. Provide sample refactors to framework services or JPATH_LIBRARIES where applicable. migrations/54-60/removed-backward-incompatibility.md [284-289] ## Move JPATH_PLATFORM constant to compat plugin - PR: https://github.com/joomla/joomla-cms/pull/44638 -- Description: The `JPATH_PLATFORM` constant is no longer globally defined. - It is only available if the Backward Compatibility plugin is enabled. - Extensions should avoid using this constant. - **(more detail needed: code examples and alternatives)** +- Description: The `JPATH_PLATFORM` constant is no longer globally defined and is only available if the Backward Compatibility plugin is enabled. Avoid relying on it. +Migration guidance: +- Detect safely (avoid notices/fatals): + ```php + $platformPath = \defined('JPATH_PLATFORM') ? JPATH_PLATFORM : JPATH_LIBRARIES; + ``` +- Replace direct path usage with autoloaded classes or services. For example, instead of: + ```php + $file = JPATH_PLATFORM . '/cms/application/site.php'; + require_once $file; + ``` + use: + ```php + use Joomla\CMS\Application\SiteApplication; + + // Rely on autoloading rather than manual includes + $app = \Joomla\CMS\Factory::getApplication(); + ``` +- If you truly need library paths, prefer `JPATH_LIBRARIES` or `JPATH_ROOT` and component-relative paths: + ```php + $path = JPATH_LIBRARIES . '/joomla/something/file.php'; + ``` + Apply / Chat Suggestion importance[1-10]: 7 __ Why: The suggestion addresses a placeholder (more detail needed: code examples and alternatives) by providing useful code snippets and guidance, which helps developers adapt to the change and avoid potential errors.	Medium
	Document replacement for removed method Replace the placeholder with a concrete replacement workflow to prevent breaking integrations. Document how to query update compatibility via the new update model/service and sample code to check CMS/PHP constraints. migrations/54-60/removed-backward-incompatibility.md [291-296] ## Remove fetchExtensionCompatibility in UpdateController - PR: https://github.com/joomla/joomla-cms/pull/45436 - File: `administrator/components/com_installer/src/Controller/UpdateController.php` -- Description: The `fetchExtensionCompatibility` method has been removed. - Extensions or scripts that called this method will break and need to be updated to use the new update handling logic. - **(more detail needed: replacement approach)** +- Description: The `fetchExtensionCompatibility` method has been removed. Update your integrations to use the update model and manifest constraints. +Replacement approach: +- Use the Installer Update model to fetch updates and evaluate compatibility: + ```php + use Joomla\CMS\MVC\Factory\MVCFactoryInterface; + use Joomla\CMS\Factory; + + /** @var MVCFactoryInterface $mvcFactory */ + $mvcFactory = Factory::getApplication()->bootComponent('com_installer')->getMVCFactory(); + + /** @var \Joomla\Component\Installer\Administrator\Model\UpdateModel $model */ + $model = $mvcFactory->createModel('Update', 'Administrator'); + + // Refresh update information + $model->findUpdates(); + + // Get available updates and evaluate constraints (Joomla version, PHP, db) + $items = $model->getItems(); + + $app = Factory::getApplication(); + $joomlaVersion = JVERSION; + $phpVersion = PHP_VERSION; + + foreach ($items as $item) { + // Example: inspect $item->targetplatform or manifest extra fields + // and compare with current environment + // Skip items that declare incompatible constraints + } + ``` +- Alternatively, query update sites directly and parse extension manifests for `<targetplatform>` and `<updateservers>` constraints. + Apply / Chat Suggestion importance[1-10]: 7 __ Why: The suggestion replaces a placeholder (more detail needed: replacement approach) with a detailed code example, which is crucial for developers to update their integrations and prevent breakages.	Medium
More