I know what you’re thinking, here’s a great tutorial on how to 100% effectively upgrade a Magento website from any version to any new version without losing any data, extensions, nuts/bolts, cobwebs, hair, fingernails or sanity. If that’s what you where thinking then you’re only half right.
The purpose of this tutorial is yes, to show you an upgrade method that works but also (and more importantly) to highlight some of the crazy things that can happen when an upgrade attempt is made.
Many Methods of Upgrading Magento
There are many ways to upgrade a Magento website so the first thing I want to say is that our example may not suit everyone and there are alternatives if you are struggling with our step by step below.
The most popular upgrade methods out there are:
Upgrade via Magento Connect
Within each Magento installation is the in-built ability to upgrade via Magento Connect. By Navigating to System>Magento Connect>Magento Connect Manager (or yourwebsite.com/downloader) you should see the following:
If your Magento website has been perfectly built-this may be the option for you! Otherwise keep reading.
Using a Cart2Cart Migration package
There are some extensions out there that allow you to migrate all of your important database items across to another version of Magento – basically a Magento to Magento import. The advantage of this is that is allows you to retain a completely fresh installation of Magento, port across all required extensions and themes etc. and then import the data. Job done.
The only issue with this is perhaps the possibility of losing some data that Cart2Cart can’t import – such as custom database tables.
In-Built File System Upgrade
Lurking within Magento’s vast file system are numerous upgrade scripts. These upgrade scripts programmatically update the database for every single module that makes up what we know as Magento. With each version of Magento that is released these scripts increase in size whenever a database change is required.
Our Chosen Upgrade Process
We’ve chosen to use the In-Built process for our example here simply because it’s probably the most complicated method there is and therefore can teach us more about Magento and the pitfalls during an upgrade.
Please bear in mind that the below steps were taken from a real upgrade from 1.4.2.0 to 1.7.0.2 which worked correctly. I may have been supremely lucky or the website could have been built really well. I’m hopeful that you’ll also find success in your upgrade.
The Manual Upgrade Process
When upgrading a Magento website you need to check which custom elements have been installed and how well the website has been coded. The difference between the upgrade of a well-formatted Magento site and one that isn’t, is anywhere between a few hours and an impossibility – so our first step is to take a good long look at the current website.
1. Take a good look around
The most important thing to check for are edited core files – the big no-no in any PHP framework development. If you have a decent FTP client you should be able to browse the folder/file structure and check for any strange modified dates.
I’ve had a few comments where developers have mentioned that there are better ways to prepare for the upgrade process – tools such as code comparisons to compare the differences between code bases should make this task easier if you have them available.
If all looks OK then the next things to check are localised Magento overrides – these little beauties can sneak up on you after an upgrade and are potentially catastrophic. They’re basically copied core Magento files that are placed within the Local folder to override the core file. Check why these are there – and whether any code changes could have been performed through an extension – overriding an entire file is not the best way to perform these changes – especially when after an upgrade who knows how much this core file could have changed?
Another thing to look out for are module files – some modules utilise the core code in different ways, through observers and overwrites. Check through your modules to make sure that those that are using observers etc will still work after an upgrade (i.e. the observers are still there and are still passing the correct data).
2. Take Backups of Everything
Never should you attempt to do this on a live website, you should have a test domain set up that you can use and then swap them over once the upgrade is complete. So what we should be doing at this point is taking our backups. We need an SQL backup and a file backup. To preserve order data etc. we may want to temporarily close down our live website at this time – though be warned sometimes this process can take a fair few hours.
3. Install new version of Magento onto Development Domain
Now we’re getting into the meat of it. We need to install a brand new Magento version on our development domain first – all the new files and the database. We will just run the browser-based installer. Once the new Magento website is up and running we need to start porting across our old files that we want to keep.
4. Copy across all files we want to keep
This is where it gets tricky, we are going to port across all of the theme files / extensions / custom layouts – all of it from our old website to the new installation we made in step 3. Normally this includes things like the following:
- app/etc/modules (all custom module xml)
- app/code/community (all these files and folders)
- app/code/local (all these files and folders)
- app/design/adminhtml (any custom adminhtml templates)
- app/design/frontend (our themes and also any extension files)
- skin/adminhtml (any custom adminhtml theming)
- skin/frontend (our themes and also any extension theme files)
- media/ (any folder really in media should be copied across – for the images etc)
- local root files that are in use (any files on the root that the old website is using)
There may be a lot more than what I’ve mentioned above but these are the usual things that must be copied across.
Another important note is that there is an alternative to the above that is also mentioned in the comments, for some installations the easier option may be to duplicate the existing site and copy across to the development domain (as opposed to installing the new version) and then overwrite all files by layering your new Magento installation across. As long as the audit is done before-hand (as per step 1) then the fixing of any base or core files will still be possible.
5. Make sure new website is still working
OK so now we should have a new Magento installation with our old theme on it – now’s the time to start looking around and making sure nothing is broken – unfortunately we are restricted as there are currently no categories or products – you can add a few test ones to test the product page / category pages etc. if you like as we will be ejecting this temporary database very shortly. This is also a good time to test our extensions work with our new version of Magento.
6. Remove Local.XML
In this step we are going to remove local.xml. The reason we do this is because we want Magento to think that we are going to run a new installation. In our development domain simply delete or rename app/etc/local.xml.
An alternative to this is to re-edit the database configuration details within our local.xml – this should also run the upgrade process without having to go through the installation process (Thanks to Ben in the comments).
7. Import old Database
Next we need to create a new database on our server and import the database dump we had taken from our old website. The easiest way to do the import/export is to do it through SSH – it’s very quick.
// to create a db dump mysqldump -u dbusername -pdbpassword olddbname > afilename.sql // to import again mysql -u dbusername -pdbpassword newdbname < afilename.sql
Once we have imported this database we need to refresh our development domain homepage – this should trigger the installation script.
8. Run installer with new files on old database
This is where the magic happens. The new files now contain all of the MySQL upgrade scripts for all of the core functionality of Magento. What we should find when we g through the installation process is that Magento picks up that we have connected to an old database (after we’ve entered the old DB information) and then let’s us know it’s performing the upgrade.
9. Wait
As I said before – depending on how great a leap you are performing across Magento versions the length of time it takes to perform the upgrade could be a few hours. I personally upgrade a version 1.4.2.0 to 1.7.0.2 in about 2 hours. If it times-out or errors appear etc. you can either try again with a new database or alternatively refresh the installation – it should carry on from where it left off.
10. Troubleshooting and setting live
Once the upgrade script has ran we now need to perform troubleshooting. First things first – clear the cache. If you can’t login to the admin then navigate to /var/ and rename the cache folder to something like cache_temp – Magento will then recreate this folder and will effectively clear it’s own cache.
Next perform a re-index of all data, as this will probably be a bit messed up during the upgrade.
Now we need to test the site thoroughly – double check all pages there may be simple little XML tweaks that need to occur – this is probably because we have copied versions of XML layouts within our theme/layouts folder. A particularly nasty one that caught me out was the customer.xml missing a few lines of XML. This caused the password-reset functionality for customers to break. Information on that bug can be found here: http://stackoverflow.com/questions/7915515/magento-password-reset-link-is-not-working
Finally once completely happy with the website – simply swap all files and database across to the old (live) domain and take the holding page off.
Conclusion
I’m hopeful at this point that you currently have an up-to-date working Magento installation. If you don’t, then to be honest any number of things could have caused it – probably extensions that are not compatible or some really bad developer coding.
In an ideal world we’d all be able to upgrade through Magento connect without an issue but sometimes it’s just not possible. The steps above are there as a way of breaking down a complex process in a reasonably safe way (remember we’re performing the upgrade on a development domain) and then checking and double checking (testing and testing again) before performing this on the live domain.