Skip to content

Instantly share code, notes, and snippets.

@ProcessEight

ProcessEight/Migrating your code from M1 to M2.md

Last active November 21, 2016 17:18
Show Gist options
  • Save ProcessEight/a4e41b3099e9a854aee4423a1bf16acf to your computer and use it in GitHub Desktop.
Save ProcessEight/a4e41b3099e9a854aee4423a1bf16acf to your computer and use it in GitHub Desktop.
Download ZIP
Notes for presentation on migrating your code from M1 to M2
Raw
Migrating your code from M1 to M2.md

Magento 1 to Magento 2 Code Migration

Theory

What are the big code changes in M2?

  • Different directory structure
  • Namespaces
  • Dependency Injection
  • Domain-specific config XML files
  • Handle-specific layout XML files

What can be migrated automatically?

  • Directory structure
  • Config XML
  • Layout XML
  • PHP Code

What can't be migrated automatically?

These must be migrated manually:

  • Themes
  • Resource scripts
  • CSS conversion from plain CSS to LESS/SASS
  • JS conversion from Prototype to jQuery
  • Custom business logic (depends)
  • Module dependencies. These need to be done separately.
  • Unit tests (?)
  • 3rd Party Libraries - these should be added to M2 composer.json manually
  • Layout XML in the admin

What shouldn't you migrate?

Migrating is a lot of work, even if some of it is automated. Don't bother migrating an extension if you can answer yes to any of the following questions: (Include that flow-chart from that Lime Soda presentation here)

  • Does it duplicate existing M2 functionality?
  • Is there an M2 extension already available that does the same thing?
  • Does the client no longer use the extension?

Practice

