9 minutes reading time (1785 words)

Pre-Update Check - Your path to Joomla 4

August

Tuesday, 17 August 2021

8256 Hits

Joomla 4's now available, but if you're thinking about upgrading from Joomla 3.9, here's some important things to keep in mind before you click the Update button.

In conjunction with the release of Joomla 4 Stable today, Joomla 3.9 users will also be able to upgrade their sites to Joomla 3.10 Stable, also released today. This update for Joomla 3 series sees a number of new features introduced mainly to assist users with their transition to Joomla 4.

There's no need to rush upgrading to Joomla 4

Joomla 4.0 Stable was released shortly before this issue of Joomla Community Magazine was published, so for many readers who have used Joomla for some time, I imagine you're like most of my Joomla user group colleagues in Australia.

You'll have been watching and looking at Joomla 4's development for a while now. Over recent months you will have been enthusiastically anticipating using it for new websites (my first Joomla 4 site is already seeing a steady stream of enquiries arriving for my client).

You will also be weighing up whether to jump straight into upgrading your Joomla 3 sites to Joomla 4.

Joomla 3.x is still going to be supported for two more years, so there's no need to rush. And there's a number of reasons why waiting is recommended.

Avoid bricking your site

Joomla users should be very aware though that though efforts have been made to streamline the upgrade process from Joomla 3 to Joomla 4, you shouldn't assume that you can upgrade your website to Joomla 4 immediately. This early in the release, the process may not be as smooth as if you wait a few months.

Paying attention to what you're doing is critical, as I found out myself when testing a release candidate for Joomla 3.10 a few weeks ago.

I rushed the update process and was blindly checking boxes and clicking buttons assuming the information on the screen was about to do what I thought I was doing. The goal had been to only update the site to Joomla 3.10 RC. Instead, I bricked the website by upgrading the site prematurely to the Joomla 4 RC that was available at the time.

Several extensions on my site were flagged by the Pre-Update Check as not being Joomla 4 ready and likely to cause problems. The template that I had on the Joomla 3.10 site was also not yet compatible with Joomla 4. Combined together, that led to the site breaking.

Joomla Error: Sorry, there was a problem we could not recover from.

“Bricked” essentially means the website has turned into a brick. In the case of an important website, that might mean hundreds or thousands of dollars had been invested in the development of the site, but it’s now as useful as a brick (or perhaps a paperweight). A bricked site is unusable, and most likely will need to be restored from a backup, which hopefully you had taken at the start of the process.

Fortunately in my case, the site was specifically for testing Joomla 3.10, and though annoying that I triggered the upgrade and destroyed the site, it's provided with an anecdote that can be used as a warning for readers such as yourself.

So the initial key take away is to read what is on the screen and pay attention to what is about to happen in the upgrade process. If you're not ready to go to Joomla 4 for reasons the Pre-Update check is showing you, be sure to not click the upgrade button.

Plan your Upgrade

You'll find a guide to planning for your mini-migration from Joomla 3.10.x to 4.x in the Joomla documentation, and as it points out in its introduction you should do three things before embarking on your upgrade: plan, plan and plan.

The following things will help you avoid potential pitfalls:

Check that your hosting meets the technical requirements for Joomla 4
Have you got a working backup of your current site in case something goes wrong?
Are all your 3rd party extensions on your Joomla 3.x site available for Joomla 4.x?
If not, will they be? Check with the extension developer. If they indicate they're not releasing a Joomla 4 version of the extension, look for replacements on the Joomla Extensions Directory.
Does my template have a version available for Joomla 4? Do I need to find a new template? Can I migrate my existing template? This is likely to be the main point most users will need to consider, especially once most major extensions have been released for Joomla 4 Stable.

Once you've gone through the checklist items above, and others raised on the migration planning list you can move onto looking at actually executing your upgrade.

Pre-Update Check

Joomla 3.10 introduces a new Pre-Update check to address many of the issues seen with previous major version changes to Joomla where in most cases you needed to rebuild your site and migrate your content to the new version.

The Pre-Update Check is documented on JDocs, but to help familiarise you with what it's doing, here are the various checks being performed.

