Code Migration Toolkit
The Magento Code Migration Toolkit provides scripts that ease the process of converting custom Magento 1.x code to Magento 2 by handling some of the most time-consuming conversion tasks. The toolkit is intended for Magento developers with reasonable expertise in both Magento 1.x and Magento 2.
The toolkit covers migration of the following aspects of the Magento code:
Module directory structure
Layout XML files
Config XML files
Migration of Magento modules is the focus of the toolkit. Magento themes are out of scope of the toolkit at the moment.
The toolkit can significantly reduce the work involved in the code migration. However, after running the toolkit one will need to manually edit some of the generated files.
PHP >= 5.5
Composer dependency management software
Note that being a command line tool the toolkit does not require a web server to be installed.
composer install in the migration toolkit root directory. This installs the toolkit’s dependency packages, including the Magento 2.x Framework, which forms the basis of the toolkit.
Before running the migration, the following directories need to be prepared:
<src>- 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.
<dst>- Empty directory for the toolkit to put the generated Magento 2 code to
<m1>- Directory that contains:
Vanilla Magento 1.x codebase, and
Custom Magento 1.x code same as in
Dependencies of the custom Magento 1.x code, if any, that are not part of
<src>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
<m2> may not necessarily be installed. Being a static analysis tool, the toolkit does not execute the Magento source code.
The migration consists of the following steps:
Migrate Magento 1.x module structure to the structure recognized in Magento 2
Migrate Magento 1.x layout XML files to the format recognized in Magento 2
Migrate Magento 1.x config XML files to the format recognized in Magento 2
Migrate the PHP code in terms of how it interacts with the Magento framework, preserving the business logic
Note that it may be necessary to regenerate the mapping files as the very first step. That is especially important in a case of migration between arbitrary Magento 1.x and Magento 2.x versions rather than the latest ones. It is an optional step, but it greatly influences the quality of the migration results. Please refer to the mapping files discussion later in the document.
Running the Migration
Run all the migration scripts:
php bin/migrate.php migrateModuleStructure <src> <dst>- Migrate directory structure
php bin/migrate.php convertLayout <dst>- Migrate layout
php bin/migrate.php convertConfig <dst>- Migrate config
php bin/migrate.php convertPhpCode <dst> <m1> <m2>- Migrate PHP code
The migration scripts are to be ran in the specified order as the output from one script may be used as input for another script.
The scripts read the Magento 1.x code from the
<src> directory, convert it, and write the transformed code to the
<dst> directory. All converted code is saved to files with a
*.converted extension. The directories
<m2> are used to lookup the context of the code being migrated.
Understanding Migration Scripts
The toolkit comes with the flexibility to adjust certain migration steps by configuring or skipping execution of respective migration scripts. This section discusses specifics of each of the migration scripts.
Module Structure Migration Script
This script does not alter contents of any files. Instead, it simply creates the appropriate Magento 2 module directory structure and moves the existing Magento 1.x code there. The output of this script is used as input by other scripts in the toolkit.
Layout Migration Script
This script splits Magento 1.x layout files into separate XML files for each layout handle and converts their XML format to the one used in Magento 2.
The script converts the contents of the handles using the mapping files. The script automatically tries to map and include/merge mapping found in the input modules. If you feel that some mapping were not picked up, then you might need to regenerate the mapping files from a magento installation that already has installed the modules that you are trying to convert.
The script does the following conversion-related tasks:
Splits the Magento 1.x layout files into separate XML files for each layout handle
Replaces the root tag and adds the proper schemas
Transforms the block type attribute to class and converts the name to Magento 2.x class
Converts to where needed removing the class on the container
Converts format of action arguments
Converts the translation labels as attributes
Config Migration Script
This script splits Magento 1.x config XML files and converts them to Magento 2.x XML format.
PHP Code Migration Script
This script converts most of the PHP code to be compatible with the Magento 2 Framework.
The script does the following conversion-related tasks:
Adds PHP 5.3+ namespaces used in Magento 2.x framework
Converts class name and full qualifier name for extends and implements
Identifies all dependencies on the
Mageclass and modifies the constructor and injects the dependencies and creates properties that are assigned to the dependency classes
Mage::getSingletonand identifies the proper class factories
Replaces all references to an Magento 1.x class with the name qualifier for the Magento 2.x class
Mage::throwExceptionreplacing it with the new namespace exceptions
Replaces all occurrences of
Mage::appby injecting a dependency for the request, cache, etc.
PSR logging with
Registry manipulation with
Mage::unregisterreplaced by dependency injection
getTableand related table aliases with real table names
Understanding Mapping Files
Mapping files are used to generate lists of classes as they were transformed from Magento 1.x to Magento 2.x. These mapping files capture these gerbil differences between Magento 1.x and Magento 2.0 files:
Files are renamed in case of names in XML
Classes named according to the new namespace conventions for PHP 5.3+
Most of these mappings are generated in automated fashion but some that have the
*_manual suffix are maintained manually because an automated process could not resolve those names, but subsequent processes are dependent on them.
Mappings for Magento 1.x names located in the
mapping/*.xml. These mapping files provides information to the tool or developers that are used to automatically or manually port legacy Magento 1.x code.
Mapping File Reference
The list of mapping files that come with the toolkit:
mapping/aliases.json- List of Magento 1.x CE module aliases defined in modules' config files to identify class namespaces as Magento 2.x will need the full class
mapping/aliases_ee.json- List of Magento 1.x EE module block aliases defined in modules' config files to identify class namespaces as Magento 2.x will need the full class
mapping/class_dependency.json- List of Magento 1.x class dependencies used for automatic vs manual class mapping
mapping/class_dependency_aggregated.json- List of aggregated Magento 1.x class dependencies used for automatic vs manual class mapping
mapping/class_mapping.json- List of automatically generated Magento 1.x (CE+EE) namespaces that map to Magento 2.x (CE+EE) namespaces for latest PHP conventions and proprietary framework
mapping/class_mapping_manual.json- List of manually maintained, Magento 1.x (CE+EE) namespaces that map to Magento 2.x (CE+EE) namespaces for latest PHP conventions and proprietary framework
mapping/module_mapping.json- List of the module names in Magento 1.x (CE+EE) that maps to the equivalent Magento 2.x (CE+EE) names
mapping/table_names_mapping.json- List of table name aliases in Magento 1.x that map to the real MySQL table names as Magento 2.x will not use aliases for
mapping/unmapped_classes.json- List of classes that are not present in the
mapping/class_mapping*.jsonand are not maintained in the manual list but used in the Magento core modules
mapping/view_mapping_adminhtml.json- List of the layout
adminhtmlhandle names in Magento 1.x that map to the Magento 2.x names that now are on a separate file using these namings
mapping/view_mapping_frontend.json- List of the layout
frontendhandle names in Magento 1.x that map to the Magento 2.x names that now are on a separate file using these namings
mapping/references.xml- List of references used in layouts that point to blocks and containers in Magento 2.x vs Magento 1.x that did not have this concept, as all were blocks
Regenerate Mapping Files
Quality of the migration greatly relies on the accuracy of mapping files. The toolkit comes with mapping files pre-generated for the latest Magento 1.x and Magento 2 releases out of the box. Migration between any given Magento 1.x and Magento 2 versions would require mappings to be regenerated prior to running the migration scripts.
Run the following to regenerate the mapping files:
php bin/utils.php generateClassDependency <m1>- Regenerate
php bin/utils.php generateClassMapping <m1> <m2>- Regenerate
php bin/utils.php generateModuleMapping <m1> <m2>- Regenerate
php bin/utils.php generateTableNamesMapping <m1>- Regenerate
php bin/utils.php generateViewMapping <m1> <m2>- Regenerate
php bin/migrate.php generateAliasMapping <m1>- Regenerate
php bin/migrate.php generateAliasMappingEE <m1>- Regenerate