Tutorial

7 Steps to a Successful M1 to M2 Migration

A Magento 1 to Magento 2 migration is not an "update". It is a replatforming project. The database structures are different, the themes are incompatible, and the API logic has changed. This guide breaks down the project into 5 manageable phases that we use at Meetanshi for our enterprise clients.

Phase 0: Pre-Migration Technical Audit

Before writing code, you must know what you are dealing with.

  • Extension Audit: List all 50+ modules. Check which ones have M2 versions, which can be dropped, and which need custom rewriting.
  • Data Audit: Check database size. Large `log_` tables should be truncated. Check for "orphaned" product records.
  • SEO Benchmark: Crawl your current site with Screaming Frog. Save the list of all URLs to ensure 301 redirects are mapped later.

Phase 1: Environment Setup

Do not develop locally on XAMPP/MAMP. Use a Docker-based environment (Warden or DDEV) that mimics your production server.

Recommended Stack

  • Magento Version: 2.4.6 or latest.
  • PHP: 8.2 (Strict typing enabled).
  • Search: OpenSearch 2.5+ (Elasticsearch is legacy).
  • Queue: RabbitMQ (for asynchronous order processing).

Phase 2: Data Migration (The Tool)

We use the official Magento Data Migration Tool. It transfers settings, categories, products, customers, and orders.

# 1. Install Tool via Composer composer require magento/data-migration-tool:2.4.6 # 2. Configure map.xml (The hard part) # You must map every custom attribute from M1 to M2 # Ignore tables that don't exist in M2 to avoid errors # 3. Run Settings Migration bin/magento migrate:settings config.xml # 4. Run Data Migration bin/magento migrate:data config.xml

Pro Tip: The first run will fail. It always does. You will encounter "Integrity Constraint Violation" errors. You must debug your map.xml file iteratively until the data flows clean.

Phase 3: Theme & Frontend

You cannot migrate your M1 theme. You have three choices for the frontend:

Luma (Default)

Free, but uses legacy technologies (RequireJS, Knockout). Low Google Core Web Vitals score out of the box.

Hyvä (Recommended)

Modern stack (AlpineJS, TailwindCSS). exceptionally fast (90+ Mobile PSI Score). Costs €1,000 license.

PWA Studio

Headless React app. Very expensive to build and maintain. Only for large teams.

Phase 4: Custom Code & Extensions

Extensions: Install fresh M2 versions of your M1 extensions via Composer. Run setup:upgrade.

Custom Code: M1 used "Local Code Pool" overrides. M2 uses Dependency Injection (DI) and Plugins (Interceptors).

  • Replace `Mage::getModel('catalog/product')` with Repository Classes.
  • Replace `config.xml` observers with `events.xml`.
  • Do not edit core files. Use afterMethod plugins to intercept logic.

Phase 5: The Delta Migration & Go-Live

While you were building the M2 site (Phase 1-4), your M1 site was still taking orders. You need to sync this "gap" data.

The Go-Live Checklist

  1. Put M1 in Maintenance Mode: Stop data changes.
  2. Run Delta Migration: bin/magento migrate:delta config.xml. This reads the M1 `m2_cl_*` triggers to copy only new orders.
  3. Flush Cache & Reindex: bin/magento indexer:reindex.
  4. Switch DNS: Point your domain to the new M2 server IP.
  5. Test Payment Gateways: Make a real purchase immediately.