Upgrading CiviCRM for Joomla¶
Use this document to upgrade CiviCRM installations on Joomla to the latest CiviCRM release.
Before upgrading
Make sure you have done the steps listed in before upgrading first.
Known Issues
If using a version prior to 4.7.29 you need to apply the following two PRs after installation but before running the upgrader:
Download the latest code¶
- Go to the CiviCRM website
-
Select the latest currently available CiviCRM tarball for Joomla.
Example:
civicrm-x.x.x-joomla.zip
Note
You may notice a file on the named something like
civicrm-x.x.xx-joomla-alt.zip
the-alt
version does not require.zip
functions compiled into PHP by your hosting company. If you get errors like "Your PHP version is missing zip functionality", then try the-alt
version. -
Save this file in
<joomla_root>/tmp/
. - Unzip and check that it created a directory called
com_civicrm
in<joomla_root>/tmp
.
Backup your settings files¶
The before upgrading steps describe steps for backing everything up in case something goes wrong during the upgrade. In particular, note that Joomla has two settings files for CiviCRM and they should both be backed up:
<joomla_root>/components/com_civicrm/civicrm.settings.php
<joomla_root>/administrator/components/com_civicrm/civicrm.settings.php
Copy these files to a location outside your Joomla project.
Install the Extension¶
- Login to your Joomla Administrator site.
- From the menu choose Extensions » Manage » Install
- Use the Install from Folder tab and enter the full path to the un-zipped com_civicrm directory, which should be something like JOOMLA.x_ROOT/tmp/com_civicrm. If your temp directory is configured correctly you should only need to add "com_civicrm" to the prepopulated path.
- You should see "CiviCRM successfully installed" message.
The steps above will install CiviCRM directly on top of your existing installation. If you run into any issues, such as the component not appearing to reflect the new version, you may need to first uninstall the existing version and then install the new version. Uninstalling CiviCRM will remove the component files, but will not impact your database in any way.
Update localisation files¶
-
If using localization, also download the latest version of the localization files. See the CiviCRM Localisation page about how to install files for running CiviCRM in languages other than American English.
Go to
<joomla_root>/administrator/components/com_civicrm
and extractcivicrm-x.x.x-l10n.tar.gz
Clear the file cache¶
Delete all cache files in <joomla_root>/media/civicrm/templates_c
on your server before proceeding with the update script.
Upgrade the database¶
After the component installation completes click the link to run the database upgrade script. You may also point your web browser to the following URL (you should already be logged in to Joomla with administrator-level permissions):
http://example.org/administrator/index.php?option=com_civicrm&task=civicrm/upgrade&reset=1
You should see an Upgrade successful message when the upgrade completes.
- If you receive any errors during the process, please note the exact error message and check for solutions on Stack Exchange or Mattermost.
- Now click the Return to CiviCRM home page link.
- You should be up and running with the latest CiviCRM version. Confirm by checking the version and revision in the page footer. Note that you may need to refresh the browser screen a couple times to clear out your local cache and ensure the layout loads correctly.
- Take some time to browse the CiviCRM features that your organization uses. If you notice unexpected behaviors or error messages, refer to the trouble-shooting section below.
Restore settings file changes¶
Review the backup versions of the files below and compare them with the new versions just installed. In particular, make sure your site key value was retained and any of the configuration options found in those files are still intact.
/components/com_civicrm/civicrm.settings.php /administrator/components/com_civicrm/civicrm.settings.php
Post upgrade¶
See these steps to take after upgrading.