Magento migration from version 1 to version 2

Magento migration from version 1 to version 2

|Commerce Codes

Magento is one of the most popular open-source eCommerce platforms for complex, professional online stores. It's built on PHP and MySQL, and was originally based on the Zend Framework. Magento has many features you won't find on other eCommerce platforms, and businesses rely on it because it's well designed and flexible. At the time of writing, more than 240,000 businesses were using Magento for their online stores.

In this guide:

Why Magento?

1. Open source

Magento comes in two versions: a paid version and a free, open-source version. That makes it suitable for small, medium and large businesses alike.

2. SEO-friendly

SEO plays a big part in marketing and growing an online business. In Magento, you can easily adjust URLs and page elements for search engines.

3. Security

Online shoppers always want to know their money and data are safe. In Magento, you can manage security at user level and control access with roles, which helps keep your store secure.

4. A large community

Magento has grown rapidly over the years and has a large community of its own, which identifies new needs, develops features to meet them and helps grow the Magento ecosystem.

Magento 2 is a completely reworked version of the platform, with a new architecture, code structure and database design. Because of these changes, the biggest question for Magento 1 merchants is how to manage the migration to Magento 2.

The four stages of migration

According to Magento's official documentation, migrating to Magento 2 involves four stages:

1. Theme migration

Magento 2 introduces new methods and techniques for delivering a better shopping experience to merchants and customers. Developers can create new Magento 2 themes or adapt existing designs to Magento 2 standards. However, you can't move a Magento 1 theme directly to Magento 2: it will need to be rebuilt or adjusted.

2. Extension migration

Extensions add new features and improve your store's functionality. The next stage is to install the Magento 2 versions of the extensions you need from the Magento Marketplace. Magento 1 extensions don't work on Magento 2, and trying to use them will cause serious compatibility problems.

3. Customizations

Custom code written for your Magento 1 store usually isn't compatible with Magento 2. Magento provides a Code Migration Toolkit to help convert it, but because the two platforms are structured so differently, extra work is usually needed to make custom code work properly in your Magento 2 store.

4. Data migration

The final stage is moving your Magento 1 settings and data to Magento 2. Magento's official Data Migration Tool lets developers migrate store data and settings using command-line (CLI) commands. It moves data from the Magento 1 database to the Magento 2 database, following a set of rules defined in XML files.

Only data and settings are transferred by the Data Migration Tool. Magento 1 extensions, themes and other code customizations can't be migrated automatically.

Differences between Magento 1 and Magento 2

Since Magento 2 launched on November 17, 2015, more and more store owners and companies have moved to it. Magento 2 has many advantages over Magento 1, but what exactly are the differences?

1. Technology stack

Here's how the two versions compared when Magento 2 launched:

Magento 1 Magento 2
API added later API built into the core
Flexible architecture New architecture built for speed
Open source Open source
No front-end library Ships with LESS
Older PHP versions PHP 5.6+ / 7.0 at launch (PHP 8 in current versions)
Limited HTML5/CSS3 support Native HTML5/CSS3 support
Responsive (RWD) theme included Responsive theme included
Basic content staging Advanced content staging
Solr search (Enterprise) Elasticsearch (Commerce edition)
PayPal on an external page PayPal checkout on your own site
Secure bridge PCI-compliant hosted fields
Minimal video features Video on product pages
Full page cache (Enterprise only) Full page cache built in, with Varnish support

2. Performance

Online shoppers expect fast websites: studies show that around half expect a page to load in two seconds or less, and about 40% will leave a page that takes more than three seconds to load. Magento said that Magento 2 could load home, category and product pages in under 1.5 seconds, even without front-end caching.

Magento 2's streamlined checkout is also faster and easier for customers. Guests can check out without registering, Magento 2 automatically recognizes registered customers from their email address, and customers can create an account after checking out.

3. Extensions

There are many third-party extensions for Magento 1, but installing them can take a lot of time, even for experienced developers, and conflicts between extensions have to be resolved by hand.

In Magento 2, plugins let developers change how core functions behave without overriding the core code. This makes extensions less likely to conflict, and makes both back-end and front-end development simpler, helped by modern technologies such as HTML5, LESS, RequireJS and CSS3.

4. Support from Magento

Support for Magento 1 was originally due to end in November 2018, was extended, and finally ended on June 30, 2020. That support mainly covered security patches and important fixes. Without it, Magento 1 stores are exposed to new vulnerabilities and malicious software that will never be patched.

Plan your migration

From data migration to custom code, plan your migration carefully and follow these best practices, in this order:

  1. Review all your extensions, modules and custom modules. Keep the ones you'll still need, and drop any you no longer use.
  2. Set up a new development server and install the latest version of Magento 2 on it.
  3. Copy your Magento 1 database to the development environment.
  4. Migrate your settings and data with the Data Migration Tool.
  5. Copy your media files, rebuild your storefront design and re-create your ACLs (access permissions).
  6. Run all indexers and clear the caches.
  7. Test your Magento 2 site thoroughly.
  8. When you're ready to go live, stop admin activity and cron jobs on Magento 1, migrate any remaining changes (the "delta"), and switch over.

Data migration in detail

Before you start

Keep these points in mind for a successful migration:

  • Don't make any changes in the Magento 1 admin, except for order management.
  • Pause all Magento 1 cron jobs.
  • Don't change any code.
  • Don't make changes in the Magento 2 admin or storefront.
  • Check that your Magento 1 version is supported for migration:
    • Community Edition (CE): 1.6.x, 1.7.x, 1.8.x and 1.9.x
    • Enterprise Edition (EE): 1.11.x, 1.12.x, 1.13.x and 1.14.x

Data is migrated using the Data Migration Tool, which works like a shell application and needs the Magento 2 framework to run. The tool for both Community and Enterprise editions is available on GitHub and through Composer.

Once it's installed, you'll find its configuration and mapping files in a folder for each edition and version, under vendor/magento/data-migration-tool/etc/.

Configuration

  1. Choose the folder that matches your Magento 1 edition and version.
  2. Copy config.xml.dist to config.xml.
  3. In config.xml, enter:
    • The database details and credentials for Magento 1.
    • The database details and credentials for Magento 2.
    • crypt_key: the encryption key from Magento 1, found in app/etc/local.xml.

Mapping files

The Data Migration Tool uses mapping files to handle custom mapping between Magento 1 and Magento 2, including:

  • Changes to table names and field names.
  • Tables and fields to ignore.
  • Tables and fields to transfer.

The map step

  1. Copy map.xml.dist to map.xml, in the same folder as your configuration file.
  2. Update config.xml so it points to your map.xml file.
  3. The map step transfers most of your data from Magento 1 to Magento 2, following the instructions in map.xml.

The mapping file has two areas:

  • Source: rules for the source (Magento 1) database.
  • Destination: rules for the destination (Magento 2) database.

And these options:

  • Ignore: any document (table), field or data type marked with this option is skipped.
  • Rename: maps a source document to a destination document with a different name. Use it when the destination table name isn't the same as the source table name.
  • Move: moves a field from the source document to the destination document. The destination document must have the same name as the source document; if the names differ, use the rename option for the document that contains the moved field.
  • Transform: migrates fields according to the behavior defined in a handler.
  • Handler: defines how a field is transformed. To use one, specify the handler class and any parameters it needs in map.xml.

Run the migration

The migration runs in three modes, in this order: settings, data and delta. Run each from your Magento 2 root folder:

bin/magento migrate:settings [-r|--reset] {<path to config.xml>}
bin/magento migrate:data [-r|--reset] {<path to config.xml>}
bin/magento migrate:delta {<path to config.xml>}
  • Settings migrates your store configuration. It doesn't migrate every setting, so check all your settings in the Magento 2 admin before continuing.
  • Data migrates your main store data, such as products, customers and orders.
  • Delta migrates any data added to Magento 1 since the data migration, such as new orders and customers.

When each step finishes successfully, you'll see a "Migration completed" message. The Data Migration Tool saves its progress as it runs. If an error or user intervention stops it, it resumes from the last successful point.

Media

  • Copy all media files manually, such as product, category and WYSIWYG editor images, from Magento 1's media folder to Magento 2's pub/media folder.
  • Don't copy the .htaccess files from the Magento 1 media folder. Magento 2 has its own .htaccess files, which you should keep.

Storefront design

  • The location and format of design files (CSS, JavaScript, templates and XML layouts) have changed in Magento 2, so your design needs to be rebuilt.
  • Layout updates stored in the Magento 1 database aren't migrated and need to be re-created manually.

ACLs (access control lists)

  • Manually re-create all credentials for web service APIs (SOAP, XML-RPC and REST).
  • Manually re-create all admin users and assign them the right access permissions.

After migration

Start the Magento 2 cron jobs:

bin/magento cron:install

Manage and flush the Magento 2 caches:

bin/magento cache:status
bin/magento cache:enable [type] ... [type]
bin/magento cache:disable [type] ... [type]
bin/magento cache:clean [type] ... [type]
bin/magento cache:flush

Reindex all Magento 2 indexers:

bin/magento indexer:info
bin/magento indexer:status [indexer]
bin/magento indexer:reindex [indexer]

Migrate extensions and custom code

Once your data is on Magento 2, you need to:

  1. Review all your extensions, including third-party and custom extensions.
  2. List the extensions you use, and find or buy their Magento 2 versions in the Magento Marketplace.
  3. If an extension isn't available for Magento 2, migrate its code from Magento 1 to Magento 2 using the Magento Code Migration Toolkit, which reduces the effort needed.

Themes and customization

Magento 2 uses a new approach and architecture for themes and customization. If your Magento 1 store uses a theme from a third-party vendor, check with the vendor whether a Magento 2 version is available. Otherwise, you'll need to build a custom theme using the Magento 2 frontend developer guide.

Recommendations during migration

  • Always work with a copy of your Magento 1 database, never the live one.
  • Remove outdated and redundant data before migrating.
  • To speed up the migration, you can enable the direct_document_copy option in config.xml. This only works when both databases are on the same MySQL server.

Once the migration is complete, test your Magento 2 store thoroughly to make sure everything works as expected before you go live.