|Use this document to UPGRADE CiviCRM installations on Joomla from versions 2.2.x, 3.0.x or earlier versions of 3.1|
IMPORTANT: CiviCRM 3.1 requires Joomla 1.5.x.
|Version 3.1 Requirements|
Before beginning this upgrade, verify that your server meets the requirements for CiviCRM 3.1.
- Joomla 1.5. : CiviCRM 3.1 has been built to run under Joomla 1.5.x and is not compatible with Joomla 1.0.x sites.
- PHP 5.2.x : Starting with the 1.9 release, CiviCRM will NOT run on PHP4 servers. CiviCRM 3.1 is also NOT compatible with PHP 5.3. (more info...).
- MySQL 5.0.x or higher with INNODB support : CiviCRM is compatible the current generally available MySQL release. Note that MySQL 5.1 is recommended for new installations and as sites are upgraded as CiviCRM is beginning to use Triggers more (eg to support multi-lingual installations), which require SUPER privileges in MySQL 5.0.
- PCRE with Unicode properties support (more info).
|Upgrade a Copy of Your Site First and Make a Complete Backup|
We strongly recommend that you create a copy of your existing site (directories and database) - and upgrade that copy first in order to make sure you can complete the upgrade successfully. In any case, you should create a full backup of the installed civicrm directory tree and civicrm database before beginning the upgrade process.
1. Download and Un-tar CiviCRM Code
All CiviCRM code and packages used by CiviCRM (such as PEAR libraries) are included in the compressed CiviCRM distribution files ('tarballs'). Follow these steps to download and install the codebase:
- Download the appropriate tarball file with your browser. Tarball file-names include the CiviCRM version. For example, civicrm-3.1.xxx-joomla.tar.gz.
- You may notice a file on the named something like civicrm-3.1.xxx-joomla-alt.tar.gz 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. Please ask your system administrator / hosting provider to recompile PHP with zip support." - Try the -alt version.
- Upload this file to your JOOMLA_1.5.x_ROOT/administrator/components/com_installer/component/ . Unzipping will create a directory called: com_civicrm.
2. Backup your CiviCRM database and settings file
Refer to the MySQLDump documentation or phpMyAdmin documentation if you need information on backing up your database.
Also take a backup/copy of civicrm settings files (as uninstaller would remove the code base) -
- <joomla_root>/components/com_civicrm/civicrm.settings.php and
If you are using certain components, you will need to backup files they use:
- CiviCase: Backup the XML files in the directory <joomla_root>/administrator/components/com_civicrm/CRM/Case/xml/configuration
3. Run the Installer
- Login to your Joomla Administrator site.
- Go to Extensions >> Install/Uninstall
- Click Components >> Select existing "CiviCRM". Click Uninstall.
- You should see "Uninstall Component Success".
- Click Install.
- Use Install from Directory and enter the full path to the un-zipped com_civicrm directory, which should be something like JOOMLA_1.5.x_ROOT/administrator/components/com_installer/component/com_civicrm.
- You should see "CiviCRM successfully installed" message.
*If you get the following error when installing or upgrading CiviCRM 3.1 for Joomla!*, Download and use civicrm-3.1.x-joomla-alt.zip package.
Your PHP version is missing zip functionality. Please ask your system administrator / hosting provider to recompile PHP with zip support.
4. Run the Database Upgrade script
|MySQL 4.0 and 4.1 are Not Supported|
Support for MySQL versions 4.0 and 4.1 has been discontinued. This means that you may encounter various issues and/or unexpected behavior if you atempt to run CiviCRM under these versions, and the CiviCRM engineering team will not provide support for debugging or resolving these issues. You are strongly encouraged to upgrade to the current generally available release of MySQL.
* Point your web browser to the following URL (you should already be logged in to Joomla with administrator-level permissions):
* You should see Upgrade successful message when the upgrade completes.
- *- If you receive any errors during the process, please note down the exact error message, and check for solutions on the community support forum.
- Now click the Return to CiviCRM home page link. This will rebuild CiviCRM menus automatically and return you to the CiviCRM home dashboard. You should the message Menu has been rebuilt.
- You should be up and running with the latest CiviCRM version. Confirm by checking the version and revision in the page footer.
- 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.
5. Verify and Update Resource URL Settings
- Go to Administer CiviCRM » Global Settings » Resource URLs
- Refer to the field help on that screen for instructions.
6. Enable Components
If you plan on using the new CiviCase component, or any components that you weren't using in the prior version (e.g. CiviPledge or CiviGrant for grant management) - you'll need to enable these component(s):
- Go to Administer CiviCRM » Global Settings » Enable Components
If you have been using Cases in 2.1 and / or want to start using the CiviCase component, you will also need to complete additional configuration steps. Learn more...
7. Restore settings file changes
If you had done any changes to civicrm settings file and took the backup in step2, copy those settings to the new files -
- <joomla_root>/components/com_civicrm/civicrm.settings.php and
If you are seeing unexpected behavior after completing the upgrade, you may need to reset your session. First simply log-out of your Administrator session and log back in. This may resolve the issues. If this doesn't help, use this procedure to force a session reset:
- Temporarily enable CiviCRM debug features:
- Go to Administer CiviCRM » Global Settings » Debugging
- Set Enable Debugging to Yes and click Save.
- Click the Administer CiviCRM menu (or any other CiviCRM menu item). After the page is loaded, add an additional query string value (&sessionReset=2) to the URL in your browser's location bar, and reload the page.
- Clear template cache by adding an additional query string value (&directoryCleanupReset=1)
- Now reset Enable Debugging to No and click Save.
|Do Not Leave Debug Features Enabled for a Public Site|
Debugging should be disabled for publicly available sites as it may allow browsers to view system configuration information.
Download and run Database Troubleshooting Tools to test the current state of the database and provides a diagnosis. The tools suite also includes a repair facility.
Remove cached copies of old templates
It may be that the install did not clear out the template cache. Try removing the cache contents. For example, with Linux, use with a command like ...
This will force CiviCRM to load the new templates rather than cached copies of the old ones.
Need More Help?
If you have any problems with these procedures, try searching the community forums and this wiki for solutions. If you've gotten an error message, use that message in your search. If you can not resolve the problem, then post your problem to the forum. Be sure to include the CiviCRM version and revision you are upgrading FROM and TO; your Joomla version; your PHP and MySQL versions; the steps you've taken and a the exact error message or problem that resulted.
Configuring Front-end Profile Listings and Forms in Joomla! Sites
Displaying Online Contribution Pages in Joomla! Frontend Sites
Configuring Front-end Event Info and Registration in Joomla! Sites