Required PHP & Database Settings Check

The first set of results displayed in the check are for the Required PHP and Database Settings. If you see a green bar for these results, your hosting platform is 100% ready for Joomla 4.

If there are issues with this part of the configuration check you'll see the heading has a red background as the issues it's detected are critical. You'll need to resolve these issues before you will be able to confidently upgrade your site to Joomla 4.

Pre-Update Check results: Required PHP & Database Settings

Recommended PHP Settings

The next check looks at other recommended PHP settings that you should have set for Joomla to operate optimally.

Similarly for this check, if there are issues with your configuration you'll see the heading has a yellow background as these issues are minor.

Pre-Update Check results: Recommended PHP Settings

Extension Pre-Update Check

This part of the check goes and looks at all the various extensions you have installed on your site, and then returns information as to whether they're ready for Joomla 4, or alternatively have any potential upgrade issues that can be identified.

You may see in the Extensions Pre-Update Check sections an indicator for Potential Upgrade Issue:

These are the types of issues that caused my site to be bricked as I described above.

Plugins with the type ('system', 'user', 'authentication', 'actionlog', 'twofactorauth') could be triggered while we are processing the upgrade. When there is a critical issue within that plugins that could result in a broken upgrade and make the site unusable. For that reason, any plugin from that type that is not explicit listed as compatible has to be even more carefully reviewed before you hit the upgrade button. It is strongly recommended to disable the plugins in question and to check with the original developer.

They fall into the following classifications:

Pre-Update Checks Failed: Your website could not connect successfully to the update server due to a time out or an error being returned.
Update Information Unavailable: These extensions have not returned any information that tells the pre-update check about the extension's compatibility with Joomla 4. For these extensions, you need to wait for the extension developer to update their extensions so that the update information is available.
Update Required: For extensions in this section of the Pre-Update Checks, there's an update available for the extension. Before updating the Joomla version, it's suggested you go to Extensions > Manage > Update and install the updated version of the extension to ensure the latest compatible version of the extension is ready before you upgrade.

Some extensions may have different versions for Joomla 3 and Joomla 4, so check with the extension developer if you're seeing different version details listed in the compatibility list. For these, you might need to install another update after upgrading to Joomla 4.
No Update Required: Extensions in this list are already at their latest available version, and that version is indicating that it's compatible with the version of Joomla that is being checked for compatibility.

When you go to update your Joomla installation and the Pre-Update Checks complete, ideally you would like to see all your extensions listed in the No Update Required group. From experience during testing, if you have a lot of third-party extensions installed on your website, a large number of extensions are still waiting on developers releasing Joomla 4.x compatible versions.

Many extension developers have been interviewed in the past year about their plans for Joomla 4 and a number of leading extensions have been released since Joomla 4 RC came out earlier this year. If you're an extension developer who hasn't yet released your Joomla 4 versions, now's the time to be looking to do so. If you're implementing sites and can't upgrade due to a Joomla 4 version of an extension not being available yet, get in touch with the extension developer and let them know you're interested in finding out when they will be releasing Joomla 4 compatible versions.

Top Take-aways

Planning your mini-migration is going to be essential. Once the extensions you use have become available for Joomla 4 and you've determined the path you want to take in regards to your site's template, then the migration can be straightforward.

To avoid problems though - especially ones you might not be able to recover from - my key take-away points for you are:

Make sure you have a working backup of your Joomla 3 site before you begin. Working backup means taking the backup and restoring it somewhere else to test it.
Read the results of the Pre-Update Check before checking the box at the bottom of the screen and continuing to install the update.
Do your research on the Joomla 4 compatibility of the extensions you use. If the developer is not going to upgrade to Joomla 4, find out what alternatives are available if you want to retain the same functionality.
Review your template's compatibility and design. It's a good time to consider giving your website a facelift if you're going to upgrade to Joomla 4, as major UX changes such as Bootstrap 5 support and the removal of jQuery as a default may impact functionality.
Don't rush your upgrade. Joomla 3 will be supported until 16 August 2023, and Joomla 4 has been stable for a few minutes at time of publication.