The new version 4 of Joomla is a great success and has helped renew interest in the platform in the very competitive CMS market. This is why it is time to update your site without further delay to this more modern and efficient version. This process called mini-migration by Joomla is relatively simple if you don't use too many third-party extensions. In the latter case, it will be necessary to examine each extension and check its compatibility with the update component present in Joomla 3.10 and with the Joomla extensions directory. Obsolete extensions can also be replaced by using Joomla custom fields, native methods or simpler extensions.
Preparing a checklist is essential before undertaking any delicate or complicated task. The following points will help you efficiently update your CMS.
Prepare to update the CMS
- Check that your server meets the minimum technical requirements requested by Joomla 4, in particular the version of PHP (7.2.5).
- Check that you have access to the files by SFTP/SSH and to the database and that you know how to modify the configuration files and the database without risk.
- Use a development or staging server to test the update.
- Don't forget to backup files and database at each step manually or with Akeeba Backup.
- If you are updating online, put the site in offline mode or use an IP address filter in the .htaccess file.
- The update process includes many database changes. If the version of Joomla is very old, you must therefore update several times from intermediate versions of the CMS, in particular, if you encounter bugs in the process. For example, if you are still on version 2.5.14, test first by upgrading to 2.5.15, then 2.5.28. You can get intermediate versions here and install them via download.
- Click Check Database in the system options after each update.
- Before moving to Joomla 4, first update your site to the latest version of Joomla 3.10. In this release, the update component checks the compatibility of the extensions used.
- Disable extensions that are not part of the core of Joomla during the update, especially plugins that are hooked into the core of the CMS execution cycle.
- Completely remove non-compatible extensions by uninstalling the package extension which will remove all dependencies at once. In general, database tables are not erased, which limits the risk of data loss.
- Disable the CMS file or memory cache systems. In the event of a problem, do not hesitate to empty the cache again from the backend or manually, without forgetting that the configurable location of the system cache files for the latest versions of the CMS can be found in /administrator/cache.
- Set PHP error reporting to none in Joomla, if you are overwhelmed by notices or if Ajax processes no longer work.
Finalize the installation of Joomla 4
- Update the server to the latest version of PHP (currently 8.1/8.2) and database.
- Check file permissions, particularly configuration.php (Joomla does this automatically after saving the configuration).
- Delete the current .htaccess file and replace it by renaming the htaccess.txt file provided by Joomla 4. Be careful, the .htaccess file may have been customized, for example with SEO redirects. You have to add them.
- Update robots.txt file.
- Disable any extensions you don't use, for example Contacts, Banners, Workflow or the old search engine (com_search).
- In System > Update Sites, remove extension links that no longer work.
- Reinstall, update and republish third-party extensions one by one and test. Remember to renew your licenses and never use the black market of commercial extensions. This leaves the door wide open to your site being hacked (we won't complain).
- Enable access to the site with Webauthn (TouchID, Windows Hello) or by double authentication (the security code can be generated by an application, by email, etc.), in order to secure the backend of your CMS.
- Check the settings of the http headers plugin and enable HSTS in particular.
- Empty the /tmp folder containing the temporary files left by the update.
- If you use them, check how scheduled tasks work, particularly on Joomla 5.
Update the frontend
Some template frameworks that rely little on Joomla for the front end will require less work. If you are using the old Joomla 3 Protostar template, it will be necessary to update it to Cassiopeia, which will shake up your layout, this is normal. The module position identifiers have changed. Some CSS class names have also changed between Bootstrap 2 and Bootstrap 5, which means changes to your stylesheet. To modify the HTML code of articles and categories, you can perform search / replace with an extension like ReReplacer from Regular labs or directly in the database. The following points must also be taken into account:
- Do not modify your template directly, but create a child template.
- Enable the accessibility check function integrated into Joomla and test your articles.
- Convert Font awesome icons to version 5 which is natively supported. Be careful of icons that disappear, because they are no longer compatible with the new syntax, especially those integrated directly into the CSS code.
- Update the substitution codes (overrides) in the html folder of your template. Obsolete code from some overrides is one of the most common causes of errors after updating. Also check changes to the chrome layout of modules that were previously in a modules.php file.
- Ideally optimize the way Javascript files are embedded in the PHP code of your custom code, although the old methods should still work.
- Use your browser's developer tool to check for possible problems caused by old Javascript scripts, files that are not loaded correctly or that are loaded too many times.
- If you are a perfectionist, take the opportunity to convert your jQuery scripts – which is no longer supported by default – to vanilla Javascript.
- I strongly advise enabling the debugging tool integrated into Joomla which will allow you to understand the nature of the errors or performance problems encountered. During one of my migrations, a crazy extension increased the number of SQL queries from 32 to 900.
- If the site is still broken, test on the default Cassiopeia template.
- Perform a SEO audit to check that there are no broken or unsuitable links for search engines (SEF).
- Check that your site is still integrated with any external services such as Google Search Console or Analytics.
Don't forget to make a complete backup of the files and the database and… put the site back online. You now have an up-to-date, secure and efficient CMS.
Source:
Updating to Joomla 4 Official documentation.