This document provides a comprehensive guide on using Magento 2 upgrade tooling, specifically focusing on code migration from Magento 1.x to Magento 2. It outlines the methodologies, commands, and sequences for migrating database schema, directory structure, layouts, configurations, and PHP code. The guide is targeted at Magento developers and emphasizes automated routines for code changes through command line interface (CLI) tools.

3. Magento 2 Upgrade Scope
Database
Schema
Data
Codebase
Magento framework
3rd party extensions
Custom modules
Custom themes
@SergiiShymko #mm16it

4. Magento 2 Upgrade Tooling
Database
Schema
Data
Codebase
Magento framework
3rd party extensions
Custom modules
Custom themes
Data migration tool
github.com/magento/data-migration-tool
Code migration tool
github.com/magento/code-migration
@SergiiShymko #mm16it

5. Code Migration Tool Scope
Directory
structure
Configuration
<?php // code ;)
Layout
Magento
module
@SergiiShymko #mm16it

6. Code Migration Tool Overview
• Audience: Magento developers
• Interface: Command line interface (CLI)
• Goal: Automate routine code changes
• Methodology: Static code analysis
Code migration tool
@SergiiShymko #mm16it
Magento 1.x
source code
Magento 2
source code

7. Prerequisite Directory Structure
@SergiiShymko #mm16it
<tool> – Installed M2 code migration tool
<src> – Custom M1 code to be migrated
<dst> – Empty directory to put generated M2 code to
<m1> – Vanilla M1 codebase + Custom M1 code (<src>)
<m2> – Vanilla M2 codebase

8. Directories Utilization
Code migration tool
@SergiiShymko #mm16it
<src> <dst>
<m1> <m2>

9. Directories Utilization
Code migration tool
@SergiiShymko #mm16it
<src> <dst>
<m1> <m2>

10. Migration Sequence
Generate
mappings
Migrate
directory
structure
Migrate
layout
Migrate
config
Migrate
PHP code
1. 2. 3. 4. 5.
@SergiiShymko #mm16it

11. Command to run:
1. Mapping Generation
• Mapping between:
– Latest M1 and M2 releases – out of the box
– Any M1 and M2 versions – generated on demand
• Mapping covers:
– Module names
– Class names & dependencies
– Table names
– View files
@SergiiShymko #mm16it
php <tool>/bin/utils.php generateClassMapping <m1> <m2>

12. Command to run:
2. Directory Structure Migration
• Removal of code pools (core, community, local)
• Aggregation of module’s files in a single directory:
– PHP code
– Templates
– Layouts
– Static assets
– Translation dictionaries
@SergiiShymko #mm16it
php <tool>/bin/migrate.php migrateModuleStructure <src> <dst>

13. Magento 1.x Magento 2
app/
code/
community/
Example/Module/
etc/modules/
locale/<locale>/
design/
<area>/base/default/
skin/
<area>/base/default/
app/
code/
Example/Module/
etc/
i18n/<locale>/
view/<area>/
2. Directory Structure Migration
@SergiiShymko #mm16it

14. Command to run:
3. Layout Migration
• Breaking down layout files by handles
• Format of layout XML files:
– Block types
– Block names
– Template references
– References to blocks and containers
– Adding JS/CSS assets to page head
@SergiiShymko #mm16it
php <tool>/bin/migrate.php convertLayout <dst>

15. Magento 1.x Magento 2
app/
design/
frontend/
base/default/
layout/
example.xml
app/
code/
Example/Module/
view/
frontend/
layout/
default.xml
…
3. Layout Migration
@SergiiShymko #mm16it

16. Command to run:
4. Configuration Migration
• Breaking down config.xml into granular configs
• Format of config XML files:
– Module declaration
– Routers
– Indexers
– Admin menu
– System configuration
– Widgets
@SergiiShymko #mm16it
php <tool>/bin/migrate.php convertConfig <dst>

17. Magento 1.x Magento 2
app/
code/community/
Example/Module/
etc/
config.xml
app/
code/
Example/Module/
etc/[<area>/]
module.xml
…
4. Configuration Migration
…
@SergiiShymko #mm16it

18. Command to run:
5. PHP Code Migration
• Breaking down controllers by actions
• Format of PHP files:
– Class namespaces
– Dependency injection via constructor
– Class name aliases in factory methods
– Class names in static calls, constants, arguments, operator “new”, PHPDoc
– Table name aliases
– Translation via “gettext”
@SergiiShymko #mm16it
php <tool>/bin/migrate.php convertPhpCode <dst> <m1> <m2>

19. 5. PHP Code Migration
@SergiiShymko #mm16it

20. Tool Commands Summary
1. Generate mappings
2. Migrate directory structure
3. Migrate layout
4. Migrate configuration
5. Migrate PHP code
php <tool>/bin/migrate.php migrateModuleStructure <src> <dst>
php <tool>/bin/migrate.php convertLayout <dst>
php <tool>/bin/migrate.php convertConfig <dst>
php <tool>/bin/migrate.php convertPhpCode <dst> <m1> <m2>
php <tool>/bin/utils.php generateClassMapping <m1> <m2>
@SergiiShymko #mm16it

21. a. Commit disabled M2 modules
b. Test, fix, and enable module by module
3. M2 codebase tasks
Upgrade Project Breakdown
2. Code migration tool tasks
a. Tailor the tool for patterns unique to the project
b. Run the tool against M1 codebase
1. M1 codebase tasks
a. Remove unused modules
b. Remove fixes of M1 bugs irrelevant in M2
@SergiiShymko #mm16it

22. Sergii Shymko
sshymko@magento.com
sergey@shymko.net
github.com/magento/code-migration
github.com/magento/data-migration-tool
devdocs.magento.com/guides/v2.0/migration/migration-tool.html
Thank You!
Q & A