Potential backward compatibility issues in Joomla 4

Content is Incomplete

This document tracks potential backward compatibility issues for Joomla! 4. Listed are issues which potentially break extensions.

The base of this comparison is Joomla! 3.7.

Updated System Requirements

The system requirements have been updated as follows:

• PHP 5.5.9
• MySQL 5.5.3
• PostgreSQL 9.2
• SQL Server support has been dropped.

PHP MySQL Extension

• Joomla no longer supports using PHP's ext/mysql driver (which was removed in PHP 7.0). Joomla will automatically try and use the mysqli extension (available since PHP 5.3) or the mysql PDO Driver (available since PHP 5.3) else it will fail to create a database connection.

CMS Libraries

The following changes have been made to Joomla! CMS libraries (this is primarily code found in the `libraries/cms` directory in Joomla! 3).

Installer

Removed Classes

The following classes have been removed in Joomla! 4.0:

• JInstallerComponent (use JInstallerAdapterComponent instead)
• JInstallerFile (use JInstallerAdapterFile instead)
• JInstallerLanguage (use JInstallerAdapterLanguage instead)
• JInstallerLibrary (use JInstallerAdapterLibrary instead)
• JInstallerModule (use JInstallerAdapterModule instead)
• JInstallerPackage (use JInstallerAdapterPackage instead)
• JInstallerPlugin (use JInstallerAdapterPlugin instead)
• JInstallerTemplate (use JInstallerAdapterTemplate instead)

JInstallerAdapter Inheritance

JInstallerAdapter no longer extends from JAdapterInstance and inherently JObject.

Menu

JMenu is now an abstract class

JMenu is now an abstract class. Subclasses of JMenu must now also implement a load method.

Manual Include Behavior Removed

The logic in JMenu::getInstance() to manually include a file from the application's includes/menu.php path has been removed. The JMenu subclass should be autoloaded instead.

Pathway

Manual Include Behavior Removed

The logic in JPathway::getInstance() to manually include a file from the application's includes/pathway.php path has been removed. The JPathway subclass should be autoloaded instead.

Router

Manual Include Behavior Removed

The logic in JRouter::getInstance() to manually include a file from the application's includes/router.php path has been removed. The JRouter subclass should be autoloaded instead.

JVersion

Support for accessing the JVersion class constants as class properties is no longer supported. The constants were introduced in Joomla! 3.5 to prevent the old class properties from being edited.

Platform

The following changes have been made to Joomla! Platform libraries (this is primarily code found in the `libraries/joomla` or `libraries/legacy` directories in Joomla! 3).

Application

Removed Classes

The following classes have been removed in Joomla! 4.0:

• JApplicationWebRouter (use the `joomla/router` package instead)
• JApplicationWebRouterBase (use the `joomla/router` package instead)
• JApplicationWebRouterRest (use the `joomla/router` package instead)

Deprecated Classes

The following classes have been deprecated and scheduled for removal in Joomla! 5.0:

• JApplicationBase (use Joomla\Application\AbstractApplication instead)

CLI/Web Class Changes

The JApplicationCli and JApplicationWeb classes have been recomposed to extend from the Framework's Application package instead. This breaks type checks for a JApplicationBase object. For forward compatibility, it is recommended to check if application classes are an instance of Joomla\Application\AbstractApplication (JApplicationBase has extended this class since Joomla! 3.4).

Additionally, both of these classes are now abstract. Developers implementing these classes must provide a `doExecute` method with their application's logic.

JApplicationCli

• Old: JApplicationCli  →  JApplicationBase  →  Joomla\Application\AbstractApplication
• New: JApplicationCli  →  Joomla\Application\AbstractCliApplication  →  Joomla\Application\AbstractApplication

JApplicationWeb

• Old: JApplicationWeb  →  JApplicationBase  →  Joomla\Application\AbstractApplication
• New: JApplicationWeb  →  Joomla\Application\AbstractWebApplication  →  Joomla\Application\AbstractApplication

Document

Deprecated Classes

The following classes have been deprecated and scheduled for removal in Joomla! 5.0:

• JDocumentError (use \Joomla\Cms\Error\RendererInterface objects instead)

JDocumentFeed

The property type of JDocumentFeed::$lastBuildDate has changed from a string to a JDate object. The property was previously unused by the core Joomla API but extensions may have used it.

JDocumentRendererFeedRss

In order to comply with the RSS feed specification, JDocumentRendererFeedRss now allows the lastBuildDate element to be configured using the JDocumentFeed::$lastBuildDate class property when a feed is rendered. This value defaults to the current time, as is the case with Joomla! 3.x and earlier, however the time can be correctly set by changing this class property to a JDate object representing the desired timestamp.

HTTP

Deprecated Classes and Interfaces

The following classes and interfaces have been deprecated and scheduled for removal in Joomla! 5.0:

• JHttpResponse (use Joomla\Http\Response instead)
• JHttpTransport (implement Joomla\Http\TransportInterface instead)

Class Changes

The Framework's HTTP package is now included in Joomla! 4.0 and JHttp and the JHttpTransport subclasses have been refactored to use the upstream package.

JHttp

The JHttp class constructor has been loosened with the following changes:

• The options parameter is no longer typehinted as a Joomla\Registry\Registry object, an array or any object implementing the ArrayAccess interface can be used instead
• The transport parameter now allows any Joomla\Http\TransportInterface object.

JHttpTransport

The now deprecated JHttpTransport interface extends Joomla\Http\TransportInterface now and has caused backward compatibility breaking changes in the interface. The constructor is no longer part of the interface, and the interface's `request()` method has had a signature change. Specifically, the second parameter which previously typehinted the JUri class now typehints Joomla\Uri\UriInterface.