Migrating using automated tools

  • Not a complete solution - some remedial work will need to be done.
  • These tools simply automate repetitive tasks, i.e. Splitting the M1 config.xml file into multiple M2 config XML files
  • Depending on the age and purpose of the extension, it may be better to start from scratch than try to migrate it (hold that thought)
  • It would be very helpful to know about the part of M2 your M1 extension works with (i.e. Payment gateways, shipping methods, etc) so you can tell how accurate the migration was after it has been migrated
  • Convert your extension using each one, then compare, contrast and merge all changes (including any manual changes you've made) into one finished product

The Tools

Code Migration Toolkit (Magento)

https://github.com/magento/code-migration

  • Standalone CLI tool, aimed at developers to automate routine code changes using static analysis
  • M1 code goes in, M2 code comes out
  • Only covers custom extensions. Themes, data and database schema are not migrated.
  • Remaining work: Converting custom business logic, testing, troubleshooting
  • Last updated: Less than a month ago

ConvertM1M2 (Unirgy)

https://github.com/unirgy/convertm1m2

  • Developed by ex-M1 core developer
  • Convert multiple extensions at once
  • Includes code validation of migrated classes
  • Difficult to configure
  • Remaining work: Converting custom business logic, testing, troubleshooting
  • Last updated: 9 months ago

Pestle (Alan Storm)

https://github.com/astorm/pestle

  • Not a migration tool, but an M2 code generation tool
  • Helpful for plugging the gaps that other code migration tools may miss
  • Last updated: Less than a month ago

Start from scratch

  • Maybe a better option if you don't get good results from automated tools
  • Use an M2 module generator (e.g. Pestle, n98-magerun2)
  • Use your M1 extension for reference

Process

Preparation

  • Get your M1 extension into the best shape possible
  • Remove anything which depends on M1 features which are not present in M2
  • Remove M1-specific bug fixes or obsolete customisations
  • Remove anything which duplicates M2 functionality

Convert

  • Run the tool(s). Output the migrated extension into separate directories.

Afterwards

  • Manual inspection (diff) of code.
  • Check to see what wasn't migrated.
  • Manually convert anything remaining.
  • Bonus points: If there is a design pattern which occurs across your extension which the tool doesn't convert, fork the tool and modify it to update that, rather than manually updating it wherever it occurs

Testing

  • Run M2 unit tests. Make sure they all pass.
  • Install the migrated extension into vanilla M2 instance.
  • Write M2 unit tests for your migrated extension!
  • Run M2 unit tests again.

Using the Magento Code Migration Toolkit

Installation

What it does

  • Moves extension files into M2 directory structure
  • Migrates layout XML
  • Migrates config XML
  • Migrates PHP code

Usage notes

  • You'll need a vanilla install of both M1 and M2
  • You'll need your extension installed in the M1 instance
  • Does not support modman, or custom extension directory structure. Extensions must be in native M1 directory structure
  • If your extension has dependencies on other extensions or libraries, they must be installed in the M1 instance as well, even if they are not to be migrated
  • Changes are cumulative, so each of the tools must be run in the specified order

How to use it

0. Preparation

Before running the migration, the following directories need to be prepared:

  • <source> - Directory that contains custom Magento 1.x code that is intended to be migrated. The code must follow the Magento 1.x directory structure. Magento 1.x core files must not be included.

  • <destination> - Empty directory for the toolkit to write the generated Magento 2 code into

  • <m1> - Directory that contains:

  • Vanilla Magento 1.x codebase, and

  • Custom Magento 1.x code same as in <source> directory, and

  • Dependencies of the custom Magento 1.x code, if any, that are not part of <source> directory as not intended to be migrated at the moment

  • <m2> - Directory that contains the vanilla Magento 2.x codebase

The above directories are not required to be positioned relatively to each other, they can be anywhere in the file system.

Note that the Magento instances living in the directories <m1> and <m2> may not necessarily be installed. Being a static analysis tool, the toolkit does not execute the Magento source code.

1. Generate mappings
  • Uses mappings to migrate module names, class names, table names and view files to M2 equivalents
  • E.g. Mage_Catalog (in M1) is mapped to Magento_Catalog (in M2)
  • Pre-generated mappings are included for 1.9x, mappings for other versions can be created on demand

Command:

php <tool>/bin/utils.php generateClassMapping <m1> <m2>
2. Migrate directories
  • Removes code pools
  • Aggregates extension files into one directory

Command:

php <tool>/bin/migrate.php migrateModuleStructure <source> <destination>
Before and after

Screenshot of M1 extension directory structure to left and M2 directory structure to right

3. Migrate layout XML
  • Splits layout XML files into handle-specific XML files

Command:

php <tool>/bin/migrate.php convertLayout <destination>
Before and after

Screenshot of M1 layout XML file to left and M2 layout file(s) to right

4. Migrate config XML
  • Splits config XML files into domain-specific XML files

Command:

php <tool>/bin/migrate.php convertConfig <destination>
Before and after

Screenshot of M1 config XML file to left and M2 config file(s) to right

5. Migrate PHP classes
  • Refactors controllers by actions
  • Updates PHP namespaces
  • Adds class dependencies to constructor using DI
  • Updates class name aliases in factory methods
  • Replaces calls to static methods (i.e. Mage::)

Command:

php <tool>/bin/migrate.php convertPhpCode <destination> <m1> <m2>
Before and after: Classes

Screenshot of M1 PHP class/observer/controller files to left and M2 equivalent files to right

Before and after: Controllers

Screenshot of M1 PHP class/observer/controller files to left and M2 equivalent files to right

Before and after: Observers

Screenshot of M1 PHP class/observer/controller files to left and M2 equivalent files to right

Live Demo!

Use Asciinema to record a session as a fallback if live demo is not possible

Alternative to code migration

  • Refactor your extension so it supports M1 and M2 simultaneously (but that's for another time ;)

Sources

Tools

Magento: Code Migration Toolkit
https://github.com/magento/code-migration
Unirgy: ConvertM1M2
https://github.com/unirgy/convertm1m2
Alan Storm: Pestle
https://github.com/astorm/pestle

Presentations

Imagine 2016 - Developer Deep Dive: Magento 1.x to Magento 2 Code Migration Tool
https://www.youtube.com/watch?v=lXJ6rMdQvkk&feature=youtu.be
Meet Magento Serbia - Porting Magento 1.x extensions to Magento 2
https://www.youtube.com/watch?v=Q19fJ2UQsaI
Meet Magento Utrecht: Migrating from Magento 1 to Magento 2
http://www.slideshare.net/mzeis/migrating-from-magento-1-to-magento-2

Documentation

Magento DevDocs: Migrate from Magento 1 to Magento 2
http://devdocs.magento.com/guides/v2.0/howdoi/migrate/migrate.html
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment