Monday, December 24, 2012

Magento Upgrade Guide

First off, I need to recognize the guys at Turnkey Ecommerce Solutions for their excellent upgrade guide which I myself have used and which has helped countless people with upgrades. I felt it would be useful though to publish my own upgrade guide with some additional information and hiccups that I’ve hit in the upgrade process.

I've included some additional steps such as recommendations around version control, testing, and functionality changes to note; also, I prefer to upgrade by simply copying in the new magento code base, as opposed to using the mage command line tools.

1. Check for PCRE Unicode Compatibility.
Use the pcretest tool at your command line.

$ pcretest -C
PCRE version 6.6 06-Feb-2006
Compiled with
  UTF-8 support
  No Unicode properties support
  Newline character is LF
  Internal link size = 2
  POSIX malloc threshold = 10
  Default match limit = 10000000
  Default recursion depth limit = 10000000
  Match recursion uses stack

If you see the “No Unicode support” message above, you need to update your PCRE module. Here’s a resource for updating PCRE, you may want to ask your hosting company for some help with this. 

If you don’t have PCRE Unicode compatibility, you’ll hit an error like this upon upgrading.
User Notice: Sorry, your PCRE extension does not support UTF8 which is needed for the I18N core in lib/Zend/Locale/Format.php

2. Commit your code to a repository.
I will use Git for the remainder of this guide. When committing your code, you can safely ignore a lot of the files in your codebase, including media, cache, etc.

git add .htaccess app skin errors shell includes lib

By having your source code committed to a repository, you can easily clear out the upgraded files and start fresh if you run into any issues.

3. Upgrading from 1.3?
If you are upgrading from a version as early as 1.3, you’ll want to first upgrade to, and from there, upgrade to 1.7.
  • Download Magento and commit it to your repository.
  • Create a branch within Git for the release and add the 1.4 code to it. This will make it easy for you to run your 1.4 database upgrades, then your 1.7 upgrades when you deploy.
4. Download Magento 1.7
  • Download Magento and commit it to your repository.
  • You’ll want to have a branch in your repository for 1.4, so that when you’re upgrading, you can check it out, run database updates, then checkout master. More on that below.

5. Database Preparation

5.1. Clear Out the Logging Tables

Before running your database upgrades, you’ll want to clear out some log tables that may be fairly large by now. These tables alone can increase your database upgrade script times by 20 to 30 minutes pretty easily, because table column changes on tables with millions of records are really slow.

You can run this SQL query in your database client:

truncate magento_log_url;
truncate magento_log_url_info;
truncate magento_log_visitor;
truncate magento_log_visitor_info;
truncate magento_report_event;

5.2. Dump Your Original Database
Make a dump of your existing database, so that if something goes sideways, you have an easy way to restore it.
mysqldump -uUsername -p DatabaseName > var/db_orig.sql

6. Executing the Upgrade
Remember that if you’re upgrading from 1.3, you first want to checkout your 1.4 branch. Simply clear your cache and then access your Magento site in a browser to kick off the upgrades. Sit tight for a while as they complete.

Note: You may want to open up a MySQL client and look at your PROCESS LIST while the upgrade is running so you can have an eye on how each of the queries are going, and that way if something hangs, you should notice it pretty quickly.

7. Theme Fixes
Depending upon what your theme looks like, there may be a few things you’ll need to fix.

7.1. Add lib/ccard.js to page.xml
If you are unable to advance in the checkout process past the step where you enter credit card information (kind of a big deal :)), you may need to add lib/ccard.js into your page.xml layout file.
<action method="addJs"><script>lib/ccard.js</script></action>

7.2. Fix your pagination for search results
Because the Product_List_Toolbar block structure was changed a bit, your toolbar may not be including the pagination that it needs. If so, you'll need to add a pager child block to your toolbar. block:

# layout/catalog.xml
<block type="catalog/product_list_toolbar" name="product_list_toolbar" template="catalog/product/list/toolbar.phtml">
    <block type="page/html_pager" name="product_list_toolbar_pager"/>

7.3. You may need to fix the profiler block.
If you get the "Call to a member function toHtml() on a non-object in …/Layout.php" error message, you'll need to update your core_profiler block:

# layout/page.xml

<block type=”core/profiler” output=”toHtml” name=”core_profiler”/>
8. Testing the Upgrade
Once the upgrade is complete, you’re going to want to test it out a bit to make sure everything is working.

Here’s a very small checklist for you - you most likely have a much larger test plan with specifics to your business, so I won’t go into too much detail here.
  • Home Page
  • Perform a live purchase with a real credit card
  • Enable a test product that only costs $0.10 cents
  • Enable free shipping (who wants to pay shipping on a fake product after all?)
  • Verify that a purchase confirmation email is received
  • Category Page
  • Check the List View on the Category Page
  • Pagination for both Category and Search pages
  • Search results
  • Backend
  • Lookup the order that you made
  • Lookup a new customer registration
9. Functionality Changes
Congratulations, if you’ve gotten this far then your upgrade is complete and tested! Now there are just a few pieces of functionality you’ll want to be aware of with your brand spanking new Magento 1.7 site.

9.1. Out of Stock Items
If you would like for Out of Stock items to be displayed, go to System > Config > Inventory > Stock Options > Display Out Of Stock Products, and enable that.

9.2. Refunds
Refunds work a little bit differently. You can’t offer a refund from the order detail page itself, you’ll need to go into the Invoices tab > Select an individual invoice > then select Credit Memo.  Also, note that you can't refund orders made prior to the upgrade because they store the payment information differently.

No comments:

Post a Comment