JHttpResponse

In refactoring the response object to inherit from the Framework's HTTP package, which is now using the PSR-7 ResponseInterface API, a minor compatibility break has been made in the structure of the response headers. As of 4.0, this will now always be a multi-dimensional array where the key is the header name and the value is an array of values for that header (previously, this was a string).

Image

Deprecated Classes and Interfaces

The following classes and interfaces have been deprecated and scheduled for removal in Joomla! 5.0:

• JImageFilter (use Joomla\Image\ImageFilter instead)
• JImageFilterBackgroundfill (use Joomla\Image\Filter\Backgroundfill instead)
• JImageFilterBrightness (use Joomla\Image\Filter\Brightness instead)
• JImageFilterContrast (use Joomla\Image\Filter\Contrast instead)
• JImageFilterEdgedetect (use Joomla\Image\Filter\Edgedetect instead)
• JImageFilterEmboss (use Joomla\Image\Filter\Emboss instead)
• JImageFilterGrayscale (use Joomla\Image\Filter\Grayscale instead)
• JImageFilterNegate (use Joomla\Image\Filter\Negate instead)
• JImageFilterSketchy (use Joomla\Image\Filter\Sketchy instead)
• JImageFilterSmooth (use Joomla\Image\Filter\Smooth instead)

Class Changes

The Framework's Image package is now included in Joomla! 4.0 and JImage and the JImageFilter subclasses have been refactored to use the upstream package.

Table

• JTable::__construct database object is now typehinted to be a JDatabaseDriver.
  • Subclasses of JTable will need to ensure they are passing a JDatabaseDriver object to the parent constructor
  • Subclasses of JTable will need to change the method signature of setDbo() if they have an extended version of that method to include the typehint

Mail

The following methods have been removed in Joomla! 4.0:

• JMail::sendAdminMail has been removed

Legacy MVC Layer

Legacy Controller

• JControllerLegacy has been removed from the legacy layer, and we no longer intend to remove it or it's subclasses in the near future.
• JControllerLegacy no longer extends JObject. Controllers should not call any of the methods contained in the JObject class.
• JControllerLegacy implements an interface for multiple task controllers
• JControllerLegacy::_construct now requires a compulsory JApplicationCms object. If you were previously getting a Controller object through JControllerLegacy::getInstance you do not need to change your code.
• JControllerForm now using the StringInflector package to determine the list view. This should improve it's ability to guess determine the list view of more view names. If extension developers find that their list view is no longer being found they should manually set the `view_list` class property in their controller.

Session

The session package has undergone a major refactoring to use the Framework's Session package. This change primarily effects the internals of the package; changes to the primary public API through the JSession class are minimal.

Removed Classes and Interfaces

The following classes and interfaces have been removed in Joomla! 5.0:

• JSessionExceptionUnsupported
• JSessionHandlerInterface
• JSessionHandlerJoomla
• JSessionHandlerNative
• JSessionStorage
• JSessionStorageApc
• JSessionStorageDatabase
• JSessionStorageMemcache
• JSessionStorageMemcached
• JSessionStorageNone
• JSessionStorageWincache
• JSessionStorageXcache

JSession

JSession now extends from the Framework's Joomla\Session\Session class. Many of the methods have a modified signature and a compatibility layer exists to help with the transition.

Namespace Parameter Deprecated

The get, set, has, and clear methods previously supported a namespace parameter. This parameter is now deprecated, the namespace should be prepended to the name before calling these methods.

JSession::clear() Repurposed

In the Joomla\Session\Session class, the clear method is used to clear all data from the session store. In JSession, this method is used to remove a single key. When this method is called with parameters, it will call the new Joomla\Session\Session::remove() method.

JSession::getInstance() Deprecated

The singleton getInstance() method has been deprecated. The session object should be retrieved from the active application or the dependency injection container instead.

Session Handlers

In Joomla! 3.x and earlier, session handlers were represented by the JSessionStorage class and its subclasses. In Joomla! 4.0, session handlers are now implementations of Joomla\Session\HandlerInterface (which is an extension of PHP's SessionHandlerInterface. All handlers which were supported in Joomla! 3.x are still available in 4.0 in addition to two additional handlers; a handler natively implementing the APCu extension and a handler supporting Redis.

Classes Removed Without Replacement

• JNode
• JTree

External Libraries

The following changes have been made to the external libraries that Joomla! packages and ships.

PHPMailer

Joomla! 4.0 ships with PHPMailer 6.0. Please review the upgrading guide for relevant changes.

PHPUTF8

At Joomla! 3.4, the PHPUTF8 library lived in two locations in the Joomla! package; `libraries/phputf8` and `libraries/vendor/joomla/string/src/phputf8`. In Joomla! 4.0, the copy of the library in `libraries/phputf8` has been removed. The Joomla\String\StringHelper class exposes many of the library's functions and the Composer autoloader definition imports much of the library as well, however, if you need a feature that is not already included then you should import the required functions from the `libraries/vendor/joomla/string/src/phputf8` path.

SimplePie

The SimplePie library is no longer included with Joomla! 4.0.

jQuery

Joomla! 4.0 ships with jQuery 3. Please review the upgrading guide for relevant changes. Note that we are not including jQuery Migrate anymore either. We recommend using it locally to help debug your code if there are any issues.

Bootstrap

Joomla! 4.0 ships with Bootstrap 4.

Templates

All the Joomla! 3 templates - ISIS and Hathor in the backend, and protostar and Beeze in the frontend are no longer supported. The new 4.0 backend template is called Atum and the frontend template is called Aurora.